Specification

Struct Location

The location object describes where the an API object was extracted from a file. Uusally this points to the source file and a line number. The filename should always be relative to the root of a project or source control repository.

Field	Type	Required	Description
filename	str	Yes	A relative filename (e.g. relative to the project root).
lineno	int	Yes	The line number in the filename from which the API object was parsed.
endlineno	Optional[int]	No	If the location of an entity spans over multiple lines, it can be indicated by specifying at which line it ends with this property.

Struct Docstring

Represents the documentation string of an API object.

Field	Type	Required	Description
location	Location	Yes	The location where the docstring is defined. This points at the position of the first character in the content field.
content	str	Yes	The content of the docstring.

Struct Indirection

Represents an imported name. It can be used to resolve references to names in the API tree to fully qualified names.

Field	Type	Required	Description
type	str	Yes	The value is "indirection".
location	Location	Yes	The location where the indirection is defined.
name	str	Yes	The name that is made available in the scope of the parent object.
target	str	Yes	The target to which the name points. In the case of Python for example this can be a fully qualified name pointing to a member or a member of a module. In the case of starred imports, the last part is a star (as in os.path.*).

Struct Variable

A Variable object represents a variable or constant.

Field	Type	Required	Description
type	str	Yes	The value is "data".
location	Location	Yes	The location where the variable or constant is defined.
name	str	Yes	The name of the variable or constant.
docstring	Optional[Docstring]	No	The docstring of the variable or constant.
datatype	Optional[str]	No	The name of the type of the variable or constant.
value	Optional[str]	No	The value that is assigned to this variable or constant as source code.
modifiers	Optional[List[str]]	No	A list of modifier keywords used in the source code to define this variable or constant, like const, static, final, mut, etc.
semantic_hints	List[VariableSemantic]	No	A list of behavioral properties for this variable or constant.

Enumeration VariableSemantic

Describes possible behavioral properties of a variable or constant.

• INSTANCE_VARIABLE –
• CLASS_VARIABLE –
• CONSTANT –

Struct Argument

Represents a function argument.

Field	Type	Required	Description
location	Location	Yes	The location of the decoration in the source code.
name	str	Yes	The name of the argument.
type	ArgumentType	Yes	The type of argument.
datatype	Optional[str]	No	The data type of the argument.
default_value	Optional[str]	No	The default value of the argument as a code string.

Enumeration ArgumentType

• POSITIONAL_ONLY – An argument that can only be given by its position in the argument list. In Python, these are arguments preceeding a / marker in the argument list. Many programming languages support only one type of positional arguments. Loaders for such languages should prefer the POSITIONAL argument type over POSITIONAL_ONLY to describe these type of arguments.
• POSITIONAL –
• POSITIONAL_REMAINDER –
• KEYWORD_ONLY –
• KEYWORD_REMAINDER –

Struct Decoration

Represents a decoration that can be applied to a function or class.

Field	Type	Required	Description
location	Location	Yes	The location of the decoration in the source code.
name	str	Yes	The name of the decorator used in this decoration. This may be a piece of code in languages that support complex decoration syntax. (e.g. in Python, @(decorator_factory().dec)(a, b, c) should be represented as "(decorator_factory().dec)" for the name and ["a", "b", "c"] for the args).
args	Optional[str]	No	Deprecated in favor of arglist. A single string that represents the entirety of the argument list for the decorator, excluding the surroinding parentheses.
arglist	Optional[List[str]]	No	A list of the raw source code for each argument of the decorator. If this is not set, that means the decorator is not called. If the list is empty, the decorator is called without arguments. For example if the full decoration code is @(decorator_factory().dec)(a, b, c), this field's value would be ["a", "b", "c"].

Struct Function

Represents a function definition in a module or class.

Field	Type	Required	Description
type	str	Yes	Value is "function"
location	Location	Yes
name	str	Yes	The name of the function.
docstring	Optional[Docstring]	No
modifiers	Optional[List[str]]	No	An list of modifier keywords that the function was defined with.
args	List[Argument]	Yes	The function arguments.
return_type	Optional[str]	No	The return type of the function.
decorations	Optional[List[Decoration]]	No	The list of decorations attached to the function.
semantic_hints	List[FunctionSemantic]	No	A list of behavioral properties for this function.

Enumeration FunctionSemantic

• ABSTRACT –
• FINAL –
• COROUTINE –
• NO_RETURN –
• INSTANCE_METHOD –
• CLASS_METHOD –
• STATIC_METHOD –
• PROPERTY_GETTER –
• PROPERTY_SETTER –
• PROPERTY_DELETER –

Struct Class

Represents a class definition.

Field	Type	Required	Description
type	str	Yes	The value is "class".
location	Location	Yes
name	str	Yes	The name of the class.
docstring	Optional[Docstring]	No
metaclass	Optional[str]	No	The name of the metaclass used in this class definition.
bases	Optional[List[str]]	No	A list of the base classes that the class inherits from.
members	List[Variable | Function | Class]	Yes	A list of the members of the class.
decorations	Optional[List[Decoration]]	No	A list of the decorations applied to the class definition.
modifiers	Optional[List[str]]	No	A list of the modifier keywords used to declare this class.
semantic_hints	List[ClassSemantic]	No	A list of the semantic hints for this class.

Enumeration ClassSemantic

• INTERFACE –
• ABSTRACT –
• FINAL –
• ENUM –

Struct Module

A module represents a collection of data, function and classes. In the Python language, it represents an actual Python module. In other languages it may refer to another file type or a namespace.

Field	Type	Required	Description
type	str	Yes	The value is "module".
location	Location	Yes	The location of the module. Usually the line number will be 0.
name	str	Yes	The name of the module. The name is supposed to be relative to the parent.
docstring	Optional[Docstring]	No	The docstring for the module as parsed from the source.
members	List[Class | Variable | Function | Module]	Yes	A list of the module members.