just-init
just-init
Use __init__.py docstrings as the single source of truth for navigating and
documenting Python packages.
Read Rule
When navigating to a new directory in the codebase, first extract its
__init__.py docstring to understand the package:
grep -nE "^(\"\"\"|''')" <file> | head -2to get the opening and closing line numbers.- Read the file with those line numbers as offset (start line) and limit (number of lines).
Use the docstring tree to decide which files to explore next. Apply recursively when entering sub-packages.
Docstring Format
Every __init__.py must start with a triple-quoted docstring:
"""
One-line description of what this package does.
package_name/
├── __init__.py # Package init and public exports.
├── module_a.py # Brief description of module_a.
├── module_b.py # Brief description of module_b.
└── subpackage/ # Brief description of subpackage.
"""
Rules:
├──for all entries except the last (└──)..pyfiles first (alphabetical), then subdirectories (alphabetical).- Subdirectories end with
/and are not expanded here. - Descriptions under 10 words. Package name matches the directory name.
- Non-Python directories (data, fixtures): list with trailing
/, no__init__.py.
Update Rule
After any file or directory add, remove, or rename inside a package,
immediately update the affected __init__.py docstring. When creating a new
package, create __init__.py with its docstring first, then add other files.
Propagate changes: update both the sub-package's __init__.py and the parent's
if the sub-package entry changed.
Missing docstring: when encountering an __init__.py without a docstring,
generate one from the current directory contents before proceeding.
Outdated docstring: if the docstring does not match actual files, update it to reflect reality before continuing.