unitelabs.jsondocs.documentations
Attributes
- Name
GriffeObjType- Type
- Value
= typing.Union[griffe.Object, griffe.Class, griffe.Function, griffe.Module, griffe.Attribute]
- Description
- Name
DOCUMENTATION_TYPE_MAP- Type
- Value
= {'package': DocumentedPackage, 'class': DocumentedClass, 'function': DocumentedFunction, 'attribute': DocumentedAttribute}
- Description
Functions
get_name(obj : GriffeObjType) -> str
Extract `obj`s name. For an obj `B` deriving from obj `A`, the name for any method or attribute of `A` which is not overridden by `B` will be the qualified path of the method in `A`. In this case, the `obj.canonical_path` will not equal the `obj.path`. We intentionally return the `obj.canonical_path` here, as it reduces redundancy.
Parameters
- Name
obj- Type
- GriffeObjType
- Default
- Description
Response
- Type
- str
- Description
get_mro(obj : GriffeObjType) -> list[str]
For a given `GriffeObjType` object return the MRO of the object.
Parameters
- Name
obj- Type
- GriffeObjType
- Default
- Description
Response
- Type
- list[str]
- Description
sort_values_list_by_mro(obj : GriffeObjType, values_list : list[GriffeObjType]) -> list[str]
For a given `obj` sort the values in `values_list` by `obj`s MRO.
Parameters
- Name
obj- Type
- GriffeObjType
- Default
- Description
- Name
values_list- Type
- list[GriffeObjType]
- Default
- Description
Response
- Type
- list[str]
- Description
get_docstring(obj : GriffeObjType, kind : str) -> typing.Optional[str]
Extract a `griffe.DocstringSection` of a given `kind`s parsed value.
Parameters
- Name
obj- Type
- GriffeObjType
- Default
- Description
The `griffe.Object` to extract the `griffe.DocstringSection` from.
- Name
kind- Type
- str
- Default
- Description
The kind of `griffe.DocstringSection` to extract. Valid values are `text`, `parameters`, `returns`, `raises`, and `examples`.
Response
- Type
- typing.Optional[str]
- Description
qualify_annotation(annotation : GriffeAnnotationType) -> typing.Union[dict[str, typing.Any], str]
For an annotation, iterate through all parts of the parsed annotation and qualify any aliases. A `griffe.Expr` can contain: - `left` : an annotation to the left of a square bracket - `slice` : the contents of a square bracket - `elements` : the contents of a comma-separated list
Parameters
- Name
annotation- Type
- GriffeAnnotationType
- Default
- Description
Response
- Type
- typing.Union[dict[str, typing.Any], str]
- Description
map_parameters(
- obj_parameters : griffe.Parameters,
- obj_parameter_docs : list,
- obj : GriffeObjType
Unite parameter docstring information with the parameter typing information between the Class.__init__ function signature and the Class docstring. If the Class.__init__ signature contains *args or **kwargs, then the parameter docstring names MUST be `*args` and `**kwargs` respectively.
Parameters
- Name
obj_parameters- Type
- griffe.Parameters
- Default
- Description
- Name
obj_parameter_docs- Type
- list
- Default
- Description
- Name
obj- Type
- GriffeObjType
- Default
- Description
Response
- Type
- list[Parameter]
- Description
A single list of `Parameter` objects, with one entry per parameter.
Exceptions
- Type
- ParameterDocumentationMismatchException
- Description
- When the parameter docstring name does not match the parameter name, or the parameter name does not exist in the Class.__init__ signature
- Type
- ImproperDocumentationException
- Description
- When variadic parameters are documented without "*" included in the docstring name.
Classes
AnnotationOnly
Stores base classes of `DocumentedClass`.
- Bases
- typing.TypedDict
Attributes
- Name
annotation- Type
- typing.Union[dict[str, typing.Any], str]
- Value
= None
- Description
Example
Stores examples from docstrings processed in `HasExamples`, i.e. in `DocumentedClass` and `DocumentedFunction`. Multiple examples are separated by an empty line. Examples are formatted as follows:
- Bases
- typing.TypedDict
Attributes
- Name
description- Type
- str
- Value
= None
- Description
- Name
code- Type
- str
- Value
= None
- Description
DescriptionAndAnnotation
Stores descriptions and annotations in `HasReturns` and `HasRaises`.
- Bases
- typing.TypedDict
Attributes
- Name
description- Type
- typing.Optional[str]
- Value
= None
- Description
- Name
annotation- Type
- typing.Union[dict[str, typing.Any], str]
- Value
= None
- Description
Parameter
Stores parameter information in `DocumentedFunction` and `DocumentedClass`.
- Bases
- typing.TypedDict
Attributes
- Name
name- Type
- str
- Value
= None
- Description
- Name
description- Type
- str
- Value
= None
- Description
- Name
kind- Type
- str
- Value
= None
- Description
- Name
annotation- Type
- typing.Union[dict[str, typing.Any], str]
- Value
= None
- Description
- Name
required- Type
- bool
- Value
= None
- Description
- Name
default- Type
- typing.Optional[typing.Union[dict[str, str], str]]
- Value
= None
- Description
HasDocstring
Methods
__init__(self, obj : GriffeObjType) -> None
Parameters
- Name
self- Type
- Default
- Description
- Name
obj- Type
- GriffeObjType
- Default
- Description
get_docstring(self, kind : str) -> typing.Optional[str]
Extract a `griffe.DocstringSection` of a given `kind`s parsed value.
Parameters
- Name
self- Type
- Default
- Description
- Name
kind- Type
- str
- Default
- Description
The kind of `griffe.DocstringSection` to extract. Valid values are `text`, `parameters`, `returns`, `raises`, and `examples`.
Response
- Type
- typing.Optional[str]
- Description
Attributes
- Name
obj- Type
- Value
= obj
- Description
DocumentedItem
Base class for documented items.
Methods
__init__(self, obj : GriffeObjType, type_ : str) -> None
Parameters
- Name
self- Type
- Default
- Description
- Name
obj- Type
- GriffeObjType
- Default
- Description
- Name
type_- Type
- str
- Default
- Description
as_dict(self) -> None
Returns a dict representation of the annotated item, filtering out the all Falsy values except the boolean `False`.
get_docstring(self, kind : str) -> typing.Optional[str]
Extract a `griffe.DocstringSection` of a given `kind`s parsed value.
Parameters
- Name
self- Type
- Default
- Description
- Name
kind- Type
- str
- Default
- Description
The kind of `griffe.DocstringSection` to extract. Valid values are `text`, `parameters`, `returns`, `raises`, and `examples`.
Response
- Type
- typing.Optional[str]
- Description
Attributes
- Name
obj- Type
- Value
= obj
- Description
- Name
type- Type
- Value
= type_
- Description
- Name
name- Type
- Value
= get_name(obj)
- Description
- Name
path- Type
- Value
= str(obj.relative_package_filepath)
- Description
- Name
parent- Type
- Value
= obj.parent if obj.parent is None else get_name(obj.parent)
- Description
- Name
description- Type
- Value
= self.get_docstring('text')
- Description
- Name
lines- Type
- Value
= () if self.type == 'package' else (obj.lineno, obj.endlineno)
- Description
HasDecorators
Process decorators, if they exist.
Methods
__init__(self, obj : GriffeObjType) -> None
Parameters
- Name
self- Type
- Default
- Description
- Name
obj- Type
- GriffeObjType
- Default
- Description
Attributes
- Name
obj- Type
- Value
= obj
- Description
- Name
decorators- Type
- list[str]
- Value
= None
- Description
HasExamples
Create `Example` objects from Examples docstring section. Examples are returned from `griffe.DocstringSection.value` as a list of (kind, value) tuples. Examples: Description >>> some code [('text', 'Description'), ('examples', 'some code')] Description of a second example, which may span multiple lines >>> the example code >>> which can span multiple lines [('text', 'Description of a second example, which may span multiple lines'), ('examples', 'the example code which can span multiple lines')]
Methods
__init__(self, obj : GriffeObjType) -> None
Parameters
- Name
self- Type
- Default
- Description
- Name
obj- Type
- GriffeObjType
- Default
- Description
get_docstring(self, kind : str) -> typing.Optional[str]
Extract a `griffe.DocstringSection` of a given `kind`s parsed value.
Parameters
- Name
self- Type
- Default
- Description
- Name
kind- Type
- str
- Default
- Description
The kind of `griffe.DocstringSection` to extract. Valid values are `text`, `parameters`, `returns`, `raises`, and `examples`.
Response
- Type
- typing.Optional[str]
- Description
Attributes
- Name
obj- Type
- Value
= obj
- Description
- Name
examples- Type
- list[Example]
- Value
= None
- Description
HasFunctions
Process child functions if they exist. Used in `DocumentedClass` and `DocumentedPackage`.
Methods
__init__(self, obj : GriffeObjType) -> None
Parameters
- Name
self- Type
- Default
- Description
- Name
obj- Type
- GriffeObjType
- Default
- Description
Attributes
- Name
obj- Type
- Value
= obj
- Description
- Name
functions- Type
- list[str]
- Value
= None
- Description
HasMRO
Process MRO of a `DocumentedClass`.
Methods
__init__(self, obj : GriffeObjType) -> None
Parameters
- Name
self- Type
- Default
- Description
- Name
obj- Type
- GriffeObjType
- Default
- Description
Attributes
- Name
obj- Type
- Value
= obj
- Description
- Name
mro- Type
- list[str]
- Value
= None
- Description
HasAttributes
Process child attributes, if they exist. Used in `DocumentedClass` and `DocumentedPackage`.
Methods
__init__(self, obj : GriffeObjType) -> None
Parameters
- Name
self- Type
- Default
- Description
- Name
obj- Type
- GriffeObjType
- Default
- Description
Attributes
- Name
obj- Type
- Value
= obj
- Description
- Name
attributes- Type
- list[str]
- Value
= None
- Description
HasReturns
Process `Returns` section, if it exists. Used in `DocumentedFunction`.
Methods
__init__(self, obj : griffe.Function) -> None
Parameters
- Name
self- Type
- Default
- Description
- Name
obj- Type
- griffe.Function
- Default
- Description
get_docstring(self, kind : str) -> typing.Optional[str]
Extract a `griffe.DocstringSection` of a given `kind`s parsed value.
Parameters
- Name
self- Type
- Default
- Description
- Name
kind- Type
- str
- Default
- Description
The kind of `griffe.DocstringSection` to extract. Valid values are `text`, `parameters`, `returns`, `raises`, and `examples`.
Response
- Type
- typing.Optional[str]
- Description
Attributes
- Name
obj- Type
- Value
= obj
- Description
- Name
returns- Type
- typing.Optional[DescriptionAndAnnotation]
- Value
= None
- Description
HasRaises
Process `Raises` section, if it exists. Used in `DocumentedFunction`.
Methods
__init__(self, obj : GriffeObjType) -> None
Parameters
- Name
self- Type
- Default
- Description
- Name
obj- Type
- GriffeObjType
- Default
- Description
get_docstring(self, kind : str) -> typing.Optional[str]
Extract a `griffe.DocstringSection` of a given `kind`s parsed value.
Parameters
- Name
self- Type
- Default
- Description
- Name
kind- Type
- str
- Default
- Description
The kind of `griffe.DocstringSection` to extract. Valid values are `text`, `parameters`, `returns`, `raises`, and `examples`.
Response
- Type
- typing.Optional[str]
- Description
Attributes
- Name
obj- Type
- Value
= obj
- Description
- Name
throws- Type
- list[DescriptionAndAnnotation]
- Value
= None
- Description
DocumentedFunction
A `DocumentedItem` subclass for python functions.
- MRO
- ⎿⎽⎽HasRaises
- ⎿⎽⎽⎽HasReturns
- ⎿⎽⎽⎽⎽HasDecorators
- ⎿⎽⎽⎽⎽⎽DocumentedItem
- ⎿⎽⎽⎽⎽⎽⎽DocumentedFunction
Methods
__init__(self, obj : GriffeObjType) -> None
Parameters
- Name
self- Type
- Default
- Description
- Name
obj- Type
- GriffeObjType
- Default
- Description
set_parameter_docs(self, obj : GriffeObjType) -> None
Passes parameter docstrings in from another object, i.e. parameters which are documented as "Args" of a class `C` should be passed to the `C.__init__` function
Parameters
- Name
self- Type
- Default
- Description
- Name
obj- Type
- GriffeObjType
- Default
- Description
as_dict(self) -> dict[str, typing.Any]
Response
- Type
- dict[str, typing.Any]
- Description
get_docstring(self, kind : str) -> typing.Optional[str]
Extract a `griffe.DocstringSection` of a given `kind`s parsed value.
Parameters
- Name
self- Type
- Default
- Description
- Name
kind- Type
- str
- Default
- Description
The kind of `griffe.DocstringSection` to extract. Valid values are `text`, `parameters`, `returns`, `raises`, and `examples`.
Response
- Type
- typing.Optional[str]
- Description
Attributes
- Name
obj- Type
- griffe.Function
- Value
= None
- Description
- Name
param_docs- Type
- Value
= None
- Description
- Name
parameters- Type
- list[Parameter]
- Value
= None
- Description
- Name
type- Type
- Value
= type_
- Description
- Name
name- Type
- Value
= get_name(obj)
- Description
- Name
path- Type
- Value
= str(obj.relative_package_filepath)
- Description
- Name
parent- Type
- Value
= obj.parent if obj.parent is None else get_name(obj.parent)
- Description
- Name
description- Type
- Value
= self.get_docstring('text')
- Description
- Name
lines- Type
- Value
= () if self.type == 'package' else (obj.lineno, obj.endlineno)
- Description
- Name
decorators- Type
- list[str]
- Value
= None
- Description
- Name
returns- Type
- typing.Optional[DescriptionAndAnnotation]
- Value
= None
- Description
- Name
throws- Type
- list[DescriptionAndAnnotation]
- Value
= None
- Description
- Name
examples- Type
- list[Example]
- Value
= None
- Description
DocumentedClass
- MRO
- ⎿⎽⎽HasExamples
- ⎿⎽⎽⎽HasFunctions
- ⎿⎽⎽⎽⎽HasAttributes
- ⎿⎽⎽⎽⎽⎽HasDecorators
- ⎿⎽⎽⎽⎽⎽⎽DocumentedItem
- ⎿⎽⎽⎽⎽⎽⎽⎽DocumentedClass
Methods
__init__(self, obj : GriffeObjType) -> None
Parameters
- Name
self- Type
- Default
- Description
- Name
obj- Type
- GriffeObjType
- Default
- Description
as_dict(self) -> dict
Response
- Type
- dict
- Description
get_docstring(self, kind : str) -> typing.Optional[str]
Extract a `griffe.DocstringSection` of a given `kind`s parsed value.
Parameters
- Name
self- Type
- Default
- Description
- Name
kind- Type
- str
- Default
- Description
The kind of `griffe.DocstringSection` to extract. Valid values are `text`, `parameters`, `returns`, `raises`, and `examples`.
Response
- Type
- typing.Optional[str]
- Description
Attributes
- Name
bases- Type
- Value
= [AnnotationOnly(annotation=qualify_annotation(m)) for m in obj.bases]
- Description
- Name
obj- Type
- Value
= obj
- Description
- Name
type- Type
- Value
= type_
- Description
- Name
name- Type
- Value
= get_name(obj)
- Description
- Name
path- Type
- Value
= str(obj.relative_package_filepath)
- Description
- Name
parent- Type
- Value
= obj.parent if obj.parent is None else get_name(obj.parent)
- Description
- Name
description- Type
- Value
= self.get_docstring('text')
- Description
- Name
lines- Type
- Value
= () if self.type == 'package' else (obj.lineno, obj.endlineno)
- Description
- Name
decorators- Type
- list[str]
- Value
= None
- Description
- Name
attributes- Type
- list[str]
- Value
= None
- Description
- Name
functions- Type
- list[str]
- Value
= None
- Description
- Name
examples- Type
- list[Example]
- Value
= None
- Description
- Name
mro- Type
- list[str]
- Value
= None
- Description
DocumentedPackage
- MRO
- ⎿⎽⎽HasDocstring
- ⎿⎽⎽⎽DocumentedItem
- ⎿⎽⎽⎽⎽DocumentedPackage
Methods
__init__(self, obj : GriffeObjType) -> None
Parameters
- Name
self- Type
- Default
- Description
- Name
obj- Type
- GriffeObjType
- Default
- Description
as_dict(self) -> dict
Response
- Type
- dict
- Description
get_docstring(self, kind : str) -> typing.Optional[str]
Extract a `griffe.DocstringSection` of a given `kind`s parsed value.
Parameters
- Name
self- Type
- Default
- Description
- Name
kind- Type
- str
- Default
- Description
The kind of `griffe.DocstringSection` to extract. Valid values are `text`, `parameters`, `returns`, `raises`, and `examples`.
Response
- Type
- typing.Optional[str]
- Description
Attributes
- Name
classes- Type
- Value
= [get_name(m) for m in obj.classes.values()]
- Description
- Name
packages- Type
- Value
= [get_name(m) for m in obj.modules.values()]
- Description
- Name
obj- Type
- Value
= obj
- Description
- Name
type- Type
- Value
= type_
- Description
- Name
name- Type
- Value
= get_name(obj)
- Description
- Name
path- Type
- Value
= str(obj.relative_package_filepath)
- Description
- Name
parent- Type
- Value
= obj.parent if obj.parent is None else get_name(obj.parent)
- Description
- Name
description- Type
- Value
= self.get_docstring('text')
- Description
- Name
lines- Type
- Value
= () if self.type == 'package' else (obj.lineno, obj.endlineno)
- Description
- Name
attributes- Type
- list[str]
- Value
= None
- Description
- Name
functions- Type
- list[str]
- Value
= None
- Description
DocumentedAttribute
Methods
__init__(self, obj : GriffeObjType) -> None
Parameters
- Name
self- Type
- Default
- Description
- Name
obj- Type
- GriffeObjType
- Default
- Description
as_dict(self) -> dict
Response
- Type
- dict
- Description
get_docstring(self, kind : str) -> typing.Optional[str]
Extract a `griffe.DocstringSection` of a given `kind`s parsed value.
Parameters
- Name
self- Type
- Default
- Description
- Name
kind- Type
- str
- Default
- Description
The kind of `griffe.DocstringSection` to extract. Valid values are `text`, `parameters`, `returns`, `raises`, and `examples`.
Response
- Type
- typing.Optional[str]
- Description
Attributes
- Name
value- Type
- Value
= str(obj.value)
- Description
- Name
obj- Type
- Value
= obj
- Description
- Name
type- Type
- Value
= type_
- Description
- Name
name- Type
- Value
= get_name(obj)
- Description
- Name
path- Type
- Value
= str(obj.relative_package_filepath)
- Description
- Name
parent- Type
- Value
= obj.parent if obj.parent is None else get_name(obj.parent)
- Description
- Name
description- Type
- Value
= self.get_docstring('text')
- Description
- Name
lines- Type
- Value
= () if self.type == 'package' else (obj.lineno, obj.endlineno)
- Description