more_autodoc.autoprotocol

A Sphinx directive for documenting Protocols in Python.

New in version 0.2.0.

Enable sphinx_toolbox.more_autodoc.autoprotocol by adding the following to the extensions variable in your conf.py:

extensions = [
    ...
    'sphinx_toolbox.more_autodoc.autoprotocol',
    ]

For more information see https://www.sphinx-doc.org/en/master/usage/extensions#third-party-extensions .

Changed in version 0.6.0: Moved from sphinx_toolbox.autoprotocol.

Changed in version 2.13.0: Added support for generic bases, such as class SupportsAbs(Protocol[T_co]): ....

Usage

.. autoprotocol::

Directive to automatically document a typing.Protocol.

The output is based on the autoclass directive, but with a few differences:

• Private members are always excluded.

• Special members (dunder methods) are always included.

• Undocumented members are always included.

The following options from autoclass are available:

:noindex: (flag)

Do not generate index entries for the documented object (and all autodocumented members).

:member-order: (string)

Override the global value of autodoc_member_order for one directive.

:show-inheritance: (flag)

Inserts a list of base classes just below the protocol’s signature.

:protocol:

Role which provides a cross-reference to the documentation generated by autoprotocol.

See also

https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html

Examples:

# stdlib
from abc import abstractmethod
from typing import Any, TypeVar

# 3rd party
from domdf_python_tools.doctools import prettify_docstrings
from typing_extensions import Protocol, runtime_checkable

__all__ = ("HasLessThan", "HasGreaterThan", "Frobnicater")


@prettify_docstrings
class HasLessThan(Protocol):
    """
    :class:`typing.Protocol` for classes that support the ``<`` operator.
    """

    def __lt__(self, other) -> bool: ...


@prettify_docstrings
class HasGreaterThan(Protocol):

    def __gt__(self, other) -> bool: ...


@runtime_checkable
class Frobnicater(Protocol):

    def frobnicate(self, something) -> Any: ...

.. automodule:: autoprotocol_demo
    :members:
    :no-autosummary:
    :exclude-members: HasGreaterThan

.. autoprotocol:: autoprotocol_demo.HasGreaterThan

The objects being sorted must implement the :protocol:`~.HasGreaterThan` protocol.

protocol Frobnicater

Bases: Protocol

This protocol is runtime checkable.

Classes that implement this protocol must have the following methods / attributes:

frobnicate(something)

Return type:

Any

protocol HasLessThan

Bases: Protocol

typing.Protocol for classes that support the < operator.

Classes that implement this protocol must have the following methods / attributes:

__lt__(other)

Return self < other.

Return type:

bool

protocol HasGreaterThan

Bases: Protocol

Classes that implement this protocol must have the following methods / attributes:

__gt__(other)

Return self > other.

Return type:

bool

The objects being sorted must implement the HasGreaterThan protocol.

API Reference

Classes:

ProtocolDocumenter(directive, name[, indent])

Sphinx autodoc Documenter for documenting typing.Protocols.

Functions:

setup(app)

Setup sphinx_toolbox.more_autodoc.autoprotocol.

class ProtocolDocumenter(directive, name, indent='')

Bases: ClassDocumenter

Sphinx autodoc Documenter for documenting typing.Protocols.

Methods:

add_content(more_content[, no_docstring])	Add the autodocumenter content.
add_directive_header(sig)	Add the directive's header and options to the generated content.
can_document_member(member, membername, ...)	Called to see if a member can be documented by this documenter.
document_members([all_members])	Generate reST for member documentation.
filter_members(members, want_all)	Filter the given member list.
format_signature(**kwargs)	Protocols do not have a signature.

add_content(more_content, no_docstring=False)

Add the autodocumenter content.

Parameters:

• more_content (Optional[StringList])

• no_docstring (bool) – Default False.

add_directive_header(sig)

Add the directive’s header and options to the generated content.

Parameters:

sig (str) – The function/class signature.

classmethod can_document_member(member, membername, isattr, parent)

Called to see if a member can be documented by this documenter.

Parameters:

• member (Any) – The member being checked.

• membername (str) – The name of the member.

• isattr (bool)

• parent (Any) – The parent of the member.

Return type:

bool

document_members(all_members=False)

Generate reST for member documentation.

All members are always documented.

filter_members(members, want_all)

Filter the given member list.

Parameters:

• members (List[Tuple[str, Any]])

• want_all (bool)

Return type:

List[Tuple[str, Any, bool]]

format_signature(**kwargs)

Protocols do not have a signature.

Return type:

str

objtype = 'protocol'

Type:    str

priority = 20

Type:    int

setup(app)

Setup sphinx_toolbox.more_autodoc.autoprotocol.

Parameters:

app (Sphinx) – The Sphinx application.

Return type:

SphinxExtMetadata