Skip to content

rendering ¤

This module implements rendering utilities.

Classes:

  • Order –

    Enumeration for the possible members ordering.

Functions:

Order ¤

Bases: Enum

Enumeration for the possible members ordering.

Attributes:

alphabetical class-attribute instance-attribute ¤

alphabetical = 'alphabetical'

Alphabetical order.

source class-attribute instance-attribute ¤

source = 'source'

Source code order.

do_any ¤

do_any(seq: Sequence, attribute: str | None = None) -> bool

Check if at least one of the item in the sequence evaluates to true.

The any builtin as a filter for Jinja templates.

Parameters:

  • seq (Sequence) –

    An iterable object.

  • attribute (str | None, default: None ) –

    The attribute name to use on each object of the iterable.

Returns:

  • bool –

    A boolean telling if any object of the iterable evaluated to True.

do_as_attributes_section ¤

do_as_attributes_section(
    attributes: Sequence[Attribute],
    *,
    check_public: bool = True
) -> DocstringSectionAttributes

Build an attributes section from a list of attributes.

Parameters:

  • attributes (Sequence[Attribute]) –

    The attributes to build the section from.

  • check_public (bool, default: True ) –

    Whether to check if the attribute is public.

Returns:

  • DocstringSectionAttributes –

    An attributes docstring section.

do_as_classes_section ¤

do_as_classes_section(
    classes: Sequence[Class], *, check_public: bool = True
) -> DocstringSectionClasses

Build a classes section from a list of classes.

Parameters:

  • classes (Sequence[Class]) –

    The classes to build the section from.

  • check_public (bool, default: True ) –

    Whether to check if the class is public.

Returns:

  • DocstringSectionClasses –

    A classes docstring section.

do_as_functions_section ¤

do_as_functions_section(
    functions: Sequence[Function],
    *,
    check_public: bool = True
) -> DocstringSectionFunctions

Build a functions section from a list of functions.

Parameters:

  • functions (Sequence[Function]) –

    The functions to build the section from.

  • check_public (bool, default: True ) –

    Whether to check if the function is public.

Returns:

  • DocstringSectionFunctions –

    A functions docstring section.

do_as_modules_section ¤

do_as_modules_section(
    modules: Sequence[Module], *, check_public: bool = True
) -> DocstringSectionModules

Build a modules section from a list of modules.

Parameters:

  • modules (Sequence[Module]) –

    The modules to build the section from.

  • check_public (bool, default: True ) –

    Whether to check if the module is public.

Returns:

  • DocstringSectionModules –

    A modules docstring section.

do_crossref ¤

do_crossref(path: str, *, brief: bool = True) -> Markup

Deprecated. Filter to create cross-references.

Parameters:

  • path (str) –

    The path to link to.

  • brief (bool, default: True ) –

    Show only the last part of the path, add full path as hover.

Returns:

  • Markup –

    Markup text.

do_filter_objects ¤

do_filter_objects(
    objects_dictionary: dict[str, Object | Alias],
    *,
    filters: Sequence[tuple[Pattern, bool]] | None = None,
    members_list: bool | list[str] | None = None,
    inherited_members: bool | list[str] = False,
    keep_no_docstrings: bool = True
) -> list[Object | Alias]

Filter a dictionary of objects based on their docstrings.

Parameters:

  • objects_dictionary (dict[str, Object | Alias]) –

    The dictionary of objects.

  • filters (Sequence[tuple[Pattern, bool]] | None, default: None ) –

    Filters to apply, based on members' names. Each element is a tuple: a pattern, and a boolean indicating whether to reject the object if the pattern matches.

  • members_list (bool | list[str] | None, default: None ) –

    An optional, explicit list of members to keep. When given and empty, return an empty list. When given and not empty, ignore filters and docstrings presence/absence.

  • inherited_members (bool | list[str], default: False ) –

    Whether to keep inherited members or exclude them.

  • keep_no_docstrings (bool, default: True ) –

    Whether to keep objects with no/empty docstrings (recursive check).

Returns:

  • list[Object | Alias] –

    A list of objects.

do_format_attribute ¤

do_format_attribute(
    context: Context,
    attribute_path: Markup,
    attribute: Attribute,
    line_length: int,
    *,
    crossrefs: bool = False
) -> str

Format an attribute using Black.

Parameters:

  • context (Context) –

    Jinja context, passed automatically.

  • attribute_path (Markup) –

    The path of the callable we render the signature of.

  • attribute (Attribute) –

    The attribute we render the signature of.

  • line_length (int) –

    The line length to give to Black.

  • crossrefs (bool, default: False ) –

    Whether to cross-reference types in the signature.

Returns:

  • str –

    The same code, formatted.

do_format_code ¤

do_format_code(code: str, line_length: int) -> str

Format code using Black.

Parameters:

  • code (str) –

    The code to format.

  • line_length (int) –

    The line length to give to Black.

Returns:

  • str –

    The same code, formatted.

do_format_signature ¤

do_format_signature(
    context: Context,
    callable_path: Markup,
    function: Function,
    line_length: int,
    *,
    annotations: bool | None = None,
    crossrefs: bool = False
) -> str

Format a signature using Black.

Parameters:

  • context (Context) –

    Jinja context, passed automatically.

  • callable_path (Markup) –

    The path of the callable we render the signature of.

  • function (Function) –

    The function we render the signature of.

  • line_length (int) –

    The line length to give to Black.

  • annotations (bool | None, default: None ) –

    Whether to show type annotations.

  • crossrefs (bool, default: False ) –

    Whether to cross-reference types in the signature.

Returns:

  • str –

    The same code, formatted.

do_heading ¤

do_heading(content: str, heading_level: int) -> str

Render a Markdown heading.

do_multi_crossref ¤

do_multi_crossref(
    text: str, *, code: bool = True
) -> Markup

Deprecated. Filter to create cross-references.

Parameters:

  • text (str) –

    The text to scan.

  • code (bool, default: True ) –

    Whether to wrap the result in a code tag.

Returns:

  • Markup –

    Markup text.

do_order_members ¤

do_order_members(
    members: Sequence[Object | Alias],
    order: Order,
    members_list: bool | list[str] | None,
) -> Sequence[Object | Alias]

Order members given an ordering method.

Parameters:

  • members (Sequence[Object | Alias]) –

    The members to order.

  • order (Order) –

    The ordering method.

  • members_list (bool | list[str] | None) –

    An optional member list (manual ordering).

Returns:

  • Sequence[Object | Alias] –

    The same members, ordered.

do_split_path ¤

do_split_path(
    path: str, full_path: str
) -> list[tuple[str, str]]

Split object paths for building cross-references.

Parameters:

  • path (str) –

    The path to split.

Returns:

from_private_package ¤

from_private_package(obj: Object | Alias) -> bool

Tell if an alias points to an object coming from a corresponding private package.

For example, return true for an alias in package ast pointing at an object in package _ast.

Parameters:

  • obj (Object | Alias) –

    The object (alias) to check.

Returns:

  • bool –

    True or false.