multidoc.parsing

Functions

yaml2dict(path[, include_name_error])

Yaml file parser.

Helper data models

Parameter(*, name[, type, description])	Parameter docstring pydantic.BaseModel data structure.
Returns(*[, name, type, description])	Returns docstring pydantic.BaseModel data structure.
Config(*[, name, version])	Multidoc module config pydantic.BaseModel data structure.

Core data models

Function(*, name[, short_summary, ...])	Function docstring pydantic.BaseModel data structure.
Class(*, name[, short_summary, ...])	Class docstring pydantic.BaseModel data structure.
Constant(*, summary[, extended_summary, ...])	Constant docstring pydantic.BaseModel data structure.
FileBased()	FileBased declaration pydantic.BaseModel data structure.
Module(*[, config, summary, ...])	Module docstring pydantic.BaseModel data structure.
Package(*[, config, summary, ...])	Module docstring pydantic.BaseModel data structure.

Reference

class multidoc.parsing.Class(*, name: str, short_summary: str = None, deprecation_warning: str = None, extended_summary: str = None, parameters: List[multidoc.parsing.models.Parameter] = None, attributes: List[multidoc.parsing.models.Parameter] = None, properties: List[multidoc.parsing.models.Property] = None, yields: List[multidoc.parsing.models.Yields] = None, other_parameters: List[multidoc.parsing.models.Parameter] = None, raises: List[multidoc.parsing.models.Raises] = None, warns: List[multidoc.parsing.models.Raises] = None, warnings: str = None, see_also: str = None, notes: str = None, references: str = None, examples: str = None, methods: List[multidoc.parsing.models.Function] = None, autoclass: multidoc.parsing.models.AutoClassConfig = None)

Class docstring pydantic.BaseModel data structure.

name

Type

str

short_summary

Type

Optional[str] # test

deprecation_warning

Type

Optional[str]

extended_summary

Type

Optional[str]

parameters

Type

Optional[List[Parameter]]

returns

Type

Optional[Returns] or Optional[List[Returns]]

yields

Type

Optional[List[Yields] or Yields]

other_parameters

Type

Optional[List[Parameter]]

raises

Type

Optional[List[Raises] or Raises]

warns

Type

Optional[List[Raises] or Raises]

warnings

Type

Optional[str]

see_also

Type

Optional[str]

notes

Type

Optional[str]

references

Type

Optional[str]

examples

Type

Optional[str]

methods

Type

Optional[str]

class multidoc.parsing.Config(*, name: str = None, version: str = None)

Multidoc module config pydantic.BaseModel data structure.

name

Type

Optional[str]

version

Type

Optional[str]

class multidoc.parsing.Constant(*, summary: str, extended_summary: str = None, see_also: str = None, references: str = None, examples: str = None)

Constant docstring pydantic.BaseModel data structure.

summary

Type

str

extended_summary

Type

Optional[str]

see_also

Type

Optional[str]

references

Type

Optional[str]

examples

Type

Optional[str]

class multidoc.parsing.FileBased

FileBased declaration pydantic.BaseModel data structure.

classmethod parse_yaml(path, **kwargs)

Parameters

• path –

• local –

class multidoc.parsing.Function(*, name: str, short_summary: str = None, deprecation_warning: str = None, extended_summary: str = None, parameters: List[multidoc.parsing.models.Parameter] = None, returns: multidoc.parsing.models.Returns = None, yields: List[multidoc.parsing.models.Yields] = None, other_parameters: List[multidoc.parsing.models.Parameter] = None, raises: List[multidoc.parsing.models.Raises] = None, warns: List[multidoc.parsing.models.Raises] = None, warnings: str = None, see_also: str = None, notes: str = None, references: str = None, examples: str = None)

Function docstring pydantic.BaseModel data structure.

name

Type

str

short_summary

Type

Optional[str] # test

deprecation_warning

Type

Optional[str]

extended_summary

Type

Optional[str]

parameters

Type

Optional[List[Parameter]]

returns

Type

Optional[Returns] or Optional[List[Returns]]

yields

Type

Optional[List[Yields] or Yields]

other_parameters

Type

Optional[List[Parameter]]

raises

Type

Optional[List[Raises] or Raises]

warns

Type

Optional[List[Raises] or Raises]

warnings

Type

Optional[str]

see_also

Type

Optional[str]

notes

Type

Optional[str]

references

Type

Optional[str]

examples

Type

Optional[str]

class multidoc.parsing.Module(*, config: multidoc.parsing.models.Config = None, summary: str = None, extended_summary: str = None, routine_listings: str = None, see_also: str = None, notes: str = None, references: str = None, examples: str = None, enums: List[multidoc.parsing.models.Enum] = None, classes: List[multidoc.parsing.models.Class] = None, functions: List[multidoc.parsing.models.Function] = None, constants: List[multidoc.parsing.models.Constant] = None)

Module docstring pydantic.BaseModel data structure.

config

Type

Optional[Config]

summary

Type

Optional[str]

extended_summary

Type

Optional[str]

routine_listings

Type

Optional[str]

see_also

Type

Optional[str]

notes

Type

Optional[str]

references

Type

Optional[str]

examples

Type

Optional[str]

classes

Type

Optional[List[Class]]

functions

Type

Optional[List[Function]]

constants

Type

Optional[List[Constant]]

class multidoc.parsing.Package(*, config: multidoc.parsing.models.Config = None, summary: str = None, extended_summary: str = None, routine_listings: str = None, see_also: str = None, notes: str = None, references: str = None, examples: str = None, enums: List[multidoc.parsing.models.Enum] = None, classes: List[multidoc.parsing.models.Class] = None, functions: List[multidoc.parsing.models.Function] = None, constants: List[multidoc.parsing.models.Constant] = None, modules: List[str] = None)

Module docstring pydantic.BaseModel data structure.

config

Type

Optional[Config]

summary

Type

Optional[str]

extended_summary

Type

Optional[str]

routine_listings

Type

Optional[str]

see_also

Type

Optional[str]

notes

Type

Optional[str]

references

Type

Optional[str]

examples

Type

Optional[str]

classes

Type

Optional[List[Class]]

functions

Type

Optional[List[Function]]

constants

Type

Optional[List[Constant]]

modules

Type

Optional[List[str]]

class multidoc.parsing.Parameter(*, name: str, type: str = None, description: str = None)

Parameter docstring pydantic.BaseModel data structure.

name

Type

str

type

Type

Optional[str]

description

Type

Optional[str]

Examples

Used in Function parameters.

functions:
 - name: foo_function
   parameters:
    - name: bar_parameter
      type: Any
      description: "The bar parameter"

Used in Class method parameters.

classes:
 - name: FooClass
   methods:
    - name: bar_method
      parameters:
       - name: bar_parameter
         type: Any
         description: "The bar parameter"

class multidoc.parsing.Returns(*, name: str = None, type: str = None, description: str = None)

Returns docstring pydantic.BaseModel data structure.

name

Type

Optional[str]

type

Type

Optional[str]

description

Type

str

multidoc.parsing.parse_api_declaration(path: str, parent=None, **kwargs)

Parameters

• path –

• local –

• parent –

multidoc.parsing.yaml2dict(path, include_name_error=False, **kwargs)

Yaml file parser.

Parameters

• path (os.PathLike or str) – Path of the yaml file to be loaded.

• _locals (dict[str, Any]) – List of definitions to parse in the yaml files. See examples for how they affect yaml loading.

• include_name_error (bool, default=True) – Include tag evaluations that return a NameError

Examples

Given the following example yaml file:

example.yaml

package:
  name: name-cpp    # [cpp]
  name: name-py     # [py]

modules:
  - module
  - module-py       # [py]
  - module-cpp      # [cpp]
  - module-not-cpp  # [not cpp]
  - module-not-py   # [not py]
  - module-both     # [py or cpp]
  - module-both     # [py and cpp]

>>> yaml2dict("../tests/example.yaml")
{'package': None, 'modules': ['module']}

>>> yaml2dict("../tests/example.yaml", cpp=True)
{'package': {'name': 'name-cpp'}, 'modules': ['module', 'module-cpp']}

>>> yaml2dict("../tests/example.yaml", py=True)
{'package': {'name': 'name-py'}, 'modules': ['module', 'module-py']}

>>> yaml2dict("../tests/example.yaml", cpp=True, py=False)
{'package': {'name': 'name-cpp'}, 'modules': ['module', 'module-cpp', 'module-not-py']}

Returns

yaml loaded into memory as Python dict, parsed for definitions.

Return type

dict