apimd API

Table of contents:

apimd
- apimd.gen_api
apimd.__main__
- apimd.__main__.main
apimd.loader
- apimd.loader.loader
- apimd.loader.walk_packages
apimd.parser
apimd.pep585

Module `apimd`

A Python API compiler for universal Markdown syntax.

gen_api()

Full name: apimd.gen_api

root_names	pwd	*	prefix	link	level	toc	dry	return
`dict[str, str]`	`str \| None`		`str`	`bool`	`int`	`bool`	`bool`	`collections.abc.Sequence[str]`
	`None`		`'docs'`	`True`	`1`	`False`	`False`

Generate API. All rules are listed in the readme.

The path pwd is the current path that provided to pkgutil, which allows the "site-packages" directory to be used.

Module `apimd.main`

The command line launcher of apimd.

main()

Full name: apimd.__main__.main

return
`None`

Main function.

Module `apimd.loader`

Constants	Type
`PEP561_SUFFIX`	`str`

Compiler functions.

loader()

Full name: apimd.loader.loader

root	pwd	link	level	toc	return
`str`	`str`	`bool`	`int`	`bool`	`str`

Package searching algorithm.

walk_packages()

Full name: apimd.loader.walk_packages

name	path	return
`str`	`str`	`collections.abc.Iterator[tuple[str, str]]`

Walk packages without import them.

Module `apimd.parser`

Constants	Type
`ANY`	`str`

Data structures.

code()

Full name: apimd.parser.code

doc	return
`str`	`str`

Escape Markdown charters from inline code.

const_type()

Full name: apimd.parser.const_type

node	return
`ast.expr`	`str`

Constant type inference.

doctest()

Full name: apimd.parser.doctest

doc	return
`str`	`str`

Wrap doctest as markdown Python code.

esc_underscore()

Full name: apimd.parser.esc_underscore

doc	return
`str`	`str`

Escape underscore in names.

is_magic()

Full name: apimd.parser.is_magic

name	return
`str`	`bool`

Check magic name.

is_public_family()

Full name: apimd.parser.is_public_family

name	return
`str`	`bool`

Check the name is come from public modules or not.

parent()

Full name: apimd.parser.parent

name	*	level	return
`str`		`int`	`str`
		`1`

Get parent name with level.

class Parser

Full name: apimd.parser.Parser

Decorators
`@dataclasses.dataclass`

Members	Type
`alias`	`dict[str, str]`
`b_level`	`int`
`const`	`dict[str, str]`
`doc`	`dict[str, str]`
`docstring`	`dict[str, str]`
`imp`	`dict[str, set[str]]`
`level`	`dict[str, int]`
`link`	`bool`
`root`	`dict[str, str]`
`toc`	`bool`

AST parser.

Usage:

>>> p = Parser()
>>> with open("pkg_path", 'r') as f:
>>>     p.parse('pkg_name', f.read())
>>> s = p.compile()

Or create with parameters:

>>> p = Parser.new(link=True, level=1)

Parser.api()

Full name: apimd.parser.Parser.api

self	root	node	*	prefix	return
`Self`	`str`	`ast.FunctionDef \| ast.AsyncFunctionDef \| ast.ClassDef`		`str`	`None`
				`''`

Create API doc for only functions and classes. Where name is the full name.

Parser.class_api()

Full name: apimd.parser.Parser.class_api

self	root	name	bases	body	return
`Self`	`str`	`str`	`list[ast.expr]`	`list[ast.stmt]`	`None`

Create class API.

Parser.compile()

Full name: apimd.parser.Parser.compile

self	return
`Self`	`str`

Compile documentation.

Parser.func_ann()

Full name: apimd.parser.Parser.func_ann

self	root	args	*	has_self	cls_method	return
`Self`	`str`	`collections.abc.Sequence[ast.arg]`		`bool`	`bool`	`collections.abc.Iterator[str]`

Function annotation table.

Parser.func_api()

Full name: apimd.parser.Parser.func_api

self	root	name	node	returns	*	has_self	cls_method	return
`Self`	`str`	`str`	`ast.arguments`	`ast.expr \| None`		`bool`	`bool`	`None`

Create function API.

Parser.globals()

Full name: apimd.parser.Parser.globals

self	root	node	return
`Self`	`str`	`ast.Assign \| ast.AnnAssign`	`None`

Set up globals:

Type alias
Constants
__all__ filter

Parser.imports()

Full name: apimd.parser.Parser.imports

self	root	node	return
`Self`	`str`	`ast.Import \| ast.ImportFrom`	`None`

Save import names.

Parser.is_public()

Full name: apimd.parser.Parser.is_public

self	s	return
`Self`	`str`	`bool`

Check the name is public style or listed in __all__.

Parser.load_docstring()

Full name: apimd.parser.Parser.load_docstring

self	root	m	return
`Self`	`str`	`types.ModuleType`	`None`

Load docstring from the module.

Parser.new()

Full name: apimd.parser.Parser.new

Decorators
`@classmethod`

cls	link	level	toc	return
`type[Self]`	`bool`	`int`	`bool`	`Self`

Create a parser by options.

Parser.parse()

Full name: apimd.parser.Parser.parse

self	root	script	return
`Self`	`str`	`str`	`None`

Main parser of the entire module.

Parser.resolve()

Full name: apimd.parser.Parser.resolve

self	root	node	self_ty	return
`Self`	`str`	`ast.expr`	`str`	`str`
			`''`

Search and resolve global names in annotation.

class Resolver

Full name: apimd.parser.Resolver

Bases
`ast.NodeTransformer`

Annotation resolver.

Resolver.init()

Full name: apimd.parser.Resolver.__init__

self	root	alias	self_ty	return
`Self`	`str`	`dict[str, str]`	`str`	`Any`
			`''`

Set root module, alias and generic self name.

Resolver.visit_Attribute()

Full name: apimd.parser.Resolver.visit_Attribute

self	node	return
`Self`	`ast.Attribute`	`ast.AST`

Remove typing.* prefix of annotation.

Resolver.visit_Constant()

Full name: apimd.parser.Resolver.visit_Constant

self	node	return
`Self`	`ast.Constant`	`ast.AST`

Check string is a name.

Resolver.visit_Name()

Full name: apimd.parser.Resolver.visit_Name

self	node	return
`Self`	`ast.Name`	`ast.AST`

Replace global names with its expression recursively.

Resolver.visit_Subscript()

Full name: apimd.parser.Resolver.visit_Subscript

self	node	return
`Self`	`ast.Subscript`	`ast.AST`

Implementation of PEP585 and PEP604.

table()

Full name: apimd.parser.table

*titles	items	return
`str`	`collections.abc.Iterable[str \| Iterable[str]]`	`str`

Create multi-column table with the titles.