base

The base module for docstring parsing.

AnnotatedObject

A helper class to store information about an annotated object.

Source code in pytkdocs/parsers/docstrings/base.py

class AnnotatedObject:
    """A helper class to store information about an annotated object."""

    def __init__(self, annotation: Any, description: str) -> None:
        """
        Initialize the object.

        Arguments:
            annotation: The object's annotation.
            description: The object's description.
        """
        self.annotation = annotation
        self.description = description

__init__(self, annotation, description) special

Initialize the object.

Parameters:

Name	Type	Description	Default
annotation	Any	The object's annotation.	required
description	str	The object's description.	required

Source code in pytkdocs/parsers/docstrings/base.py

def __init__(self, annotation: Any, description: str) -> None:
    """
    Initialize the object.

    Arguments:
        annotation: The object's annotation.
        description: The object's description.
    """
    self.annotation = annotation
    self.description = description

Attribute (AnnotatedObject)

A helper class to store information about a documented attribute.

Source code in pytkdocs/parsers/docstrings/base.py

class Attribute(AnnotatedObject):
    """A helper class to store information about a documented attribute."""

    def __init__(self, name: str, annotation: Any, description: str) -> None:
        """
        Initialize the object.

        Arguments:
            name: The attribute's name.
            annotation: The object's annotation.
            description: The object's description.
        """
        super().__init__(annotation, description)
        self.name = name

__init__(self, name, annotation, description) special

Initialize the object.

Parameters:

Name	Type	Description	Default
name	str	The attribute's name.	required
annotation	Any	The object's annotation.	required
description	str	The object's description.	required

Source code in pytkdocs/parsers/docstrings/base.py

def __init__(self, name: str, annotation: Any, description: str) -> None:
    """
    Initialize the object.

    Arguments:
        name: The attribute's name.
        annotation: The object's annotation.
        description: The object's description.
    """
    super().__init__(annotation, description)
    self.name = name

Parameter (AnnotatedObject)

A helper class to store information about a signature parameter.

Source code in pytkdocs/parsers/docstrings/base.py

class Parameter(AnnotatedObject):
    """A helper class to store information about a signature parameter."""

    def __init__(self, name: str, annotation: Any, description: str, kind: Any, default: Any = empty) -> None:
        """
        Initialize the object.

        Arguments:
            name: The parameter's name.
            annotation: The parameter's annotation.
            description: The parameter's description.
            kind: The parameter's kind (positional only, keyword only, etc.).
            default: The parameter's default value.
        """
        super().__init__(annotation, description)
        self.name = name
        self.kind = kind
        self.default = default

    def __str__(self):
        return self.name

    def __repr__(self):
        return f"<Parameter({self.name}, {self.annotation}, {self.description}, {self.kind}, {self.default})>"

    @property
    def is_optional(self):
        """Tell if this parameter is optional."""
        return self.default is not empty

    @property
    def is_required(self):
        """Tell if this parameter is required."""
        return not self.is_optional

    @property
    def is_args(self):
        """Tell if this parameter is positional."""
        return self.kind is inspect.Parameter.VAR_POSITIONAL

    @property
    def is_kwargs(self):
        """Tell if this parameter is a keyword."""
        return self.kind is inspect.Parameter.VAR_KEYWORD

    @property
    def default_string(self):
        """Return the default value as a string."""
        if self.is_kwargs:
            return "{}"
        if self.is_args:
            return "()"
        if self.is_required:
            return ""
        return repr(self.default)

default_string property readonly

Return the default value as a string.

is_args property readonly

Tell if this parameter is positional.

is_kwargs property readonly

Tell if this parameter is a keyword.

is_optional property readonly

Tell if this parameter is optional.

is_required property readonly

Tell if this parameter is required.

__init__(self, name, annotation, description, kind, default) special

Initialize the object.

Parameters:

Name	Type	Description	Default
name	str	The parameter's name.	required
annotation	Any	The parameter's annotation.	required
description	str	The parameter's description.	required
kind	Any	The parameter's kind (positional only, keyword only, etc.).	required
default	Any	The parameter's default value.	required

Source code in pytkdocs/parsers/docstrings/base.py

def __init__(self, name: str, annotation: Any, description: str, kind: Any, default: Any = empty) -> None:
    """
    Initialize the object.

    Arguments:
        name: The parameter's name.
        annotation: The parameter's annotation.
        description: The parameter's description.
        kind: The parameter's kind (positional only, keyword only, etc.).
        default: The parameter's default value.
    """
    super().__init__(annotation, description)
    self.name = name
    self.kind = kind
    self.default = default

Parser

A class to parse docstrings.

It is instantiated with an object's path, docstring, signature and return type.

The parse method then returns structured data, in the form of a list of Sections. It also return the list of errors that occurred during parsing.

Source code in pytkdocs/parsers/docstrings/base.py

class Parser(metaclass=ABCMeta):
    """
    A class to parse docstrings.

    It is instantiated with an object's path, docstring, signature and return type.

    The `parse` method then returns structured data,
    in the form of a list of [`Section`][pytkdocs.parsers.docstrings.base.Section]s.
    It also return the list of errors that occurred during parsing.
    """

    def __init__(self) -> None:
        """Initialize the object."""
        self.context: dict = {}
        self.errors: List[str] = []

    def parse(self, docstring: str, context: Optional[dict] = None) -> Tuple[List[Section], List[str]]:
        """
        Parse a docstring and return a list of sections and parsing errors.

        Arguments:
            docstring: The docstring to parse.
            context: Some context helping to parse the docstring.

        Returns:
            A tuple containing the list of sections and the parsing errors.
        """
        self.context = context or {}
        self.errors = []
        sections = self.parse_sections(docstring)
        errors = self.errors
        return sections, errors

    def error(self, message) -> None:
        """
        Record a parsing error.

        Arguments:
            message: A message described the error.
        """
        if self.context["obj"]:
            message = f"{self.context['obj'].path}: {message}"
        self.errors.append(message)

    @abstractmethod
    def parse_sections(self, docstring: str) -> List[Section]:
        """
        Parse a docstring as a list of sections.

        Arguments:
            docstring: The docstring to parse.

        Returns:
            A list of [`Section`][pytkdocs.parsers.docstrings.base.Section]s.
        """
        raise NotImplementedError

__init__(self) special

Initialize the object.

Source code in pytkdocs/parsers/docstrings/base.py

def __init__(self) -> None:
    """Initialize the object."""
    self.context: dict = {}
    self.errors: List[str] = []

error(self, message)

Record a parsing error.

Parameters:

Name	Type	Description	Default
message		A message described the error.	required

Source code in pytkdocs/parsers/docstrings/base.py

def error(self, message) -> None:
    """
    Record a parsing error.

    Arguments:
        message: A message described the error.
    """
    if self.context["obj"]:
        message = f"{self.context['obj'].path}: {message}"
    self.errors.append(message)

parse(self, docstring, context=None)

Parse a docstring and return a list of sections and parsing errors.

Parameters:

Name	Type	Description	Default
docstring	str	The docstring to parse.	required
context	Optional[dict]	Some context helping to parse the docstring.	None

Returns:

Type	Description
Tuple[List[pytkdocs.parsers.docstrings.base.Section], List[str]]	A tuple containing the list of sections and the parsing errors.

Source code in pytkdocs/parsers/docstrings/base.py

def parse(self, docstring: str, context: Optional[dict] = None) -> Tuple[List[Section], List[str]]:
    """
    Parse a docstring and return a list of sections and parsing errors.

    Arguments:
        docstring: The docstring to parse.
        context: Some context helping to parse the docstring.

    Returns:
        A tuple containing the list of sections and the parsing errors.
    """
    self.context = context or {}
    self.errors = []
    sections = self.parse_sections(docstring)
    errors = self.errors
    return sections, errors

parse_sections(self, docstring)

Parse a docstring as a list of sections.

Parameters:

Name	Type	Description	Default
docstring	str	The docstring to parse.	required

Returns:

Type	Description
List[pytkdocs.parsers.docstrings.base.Section]	A list of Sections.

Source code in pytkdocs/parsers/docstrings/base.py

@abstractmethod
def parse_sections(self, docstring: str) -> List[Section]:
    """
    Parse a docstring as a list of sections.

    Arguments:
        docstring: The docstring to parse.

    Returns:
        A list of [`Section`][pytkdocs.parsers.docstrings.base.Section]s.
    """
    raise NotImplementedError

Section

A helper class to store a docstring section.

Source code in pytkdocs/parsers/docstrings/base.py

class Section:
    """A helper class to store a docstring section."""

    class Type:
        """The possible section types."""

        MARKDOWN = "markdown"
        PARAMETERS = "parameters"
        EXCEPTIONS = "exceptions"
        RETURN = "return"
        YIELD = "yield"
        EXAMPLES = "examples"
        ATTRIBUTES = "attributes"
        KEYWORD_ARGS = "keyword_args"

    def __init__(self, section_type: str, value: Any) -> None:
        """
        Initialize the object.

        Arguments:
            section_type: The type of the section, from the [`Type`][pytkdocs.parsers.docstrings.base.Section.Type] enum.
            value: The section value.
        """
        self.type = section_type
        self.value = value

    def __str__(self):
        return self.type

    def __repr__(self):
        return f"<Section(type={self.type!r})>"

Type

The possible section types.

Source code in pytkdocs/parsers/docstrings/base.py

class Type:
    """The possible section types."""

    MARKDOWN = "markdown"
    PARAMETERS = "parameters"
    EXCEPTIONS = "exceptions"
    RETURN = "return"
    YIELD = "yield"
    EXAMPLES = "examples"
    ATTRIBUTES = "attributes"
    KEYWORD_ARGS = "keyword_args"

__init__(self, section_type, value) special

Initialize the object.

Parameters:

Name	Type	Description	Default
section_type	str	The type of the section, from the Type enum.	required
value	Any	The section value.	required

Source code in pytkdocs/parsers/docstrings/base.py

def __init__(self, section_type: str, value: Any) -> None:
    """
    Initialize the object.

    Arguments:
        section_type: The type of the section, from the [`Type`][pytkdocs.parsers.docstrings.base.Section.Type] enum.
        value: The section value.
    """
    self.type = section_type
    self.value = value