Skip to content

utils ¤

This module contains utilities for docstrings parsers.

Functions:

  • parse_annotation –

    Parse a string into a true name or expression that can be resolved later.

  • warning –

    Create and return a warn function.

parse_annotation ¤

parse_annotation(
    annotation: str,
    docstring: Docstring,
    log_level: LogLevel = error,
) -> str | Expr

Parse a string into a true name or expression that can be resolved later.

Parameters:

  • annotation (str) –

    The annotation to parse.

  • docstring (Docstring) –

    The docstring in which the annotation appears. The docstring's parent is accessed to bind a resolver to the resulting name/expression.

  • log_level (LogLevel, default: error ) –

    Log level to use to log a message.

Returns:

  • str | Expr –

    The string unchanged, or a new name or expression.

warning ¤

warning(name: str) -> WarningCallable

Create and return a warn function.

Parameters:

  • name (str) –

    The logger name.

Returns:

  • WarningCallable –

    A function used to log parsing warnings.

This function logs a warning message by prefixing it with the filepath and line number.

Parameters of the returned function:

  • docstring (Docstring) –

    The docstring object.

  • offset (int) –

    The offset in the docstring lines.

  • message (str) –

    The message to log.