# inherit-docstring
[](https://github.com/rcmdnk/inherit-docstring/actions/workflows/test.yml)
[](https://github.com/rcmdnk/inherit-docstring/tree/coverage)
A python decorator to inherit docstring.
Easily inherit docstrings from parent classes with `@inherit_docstring` decorator, designed specifically for [the NumPy docstring style](https://numpydoc.readthedocs.io/en/latest/format.html).
Use inherit-docstring to streamline your documentation process, ensuring consistency and reducing redundancy!
## Features
- Automatic Inheritance: Just add the `@inherit_docstring` decorator, and the child class will seamlessly inherit the parent's class and function docstrings.
- Structured Sections: Docstrings are broken into sections like `Attributes`, `Notes`, etc. Each section is denoted by its title followed by `---`.
- Header Section: An exclusive `Header` section is introduced for the starting portion of the docstring without a specific title.
- Parameter Sections: Certain sections are treated as parameter sections where the content is interpreted as parameter explanations. They include:
- Attributes
- Parameters
- Returns
- Yields
- Receives
- Raises
- Warns
- Warnings
- Deprecated sections: Sections starting with `.. deprecated:: x.y.z`, is parsed as deprecated sections.
## Behavior
- If a child class function lacks a docstring, it inherits the parent's docstring verbatim.
- For functions where both parent and child have docstrings:
- Section-wise Merge: Docstrings are combined on a section-by-section basis.
- Parameter-wise Merge: Within parameter sections, docstrings are combined parameter by parameter.
- Child Priority: When both parent and child provide docstrings for the same function or parameter, the child's version is prioritized.
## Requirement
- Python >=3.9
- Poetry (For development)
## Installation
By pip:
```
$ pip3 install inherit-docstring
```
## Usage
Add `inherit_docstring` decorator to the inherited class:
```
from inherit_docstring import inherit_docstring
class Parent:
"""Parent class.
This is an explanation.
Attributes
----------
name: str
The name of
the parent.
age:
The age. w/o type.
Notes
-----
This is parent's note.
"""
name: str = 'parent'
age: int = 40
def func1(self, param1: int, param2: int) -> int:
"""Parent's func1.
Parameters
----------
param1: int
First input.
param2: int
Second input.
Returns
-------
ret: int
param1 + param2
"""
return param1 + param2
def func2(self) -> None:
"""Parent's func2.
Returns
-------
ret: str
something
"""
return 'Something'
@inherit_docstring
class Child(Parent):
"""Child class.
Attributes
----------
sex: str
Additional attributes.
girl or boy.
"""
sex: str = "boy"
def func1(self, param1: int, param2: int) -> int:
"""Child's func1.
Returns
-------
ret: int
param1 - param2
"""
return param1 - param2
```
Child class' help will be:
```
class Child(Parent)
| Child class.
|
| Attributes
| ----------
| name: str
| The name of
| the parent.
| age:
| The age. w/o type.
| sex: str
| Additional attributes.
| girl or boy.
|
| Notes
| -----
| This is parent's note.
|
| Method resolution order:
| Child
| Parent
| builtins.object
|
| Methods defined here:
|
| func1(self, param1: int, param2: int) -> int
| Child's func1.
|
| Parameters
| ----------
| param1: int
| First input.
| param2: int
| Second input.
|
| Returns
| -------
| ret: int
| param1 - param2
```
Raw data
{
"_id": null,
"home_page": "https://github.com/rcmdnk/inherit-docstring",
"name": "inherit-docstring",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "docstring, inherit, decorator",
"author": "rcmdnk",
"author_email": "rcmdnk@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/83/f8/2110b342dc41fb6169b952b9673704cf41735c71a0947690dbb9844917f9/inherit_docstring-0.1.4.tar.gz",
"platform": null,
"description": "# inherit-docstring\n\n[](https://github.com/rcmdnk/inherit-docstring/actions/workflows/test.yml)\n[](https://github.com/rcmdnk/inherit-docstring/tree/coverage)\n\nA python decorator to inherit docstring.\n\nEasily inherit docstrings from parent classes with `@inherit_docstring` decorator, designed specifically for [the NumPy docstring style](https://numpydoc.readthedocs.io/en/latest/format.html).\n\nUse inherit-docstring to streamline your documentation process, ensuring consistency and reducing redundancy!\n\n## Features\n\n- Automatic Inheritance: Just add the `@inherit_docstring` decorator, and the child class will seamlessly inherit the parent's class and function docstrings.\n- Structured Sections: Docstrings are broken into sections like `Attributes`, `Notes`, etc. Each section is denoted by its title followed by `---`.\n- Header Section: An exclusive `Header` section is introduced for the starting portion of the docstring without a specific title.\n- Parameter Sections: Certain sections are treated as parameter sections where the content is interpreted as parameter explanations. They include:\n - Attributes\n - Parameters\n - Returns\n - Yields\n - Receives\n - Raises\n - Warns\n - Warnings\n- Deprecated sections: Sections starting with `.. deprecated:: x.y.z`, is parsed as deprecated sections.\n\n## Behavior\n\n- If a child class function lacks a docstring, it inherits the parent's docstring verbatim.\n- For functions where both parent and child have docstrings:\n - Section-wise Merge: Docstrings are combined on a section-by-section basis.\n - Parameter-wise Merge: Within parameter sections, docstrings are combined parameter by parameter.\n - Child Priority: When both parent and child provide docstrings for the same function or parameter, the child's version is prioritized.\n\n## Requirement\n\n- Python >=3.9\n- Poetry (For development)\n\n## Installation\n\nBy pip:\n\n```\n$ pip3 install inherit-docstring\n```\n\n## Usage\n\nAdd `inherit_docstring` decorator to the inherited class:\n\n```\nfrom inherit_docstring import inherit_docstring\n\nclass Parent:\n \"\"\"Parent class.\n\n This is an explanation.\n\n Attributes\n ----------\n name: str\n The name of\n the parent.\n age:\n The age. w/o type.\n\n Notes\n -----\n This is parent's note.\n \"\"\"\n\n name: str = 'parent'\n age: int = 40\n\n def func1(self, param1: int, param2: int) -> int:\n \"\"\"Parent's func1.\n\n Parameters\n ----------\n param1: int\n First input.\n param2: int\n Second input.\n\n Returns\n -------\n ret: int\n param1 + param2\n \"\"\"\n\n return param1 + param2\n\n def func2(self) -> None:\n \"\"\"Parent's func2.\n\n Returns\n -------\n ret: str\n something\n \"\"\"\n\n return 'Something'\n\n@inherit_docstring\nclass Child(Parent):\n \"\"\"Child class.\n\n Attributes\n ----------\n sex: str\n Additional attributes.\n girl or boy.\n \"\"\"\n\n sex: str = \"boy\"\n\n def func1(self, param1: int, param2: int) -> int:\n \"\"\"Child's func1.\n\n Returns\n -------\n ret: int\n param1 - param2\n \"\"\"\n\n return param1 - param2\n```\n\nChild class' help will be:\n\n```\nclass Child(Parent)\n | Child class.\n |\n | Attributes\n | ----------\n | name: str\n | The name of\n | the parent.\n | age:\n | The age. w/o type.\n | sex: str\n | Additional attributes.\n | girl or boy.\n |\n | Notes\n | -----\n | This is parent's note.\n |\n | Method resolution order:\n | Child\n | Parent\n | builtins.object\n |\n | Methods defined here:\n |\n | func1(self, param1: int, param2: int) -> int\n | Child's func1.\n |\n | Parameters\n | ----------\n | param1: int\n | First input.\n | param2: int\n | Second input.\n |\n | Returns\n | -------\n | ret: int\n | param1 - param2\n```\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "A python decorator to inherit docstring.",
"version": "0.1.4",
"project_urls": {
"Homepage": "https://github.com/rcmdnk/inherit-docstring",
"Repository": "https://github.com/rcmdnk/inherit-docstring"
},
"split_keywords": [
"docstring",
" inherit",
" decorator"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b87f7ff1a8cffc40c9cc8d89660cb91841f903a1e0b2bf03a0bd2a5f6e67ee5f",
"md5": "a7aef27401d350a76355198eb10d2f35",
"sha256": "9e77f7e20e6faf0a924244967abd37380233679d1680e102a2ff1e49fd0c74a1"
},
"downloads": -1,
"filename": "inherit_docstring-0.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a7aef27401d350a76355198eb10d2f35",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 9160,
"upload_time": "2024-05-22T23:53:35",
"upload_time_iso_8601": "2024-05-22T23:53:35.084322Z",
"url": "https://files.pythonhosted.org/packages/b8/7f/7ff1a8cffc40c9cc8d89660cb91841f903a1e0b2bf03a0bd2a5f6e67ee5f/inherit_docstring-0.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "83f82110b342dc41fb6169b952b9673704cf41735c71a0947690dbb9844917f9",
"md5": "479e597f8af34b84c9433dd43755a873",
"sha256": "9fca2f69aa9f140ada0a3b67430163bb0e0d6e6a3f28e1a3bf4c4dba1134aa0c"
},
"downloads": -1,
"filename": "inherit_docstring-0.1.4.tar.gz",
"has_sig": false,
"md5_digest": "479e597f8af34b84c9433dd43755a873",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 8803,
"upload_time": "2024-05-22T23:53:36",
"upload_time_iso_8601": "2024-05-22T23:53:36.420822Z",
"url": "https://files.pythonhosted.org/packages/83/f8/2110b342dc41fb6169b952b9673704cf41735c71a0947690dbb9844917f9/inherit_docstring-0.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-22 23:53:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rcmdnk",
"github_project": "inherit-docstring",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "inherit-docstring"
}
JSON
