A python decorator to inherit docstring.
Project description
inherit-docstring
A python decorator to inherit docstring.
Easily inherit docstrings from parent classes with @inherit_docstring
decorator, designed specifically for the NumPy docstring style.
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
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.12, 3.11, 3.10, 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
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.
Source Distribution
Built Distribution
Close
Hashes for inherit_docstring-0.0.2-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 6dada0cbffe339505c7a9b38e90f9c965da222fab93e2ddeeb2091d99e98f7bd |
|
MD5 | 31ed53c708c83d74a605b8a808494419 |
|
BLAKE2b-256 | 1a865ffff4f10367ad5a733c71c3d098b5508bd0840af90bd4dbda1b861e9b92 |