# docstring-extractor
This library allows parsing docstrings of an entire Python file. It uses [ast](https://docs.python.org/3/library/ast.html) and [docstring-parser](https://github.com/rr-/docstring_parser).
The main difference between this library and docstring-parser is that this one is able to parse entire Python files.
## Installation:
`pip install docstring-extractor`
## Usage
```python
>>> from canonicalwebteam.docstring_extractor import get_docstrings
>>>
>>> with open("example.py") as file:
... docstrings = get_docstrings(file)
```
Imaging you have the following Python code:
```python
"""
Example module.
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua.
"""
def test_function():
"""
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim
veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea
commodo consequat. Duis aute irure dolor in reprehenderit in voluptate
velit esse cillum dolore eu fugiat nulla pariatur.
Parameters:
a (int): A decimal integer
b (int): Another decimal integer
Returns:
str: A string containing "foo"
"""
return "foo"
```
The output of the `get_docstrings` function will be the following dict object:
```python
{'type': 'Module',
'name': 'example',
'line': 0,
'docstring': <docstring_parser.common.Docstring at 0x7f06adee7a00>,
'docstring_text': 'Example module.\n\nLorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod\ntempor incididunt ut labore et dolore magna aliqua.',
'content': [
{'type': 'Function',
'name': 'test_function',
'line': 9,
'docstring': <docstring_parser.common.Docstring at 0x7f06adef7490>,
'docstring_text': 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod\ntempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim\nveniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea\ncommodo consequat. Duis aute irure dolor in reprehenderit in voluptate\nvelit esse cillum dolore eu fugiat nulla pariatur.\n\nParameters:\n a (int): A decimal integer\n b (int): Another decimal integer\n\nReturns:\n str: A string containing "foo"',
'content': []
}
]
}
```
You can see the different properties of the Docstring object [here](https://github.com/rr-/docstring_parser/blob/master/docstring_parser/common.py), as an example if you are interested in obtaining the return type and return description of the first function:
```python
>>> docstrings["content"][0]["docstring"].returns.type_name
'str'
>>> docstrings["content"][0]["docstring"].returns.description
'A string containing "foo"'
```
Raw data
{
"_id": null,
"home_page": "https://github.com/canonical-web-and-design/canonicalwebteam.docstring-extractor",
"name": "canonicalwebteam-docstring-extractor",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "docstring,docstrings,parser",
"author": "Canonical Web Team",
"author_email": "webteam@canonical.com",
"download_url": "https://files.pythonhosted.org/packages/dc/b1/9fb6c2a0ced9ac7338ed5d8a2187b6e4f57ec66b4d65385028e6785ea3ef/canonicalwebteam_docstring_extractor-1.1.2.tar.gz",
"platform": null,
"description": "# docstring-extractor\n\nThis library allows parsing docstrings of an entire Python file. It uses [ast](https://docs.python.org/3/library/ast.html) and [docstring-parser](https://github.com/rr-/docstring_parser).\n\nThe main difference between this library and docstring-parser is that this one is able to parse entire Python files.\n\n## Installation:\n`pip install docstring-extractor`\n\n## Usage\n\n```python\n>>> from canonicalwebteam.docstring_extractor import get_docstrings\n>>>\n>>> with open(\"example.py\") as file:\n... docstrings = get_docstrings(file)\n```\n\nImaging you have the following Python code:\n```python\n\"\"\"\nExample module.\n\nLorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod\ntempor incididunt ut labore et dolore magna aliqua.\n\"\"\"\n\n\ndef test_function():\n \"\"\"\n Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod\n tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim\n veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea\n commodo consequat. Duis aute irure dolor in reprehenderit in voluptate\n velit esse cillum dolore eu fugiat nulla pariatur.\n\n Parameters:\n a (int): A decimal integer\n b (int): Another decimal integer\n\n Returns:\n str: A string containing \"foo\"\n \"\"\"\n return \"foo\"\n```\n\nThe output of the `get_docstrings` function will be the following dict object:\n\n```python\n{'type': 'Module',\n 'name': 'example',\n 'line': 0,\n 'docstring': <docstring_parser.common.Docstring at 0x7f06adee7a00>,\n 'docstring_text': 'Example module.\\n\\nLorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod\\ntempor incididunt ut labore et dolore magna aliqua.',\n 'content': [\n {'type': 'Function',\n 'name': 'test_function',\n 'line': 9,\n 'docstring': <docstring_parser.common.Docstring at 0x7f06adef7490>,\n 'docstring_text': 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod\\ntempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim\\nveniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea\\ncommodo consequat. Duis aute irure dolor in reprehenderit in voluptate\\nvelit esse cillum dolore eu fugiat nulla pariatur.\\n\\nParameters:\\n a (int): A decimal integer\\n b (int): Another decimal integer\\n\\nReturns:\\n str: A string containing \"foo\"',\n 'content': []\n }\n ]\n}\n```\n\nYou can see the different properties of the Docstring object [here](https://github.com/rr-/docstring_parser/blob/master/docstring_parser/common.py), as an example if you are interested in obtaining the return type and return description of the first function:\n\n```python\n>>> docstrings[\"content\"][0][\"docstring\"].returns.type_name\n'str'\n>>> docstrings[\"content\"][0][\"docstring\"].returns.description\n'A string containing \"foo\"'\n```\n\n",
"bugtrack_url": null,
"license": "GPL-3.0-or-later",
"summary": "Get Python docstrings from files",
"version": "1.1.2",
"split_keywords": [
"docstring",
"docstrings",
"parser"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e1b44383f62fff6074df5c0b2b1d320bfaa5f923fcd223789bbe71116b6f81cd",
"md5": "e39aacfecd771413d200f4201da08528",
"sha256": "ec2c5bb200183abc71203995016604f477e2a15f6e2614f12d4b8997e13efa95"
},
"downloads": -1,
"filename": "canonicalwebteam_docstring_extractor-1.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e39aacfecd771413d200f4201da08528",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 16438,
"upload_time": "2023-01-04T15:57:36",
"upload_time_iso_8601": "2023-01-04T15:57:36.472109Z",
"url": "https://files.pythonhosted.org/packages/e1/b4/4383f62fff6074df5c0b2b1d320bfaa5f923fcd223789bbe71116b6f81cd/canonicalwebteam_docstring_extractor-1.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "dcb19fb6c2a0ced9ac7338ed5d8a2187b6e4f57ec66b4d65385028e6785ea3ef",
"md5": "1d4e802e100192a8de2177c894717911",
"sha256": "04f385da4c131e6a62f794fabacf9223d6d7965f51d5fe5e2d4b3e712a37e513"
},
"downloads": -1,
"filename": "canonicalwebteam_docstring_extractor-1.1.2.tar.gz",
"has_sig": false,
"md5_digest": "1d4e802e100192a8de2177c894717911",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 16148,
"upload_time": "2023-01-04T15:57:37",
"upload_time_iso_8601": "2023-01-04T15:57:37.485992Z",
"url": "https://files.pythonhosted.org/packages/dc/b1/9fb6c2a0ced9ac7338ed5d8a2187b6e4f57ec66b4d65385028e6785ea3ef/canonicalwebteam_docstring_extractor-1.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-04 15:57:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "canonical-web-and-design",
"github_project": "canonicalwebteam.docstring-extractor",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "canonicalwebteam-docstring-extractor"
}
JSON
