g_docformatter.formatters.paragraph

Module with classes to format paragraphs, which are iterables of docstring tokens.

exception g_docformatter.formatters.paragraph.ParagraphFormatterError

Bases: RuntimeError

Custom error for ParagraphFormatterABC.

class g_docformatter.formatters.paragraph.ParagraphFormatterABC(settings: FormatterSettings, token_collector: collectors.TokenCollectorABC, text_formatters: TextFormattersContainer, subformatters: Mapping[_ParagraphType, ParagraphFormatterABC] | None = None)

Bases: ABC

Abstract base class for formatting iterables of docstring tokens (paragraphs).

Formatter methods are registered via the @formatter_method decorator. A formatter method should be a callable accepting (tokens, tokeninfo) and returning a string. The optional decorator argument allows the paragraph type to be specified explicitly; otherwise the type is derived from the method name by stripping the format_ prefix and _paragraph suffix and uppercasing the result.

Subclasses may defer to other ParagraphFormatterABC instances for specific paragraph types by passing them in the subformatters argument during initialization.

Parameters:

• settings – A dictionary of settings for the formatter.

• token_collector – An instance of TokenCollectorABC to collect tokens.

• text_formatters – The container providing TextFormatterABC instances.

• subformatters – An optional dictionary mapping paragraph types to ParagraphFormatterABC instances for sub-formatting specific paragraph types.

SUFFIX = 'ParagraphFormatter'

Class name suffix that all subclasses must end with.

Used for validation and to derive formatter config keys from class names when not explicitly provided.

required_subformatters: frozenset[str] = frozenset({})

Subformatter names that must be provided during instantiation.

Subclasses should override this with a frozenset of paragraph type names (e.g., frozenset({"description", "std_section"})). The names supplied here are normalized to uppercase by __init__() before validation, so callers may use either case; the conversion prevents validation mismatches. After normalization, names are validated only against explicitly passed subformatters.

Formatter methods defined on this class (or inherited from parent classes) do not satisfy this requirement.

class FormatterMethod(func: Callable[[...], object] | None = None, paragraph_type: str | None = None)

Bases: object

Descriptor used to register paragraph formatter methods.

Parameters:

• func – The formatter method being decorated. This is set when the decorator is used without arguments (e.g., @formatter_method).

• paragraph_type – An optional explicit paragraph type to register the method for. This can be provided either as a positional argument (e.g., @formatter_method("TYPE")) or as a keyword argument (e.g., @formatter_method(paragraph_type="TYPE")). If not provided, the paragraph type is derived from the method name.

Example

The descriptor may be used with or without arguments:

@formatter_method
def format_summary_paragraph(self, tokens, tokeninfo): ...


@formatter_method("CUSTOM")
def some_method(self, tokens, tokeninfo): ...

If no explicit paragraph type is provided, the type is derived by stripping the format_ prefix and _paragraph suffix from the method name and converting to uppercase. An error is raised if the name does not follow the expected pattern and no explicit type was given.

Note

The tokens parameter of each formatter method should be annotated as FrozenParagraph, not ParagraphArgument. Formatter methods receive their tokens from collect_tokens(), which always returns FrozenParagraph (frozen tuples of DocstringToken). The broader ParagraphArgument type is accepted only at the format_tokens() / __call__() boundary where callers may supply any iterable.

abstract property join_with: str

The string used to join formatted paragraphs.

formatters: ChainMap[_ParagraphType, FormatterCallableProtocol]

A ChainMap of paragraph types to their formatting functions.

The maps of the ChainMap are, in order of precedence:

1. An empty dictionary (to prevent modification of class-level mappings)

2. Formatter methods defined on the class (e.g., format_summary_tokens)

3. Subformatters passed during initialization (e.g., a DescriptionParagraphFormatter instance)

format_tokens(tokens: ParagraphArgument, tokeninfo: tokenize.TokenInfo) → str

Format a docstring given its tokens and token info.

Parameters:

• tokens – Paragraph tokens as a ParagraphArgument — an iterable of DocstringToken objects.

• tokeninfo – TokenInfo object for the docstring.

Returns:

Formatted docstring as a string.

get_base_indent(tokeninfo: tokenize.TokenInfo) → int

Get the base indentation column from token info.

Parameters:

tokeninfo – The token info object containing position information.

Returns:

The column number where the token starts.

get_base_indent_level(tokeninfo: tokenize.TokenInfo) → int

Get the base indentation level from token info.

The indentation level is calculated by dividing the base indent column by the configured indent size.

Parameters:

tokeninfo – The token info object containing position information.

Returns:

The indentation level as an integer.

get_text_formatter(format_option_key: str, formatter_config_key: str | None = None) → TextFormatterABC

Get a text formatter instance from the container.

Retrieves a text formatter based on the format option key and an optional configuration key. If no configuration key is provided, it automatically derives one from the class name by converting the class name prefix (before ‘ParagraphFormatter’) to snake_case.

Parameters:

• format_option_key – The format option to retrieve (e.g., ‘summary’, ‘eod’, ‘header’, ‘list_item’).

• formatter_config_key – Optional configuration key for looking up the formatter in settings. If None, derives the key from the class name.

Returns:

An instance of the text formatter configured for the specified format option.

Raises:

ValueError – If the text formatter name specified in settings is not found in the text formatters container.

get_token_text(tokens: FrozenParagraph, join_with: str = '', lstrip_chars: str | None = ' ', rstrip_chars: str | None = None) → str

Extract and concatenate text from a sequence of tokens.

Processes tokens by removing leading characters specified in lstrip_chars from each token’s text and concatenating them together using the join_with string, then removing any trailing characters specified in rstrip_chars from the final result.

Parameters:

• tokens – A sequence of docstring tokens to extract text from.

• join_with – A string to join the token texts with.

• lstrip_chars – A string of characters to remove from the start of each token’s text.

• rstrip_chars – A string of characters to remove from the end of the final concatenated text.

Returns:

The concatenated text from all tokens with leading characters removed from each token and trailing characters removed from the result.

g_docformatter.formatters.paragraph.formatter_method

Decorator for registering paragraph formatter methods on ParagraphFormatterABC subclasses.

class g_docformatter.formatters.paragraph.RootParagraphFormatter(settings: FormatterSettings, token_collector: collectors.TokenCollectorABC, text_formatters: TextFormattersContainer, subformatters: Mapping[_ParagraphType, ParagraphFormatterABC] | None = None)

Bases: ParagraphFormatterABC

Formatter for root-level docstring paragraphs.

Handles formatting of summary, summary-only, and end-of-docstring (EOD) paragraphs. Joins formatted paragraphs with double newlines.

Delegates formatting of description and section paragraphs to specialized subformatters.

required_subformatters: frozenset[str] = frozenset({'description', 'list_section', 'std_section'})

Subformatter names that must be provided during instantiation.

Subclasses should override this with a frozenset of paragraph type names (e.g., frozenset({"description", "std_section"})). The names supplied here are normalized to uppercase by __init__() before validation, so callers may use either case; the conversion prevents validation mismatches. After normalization, names are validated only against explicitly passed subformatters.

Formatter methods defined on this class (or inherited from parent classes) do not satisfy this requirement.

property join_with: str

The string used to join formatted paragraphs.

format_summary_only_paragraph(tokens: FrozenParagraph, tokeninfo: tokenize.TokenInfo) → str

Format summary-only paragraph tokens.

Summary-only paragraphs are expected to contain exactly one token. If the iterable is empty an explicit ParagraphFormatterError is raised.

format_summary_paragraph(tokens: FrozenParagraph, tokeninfo: tokenize.TokenInfo) → str

Format summary paragraph tokens.

format_eod_paragraph(tokens: FrozenParagraph, tokeninfo: tokenize.TokenInfo) → str

Format end-of-docstring paragraph tokens.

An empty iterable is considered an error; raise a ParagraphFormatterError rather than letting next() trigger a StopIteration.

formatters: ChainMap[_ParagraphType, FormatterCallableProtocol]

A ChainMap of paragraph types to their formatting functions.

The maps of the ChainMap are, in order of precedence:

1. An empty dictionary (to prevent modification of class-level mappings)

2. Formatter methods defined on the class (e.g., format_summary_tokens)

3. Subformatters passed during initialization (e.g., a DescriptionParagraphFormatter instance)

class g_docformatter.formatters.paragraph.BodyParagraphFormatter(settings: FormatterSettings, token_collector: collectors.TokenCollectorABC, text_formatters: TextFormattersContainer, subformatters: Mapping[str, ParagraphFormatterABC] | None = None)

Bases: ParagraphFormatterABC

A ParagraphFormatterABC for formatting body paragraphs.

required_subformatters = frozenset({'sphinx_code'})

Subformatter names that must be provided during instantiation.

Subclasses should override this with a frozenset of paragraph type names (e.g., frozenset({"description", "std_section"})). The names supplied here are normalized to uppercase by __init__() before validation, so callers may use either case; the conversion prevents validation mismatches. After normalization, names are validated only against explicitly passed subformatters.

Formatter methods defined on this class (or inherited from parent classes) do not satisfy this requirement.

additional_indent: int

Additional indentation levels to apply to the paragraph, added on top of the base indent level from token info; defaults to 0.

property join_with: str

The string used to join formatted paragraphs.

format_text_paragraph(tokens: FrozenParagraph, tokeninfo: tokenize.TokenInfo) → str

Format text paragraph tokens.

format_repl_code_paragraph(tokens: FrozenParagraph, tokeninfo: tokenize.TokenInfo) → str

Format REPL code paragraph tokens.

class g_docformatter.formatters.paragraph.StdSectionParagraphFormatter(settings: FormatterSettings, token_collector: collectors.TokenCollectorABC, text_formatters: TextFormattersContainer, subformatters: Mapping[_ParagraphType, ParagraphFormatterABC] | None = None)

Bases: ParagraphFormatterABC

A ParagraphFormatterABC for formatting standard sections.

required_subformatters: frozenset[str] = frozenset({'body'})

Subformatter names that must be provided during instantiation.

Subclasses should override this with a frozenset of paragraph type names (e.g., frozenset({"description", "std_section"})). The names supplied here are normalized to uppercase by __init__() before validation, so callers may use either case; the conversion prevents validation mismatches. After normalization, names are validated only against explicitly passed subformatters.

Formatter methods defined on this class (or inherited from parent classes) do not satisfy this requirement.

property join_with: str

The string used to join formatted paragraphs.

format_header_paragraph(tokens: FrozenParagraph, tokeninfo: tokenize.TokenInfo) → str

Format standard section header paragraph token.

Raises ParagraphFormatterError if the paragraph contains no tokens or more than one token.

formatters: ChainMap[_ParagraphType, FormatterCallableProtocol]

A ChainMap of paragraph types to their formatting functions.

The maps of the ChainMap are, in order of precedence:

1. An empty dictionary (to prevent modification of class-level mappings)

2. Formatter methods defined on the class (e.g., format_summary_tokens)

3. Subformatters passed during initialization (e.g., a DescriptionParagraphFormatter instance)

class g_docformatter.formatters.paragraph.ListSectionParagraphFormatter(settings: FormatterSettings, token_collector: collectors.TokenCollectorABC, text_formatters: TextFormattersContainer, subformatters: Mapping[_ParagraphType, ParagraphFormatterABC] | None = None)

Bases: ParagraphFormatterABC

A ParagraphFormatterABC for formatting list sections.

required_subformatters: frozenset[str] = frozenset({'list_item_body'})

Subformatter names that must be provided during instantiation.

Subclasses should override this with a frozenset of paragraph type names (e.g., frozenset({"description", "std_section"})). The names supplied here are normalized to uppercase by __init__() before validation, so callers may use either case; the conversion prevents validation mismatches. After normalization, names are validated only against explicitly passed subformatters.

Formatter methods defined on this class (or inherited from parent classes) do not satisfy this requirement.

property join_with: str

The string used to join formatted paragraphs.

format_header_paragraph(tokens: FrozenParagraph, tokeninfo: tokenize.TokenInfo) → str

Format list section header tokens.

format_list_item_paragraph(tokens: FrozenParagraph, tokeninfo: tokenize.TokenInfo) → str

Format list item paragraph tokens.

format_list_item_body_paragraph(tokens: FrozenParagraph, tokeninfo: tokenize.TokenInfo) → str

Format list item body paragraph tokens.

formatters: ChainMap[_ParagraphType, FormatterCallableProtocol]

A ChainMap of paragraph types to their formatting functions.

The maps of the ChainMap are, in order of precedence:

1. An empty dictionary (to prevent modification of class-level mappings)

2. Formatter methods defined on the class (e.g., format_summary_tokens)

3. Subformatters passed during initialization (e.g., a DescriptionParagraphFormatter instance)

class g_docformatter.formatters.paragraph.SphinxCodeBlockParagraphFormatter(settings: FormatterSettings, token_collector: collectors.TokenCollectorABC, text_formatters: TextFormattersContainer, subformatters: Mapping[str, ParagraphFormatterABC] | None = None)

Bases: ParagraphFormatterABC

A ParagraphFormatterABC for formatting Sphinx code blocks.

property join_with: str

The string used to join formatted paragraphs.

additional_indent: int

Additional indentation levels to apply to the code block, added on top of the base indent level from token info.

format_header_paragraph(tokens: FrozenParagraph, tokeninfo: tokenize.TokenInfo) → str

Format Sphinx code block header paragraph tokens.

format_option_paragraph(tokens: FrozenParagraph, tokeninfo: tokenize.TokenInfo) → str

Format Sphinx code block option paragraph tokens.

format_code_paragraph(tokens: FrozenParagraph, tokeninfo: tokenize.TokenInfo) → str

Format Sphinx code block code paragraph tokens.