Skip to content

docspec

Class Location

@dataclasses.dataclass
class Location()

[view_source]

Represents the location of an ApiObject by a filename and line number.

endlineno

If the location of an entity spans over multiple lines, it can be indicated by specifying at which line it ends with this property.

Class HasLocation

@dataclasses.dataclass
class HasLocation()

[view_source]

Base class for objects that have a Location.

Class Docstring

@dataclasses.dataclass
class Docstring(HasLocation)

[view_source]

Represents a docstring for an APIObject, i.e. it's content and location. This class is a subclass of str for backwards compatibility reasons. Use the content property to access the docstring content over the Docstring value directory.

location

The location of where the docstring is defined.

content

The content of the docstring. While the Docstring class is a subclass of str and holds the same value as content, using the content property should be preferred as the inheritance from the str class may be removed in future versions.

Class Decoration

@dataclasses.dataclass
class Decoration(HasLocation)

[view_source]

Represents a decorator on a Class or Function.

location

The location of the decoration in the source code.

name

The name of the decorator (i.e. the text between the @ and (). In languages that support it, this may be a piece of code.

args

Decorator arguments as plain code (including the leading and trailing parentheses). This is None when the decorator does not have call arguments. This is deprecated in favor of arglist. For backwards compatibility, loaders may populate both the args and arglist fields.

arglist

Decorator arguments, one item per argument. For keyword arguments, the keyword name and equals sign preceed the argument value expression code.

Class Argument

@dataclasses.dataclass
class Argument(HasLocation)

[view_source]

Represents a Function argument.

Class Type

class Type(enum.Enum)

[view_source]

The type of the argument. This is currently very Python-centric, however most other languages should be able to represent the various argument types with a subset of these types without additions (e.g. Java or TypeScript only support Positional and PositionalRemainder arguments).

POSITIONAL_ONLY

A positional only argument. Such arguments are denoted in Python like this: def foo(a, b, /): ...

POSITIONAL

A positional argument, which may also be given as a keyword argument. Basically that is just a normal argument as you would see most commonly in Python function definitions.

POSITIONAL_REMAINDER

An argument that denotes the capture of additional positional arguments, aka. "args" or "varags".

KEYWORD_ONLY

A keyword-only argument is denoted in Python like thisL def foo(*, kwonly): ...

KEYWORD_REMAINDER

An argument that captures additional keyword arguments, aka. "kwargs".

location

The location of the argument in the source code.

name

The name of the argument.

type

The argument type.

decorations

A list of argument decorations. Python does not actually support decorators on function arguments like for example Java does. This is probably premature to add into the API, but hey, here it is.

datatype

The datatype/type annotation of this argument as a code string.

default_value

The default value of the argument as a code string.

Class ApiObject

@dataclasses.dataclass
class ApiObject(HasLocation)

[view_source]

The base class for representing "API Objects". Any API object is any addressable entity in code, be that a variable/constant, function, class or module.

location

The location of the API object, i.e. where it is sourced from/defined in the code.

name

The name of the entity. This is usually relative to the respective parent of the entity, as opposed to it's fully qualified name/absolute name. However, that is more of a recommendation than rule. For example the docspec_python loader by default returns Module objects with their full module name (and does not create a module hierarchy).

docstring

The documentation string of the API object.

parent

@property
def parent() -> t.Optional["HasMembers"]

[view_source]

Returns the parent of the HasMembers. Note that if you make any modifications to the API object tree, you will need to call sync_hierarchy() afterwards because adding to Class.members or Module.members does not automatically keep the parent property in sync.

path

@property
def path() -> t.List["ApiObject"]

[view_source]

Returns a list of all of this API object's parents, from top to bottom. The list includes self as the last item.

sync_hierarchy

def sync_hierarchy(parent: t.Optional["HasMembers"] = None) -> None

[view_source]

Synchronize the hierarchy of this API object and all of it's children. This should be called when the HasMembers.members are updated to ensure that all child objects reference the right parent. Loaders are expected to return ApiObjects in a fully synchronized state such that the user does not have to call this method unless they are doing modifications to the tree.

Class VariableSemantic

class VariableSemantic(enum.Enum)

[view_source]

A list of well-known properties and behaviour that can be attributed to a variable/constant.

INSTANCE_VARIABLE

The Variable object is an instance variable of a class.

CLASS_VARIABLE

The Variable object is a static variable of a class.

CONSTANT

The Variable object represents a constant value.

Class Variable

@dataclasses.dataclass
class Variable(ApiObject)

[view_source]

Represents a variable assignment (e.g. for global variables (often used as constants) or class members).

datatype

The datatype associated with the assignment as code.

value

The value of the variable as code.

modifiers

A list of language-specific modifiers that were used to declare this Variable object.

semantic_hints

A list of hints that express semantics of this Variable object which are not otherwise derivable from the context.

Class Indirection

@dataclasses.dataclass
class Indirection(ApiObject)

[view_source]

Represents an imported name. It can be used to properly find the full name target of a link written with a local name.

Class FunctionSemantic

class FunctionSemantic(enum.Enum)

[view_source]

A list of well-known properties and behaviour that can be attributed to a function.

ABSTRACT

The function is abstract.

FINAL

The function is final.

COROUTINE

The function is a coroutine.

NO_RETURN

The function does not return.

INSTANCE_METHOD

The function is an instance method.

CLASS_METHOD

The function is a classmethod.

STATIC_METHOD

The function is a staticmethod.

PROPERTY_GETTER

The function is a property getter.

PROPERTY_SETTER

The function is a property setter.

PROPERTY_DELETER

The function is a property deleter.

Class Function

@dataclasses.dataclass
class Function(ApiObject)

[view_source]

Represents a function definition. This can be in a Module for plain functions or in a Class for methods. The decorations need to be introspected to understand if the function has a special purpose (e.g. is it a @property, @classmethod or @staticmethod?).

modifiers

A list of modifiers used in the function definition. For example, the only valid modifier in Python is "async".

args

A list of the function arguments.

return_type

The return type of the function as a code string.

decorations

A list of decorations used on the function.

semantic_hints

A list of hints that describe the object.

Class HasMembers

@dataclasses.dataclass
class HasMembers(ApiObject)

[view_source]

Base class for API objects that can have members, e.g. Class and Module.

members

The members of the API object.

Class ClassSemantic

class ClassSemantic(enum.Enum)

[view_source]

A list of well-known properties and behaviour that can be attributed to a class.

INTERFACE

The class describes an interface.

ABSTRACT

The class is abstract.

FINAL

The class is final.

ENUM

The class is an enumeration.

Class Class

@dataclasses.dataclass
class Class(HasMembers)

[view_source]

Represents a class definition.

metaclass

The metaclass used in the class definition as a code string.

bases

The list of base classes as code strings.

decorations

A list of decorations used in the class definition.

members

A list of the classes members. Functions in a class are to be considered instance methods of that class unless some information about the Function indicates otherwise.

modifiers

A list of language-specific modifiers that were used to declare this Variable object.

semantic_hints

A list of hints that describe the object.

Class Module

@dataclasses.dataclass
class Module(HasMembers)

[view_source]

Represents a module, basically a named container for code/API objects. Modules may be nested in other modules. Be aware that for historical reasons, some loaders lile docspec_python by default do not return nested modules, even if nesting would be appropriate (and instead the Module.name simply contains the fully qualified name).

members

A list of module members.

load_module

def load_module(source: t.Union[str, t.TextIO, t.Dict[str, t.Any]],
                filename: t.Optional[str] = None,
                loader: t.Callable[[t.IO[str]], t.Any] = json.load) -> Module

[view_source]

Loads a Module from the specified source, which may be either a filename, a file-like object to read from or plain structured data.

Arguments

  • source: The JSON source to load the module from.
  • filename: The name of the source. This will be displayed in error messages if the deserialization fails.
  • loader: A function for loading plain structured data from a file-like object. Defaults to json.load().

Returns

The loaded Module object.

load_modules

def load_modules(
        source: t.Union[str, t.TextIO, t.Iterable[t.Any]],
        filename: t.Optional[str] = None,
        loader: t.Callable[[t.IO[str]],
                           t.Any] = json.load) -> t.Iterable[Module]

[view_source]

Loads a stream of modules from the specified source. Similar to load_module(), the source can be a filename, file-like object or a list of plain structured data to deserialize from.

dump_module

def dump_module(
        module: Module,
        target: t.Optional[t.Union[str, t.IO[str]]] = None,
        dumper: t.Callable[[t.Any, t.IO[str]], None] = json.dump,
        serialize_defaults: bool = False) -> t.Optional[t.Dict[str, t.Any]]

[view_source]

Dumps a module to the specified target or returns it as plain structured data.

Arguments:

  • module: The module to dump.
  • target: The target to dump to. If None, the module will be returned as plain structured data.
  • dumper: A function for dumping plain structured data to a file-like object. Defaults to json.dump().
  • serialize_defaults: If True, default values will be serialized into the payload. Otherwise, they will be omitted. Defaults to False.

filter_visit

def filter_visit(objects: t.MutableSequence[ApiObject],
                 predicate: t.Callable[[ApiObject], bool],
                 order: str = "pre") -> t.MutableSequence[ApiObject]

[view_source]

Visits all objects recursively, applying the predicate in the specified order. If

the predicate returrns False, the object will be removed from it's containing list.

If an object is removed in pre-order, it's members will not be visited.

Arguments:

  • objects: A list of objects to visit recursively. This list will be modified if the predicate returns False for an object.
  • predicate: The function to apply over all visited objects.
  • order: The order in which the objects are visited. The default order is 'pre' in which case the predicate is called before visiting the object's members. The order may also be 'post'.

visit

def visit(objects: t.Sequence[ApiObject],
          func: t.Callable[[ApiObject], t.Any],
          order: str = "pre") -> None

[view_source]

Visits all objects, applying func in the specified order.

get_member

def get_member(obj: ApiObject, name: str) -> t.Optional[ApiObject]

[view_source]

Generic function to retrieve a member from an API object. This will always return None for objects that don't support members (eg. Function and Variable).