pydoclint

https://jsh9.github.io/pydoclint/
Admin
pydoclint is a Python linter that ensures docstrings match the code they describe, checking...
Tokens:21,487
Snippets:179
Trust Score:9.7
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Example pyproject.toml for native pydoclint

Source: https://jsh9.github.io/pydoclint/how_to_config.html

Example pyproject.toml configuration for native pydoclint, used with the pre-commit hook that passes --config=pyproject.toml.

```toml
[tool.pydoclint]
check-return-types = false
style = "google"
```

--------------------------------

### Install pydoclint native tool

Source: https://jsh9.github.io/pydoclint

Installs the native pydoclint tooling. Requires Python 3.10 or newer.

```bash
pip install pydoclint

```

--------------------------------

### Example pyproject.toml for flake8 plugin

Source: https://jsh9.github.io/pydoclint/how_to_config.html

Example pyproject.toml configuration for the flake8 plugin, used with the pre-commit hook that passes --toml-config=pyproject.toml.

```toml
[tool.flake8]
check-return-types = false
style = "google"
```

--------------------------------

### Configure pydoclint to document private class attributes

Source: https://jsh9.github.io/pydoclint/config_options.html

Configuration example for pydoclint to require documentation for private class attributes like `_value` while ignoring underscore-only placeholders such as `_` (e.g., `_: dataclasses.KW_ONLY`).

```ini
ignore-private-class-attributes = false
ignore-underscore-only-class-attributes = true
```

--------------------------------

### Install pydoclint flake8 plugin

Source: https://jsh9.github.io/pydoclint

Installs pydoclint as a flake8 plugin, which also installs flake8 into the current Python environment.

```bash
pip install pydoclint[flake8]

```

--------------------------------

### pydoclint --style usage

Source: https://jsh9.github.io/pydoclint/config_options.html

Sets the docstring style to numpy, google, or sphinx (default numpy). This example uses google style.

```bash
pydoclint --style=google <FILE_OR_FOLDER>

```

--------------------------------

### Inline ClassVar documentation example

Source: https://jsh9.github.io/pydoclint/config_options.html

Shows the required inline documentation format for class attributes when --require-inline-class-var-docs is True. The attribute type is specified as the first token in the docstring followed by a colon.

```python
class MyClass:
    """My class."""

    field1: int = 5
    """int: Field 1 documentation."""

```

--------------------------------

### Accepted Google-style docstring with type hints

Source: https://jsh9.github.io/pydoclint/style_deviations.html

This is an example of a Google-style docstring that is acceptable by pydoclint's default settings. It requires argument types in the docstring and checks return and yield types. You can tweak this behavior with `--arg-type-hints-in-docstring`, `--check-return-types`, and `--check-yield-types`.

```python
"""
This is a function.

Args:
    arg1 (int): Arg 1
    arg2 (float): Arg 2
    arg3 (Optional[Union[float, int, str]]): Arg 3

Returns:
    int: Result
"""

```

--------------------------------

### Sphinx-style class docstring with attribute directives

Source: https://jsh9.github.io/pydoclint/checking_class_attributes.html

Shows a class with a Sphinx-style docstring using .. attribute:: directives for class attributes and :param:/:type: for the __init__ parameter. Works with the same class attribute definitions as the Google-style example.

```python
class MyPet:
    """
    A class to hold information of my pet.

    .. attribute :: name
        :type: str

        Name of my pet

    .. attribute :: age_in_months
        :type: int

        Age of my pet (unit: months)

    .. attribute :: weight_in_kg
        :type: float

        Weight of my pet (unit: kg)

    .. attribute :: is_very_cute_or_not
        :type: bool

        Is my pet very cute?  Or just cute?

    :param airtag_id: The ID of the AirTag that I put on my pet
    :type airtag_id: int
    """
    name: str
    age_in_months: int
    weight_in_kg: float
    is_very_cute_or_not: bool = True

    def __init__(self, airtag_id: int) -> None:
        self.airtag_id = airtag_id

```

--------------------------------

### Accepted numpy-style type annotations

Source: https://jsh9.github.io/pydoclint/style_deviations.html

This is an example of a numpy-style docstring that is accepted by pydoclint. The type hints must look identical to the function signature. The `default=None` part is only expected when `--check-arg-defaults` is `True`.

```text
Parameters
----------
iterable : Iterable[int]
shape : int | tuple[int, ...]
files : list[str]
flag : int | None, default=None

```

--------------------------------

### Unaccepted numpy-style type annotations

Source: https://jsh9.github.io/pydoclint/style_deviations.html

This is an example of a numpy-style docstring that is not accepted by pydoclint because the type hints are ambiguous and not identical to the function signature.

```text
Parameters
----------
iterable : iterable object
shape : int or tuple of int
files : list of str
flag : int, optional

```

--------------------------------

### Register pydoclint with null-ls in Neovim

Source: https://jsh9.github.io/pydoclint/notes_for_users.html

Registers pydoclint as a diagnostic source in Neovim using null-ls. Requires null-ls to be installed first.

```lua
local null_ls = require("null-ls")

null_ls.setup({
    sources = {
        null_ls.builtins.diagnostics.pydoclint,
    },
})

```

--------------------------------

### Unaccepted Google-style default value

Source: https://jsh9.github.io/pydoclint/style_deviations.html

This is an example of a Google-style default value specification that is not accepted by pydoclint.

```text
flag (int, optional): The flag. Defaults to 1

```

--------------------------------

### Accepted Google-style default value

Source: https://jsh9.github.io/pydoclint/style_deviations.html

This is an example of a Google-style default value specification that is accepted by pydoclint. Default values are only expected when `--check-arg-defaults` is `True`; by default, write `flag (int): The flag` instead.

```text
flag (int, default=None): The flag

```

--------------------------------

### Non-runnable Python code example

Source: https://jsh9.github.io/pydoclint/notes_for_users.html

Shows a non-runnable Python snippet (b is undefined) that pydoclint's static syntax analyzer can still parse without executing.

```python
a = b

```

--------------------------------

### Accepted numpy-style default values

Source: https://jsh9.github.io/pydoclint/style_deviations.html

These are examples of numpy-style default value specifications that are accepted by pydoclint. They are only expected when `--check-arg-defaults` is `True`; otherwise, pydoclint reports `DOC105` if you add them.

```text
flag : int | None, default=None
something: int, default=2
onething: bool, default=False

```

--------------------------------

### Configuration to ignore underscore-only class attributes while requiring private ones

Source: https://jsh9.github.io/pydoclint/checking_class_attributes.html

Use this configuration to ignore underscore-only class attributes (like `_`) while still requiring private attributes (like `_value`). The options are set to `false` for private and `true` for underscore-only, as shown in the example.

```ini
ignore-private-class-attributes = false
ignore-underscore-only-class-attributes = true

```

--------------------------------

### Google-style class docstring with Attributes and Args

Source: https://jsh9.github.io/pydoclint/checking_class_attributes.html

Shows a class with a Google-style docstring that includes an Attributes section for class attributes and an Args section for the __init__ parameter. The --allow-init-docstring=True flag permits a separate __init__() docstring.

```python
class MyPet:
    """
    A class to hold information of my pet.

    Attributes:
        name (str): Name of my pet
        age_in_months (int): Age of my pet (unit: months)
        weight_in_kg (float): Weight of my pet (unit: kg)
        is_very_cute_or_not (bool): Is my pet very cute?  Or just cute?

    Args:
        airtag_id (int): The ID of the AirTag that I put on my pet
    """
    name: str
    age_in_months: int
    weight_in_kg: float
    is_very_cute_or_not: bool = True

    def __init__(self, airtag_id: int) -> None:
        self.airtag_id = airtag_id

```

--------------------------------

### Unaccepted numpy-style default values

Source: https://jsh9.github.io/pydoclint/style_deviations.html

These are examples of numpy-style default value specifications that are not accepted by pydoclint.

```text
flag : int, optional
something: int, default 2
onething: bool, default: False

```

--------------------------------

### Configure pydoclint in a .toml file

Source: https://jsh9.github.io/pydoclint/how_to_config.html

Add a [tool.pydoclint] section to a .toml file in your project folder. Include only the configuration options you need.

```toml
[tool.pydoclint]
style = 'google'
exclude = '\.git|\.tox|tests/data|some_script\.py'
require-return-section-when-returning-nothing = true
```

--------------------------------

### NumPy style with --allow-init-docstring=True

Source: https://jsh9.github.io/pydoclint/checking_class_attributes.html

NumPy-style class docstring with Attributes section, and __init__ arguments documented in a separate docstring under __init__ when --allow-init-docstring=True.

```python
class MyPet:
    """
    A class to hold information of my pet.

    Attributes
    ----------
    name : str
        Name of my pet
    age_in_months : int
        Age of my pet (unit: months)
    weight_in_kg : float
        Weight of my pet (unit: kg)
    is_very_cute_or_not : bool
        Is my pet very cute?  Or just cute?
    """
    name: str
    age_in_months: int
    weight_in_kg: float
    is_very_cute_or_not: bool = True

    def __init__(self, airtag_id: int) -> None:
        """
        Initialize a class object.

        Parameters
        ----------
        airtag_id : int
            The ID of the AirTag that I put on my pet
        """
        self.airtag_id = airtag_id

```

--------------------------------

### Run pydoclint natively

Source: https://jsh9.github.io/pydoclint

Runs pydoclint as a native command line tool. Replace <FILE_OR_FOLDER> with the file or folder names you want, such as '.'.

```bash
pydoclint <FILE_OR_FOLDER>

```

--------------------------------

### NumPy style with default --allow-init-docstring=False

Source: https://jsh9.github.io/pydoclint/checking_class_attributes.html

NumPy-style class docstring with Attributes and Parameters sections. With default --allow-init-docstring=False, both sections stay in the class docstring.

```python
class MyPet:
    """
    A class to hold information of my pet.

    Attributes
    ----------
    name : str
        Name of my pet
    age_in_months : int
        Age of my pet (unit: months)
    weight_in_kg : float
        Weight of my pet (unit: kg)
    is_very_cute_or_not : bool
        Is my pet very cute?  Or just cute?

    Parameters
    ----------
    airtag_id : int
        The ID of the AirTag that I put on my pet
    """
    name: str
    age_in_months: int
    weight_in_kg: float
    is_very_cute_or_not: bool = True

    def __init__(self, airtag_id: int) -> None:
        self.airtag_id = airtag_id

```

--------------------------------

### Pre-commit hook configuration to check stub files

Source: https://jsh9.github.io/pydoclint/config_options.html

Override the hook's file types in .pre-commit-config.yaml to include .pyi files. Pre-commit passes files explicitly, so --include-stub-files is not needed.

```yaml
- repo: https://github.com/jsh9/pydoclint
  rev: <latest_tag>
  hooks:
    - id: pydoclint  # or pydoclint-flake8
      types: [file]
      types_or: [python, pyi]

```

--------------------------------

### Run pydoclint with --include-stub-files=True

Source: https://jsh9.github.io/pydoclint/config_options.html

Command-line usage to enable checking of stub files when scanning a folder. The option is only available in native command-line mode; in flake8 use --filename instead.

```bash
pydoclint --include-stub-files=True <FOLDER_NAME>

```

--------------------------------

### Ignore DOC code categories with partial prefix in flake8 mode

Source: https://jsh9.github.io/pydoclint/how_to_ignore.html

In flake8 mode, use a partial prefix like DOC2 to ignore all violations whose codes start with DOC2 (e.g., DOC201, DOC301).

```python
def my_function(  # noqa: DOC2
        arg1,
        arg2,
) -> None:
    ...
```

--------------------------------

### Run pydoclint with a custom config file

Source: https://jsh9.github.io/pydoclint/how_to_config.html

Specify the path of the .toml configuration file when running pydoclint. The default value for --config is pyproject.toml in the project root if not specified.

```bash
pydoclint --config=path/to/my/config.toml <FILE_OR_FOLDER_PATH>
```

--------------------------------

### Allowlist DOC codes in Ruff with external setting

Source: https://jsh9.github.io/pydoclint/how_to_ignore.html

For Ruff >=0.1.3, add this to pyproject.toml to allowlist DOC codes from pydoclint using the external setting.

```toml
[tool.ruff]
external = [
    "DOC",  # pydoclint
]
```

--------------------------------

### pydoclint config file: ignore-underscore-only-args = false

Source: https://jsh9.github.io/pydoclint/config_options.html

Configuration file syntax to set the ignore-underscore-only-args option to false, replacing the removed --ignore-underscore-args option when it was set to false.

```ini
ignore-underscore-only-args = false
```

--------------------------------

### Configure --baseline in pyproject.toml

Source: https://jsh9.github.io/pydoclint/config_options.html

Configure the --baseline option in pyproject.toml to specify the baseline file path. When --generate-baseline is not set (default False), pydoclint reads this file and ignores all violations listed in it.

```toml
[tool.pydoclint]
baseline = "pydoclint-baseline.txt"

```

--------------------------------

### flake8 --style usage

Source: https://jsh9.github.io/pydoclint/config_options.html

Alternative usage of the --style option within flake8, setting the docstring style to google.

```bash
flake8 --style=google <FILE_OR_FOLDER>

```

--------------------------------

### Renaming classmethod to hello

Source: https://jsh9.github.io/pydoclint/notes_for_users.html

Illustrates renaming classmethod to 'hello', a case pydoclint is not designed to handle because it breaks Pythonic naming conventions.

```python
hello = classmethod

class MyClass:
    @hello
    def myClassMethod(cls):
        pass

```

--------------------------------

### Run pydoclint with inline option

Source: https://jsh9.github.io/pydoclint/how_to_config.html

Run pydoclint from the terminal or CI/CD file with an inline option. The equals sign is optional but encouraged for readability.

```bash
pydoclint --check-arg-order=False <FILE_OR_FOLDER_PATH>
```

--------------------------------

### Run pydoclint via Flake8 with inline option

Source: https://jsh9.github.io/pydoclint/how_to_config.html

Run pydoclint via Flake8 with an inline option. The equals sign is optional but encouraged for readability.

```bash
flake8 --check-arg-order=False <FILE_OR_FOLDER_PATH>
```

--------------------------------

### Customize pydoclint with extra_args in null-ls

Source: https://jsh9.github.io/pydoclint/notes_for_users.html

Customizes pydoclint behavior in null-ls by passing extra_args, e.g., --style=google and --check-return-types=False. Adjust extra_args based on your preferred configuration.

```lua
local null_ls = require("null-ls")

null_ls.setup({
    sources = {
        null_ls.builtins.diagnostics.pydoclint.with({
            extra_args = {"--style=google", "--check-return-types=False"},
        }),
    },
})

```

--------------------------------

### Inline class attribute docstring with type prefix

Source: https://jsh9.github.io/pydoclint/checking_class_attributes.html

Demonstrates an inline attribute docstring that begins with the attribute's type and a colon, as defined by PEP 257. Requires --require-inline-class-var-docs=True (default is False) to enforce this form; when enabled, document every class attribute inline and omit the Attributes section.

```python
class MyClass:
    """My class that does things."""

    field1 = 5
    """int: My first field"""

```

--------------------------------

### Run pydoclint as flake8 plugin

Source: https://jsh9.github.io/pydoclint

Runs pydoclint as a flake8 plugin. If you omit --select=DOC, flake8 will also run other built-in flake8 linters on your code.

```bash
flake8 --select=DOC <FILE_OR_FOLDER>

```

--------------------------------

### Use pydoclint as a native pre-commit hook

Source: https://jsh9.github.io/pydoclint/how_to_config.html

Template for using pydoclint as a native pre-commit hook. Replace the rev field with the desired version.

```yaml
- repo: https://github.com/jsh9/pydoclint
  rev: 
  hooks:
    - id: pydoclint
      args:
        - --style=google
        - --check-return-types=False
```

--------------------------------

### Using non-standard self/cls argument names

Source: https://jsh9.github.io/pydoclint/notes_for_users.html

Shows methods using argument names other than self or cls, which pydoclint does not handle.

```python
class MyClass:
    def myMethod(hello, arg1):  # the 1st argument is `self` by convention
        pass

    @classmethod
    def myClassMethod(hey, arg2):  # the 1st argument is `cls` by convention
        pass

```

--------------------------------

### Use pydoclint as a flake8 plugin in pre-commit

Source: https://jsh9.github.io/pydoclint/how_to_config.html

Template for using pydoclint as a flake8 plugin in pre-commit. Replace the rev and pydoclint version placeholders.

```yaml
- repo: https://github.com/pycqa/flake8
  rev: 
  hooks:
    - id: flake8
      additional_dependencies:
        - pydoclint==
      args:
        - --style=google
        - --check-return-types=False
```
Tokens:
Raw