A python package to avoid writing and maintaining duplicated python docstrings.

Overview

PyPI - Python Version PyPI Code Style Codecov branch

docstring-inheritance is a python package to avoid writing and maintaining duplicated python docstrings. The typical usage is to enable the inheritance of the docstrings from a base class such that its derived classes fully or partly inherit the docstrings.

Features

  • Handle numpy and google docstring formats (i.e. sections based docstrings):
  • Handle docstrings for functions, classes, methods, class methods, static methods, properties.
  • Handle docstrings for classes with multiple or multi-level inheritance.
  • Docstring sections are inherited individually, like methods for a classes.
  • For docstring sections documenting signatures, the signature arguments are inherited individually.
  • Minimum performance cost: the inheritance is performed at import time, not for each call.
  • Compatible with rendering the documentation with Sphinx.

Licenses

The source code is distributed under the MIT license. The documentation is distributed under the CC BY-SA 4.0 license. The dependencies, with their licenses, are given in the CREDITS.rst file.

Installation

Install via pip:

pip install docstring-inheritance

Basic Usage

Inheriting docstrings for classes

docstring-inheritance provides metaclasses to enable the docstrings of a class to be inherited from its base classes. This feature is automatically transmitted to its derived classes as well. The docstring inheritance is performed for the docstrings of the:

  • class
  • methods
  • classmethods
  • staticmethods
  • properties

Use the NumpyDocstringInheritanceMeta metaclass to inherit docstrings in numpy format.

Use the GoogleDocstringInheritanceMeta metaclass to inherit docstrings in google format.

from docstring_inheritance import NumpyDocstringInheritorMeta


class Parent(metaclass=NumpyDocstringInheritorMeta):
    def meth(self, x, y=None):
        """Parent summary.

        Parameters
        ----------
        x:
           Description for x.
        y:
           Description for y.

        Notes
        -----
        Parent notes.
        """


class Child(Parent):
    def meth(self, x, z):
        """
        Parameters
        ----------
        z:
           Description for z.

        Returns
        -------
        Something.

        Notes
        -----
        Child notes.
        """


# The inherited docstring is
Child.meth.__doc__ = """Parent summary.

Parameters
----------
x:
   Description for x.
z:
   Description for z.

Returns
-------
Something.

Notes
-----
Child notes.
"""

Inheriting docstrings for functions

docstring-inheritance provides functions to inherit the docstring of a callable from a string. This is typically used to inherit the docstring of a function from another function.

Use the inherit_google_docstring function to inherit docstrings in google format.

Use the inherit_numpy_docstring function to inherit docstrings in numpy format.

from docstring_inheritance import inherit_google_docstring


def parent():
    """Parent summary.

    Args:
        x: Description for x.
        y: Description for y.

    Notes:
        Parent notes.
    """


def child():
    """
    Args:
        z: Description for z.

    Returns:
        Something.

    Notes:
        Child notes.
    """
    

inherit_google_docstring(parent.__doc__, child)


# The inherited docstring is
child.__doc__ = """Parent summary.

Args:
    x: Description for x.
    z: Description for z.

Returns:
    Something.

Notes:
    Child notes.
"""

Docstring inheritance specification

Sections order

The sections of an inherited docstring are sorted according to order defined in the NumPy docstring format specification:

  • Summary
  • Extended summary
  • Parameters for the NumPy format or Args for the Google format
  • Returns
  • Yields
  • Receives
  • Other Parameters
  • Attributes
  • Methods
  • Raises
  • Warns
  • Warnings
  • See Also
  • Notes
  • References
  • Examples
  • sections with other names come next

This ordering is also used for the docstring written with the Google docstring format specification even though it does not define all of these sections.

Sections with items

Those sections are:

  • Other Parameters
  • Methods
  • Attributes

The inheritance is done at the key level, i.e. a section of the inheritor will not fully override the parent one:

  • the keys in the parent section and not in the child section are inherited,
  • the keys in the child section and not in the parent section are kept,
  • for keys that are both in the parent and child section, the child ones are kept.

This allows to only document the new keys in such a section of an inheritor. For instance:

from docstring_inheritance import NumpyDocstringInheritorMeta


class Parent(metaclass=NumpyDocstringInheritorMeta):
    """
    Attributes
    ----------
    x:
       Description for x
    y:
       Description for y
    """


class Child(Parent):
    """
    Attributes
    ----------
    y:
       Overridden description for y
    z:
       Description for z
    """

    
# The inherited docstring is
Child.__doc__ = """
Attributes
----------
x:
   Description for x
y:
   Overridden description for y
z:
   Description for z
"""

Here the keys are the attribute names. The description for the key y has been overridden and the description for the key z has been added. The only remaining description from the parent is for the key x.

Sections documenting signatures

Those sections are:

  • Parameters (numpy format only)
  • Args (google format only)

In addition to the inheritance behavior described above:

  • the arguments not existing in the inheritor signature are removed,
  • the arguments are sorted according the inheritor signature,
  • the arguments with no descriptions are provided with a dummy description.
from docstring_inheritance import GoogleDocstringInheritorMeta


class Parent(metaclass=GoogleDocstringInheritorMeta):
    def meth(self, w, x, y):
        """
        Args:
            w: Description for w
            x: Description for x
            y: Description for y
        """


class Child(Parent):
    def meth(self, w, y, z):
        """
        Args:
            z: Description for z
            y: Overridden description for y
        """


# The inherited docstring is
Child.meth.__doc__ = """
Args:
    w: Description for w
    y: Overridden description for y
    z: Description for z
"""

Here the keys are the arguments names. The description for the key y has been overridden and the description for the key z has been added. The only remaining description from the parent is for the key w.

Advanced usage

Abstract base class

To create a parent class that both is abstract and has docstring inheritance, an additional metaclass is required:

import abc
from docstring_inheritance import NumpyDocstringInheritorMeta


class Meta(abc.ABCMeta, NumpyDocstringInheritorMeta):
    pass


class Parent(metaclass=Meta):
    pass

Similar projects

custom_inherit: docstring-inherit started as fork of this project, we would like to thank its author.

Some code that takes a pipe-separated input and converts that into a table!

tablemaker A program that takes an input: a | b | c # With comments as well. e | f | g h | i |jk And converts it to a table: ┌───┬───┬────┐ │ a │ b │

CodingSoda 2 Aug 30, 2022
SamrSearch - SamrSearch can get user info and group info with MS-SAMR

SamrSearch SamrSearch can get user info and group info with MS-SAMR.like net use

knight 10 Oct 06, 2022
Create Python API documentation in Markdown format.

Pydoc-Markdown Pydoc-Markdown is a tool and library to create Python API documentation in Markdown format based on lib2to3, allowing it to parse your

Niklas Rosenstein 375 Jan 05, 2023
Plotting and analysis tools for ARTIS simulations

Artistools Artistools is collection of plotting, analysis, and file format conversion tools for the ARTIS radiative transfer code. Installation First

ARTIS Monte Carlo Radiative Transfer 8 Nov 07, 2022
A collection of online resources to help you on your Tech journey.

Everything Tech Resources & Projects About The Project Coming from an engineering background and looking to up skill yourself on a new field can be di

Mohamed A 396 Dec 31, 2022
Automated Integration Testing and Live Documentation for your API

Automated Integration Testing and Live Documentation for your API

ScanAPI 1.3k Dec 30, 2022
API Documentation for Python Projects

API Documentation for Python Projects. Example pdoc -o ./html pdoc generates this website: pdoc.dev/docs. Installation pip install pdoc pdoc is compat

mitmproxy 1.4k Jan 07, 2023
JMESPath is a query language for JSON.

JMESPath JMESPath (pronounced "james path") allows you to declaratively specify how to extract elements from a JSON document. For example, given this

1.7k Dec 31, 2022
Sphinx Bootstrap Theme

Sphinx Bootstrap Theme This Sphinx theme integrates the Bootstrap CSS / JavaScript framework with various layout options, hierarchical menu navigation

Ryan Roemer 584 Nov 16, 2022
OpenTelemetry Python API and SDK

Getting Started • API Documentation • Getting In Touch (GitHub Discussions) Contributing • Examples OpenTelemetry Python This page describes the Pytho

OpenTelemetry - CNCF 1.1k Jan 08, 2023
An open source utility for creating publication quality LaTex figures generated from OpenFOAM data files.

foamTEX An open source utility for creating publication quality LaTex figures generated from OpenFOAM data files. Explore the docs » Report Bug · Requ

1 Dec 19, 2021
Get link preview of a website.

Preview Link You may have seen a preview of a link with a title, image, domain, and description when you share a link on social media. This preview ha

SREEHARI K.V 8 Jan 08, 2023
Uses diff command to compare expected output with student's submission output

AUTOGRADER for GRADESCOPE using diff with partial grading Description: Uses diff command to compare expected output with student's submission output U

2 Jan 11, 2022
A hack to run custom shell commands when building documentation on Read the Docs.

readthedocs-custom-steps A hack to run custom steps when building documentation on Read the Docs. Important: This module should not be installed outsi

Niklas Rosenstein 5 Feb 22, 2022
Literate-style documentation generator.

888888b. 888 Y88b 888 888 888 d88P 888 888 .d8888b .d8888b .d88b. 8888888P" 888 888 d88P" d88P" d88""88b 888 888 888

Pycco 808 Dec 27, 2022
Code for our SIGIR 2022 accepted paper : P3 Ranker: Mitigating the Gaps between Pre-training and Ranking Fine-tuning with Prompt-based Learning and Pre-finetuning

P3 Ranker Implementation for our SIGIR2022 accepted paper: P3 Ranker: Mitigating the Gaps between Pre-training and Ranking Fine-tuning with Prompt-bas

14 Jan 04, 2023
Contains the assignments from the course Building a Modern Computer from First Principles: From Nand to Tetris.

Contains the assignments from the course Building a Modern Computer from First Principles: From Nand to Tetris.

Matheus Rodrigues 1 Jan 20, 2022
Testing-crud-login-drf - Creation of an application in django on music albums

testing-crud-login-drf Creation of an application in django on music albums Befo

Juan 1 Jan 11, 2022
Version bêta d'un système pour suivre les prix des livres chez Books to Scrape,

Version bêta d'un système pour suivre les prix des livres chez Books to Scrape, un revendeur de livres en ligne. En pratique, dans cette version bêta, le programme n'effectuera pas une véritable surv

Mouhamed Dia 1 Jan 06, 2022
Easy OpenAPI specs and Swagger UI for your Flask API

Flasgger Easy Swagger UI for your Flask API Flasgger is a Flask extension to extract OpenAPI-Specification from all Flask views registered in your API

Flasgger 3.1k Dec 24, 2022