| Name | pardoc JSON |
| Version |
0.1.1
JSON |
| download |
| home_page | https://github.com/pwwang/pardoc |
| Summary | Yet another docstring parser for python |
| upload_time | 2023-06-27 01:26:33 |
| maintainer | |
| docs_url | None |
| author | pwwang |
| requires_python | >=3.7,<4.0 |
| license | MIT |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# pardoc
[![pypi][3]][4] [![tag][5]][6] ![pyver][12] [![build][7]][8] [![codacy quality][9]][10] [![codacy quality][11]][10]
Yet another docstring parser for python, using [`lark-parser`][1]
## Installation
```python
pip install pardoc
```
## A quick look
```python console
>>> from pardoc import google_parser, pretty
>>> docstring = """This is an example of a module level function.
Function parameters should be documented in the ``Args`` section. The name
of each parameter is required. The type and description of each parameter
is optional, but should be included if not obvious.
If \*args or \*\*kwargs are accepted,
they should be listed as ``*args`` and ``**kwargs``.
The format for a parameter is::
name (type): description
The description may span multiple lines. Following
lines should be indented. The "(type)" is optional.
Multiple paragraphs are supported in parameter
descriptions.
Args:
param1 (int): The first parameter.
param2 (:obj:`str`, optional): The second parameter. Defaults to None.
Second line of description should be indented.
*args: Variable length argument list.
**kwargs: Arbitrary keyword arguments.
Returns:
bool: True if successful, False otherwise.
The return type is optional and may be specified at the beginning of
the ``Returns`` section followed by a colon.
The ``Returns`` section may span multiple lines and paragraphs.
Following lines should be indented to match the first line.
The ``Returns`` section supports any reStructuredText formatting,
including literal blocks::
{
'param1': param1,
'param2': param2
}
Raises:
AttributeError: The ``Raises`` section is a list of all exceptions
that are relevant to the interface.
ValueError: If `param2` is equal to `param1`.
"""
>>> parsed = google_parser.parse(docstring)
>>> pretty(parsed, print_=True)
ParsedSection(title=SUMMARY)
ParsedPara(lines=1)
This is an example of a module level function.
ParsedPara(lines=3)
Function parameters should be documented in the ``Args`` section. The name
of each parameter is required. The type and description of each parameter
is optional, but should be included if not obvious.
ParsedPara(lines=2)
If \*args or \*\*kwargs are accepted,
they should be listed as ``*args`` and ``**kwargs``.
ParsedPara(lines=1)
The format for a parameter is::
ParsedPara(lines=2)
ParsedPara(lines=1)
name (type): description
ParsedPara(lines=2)
ParsedPara(lines=2)
The description may span multiple lines. Following
lines should be indented. The "(type)" is optional.
ParsedPara(lines=2)
Multiple paragraphs are supported in parameter
descriptions.
ParsedSection(title=Args)
ParsedItem(name=param1, type=int, desc=The first parameter.)
ParsedItem(name=param2, type=:obj:`str`, optional, desc=The second parameter. Defaults to None.)
ParsedPara(lines=1)
Second line of description should be indented.
ParsedItem(name=*args, type=None, desc=Variable length argument list.)
ParsedItem(name=**kwargs, type=None, desc=Arbitrary keyword arguments.)
ParsedSection(title=Returns)
ParsedItem(name=bool, type=None, desc=True if successful, False otherwise.)
ParsedPara(lines=2)
The return type is optional and may be specified at the beginning of
the ``Returns`` section followed by a colon.
ParsedPara(lines=2)
The ``Returns`` section may span multiple lines and paragraphs.
Following lines should be indented to match the first line.
ParsedPara(lines=2)
The ``Returns`` section supports any reStructuredText formatting,
including literal blocks::
ParsedPara(lines=2)
ParsedPara(lines=1)
{
ParsedPara(lines=1)
ParsedPara(lines=2)
'param1': param1,
'param2': param2
ParsedPara(lines=1)
ParsedPara(lines=1)
}
ParsedSection(title=Raises)
ParsedItem(name=AttributeError, type=None, desc=The ``Raises`` section is a list of all exceptions)
ParsedPara(lines=1)
that are relevant to the interface.
ParsedItem(name=ValueError, type=None, desc=If `param2` is equal to `param1`.)
```
## Usage
### Parsing a known style docstring
```python
from pardoc import google_parser, numpy_parser
parsed = google_parser(docstring)
# or
parsed = numpy_parser(docstring)
```
### Parsing an unknown style docstring
```python
from pardoc import auto_parser
parser = auto_parser(docstring)
# parsing results from auto_parser is cached and reused.
parsed = parser.parse(docstring)
```
### Parsed object
There are 6 types of parsed objects, include the final `Parsed` object that
attaches all sections
The first 5 are all `namedtuple`s:
```python
ParsedItem = namedtuple('ParsedItem',
['name', 'type', 'desc', 'more'])
ParsedTodo = namedtuple('ParsedTodo', ['todo', 'more'])
ParsedSection = namedtuple('ParsedSection', ['title', 'section'])
ParsedPara = namedtuple('ParsedPara', ['lines'])
ParsedCode = namedtuple('ParsedCode', ['lang', 'codes'])
```
The `Parsed` is an ordered dictionary (`OrderedDiot`) from [`diot`][2], which
allows dot access to keys:
```python
from diot import OrderedDiot
class Parsed(OrderedDiot):
"""Parsed object"""
```
### Formatting a parsed object to the original style
```python console
>>> from pardoc import google_parser
>>> docstring = """Example function with types documented in the docstring.
Args:
param0: No type
param1 (int): The first parameter.
param2 (str): The second parameter.
Returns:
bool: The return value. True for success, False otherwise.
"""
>>> # note the arbitrary empty lines
>>> reformatted = google_parser.format(docstring)
>>> # or
>>> reformatted = google_parser.format(google_parser.parse(docstring))
>>> print(reformatted)
Example function with types documented in the docstring.
Args:
param0: No type
param1 (int): The first parameter.
param2 (str): The second parameter.
Returns:
bool: The return value. True for success, False otherwise.
```
### Pretty printing the parsed objects
See `A quick look`
[1]: https://github.com/lark-parser/lark
[2]: https://github.com/pwwang/diot
[3]: https://img.shields.io/pypi/v/pardoc?style=flat-square
[4]: https://pypi.org/project/pardoc/
[5]: https://img.shields.io/github/tag/pwwang/pardoc?style=flat-square
[6]: https://github.com/pwwang/pardoc
[7]: https://img.shields.io/github/workflow/status/pwwang/pardoc/Build%20and%20Deploy?style=flat-square
[8]: https://github.com/pwwang/pardoc
[9]: https://img.shields.io/codacy/grade/a1ba6573a5fa4fc589ce3cf7daa5ddea?style=flat-square
[10]: https://app.codacy.com/project/pwwang/pardoc/dashboard
[11]: https://img.shields.io/codacy/coverage/a1ba6573a5fa4fc589ce3cf7daa5ddea?style=flat-square
[12]: https://img.shields.io/pypi/pyversions/pardoc?style=flat-square
Raw data
{
"_id": null,
"home_page": "https://github.com/pwwang/pardoc",
"name": "pardoc",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7,<4.0",
"maintainer_email": "",
"keywords": "",
"author": "pwwang",
"author_email": "pwwang@pwwang.com",
"download_url": "https://files.pythonhosted.org/packages/19/24/7a18a515e5a23a6c8e47c4991ffa8c0d837ee001b73c87db9ccd752cf5d9/pardoc-0.1.1.tar.gz",
"platform": null,
"description": "# pardoc\n\n[![pypi][3]][4] [![tag][5]][6] ![pyver][12] [![build][7]][8] [![codacy quality][9]][10] [![codacy quality][11]][10]\n\nYet another docstring parser for python, using [`lark-parser`][1]\n\n## Installation\n\n```python\npip install pardoc\n```\n\n## A quick look\n\n```python console\n>>> from pardoc import google_parser, pretty\n\n>>> docstring = \"\"\"This is an example of a module level function.\n\nFunction parameters should be documented in the ``Args`` section. The name\nof each parameter is required. The type and description of each parameter\nis optional, but should be included if not obvious.\n\nIf \\*args or \\*\\*kwargs are accepted,\nthey should be listed as ``*args`` and ``**kwargs``.\n\nThe format for a parameter is::\n\n name (type): description\n The description may span multiple lines. Following\n lines should be indented. The \"(type)\" is optional.\n\n Multiple paragraphs are supported in parameter\n descriptions.\n\nArgs:\n param1 (int): The first parameter.\n param2 (:obj:`str`, optional): The second parameter. Defaults to None.\n Second line of description should be indented.\n *args: Variable length argument list.\n **kwargs: Arbitrary keyword arguments.\n\nReturns:\n bool: True if successful, False otherwise.\n\n The return type is optional and may be specified at the beginning of\n the ``Returns`` section followed by a colon.\n\n The ``Returns`` section may span multiple lines and paragraphs.\n Following lines should be indented to match the first line.\n\n The ``Returns`` section supports any reStructuredText formatting,\n including literal blocks::\n\n {\n 'param1': param1,\n 'param2': param2\n }\n\nRaises:\n AttributeError: The ``Raises`` section is a list of all exceptions\n that are relevant to the interface.\n ValueError: If `param2` is equal to `param1`.\n\n\"\"\"\n\n>>> parsed = google_parser.parse(docstring)\n>>> pretty(parsed, print_=True)\n\nParsedSection(title=SUMMARY)\n ParsedPara(lines=1)\n This is an example of a module level function.\n ParsedPara(lines=3)\n Function parameters should be documented in the ``Args`` section. The name\n of each parameter is required. The type and description of each parameter\n is optional, but should be included if not obvious.\n ParsedPara(lines=2)\n If \\*args or \\*\\*kwargs are accepted,\n they should be listed as ``*args`` and ``**kwargs``.\n ParsedPara(lines=1)\n The format for a parameter is::\n ParsedPara(lines=2)\n ParsedPara(lines=1)\n name (type): description\n ParsedPara(lines=2)\n ParsedPara(lines=2)\n The description may span multiple lines. Following\n lines should be indented. The \"(type)\" is optional.\n ParsedPara(lines=2)\n Multiple paragraphs are supported in parameter\n descriptions.\n\nParsedSection(title=Args)\n ParsedItem(name=param1, type=int, desc=The first parameter.)\n ParsedItem(name=param2, type=:obj:`str`, optional, desc=The second parameter. Defaults to None.)\n ParsedPara(lines=1)\n Second line of description should be indented.\n ParsedItem(name=*args, type=None, desc=Variable length argument list.)\n ParsedItem(name=**kwargs, type=None, desc=Arbitrary keyword arguments.)\n\nParsedSection(title=Returns)\n ParsedItem(name=bool, type=None, desc=True if successful, False otherwise.)\n ParsedPara(lines=2)\n The return type is optional and may be specified at the beginning of\n the ``Returns`` section followed by a colon.\n ParsedPara(lines=2)\n The ``Returns`` section may span multiple lines and paragraphs.\n Following lines should be indented to match the first line.\n ParsedPara(lines=2)\n The ``Returns`` section supports any reStructuredText formatting,\n including literal blocks::\n ParsedPara(lines=2)\n ParsedPara(lines=1)\n {\n ParsedPara(lines=1)\n ParsedPara(lines=2)\n 'param1': param1,\n 'param2': param2\n ParsedPara(lines=1)\n ParsedPara(lines=1)\n }\n\nParsedSection(title=Raises)\n ParsedItem(name=AttributeError, type=None, desc=The ``Raises`` section is a list of all exceptions)\n ParsedPara(lines=1)\n that are relevant to the interface.\n ParsedItem(name=ValueError, type=None, desc=If `param2` is equal to `param1`.)\n\n```\n\n## Usage\n\n### Parsing a known style docstring\n\n```python\nfrom pardoc import google_parser, numpy_parser\nparsed = google_parser(docstring)\n# or\nparsed = numpy_parser(docstring)\n```\n\n### Parsing an unknown style docstring\n\n```python\nfrom pardoc import auto_parser\n\nparser = auto_parser(docstring)\n# parsing results from auto_parser is cached and reused.\nparsed = parser.parse(docstring)\n```\n\n### Parsed object\n\nThere are 6 types of parsed objects, include the final `Parsed` object that\nattaches all sections\n\nThe first 5 are all `namedtuple`s:\n\n```python\nParsedItem = namedtuple('ParsedItem',\n ['name', 'type', 'desc', 'more'])\nParsedTodo = namedtuple('ParsedTodo', ['todo', 'more'])\nParsedSection = namedtuple('ParsedSection', ['title', 'section'])\nParsedPara = namedtuple('ParsedPara', ['lines'])\nParsedCode = namedtuple('ParsedCode', ['lang', 'codes'])\n\n```\n\nThe `Parsed` is an ordered dictionary (`OrderedDiot`) from [`diot`][2], which\nallows dot access to keys:\n\n```python\nfrom diot import OrderedDiot\n\nclass Parsed(OrderedDiot):\n \"\"\"Parsed object\"\"\"\n```\n\n### Formatting a parsed object to the original style\n\n```python console\n>>> from pardoc import google_parser\n>>> docstring = \"\"\"Example function with types documented in the docstring.\n\n\nArgs:\n\n\n param0: No type\n\n param1 (int): The first parameter.\n param2 (str): The second parameter.\n\nReturns:\n\n\n bool: The return value. True for success, False otherwise.\n\n\"\"\"\n>>> # note the arbitrary empty lines\n>>> reformatted = google_parser.format(docstring)\n>>> # or\n>>> reformatted = google_parser.format(google_parser.parse(docstring))\n>>> print(reformatted)\nExample function with types documented in the docstring.\n\nArgs:\n param0: No type\n param1 (int): The first parameter.\n param2 (str): The second parameter.\n\nReturns:\n bool: The return value. True for success, False otherwise.\n```\n\n### Pretty printing the parsed objects\n\nSee `A quick look`\n\n[1]: https://github.com/lark-parser/lark\n[2]: https://github.com/pwwang/diot\n[3]: https://img.shields.io/pypi/v/pardoc?style=flat-square\n[4]: https://pypi.org/project/pardoc/\n[5]: https://img.shields.io/github/tag/pwwang/pardoc?style=flat-square\n[6]: https://github.com/pwwang/pardoc\n[7]: https://img.shields.io/github/workflow/status/pwwang/pardoc/Build%20and%20Deploy?style=flat-square\n[8]: https://github.com/pwwang/pardoc\n[9]: https://img.shields.io/codacy/grade/a1ba6573a5fa4fc589ce3cf7daa5ddea?style=flat-square\n[10]: https://app.codacy.com/project/pwwang/pardoc/dashboard\n[11]: https://img.shields.io/codacy/coverage/a1ba6573a5fa4fc589ce3cf7daa5ddea?style=flat-square\n[12]: https://img.shields.io/pypi/pyversions/pardoc?style=flat-square\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Yet another docstring parser for python",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/pwwang/pardoc",
"Repository": "https://github.com/pwwang/pardoc"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6c208b9319d79cbc2b1e95d74baf81864a502b175d9ce3add10da1d32c0a06e8",
"md5": "e36c05cd7645b4f241c037edef4bbbca",
"sha256": "4e6314e4768c031996e4ebf75fe5e80f38605721bd0248a63929254391ce39be"
},
"downloads": -1,
"filename": "pardoc-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e36c05cd7645b4f241c037edef4bbbca",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7,<4.0",
"size": 13724,
"upload_time": "2023-06-27T01:26:32",
"upload_time_iso_8601": "2023-06-27T01:26:32.604615Z",
"url": "https://files.pythonhosted.org/packages/6c/20/8b9319d79cbc2b1e95d74baf81864a502b175d9ce3add10da1d32c0a06e8/pardoc-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "19247a18a515e5a23a6c8e47c4991ffa8c0d837ee001b73c87db9ccd752cf5d9",
"md5": "438eb14f459b6d0acb851236d65ccbe2",
"sha256": "6cab869cca2500e665b5e97eb3d49135099932aea9bedef3a7eb7f6f6adbee50"
},
"downloads": -1,
"filename": "pardoc-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "438eb14f459b6d0acb851236d65ccbe2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7,<4.0",
"size": 11040,
"upload_time": "2023-06-27T01:26:33",
"upload_time_iso_8601": "2023-06-27T01:26:33.724267Z",
"url": "https://files.pythonhosted.org/packages/19/24/7a18a515e5a23a6c8e47c4991ffa8c0d837ee001b73c87db9ccd752cf5d9/pardoc-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-27 01:26:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pwwang",
"github_project": "pardoc",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "pardoc"
}
