Metadata-Version: 2.4
Name: pylint-tyrant
Version: 0.3.1
Summary: Pylint plugin with documentation and architecture rules.
Author-email: otakutyrant <otakutyrant@gmail.com>
Requires-Python: >=3.13
Description-Content-Type: text/markdown
Requires-Dist: pylint>=4.0.0
Requires-Dist: tomli>=2.0.1; python_version < "3.11"

# 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`:

```sh
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`.

```sh
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:

```python
class UserService:
    """Load users."""

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

Also valid:

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

Invalid:

```python
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:

```toml
[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:

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

Valid:

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

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

Invalid:

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

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