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.

See https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html for further information.

:protocol:

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

Examples:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
# 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[source]

Bases: Protocol

This protocol is runtime checkable.

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

frobnicate(something)[source]
Return type

Any

protocol HasLessThan[source]

Bases: Protocol

typing.Protocol for classes that support the < operator.

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

__lt__(other)[source]

Return self < other.

Return type

bool

protocol HasGreaterThan[source]

Bases: Protocol

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

__gt__(other)[source]

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='')[source]

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 header.

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)[source]

Add the autodocumenter content.

Parameters
add_directive_header(sig)[source]

Add the directive header.

Parameters

sig (str)

classmethod can_document_member(member, membername, isattr, parent)[source]

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)[source]

Generate reST for member documentation.

All members are always documented.

filter_members(members, want_all)[source]

Filter the given member list.

Parameters
Return type

List[Tuple[str, Any, bool]]

format_signature(**kwargs)[source]

Protocols do not have a signature.

Return type

str

setup(app)[source]

Setup sphinx_toolbox.more_autodoc.autoprotocol.

Parameters

app (Sphinx) – The Sphinx application.

Return type

SphinxExtMetadata