placard 2026.5.30.83589

Install

pip install placard

placard registers itself with flake8 via the flake8.extension entry point. Once installed, flake8 discovers it automatically; no extra configuration is needed to start emitting PLC codes.

What it checks

placard does one job: given a docstring that exists, check that it is shaped the way the Google style guide demands. It does not decide whether a docstring should exist, and it does not check whether the docstring’s contents are true about the code.

Recognized section headers: Args:, Attributes:, Raises:, Returns:, Yields:. Attributes: is included because Google style uses it in class docstrings to document instance attributes (e.g. dataclass fields), using the same name: description shape as Args: entries.

Types belong in the signature

placard requires Args: entries in the bare name: description form and rejects name (type): description. Every consumer of a docstring that cares about types already has the signature – IDEs, help(), Sphinx autodoc, mkdocstrings, pydoc – so a parenthesized type in the docstring duplicates information already visible an inch above, with the added cost of having to stay in sync.

This is the one place placard is more opinionated than the published Google spec, which calls both forms canonical. Projects that prefer the typed form can # noqa: PLC301 on the entries that use it.

Works with pydoclint

Two tools, one flake8 invocation, no overlap:

• placard (PLC) – is the docstring shaped correctly?

• pydoclint (DOC) – does the docstring agree with the code?

A lowercase args: with a ragged body is correct-by-pydoclint, wrong-by-placard. A perfectly formatted Args: block missing half the parameters is correct-by-placard, wrong-by-pydoclint. The prefixes differ, so the two compose cleanly in one flake8 run.

A placard-aligned pydoclint invocation:

pydoclint \
    --style=google \
    --skip-checking-short-docstrings=False \
    --arg-type-hints-in-docstring=False \
    --check-return-types=False \
    --check-yield-types=False \
    src/

--skip-checking-short-docstrings=False makes pydoclint reject description-only docstrings on functions that take arguments; the remaining flags align with placard’s opinion that types belong in the signature, not the docstring.