pylint-tyrant 0.3.0

Pylint plugin with documentation and architecture rules.

pylint-tyrant

Pylint plugin with documentation and architecture rules inspired by eslint-plugin-tyrant.

The plugin currently ships these rules:

• tyrant-enforce-doc-tag-order
• tyrant-no-direct-error-instantiation
• tyrant-require-docstring-for-public-api
• tyrant-require-module-docstring
• tyrant-require-empty-line-after-module-docstring
• tyrant-require-package-init-module-organization-docstring
• tyrant-prefer-single-line-docstring
• tyrant-enforce-module-layer-dependencies
• tyrant-restrict-relative-imports-to-base-module

tyrant-enforce-module-layer-dependencies

Requires configured project directories and package-local module layers to depend only on themselves or lower layers.

Project-layer mode uses --tyrant-layers:

pylint \
  --load-plugins=pylint_tyrant \
  --enable=tyrant-enforce-module-layer-dependencies \
  --tyrant-layers=lib,services,app \
  path/to/your_package

Package-local mode uses --tyrant-shared-modules. In this mode, __init__.py is treated as the entry module automatically, configured same-directory module names such as base or types.py are treated as shared low-level modules, and every other module in the directory is treated as a feature module. Imports may only go downward: entry -> feature/shared, feature -> feature/shared, shared -> shared.

pylint \
  --load-plugins=pylint_tyrant \
  --enable=tyrant-enforce-module-layer-dependencies \
  --tyrant-shared-modules=base,types.py \
  path/to/your_package

tyrant-require-docstring-for-public-api

Requires public classes, functions, and methods to have docstrings.

This rule currently treats names that do not start with _ as public. It checks:

• top-level public classes
• top-level public functions
• public methods on public classes

Valid:

class UserService:
    """Load users."""

    def load_user(self) -> None:
        """Load one user."""

Also valid:

def load_user() -> None:
    """Load one user."""

Invalid:

def load_user() -> None:
    pass

tyrant-enforce-doc-tag-order

Requires recognized docstring tags to follow one configured order.

This rule reads tags written as @tag - value from module, class, and function docstrings. It only checks tags listed in tyrant-doc-tag-order.

Configure it in pyproject.toml like this:

[tool.pylint.main]
load-plugins = ["pylint_tyrant"]

[tool.pylint."messages control"]
enable = ["tyrant-enforce-doc-tag-order"]

[tool.pylint.tyrant-doc-tag-order]
tyrant-doc-tag-order = ["@remarks", "@param", "@returns"]

Command-line equivalent:

pylint \
  --load-plugins=pylint_tyrant \
  --enable=tyrant-enforce-doc-tag-order \
  --tyrant-doc-tag-order=@remarks,@param,@returns \
  path/to/your_package

Valid:

def load_user() -> User:
    """Load one user.

    @remarks - Used by the public API.
    @param - User id.
    @returns - Loaded user.
    """

Invalid:

def load_user() -> User:
    """Load one user.

    @returns - Loaded user.
    @param - User id.
    """