pylint-gajaguar
Opinionated lint rules that encode review preferences beyond ruff, as a ferrolint plugin.
From 3.0.0 the package only works with ferrolint. It no longer loads in Pylint. Pin
pylint-gajaguar==2.0.3, the last version for Pylint, to keep using it there.
Table of Contents
- About
- Key features
- Requirements
- Usage
- Getting started
- Architecture
- Built with
- Configuration
- Contributing
- Security
- License
About
Ruff with lint.select = ["ALL"] covers lint hygiene but leaves
review-time preferences unenforced: no docstrings on functions, mandatory
AAA section markers inside tests, Final annotations on module-level
constants, and similar project-specific rules. Restating these in code
review is repetitive and lossy.
This plugin encodes those preferences as 14 ferrolint rules. Each keeps the Pylint msg-id and symbol it had in 2.0.3 as an alias.
Key features
- 14 rules: docstrings, AAA test markers, blank-line discipline, imports,
naming,
Finalannotations,frozensetconstants, andcontextlib.suppress. - Test-scoped rules: the
gajaguar-test-*rules apply only to files namedtest_*.pyor*_test.py, or under a directory namedtestortests. - Configurable section markers: tune the AAA markers with the
test-section-markersoption. - No Python dependencies: the wheel carries one WASM component, built from the Rust crate in this repository.
Requirements
ferrolint 1.1.0 or later. To build
from source: Rust with the wasm32-wasip2 target, uv
and, for the Markdown lint and spell targets, pnpm.
Usage
Install the package into the virtual environment that ferrolint reads:
uv pip install pylint-gajaguar
ferrolint finds the plugin only through VIRTUAL_ENV, and loads it only when
load-plugins names it. In pyproject.toml:
[tool.pylint.main]
load-plugins = ["pylint_gajaguar"]
Then run ferrolint in the project. Every rule is on; ferrolint does not read
the Pylint checker name, so enable = ["gajaguar"] selects nothing. Narrow the
set with select and ignore in ferrolint.toml, for example
ignore = ["GAJ016", "GAJ017"] to drop the two advisory rules.
See ferrolint plugin for the codes, how the plugin is built and tested, and where it differs from 2.0.3.
Getting started
Use in another project
Follow Usage.
Develop this repository
git clone https://github.com/gajaguar/pylint-gajaguar.git
cd pylint-gajaguar
make install
make help
make check is the read-only gate, make fix applies safe fixes and
make test runs the plugin over the fixtures with ferrolint on PATH
(uv tool install ferrolint==1.1.0). make wheel builds the wheel into
dist/.
Architecture
ferrolint (load-plugins = ["pylint_gajaguar"])
-> ferrolint.plugins entry point -> python/pylint_gajaguar/plugin.wasm
-> src/lib.rs: registers each rule module (one file per rule)
tests/fixtures/<CODE>*/ -> *.py inputs + expected findings per rule
The crate builds to target/wasm32-wasip2/release/pylint_gajaguar.wasm;
make plugin copies it into the pylint_gajaguar package, which hatchling
packs into a py3-none-any wheel with the ferrolint.plugins entry point.
Built with
- Rust and the ferrolint plugin SDK — the rules
- hatchling and uv — the wheel
- clippy, rustfmt and cargo-deny — Rust checks
- markdownlint-cli2 and cspell via pnpm (dev-only) — Markdown lint and spell
- pre-commit — git hook runner
Configuration
Rule reference
| Code | Rule (name) |
Pylint | Enforces |
|---|---|---|---|
GAJ001 |
gajaguar-no-docstrings |
W9001 |
No docstrings on functions, methods, or classes (use comments) |
GAJ002 |
gajaguar-test-aaa-markers |
W9002 |
test_* bodies contain # Arrange, # Act, # Assert |
GAJ003 |
gajaguar-test-no-blank-lines |
W9003 |
No blank lines inside test method bodies |
GAJ004 |
gajaguar-unused-arg-use-del |
W9004 |
Use del arg at body top, not a _-prefixed arg |
GAJ005 |
gajaguar-module-const-naming |
C9005 |
Module-level names are SCREAMING_SNAKE_CASE |
GAJ006 |
gajaguar-no-file-level-disable |
W9006 |
No standalone # pylint: disable=; use inline / disable-next |
GAJ008 |
gajaguar-no-inline-imports |
W9008 |
Imports at module top, not inside functions |
GAJ009 |
gajaguar-no-relative-imports |
W9009 |
Absolute imports only |
GAJ012 |
gajaguar-use-contextlib-suppress |
W9012 |
contextlib.suppress(...) over try/except/pass |
GAJ013 |
gajaguar-frozenset-constant |
W9013 |
Module-level set constants use frozenset(...) |
GAJ014 |
gajaguar-require-final |
C9014 |
Module-level constants carry a Final annotation |
GAJ015 |
gajaguar-test-no-extra-comments |
W9015 |
Test bodies carry only the configured section markers |
GAJ016 |
gajaguar-test-partial-assertion |
W9016 |
Field assertions without a whole-object assertion (advisory) |
GAJ017 |
gajaguar-test-name-implementation-detail |
W9017 |
Test names naming mocks, patches, internals (advisory) |
gajaguar-test-partial-assertion and gajaguar-test-name-implementation-detail
use heuristics with a measurable false-positive rate; treat their output
as advisory, not a hard gate.
Options
| Option | Type | Default | Description |
|---|---|---|---|
test-section-markers |
csv | Arrange,Act,Assert |
Section names a test body must carry, in order, without the # mark. |
Set it as a configuration option ([options] in ferrolint.toml), or in the
options table of a [[plugins]] entry. The TEST_SECTION_MARKERS
environment variable of 2.0.3 is gone. See
ferrolint plugin.
Test scoping
The gajaguar-test-* rules activate only on files matching one of these:
- Stem starts with
test_(e.g.test_module.py) - Stem ends with
_test(e.g.module_test.py) - Any parent directory is named
testortests
Files outside those paths are skipped entirely. Function-scoping applies
on top: a test_* function inside a test file is checked; a helper
function in the same file is not. Run ferrolint from the project root.
Contributing
Read CONTRIBUTING.md for the local setup, the conventions and the procedure for adding a rule.
Security
Report vulnerabilities privately by email to dev@gajaguar.com. Do not open a public issue, pull request, or discussion.
See SECURITY.md for supported versions and the reporting process.
License
Distributed under the MIT License. See LICENSE for the full text.
Metadata
Release files for pylint-gajaguar 3.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pylint_gajaguar-3.0.0-py3-none-any.whl | Python 3 | none | any | Details for pylint_gajaguar-3.0.0-py3-none-any.whl |
Release files / pylint_gajaguar-3.0.0-py3-none-any.whl
| Download URL | pylint_gajaguar-3.0.0-py3-none-any.whl |
|---|---|
| Size | 78.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
bb370b05908bb551d5f70f28627b9ee7d4cc7c249fb8a7f8238d28b07e32ae56
|
|
BLAKE2b-256 checksum How to use checksums |
213a4e5973b8580482b9050384b61a24336ecc7d79b4a18bc5d19a61e0c5cf04
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.
Transparency logSecurity for pylint-gajaguar 3.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
1 file in this release has been uploaded with provenance metadata.
Attestation for pylint_gajaguar-3.0.0-py3-none-any.whl
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.