or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/pypi-flake8-rst-docstrings

Python docstring reStructuredText (RST) validator for flake8

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/flake8-rst-docstrings@0.3.x

To install, run

npx @tessl/cli install tessl/pypi-flake8-rst-docstrings@0.3.0

index.mddocs/

flake8-rst-docstrings

A flake8 plugin that validates Python docstrings as reStructuredText (RST) markup using the docutils library. This plugin helps ensure that your docstrings conform to proper RST syntax, preventing documentation generation failures when using tools like Sphinx.

Package Information

  • Package Name: flake8-rst-docstrings
  • Package Type: pypi
  • Language: Python
  • Installation: pip install flake8-rst-docstrings

Core Imports

import flake8_rst_docstrings

Accessing the main checker class:

from flake8_rst_docstrings import reStructuredTextChecker

Accessing utility functions:

from flake8_rst_docstrings import code_mapping

Basic Usage

This package is designed to be used as a flake8 plugin and integrates automatically when installed:

# Install the plugin
pip install flake8-rst-docstrings

# Run flake8 with RST validation
flake8 --select=RST your_file.py

# Configure additional RST directives, roles, or substitutions
flake8 --rst-directives=mydirective,anotherdirective \
       --rst-roles=myrole \
       --rst-substitutions=mysubst \
       your_file.py

The plugin automatically validates docstrings in Python files and reports RST markup errors with specific error codes.

Capabilities

Plugin Registration

The package registers as a flake8 extension through setuptools entry points.

# Entry point configuration in pyproject.toml:
# [project.entry-points]
# 'flake8.extension' = {RST = 'flake8_rst_docstrings:reStructuredTextChecker'}

Main Checker Class

The core functionality is provided by the reStructuredTextChecker class that integrates with flake8's plugin system.

class reStructuredTextChecker:
    """Checker of Python docstrings as reStructuredText."""
    
    name: str = "rst-docstrings"
    version: str
    
    def __init__(self, tree, filename="(none)"):
        """
        Initialize the checker.
        
        Args:
            tree: AST tree from flake8
            filename (str): Source filename (default: "(none)")
        """
    
    @classmethod
    def add_options(cls, parser):
        """
        Add RST directives, roles and substitutions options to flake8 parser.
        
        Args:
            parser: flake8 options parser
            
        Adds the following options:
        - --rst-directives: Comma-separated list of additional RST directives
        - --rst-roles: Comma-separated list of additional RST roles  
        - --rst-substitutions: Comma-separated list of additional RST substitutions
        """
    
    @classmethod
    def parse_options(cls, options):
        """
        Parse and store plugin configuration options.
        
        Args:
            options: parsed options object
            
        Sets class attributes:
        - extra_directives: List of additional allowed directives
        - extra_roles: List of additional allowed roles
        - extra_substitutions: List of additional allowed substitutions
        """
    
    def run(self):
        """
        Main validation logic - walks AST, extracts docstrings, validates RST.
        
        Returns:
            Generator yielding tuples of (line, column, message, checker_type)
            
        Process:
        1. Walks AST for modules, classes, functions, async functions
        2. Extracts docstrings using ast.get_docstring()
        3. Strips Python signatures using py_ext_sig_re
        4. Validates RST using restructuredtext_lint.lint()
        5. Maps validation errors to flake8 codes using code_mapping()
        6. Yields formatted error messages with line numbers
        """

Error Code Mapping

Utility function for converting docutils validation messages to flake8 error codes.

def code_mapping(level, msg, extra_directives, extra_roles, extra_substitutions, default=99):
    """
    Map RST validation messages and levels to flake8 error codes.
    
    Args:
        level (int): Error level (1-4)
        msg (str): Error message from docutils
        extra_directives (list): Additional allowed RST directives
        extra_roles (list): Additional allowed RST roles
        extra_substitutions (list): Additional allowed RST substitutions
        default (int): Default error code if no mapping found (default: 99)
    
    Returns:
        int: Error code between 0-99, or 0 if error should be ignored
    """

Version Information

__version__: str

The package version string.

Constants and Configuration

rst_prefix: str = "RST"
rst_fail_load: int = 900
rst_fail_lint: int = 903
py_ext_sig_re: Pattern

Configuration constants used by the checker:

  • rst_prefix: Error code prefix for flake8 messages
  • rst_fail_load: Error code for file load failures
  • rst_fail_lint: Error code for linting failures
  • py_ext_sig_re: Compiled regex for matching Python extension signatures

Error Code Mappings

code_mapping_info: dict
code_mapping_warning: dict  
code_mapping_error: dict
code_mapping_severe: dict
code_mappings_by_level: dict

Dictionaries mapping RST validation messages to numeric error codes:

  • code_mapping_info: Level 1 (info) message mappings
  • code_mapping_warning: Level 2 (warning) message mappings
  • code_mapping_error: Level 3 (error) message mappings
  • code_mapping_severe: Level 4 (severe) message mappings
  • code_mappings_by_level: Master mapping of levels to their code mappings

Error Code System

The plugin uses a structured error code system with the "RST" prefix:

  • RST1xx: Info level (currently unused in practice)
  • RST2xx: Warning level (codes 201-220) - Issues that should be addressed
  • RST3xx: Error level (codes 301-307) - Major issues that must be addressed
  • RST4xx: Severe level (code 401) - Critical errors that halt processing
  • RST9xx: System errors (codes 900, 903) - File loading or linting failures

Common warning codes include:

  • RST201: Block quote ends without a blank line
  • RST202: Bullet list ends without a blank line
  • RST210: Inline strong start-string without end-string
  • RST212: Title underline too short

Common error codes include:

  • RST301: Unexpected indentation
  • RST302: Malformed table
  • RST303: Unknown directive type
  • RST304: Unknown interpreted text role
  • RST305: Undefined substitution referenced

Configuration

Users can configure the plugin via flake8 configuration files or command line:

# In setup.cfg or tox.ini
[flake8]
rst-directives = custom-directive,another-directive
rst-roles = custom-role
rst-substitutions = custom-substitution
# Command line
flake8 --rst-directives=custom-directive --rst-roles=custom-role

These options allow recognition of additional RST constructs beyond the standard set, preventing false positives for project-specific or Sphinx-specific RST extensions.