| name | python-writer |
| description | Use when writing or modifying Python code. Apply when adding functions, fixing bugs, or implementing features. |
Python Writer
Overview
Write Python code consistent with my conventions.
Core Workflow
Step 1 — Do you really need Python?
Goal: Confirm Python is the right choice.
Exit criterion: Python is unavoidable for this task.
I prefer zsh (through /zsh-writer) for simple scripts or JavaScript (through /js-writer) for more complex modules.
Python is warranted only when a library or runtime has no ZSH/JS equivalent (e.g. kitty config)
If you can solve the problem in ZSH or JS — do that instead, and stop here.
Step 2 — Place the file
Goal: Correct structure around the file.
Exit criterion: Source file, __tests__/, and conftest.py are colocated.
- Place the source file wherever it belongs for the project.
- Put tests in a
__tests__/ sibling directory, named test_<module>.py.
- Place
conftest.py and pyproject.toml at the project root.
Step 3 — TDD: Write a failing test
Goal: Ensure the bug/feature has a failing test first.
Exit criterion: Test fails.
Write a failing test for the bug or missing feature you want to implement.
- Test file:
test_<module>.py in a __tests__/ sibling directory
- Run
python-test <filepath> to run the tests
- See Testing for full examples and best practices
def test_returns_slugified_name():
result = slugify("Hello World")
assert result == "hello-world"
Step 4 — Make it work
Goal: Minimal code that makes the test pass.
Exit criterion: Test passes.
Write the simplest code that makes the test green. Don't optimize yet.
Run python-test <filepath> to confirm.
Step 5 — Refactor
Goal: Clean code that still passes.
Exit criterion: Tests still pass, patterns applied.
Apply patterns from Style:
| Pattern | Rule |
|---|
| Return early | No avoidable nesting |
Run python-test <filepath> to confirm tests still pass.
Step 6 — Lint
Goal: Automated style gate.
Exit criterion: Lint passes.
- Run
python-lint --fix <file> on any modified .py files
- Fix every remaining violation
Common Rationalizations
| Rationalization | Reality |
|---|
| "Python is fine for this, it's just a small script." | Prefer ZSH or JS first. Python only when a library or runtime forces it. |
| "It's only two levels of if/else, it's ok." | No it's not. Return early, always. |
Checklist
