A Python API compiler for universal Markdown syntax.
Project description
apimd
A Python API compiler for universal Markdown syntax.
Required Python 3.9 and above. (for ast.unparse
function)
This parser using ast
standard library to extract the type annotations (without inference) and docstrings, similar to MyPy.
The target modules must be from at least Python 3.0, which is the lowest version with ast
support.
Install
Install by pip:
pip install apimd
From Git repository:
pip install .
Command Line Interface
Following syntax are allowed:
apimd module_name
apimd Module-Name=module_name
apimd "Module Name=module_name"
The first is the readable name of the package, and the second is the name used in import syntax.
The output path can be chosen by "-d" or "--dir" option, default is docs
.
Multiple modules are supported either.
apimd module1 module2 -d out_path
If you just want to show output, use dry run mode.
apimd module --dry
Rules
Basically, this compiler can extract docstrings from those "public" names:
- Modules
- Functions & Generators (support async version)
- Classes and its methods
According to PEP 8, "public" means a name can't start with underscore symbol "_
",
except magic methods. (Naming Conventions)
Normal objects are no docstring their owned.
Please pack them into functions or classes such as Enum
,
or mention them in the docstring of root module __init__.py
.
The type inference for global names is not yet supported.
A package should list the objects __all__
to prevent other public style names.
In this parser, wildcard import syntax (from ... import *
) will be ignored,
which will cause the name from the statement will lose its parent module.
If there has any import statements in the package root __init__.py
, the API can be substituted into a short name, for example, change a.b.c
to a.c
.
(Global Variable Names)
Object attributes should be noted in the stub files or use Variable Annotations. (PEP 526)
Stubs
If a module has a stub file (.pyi
), the stub file will be loaded for annotations once again.
Docstrings should still be written in the module first.
For extensions (.so
, .pyd
or .dylib
with Python version suffix), this tool will try to load the docstrings from module
if .py
file is not found.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.