{"id":13592667,"url":"https://github.com/AntoineD/docstring-inheritance","last_synced_at":"2025-04-08T23:33:54.176Z","repository":{"id":57423392,"uuid":"424710593","full_name":"AntoineD/docstring-inheritance","owner":"AntoineD","description":"A python package to avoid writing and maintaining duplicated python docstrings.","archived":false,"fork":false,"pushed_at":"2024-10-21T08:26:49.000Z","size":191,"stargazers_count":23,"open_issues_count":0,"forks_count":5,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-10-21T11:38:47.322Z","etag":null,"topics":["docstrings","python"],"latest_commit_sha":null,"homepage":"https://antoined.github.io/docstring-inheritance/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AntoineD.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-11-04T19:09:31.000Z","updated_at":"2024-10-21T08:26:53.000Z","dependencies_parsed_at":"2023-02-09T23:45:26.482Z","dependency_job_id":"829e45ea-b8ce-4f4b-9c36-8e18ebe1675e","html_url":"https://github.com/AntoineD/docstring-inheritance","commit_stats":{"total_commits":36,"total_committers":2,"mean_commits":18.0,"dds":0.02777777777777779,"last_synced_commit":"ed60d967971e2b0332319a20756f9178ddb41e86"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AntoineD%2Fdocstring-inheritance","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AntoineD%2Fdocstring-inheritance/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AntoineD%2Fdocstring-inheritance/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AntoineD%2Fdocstring-inheritance/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AntoineD","download_url":"https://codeload.github.com/AntoineD/docstring-inheritance/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223346927,"owners_count":17130531,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docstrings","python"],"created_at":"2024-08-01T16:01:11.862Z","updated_at":"2024-11-06T13:32:05.282Z","avatar_url":"https://github.com/AntoineD.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"\u003c!--\n Copyright 2021 Antoine DECHAUME\n\n This work is licensed under the Creative Commons Attribution 4.0\n International License. To view a copy of this license, visit\n http://creativecommons.org/licenses/by/4.0/ or send a letter to Creative\n Commons, PO Box 1866, Mountain View, CA 94042, USA.\n --\u003e\n\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/docstring-inheritance)\n![PyPI](https://img.shields.io/pypi/v/docstring-inheritance)\n![Conda (channel only)](https://img.shields.io/conda/vn/conda-forge/docstring-inheritance)\n![Codecov branch](https://img.shields.io/codecov/c/gh/AntoineD/docstring-inheritance/main)\n\n`docstring-inheritance` is a python package to avoid writing and maintaining duplicated python docstrings.\nThe typical usage is to enable the inheritance of the docstrings from a base class\nsuch that its derived classes fully or partly inherit the docstrings.\n\n# Features\n\n- Handle numpy and google docstring formats (i.e. sections based docstrings):\n    - [NumPy docstring format specification](https://numpydoc.readthedocs.io/en/latest/format.html)\n    - [Google docstring format specification](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings)\n- Handle docstrings for functions, classes, methods, class methods, static methods, properties.\n- Handle docstrings for classes with multiple or multi-level inheritance.\n- Docstring sections are inherited individually,\n  like methods.\n- For docstring sections documenting signatures,\n  the signature arguments are inherited individually.\n- Minimum performance cost: the inheritance is performed at import time,\n  not for each call.\n- Compatible with rendering the documentation with [Sphinx](http://www.sphinx-doc.org/) and [mkdocs](https://www.mkdocs.org/) (See [below](#mkdocs)).\n- Missing docstring sections for signature arguments can be notified by warnings\n  when the environment variable `DOCSTRING_INHERITANCE_WARNS` is set.\n- Docstring sections can be compared to detect duplicated or similar contents that could be inherited.\n\n# Licenses\n\nThe source code is distributed under the MIT license.\nThe documentation is distributed under the CC BY 4.0 license.\nThe dependencies, with their licenses, are given in the CREDITS.md file.\n\n# Installation\n\nInstall with pip:\n\n```commandline\npip install docstring-inheritance\n```\n\nOr with conda:\n\n```commandline\nconda install -c conda-forge docstring-inheritance\n```\n\n# Basic Usage\n\n## Inheriting docstrings for classes\n\n`docstring-inheritance` provides\n[metaclasses](https://docs.python.org/3/reference/datamodel.html#customizing-class-creation)\nto enable the docstrings of a class to be inherited from its base classes.\nThis feature is automatically transmitted to its derived classes as well.\nThe docstring inheritance is performed for the docstrings of the:\n- class\n- methods\n- classmethods\n- staticmethods\n- properties\n\nUse the `NumpyDocstringInheritanceMeta` metaclass to inherit docstrings in numpy format\nif `__init__` method is documented in its own docstring.\nOtherwise, if `__init__` method is documented in the class docstring,\nuse the `NumpyDocstringInheritanceInitMeta` metaclass.\n\nUse the `GoogleDocstringInheritanceMeta` metaclass to inherit docstrings in google format.\nif `__init__` method is documented in its own docstring.\nOtherwise, if `__init__` method is documented in the class docstring,\nuse the `GoogleDocstringInheritanceInitMeta` metaclass.\n\n```python\nfrom docstring_inheritance import NumpyDocstringInheritanceMeta\n\n\nclass Parent(metaclass=NumpyDocstringInheritanceMeta):\n  def method(self, x, y=None):\n    \"\"\"Parent summary.\n\n    Parameters\n    ----------\n    x:\n       Description for x.\n    y:\n       Description for y.\n\n    Notes\n    -----\n    Parent notes.\n    \"\"\"\n\n\nclass Child(Parent):\n  def method(self, x, z):\n    \"\"\"\n    Parameters\n    ----------\n    z:\n       Description for z.\n\n    Returns\n    -------\n    Something.\n\n    Notes\n    -----\n    Child notes.\n    \"\"\"\n\n\n# The inherited docstring is\nChild.method.__doc__ == \"\"\"Parent summary.\n\nParameters\n----------\nx:\n   Description for x.\nz:\n   Description for z.\n\nReturns\n-------\nSomething.\n\nNotes\n-----\nChild notes.\n\"\"\"\n```\n\n## Inheriting docstrings for functions\n\n`docstring-inheritance` provides functions to inherit the docstring of a callable from a string.\nThis is typically used to inherit the docstring of a function from another function.\n\nUse the `inherit_google_docstring` function to inherit docstrings in google format.\n\nUse the `inherit_numpy_docstring` function to inherit docstrings in numpy format.\n\n```python\nfrom docstring_inheritance import inherit_google_docstring\n\n\ndef parent():\n    \"\"\"Parent summary.\n\n    Args:\n        x: Description for x.\n        y: Description for y.\n\n    Notes:\n        Parent notes.\n    \"\"\"\n\n\ndef child():\n    \"\"\"\n    Args:\n        z: Description for z.\n\n    Returns:\n        Something.\n\n    Notes:\n        Child notes.\n    \"\"\"\n\n\ninherit_google_docstring(parent.__doc__, child)\n\n# The inherited docstring is\nchild.__doc__ == \"\"\"Parent summary.\n\nArgs:\n    x: Description for x.\n    z: Description for z.\n\nReturns:\n    Something.\n\nNotes:\n    Child notes.\n\"\"\"\n```\n\n# Docstring inheritance specification\n\n## Sections order\n\nThe sections of an inherited docstring are sorted according to order defined in the\n[NumPy docstring format specification](https://numpydoc.readthedocs.io/en/latest/format.html):\n- `Summary`\n- `Extended summary`\n- `Parameters` for the NumPy format or `Args` for the Google format\n- `Returns`\n- `Yields`\n- `Receives`\n- `Other Parameters`\n- `Attributes`\n- `Methods`\n- `Raises`\n- `Warns`\n- `Warnings`\n- `See Also`\n- `Notes`\n- `References`\n- `Examples`\n- sections with other names come next\n\nThis ordering is also used for the docstring written with the\n[Google docstring format specification](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings)\neven though it does not define all of these sections.\n\n## Sections with items\n\nThose sections are:\n- `Other Parameters`\n- `Methods`\n- `Attributes`\n\nThe inheritance is done at the key level,\ni.e. a section of the inheritor will not fully override the parent one:\n- the keys in the parent section and not in the child section are inherited,\n- the keys in the child section and not in the parent section are kept,\n- for keys that are both in the parent and child section,\n  the child ones are kept.\n\nThis allows to only document the new keys in such a section of an inheritor.\nFor instance:\n\n```python\nfrom docstring_inheritance import NumpyDocstringInheritanceMeta\n\n\nclass Parent(metaclass=NumpyDocstringInheritanceMeta):\n  \"\"\"\n  Attributes\n  ----------\n  x:\n     Description for x\n  y:\n     Description for y\n  \"\"\"\n\n\nclass Child(Parent):\n  \"\"\"\n  Attributes\n  ----------\n  y:\n     Overridden description for y\n  z:\n     Description for z\n  \"\"\"\n\n\n# The inherited docstring is\nChild.__doc__ == \"\"\"\nAttributes\n----------\nx:\n   Description for x\ny:\n   Overridden description for y\nz:\n   Description for z\n\"\"\"\n```\n\nHere the keys are the attribute names.\nThe description for the attribute `y` has been overridden\nand the description for the attribute `z` has been added.\nThe only remaining description from the parent is for the attribute `x`.\n\n### Sections documenting signatures\n\nThose sections are:\n- `Parameters` (numpy format only)\n- `Args` (google format only)\n\nIn addition to the inheritance behavior described [above](#sections-with-items):\n- the arguments not existing in the inheritor signature are removed,\n- the arguments are sorted according the inheritor signature,\n- the arguments with no description are provided with a dummy description.\n\n```python\nfrom docstring_inheritance import GoogleDocstringInheritanceMeta\n\n\nclass Parent(metaclass=GoogleDocstringInheritanceMeta):\n  def method(self, w, x, y):\n    \"\"\"\n    Args:\n        w: Description for w\n        x: Description for x\n        y: Description for y\n    \"\"\"\n\n\nclass Child(Parent):\n  def method(self, w, y, z):\n    \"\"\"\n    Args:\n        z: Description for z\n        y: Overridden description for y\n    \"\"\"\n\n\n# The inherited docstring is\nChild.method.__doc__ == \"\"\"\nArgs:\n    w: Description for w\n    y: Overridden description for y\n    z: Description for z\n\"\"\"\n```\n\nHere the keys are the argument names.\nThe description for the argument `y` has been overridden\nand the description for the argument `z` has been added.\nThe only remaining description from the parent is for the argument `w`.\n\n# Advanced usage\n\n## Abstract base class\n\nTo create a parent class that both is abstract and has docstring inheritance,\nan additional metaclass is required:\n\n```python\nimport abc\nfrom docstring_inheritance import NumpyDocstringInheritanceMeta\n\n\nclass Meta(abc.ABCMeta, NumpyDocstringInheritanceMeta):\n  pass\n\n\nclass Parent(metaclass=Meta):\n  pass\n```\n\n## Detecting similar docstrings\n\nDuplicated docstrings that could benefit from inheritance can be detected\nby setting the environment variable `DOCSTRING_INHERITANCE_SIMILARITY_RATIO` to a value between `0` and `1`.\nWhen set, the docstring sections of a child and its parent are compared and warnings are issued when the docstrings are\nsimilar.\nThe docstring sections are compared with\n[difflib ratio](https://docs.python.org/3/library/difflib.html#difflib.SequenceMatcher.ratio)\nfrom the standard library.\nIf the ratio is higher or equal to the value of `DOCSTRING_INHERITANCE_SIMILARITY_RATIO`,\nthe docstring sections are considered similar.\nUse a ratio of `1` to detect identical docstring sections.\nUse a ratio lower than `1` to detect similar docstring sections.\n\n# Mkdocs\n\nTo render the documentation with `mkdocs`,\nthe package `mkdocstring[python]` is required and\nthe package `griffe-inherited-docstrings` is recommended,\nfinally the following shall be added to `mkdocs.yml`:\n\n```yaml\nplugins:\n- mkdocstrings:\n    handlers:\n      python:\n        options:\n          extensions:\n            - griffe_inherited_docstrings\n            - docstring_inheritance.griffe\n```\n\n# Similar projects\n\n[custom_inherit](https://github.com/rsokl/custom_inherit):\n`docstring-inherit` started as fork of this project before being re-written,\nwe thank its author.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAntoineD%2Fdocstring-inheritance","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FAntoineD%2Fdocstring-inheritance","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAntoineD%2Fdocstring-inheritance/lists"}