Skip to content

undocumented-init-params

Part of: Enrichment Check
Check enrichment
Category required
Applies to classes
Since v1.14.0

Class init has parameters but no Args section in class or init docstring

What it detects

This rule flags classes whose __init__ method takes parameters beyond self, but neither the class docstring nor the __init__ docstring contains an Args: section. Either location satisfies the check.

Structural types (@dataclass, NamedTuple, TypedDict) whose __init__ is auto-generated are naturally skipped because the generated __init__ does not appear in the source code.

Why is this a problem?

Without documented constructor parameters, users must read the __init__ source to understand how to instantiate the class. API documentation generated by mkdocstrings will show parameters without descriptions, and IDE tooltips will lack context.

Documenting __init__ parameters in either the class docstring or the __init__ docstring (but not both) follows the Google Python Style Guide's recommendation.

How to Fix

Add an Args: section documenting the constructor parameters in either the class docstring or the __init__ docstring:

class Server:
    """A network server.

    Args:
        host: The server hostname.
        port: The server port number.
    """

Or document them in the __init__ docstring instead:

def __init__(self, host, port):
    """Initialize the server.

    Args:
        host: The server hostname.
        port: The server port number.
    """

Either location is sufficient — you don't need both.

Example

class Server:
    """A network server."""

    def __init__(self, host, port, timeout=30):
        self.host = host
        self.port = port
        self.timeout = timeout

class Server:
    """A network server.

    Args:
        host: The server hostname.
        port: The server port number.
        timeout: Connection timeout in seconds. Defaults to 30.
    """

    def __init__(self, host, port, timeout=30):
        self.host = host
        self.port = port
        self.timeout = timeout

class Server:
    """A network server."""

    def __init__(self, host, port, timeout=30):
        """Initialize the server.

        Args:
            host: The server hostname.
            port: The server port number.
            timeout: Connection timeout in seconds. Defaults to 30.
        """
        self.host = host
        self.port = port
        self.timeout = timeout

Configuration

This rule is opt-in and disabled by default. Enable it in pyproject.toml:

[tool.docvet.enrichment]
require-init-params = true

When exclude-args-kwargs = true (the default), *args and **kwargs are excluded from the parameter count, so a pass-through __init__(self, *args, **kwargs) will not trigger the rule.