Push to 10/10: shell injection, testing depth, FAQ

Closing the gap from 9.4 to 10:

1. Shell command injection: /check now runs check-structure.py automatically
   via ${CLAUDE_SKILL_DIR}, giving Claude real audit data instead of improvising
2. Testing depth: added 12-testing-mocking.md (pytest-mock, monkeypatch,
   HTTP mocking, anti-patterns) and 13-testing-snapshots.md (syrupy, CLI output)
3. FAQ: added 14-faq.md answering 12 pushback questions (why hatchling,
   why not poetry, why src layout, why rich, why ruff not black, etc.)
4. No-args assessment now runs automated audit first, then manual review

14 reference docs total. All within token budget (200/500 lines, ~1900 tokens).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: Naareman

skills/python-package-development/SKILL.md

@@ -36,6 +36,9 @@ relevant reference file from `references/`:
 | Adding a CLI to your package | [references/09-cli-entry-points.md](references/09-cli-entry-points.md) |
 | Managing a monorepo / namespace packages | [references/10-monorepo.md](references/10-monorepo.md) |
 | Automating releases (bump, changelog, CI) | [references/11-automated-release.md](references/11-automated-release.md) |
+| Mocking in tests (APIs, filesystem, time) | [references/12-testing-mocking.md](references/12-testing-mocking.md) |
+| Snapshot testing | [references/13-testing-snapshots.md](references/13-testing-snapshots.md) |
+| FAQ (why these opinions?) | [references/14-faq.md](references/14-faq.md) |
 
 Read only what's relevant to the current task. Don't load everything at once.
 
@@ -113,20 +116,25 @@ When invoked with `/python-package-development <subcommand>`, route based on the
 | `/python-package-development docs` | Read [references/04-docs.md](references/04-docs.md) and set up or improve documentation |
 | `/python-package-development lifecycle` | Read [references/05-lifecycle.md](references/05-lifecycle.md) and manage deprecations |
 | `/python-package-development release` | Read [references/06-release.md](references/06-release.md) and walk through the release ritual |
-| `/python-package-development check` | Read [references/07-common-mistakes.md](references/07-common-mistakes.md) and audit current project for anti-patterns |
+| `/python-package-development check` | Run `python ${CLAUDE_SKILL_DIR}/../../scripts/check-structure.py .` then read [references/07-common-mistakes.md](references/07-common-mistakes.md) to fix any failures |
 | `/python-package-development pre-commit` | Read [references/08-pre-commit.md](references/08-pre-commit.md) and set up pre-commit hooks |
 | `/python-package-development cli` | Read [references/09-cli-entry-points.md](references/09-cli-entry-points.md) and add a CLI to the package |
 | `/python-package-development` (no args) | Assess the current project against all five principles (see checklist below) |
 
-When invoked without a subcommand (auto-triggered or plain `/python-package-development`), run this assessment:
+When invoked without a subcommand (auto-triggered or plain `/python-package-development`):
 
-1. **Structure** — Is there a `src/` layout? Does `__init__.py` have `__all__`?
-2. **Communication** — Is there an `errors.py` with a base exception? A `_messages.py` with `rich`?
-3. **Naming** — Do public functions follow `verb_noun()`? Are families consistent?
-4. **Documentation** — Do all public functions have Google-style docstrings?
-5. **Lifecycle** — Is `__version__` from `importlib.metadata`? Is there a CHANGELOG?
+**Step 1 — Automated audit.** Run the convention checker if available:
+```
+python ${CLAUDE_SKILL_DIR}/../../scripts/check-structure.py .
+```
+
+**Step 2 — Manual review** of things the script can't check:
+1. **Naming** — Do public functions follow `verb_noun()`? Are families consistent?
+2. **Documentation** — Do all public functions have Google-style docstrings with Args/Returns/Raises?
+3. **Messages** — Is `_messages.py` actually used? Any bare `print()` calls?
+4. **Lifecycle** — Is `__version__` from `importlib.metadata`? Any undocumented breaking changes?
 
-Then use the Quick Decision Guide below for any specific improvements.
+**Step 3 — Suggest improvements** using the Quick Decision Guide below.
 
 ---
 

skills/python-package-development/references/12-testing-mocking.md

@@ -0,0 +1,149 @@
+# 12 — Testing: Mocking
+
+R equivalent: `testthat::local_mocked_bindings()`, `httptest2`, `webfakes`. The goal is
+the same: isolate your code from things you don't control.
+
+---
+
+## When to Mock
+
+Mock **external boundaries** — things that are slow, flaky, or have side effects:
+
+- HTTP APIs and web services
+- File systems (when testing logic, not I/O)
+- Time (`datetime.now()`, `time.time()`)
+- Databases and caches
+- Environment variables
+
+Do **not** mock:
+
+- Your own package code (test the real thing)
+- Standard library basics (don't mock `len()` or `dict.get()`)
+- Simple data transformations (just assert the output)
+
+---
+
+## pytest-mock — The Preferred Approach
+
+Use `pytest-mock` over raw `unittest.mock`. It gives you a `mocker` fixture that
+auto-cleans up after each test.
+
+```bash
+uv add --dev pytest-mock
+```
+
+```python
+def test_fetch_data_calls_api(mocker):
+    mock_get = mocker.patch("my_package.client.httpx.get")
+    mock_get.return_value.json.return_value = {"status": "ok"}
+
+    result = fetch_data("https://api.example.com/data")
+
+    mock_get.assert_called_once_with("https://api.example.com/data")
+    assert result == {"status": "ok"}
+```
+
+### Common mocker methods
+
+```python
+mocker.patch("module.path.function")          # replace a function
+mocker.patch.object(obj, "method")            # replace a method on an object
+mocker.patch.dict("os.environ", {"KEY": "v"}) # patch a dict
+mocker.spy(obj, "method")                     # wrap real method, track calls
+```
+
+---
+
+## MagicMock Basics
+
+When you need a stand-in object that accepts any attribute or call:
+
+```python
+def test_processor_calls_writer(mocker):
+    writer = mocker.MagicMock()
+    processor = DataProcessor(writer=writer)
+
+    processor.run(records=[{"id": 1}])
+
+    writer.write.assert_called_once()
+    assert writer.write.call_args[0][0] == [{"id": 1}]
+```
+
+---
+
+## Mocking HTTP Calls
+
+For packages that hit APIs, use `responses` (for `requests`) or `respx` (for `httpx`).
+
+```bash
+uv add --dev responses   # if using requests
+uv add --dev respx       # if using httpx
+```
+
+### With responses
+
+```python
+import responses
+
+@responses.activate
+def test_fetch_users():
+    responses.add(
+        responses.GET,
+        "https://api.example.com/users",
+        json=[{"id": 1, "name": "Alice"}],
+        status=200,
+    )
+    result = fetch_users()
+    assert len(result) == 1
+    assert result[0]["name"] == "Alice"
+```
+
+### With respx
+
+```python
+import respx
+import httpx
+
+def test_fetch_users(respx_mock):
+    respx_mock.get("https://api.example.com/users").mock(
+        return_value=httpx.Response(200, json=[{"id": 1, "name": "Alice"}])
+    )
+    result = fetch_users()
+    assert result[0]["name"] == "Alice"
+```
+
+---
+
+## monkeypatch — Environment and Attributes
+
+Built into pytest. Best for environment variables and simple attribute swaps.
+
+```python
+def test_reads_api_key_from_env(monkeypatch):
+    monkeypatch.setenv("API_KEY", "test-key-123")
+    config = load_config()
+    assert config.api_key == "test-key-123"
+
+
+def test_handles_missing_api_key(monkeypatch):
+    monkeypatch.delenv("API_KEY", raising=False)
+    with pytest.raises(ConfigError, match="API_KEY"):
+        load_config()
+```
+
+Use `monkeypatch` for env vars. Use `mocker.patch` for replacing functions and methods.
+
+---
+
+## Anti-Patterns
+
+1. **Mocking everything** — if a test mocks five things, it tests nothing. Mock only
+   the boundary, then assert real behavior.
+2. **Mocking implementation details** — don't mock internal helpers. If you refactor
+   internals, tests shouldn't break.
+3. **Brittle return chains** — `mock.return_value.foo.return_value.bar` is a sign
+   you're testing the mock, not your code. Simplify the interface.
+4. **Forgetting to assert calls** — a mock that's never checked is just dead code.
+   Always verify the mock was actually used.
+5. **Patching the wrong path** — patch where the name is *looked up*, not where it's
+   *defined*. Patch `my_package.client.httpx.get`, not `httpx.get`.

skills/python-package-development/references/13-testing-snapshots.md

@@ -0,0 +1,102 @@
+# 13 — Testing: Snapshots
+
+R equivalent: `testthat::expect_snapshot()`. Snapshot tests capture complex output once,
+then verify it doesn't change unexpectedly.
+
+---
+
+## When to Use Snapshots
+
+Use them when the expected output is **complex, verbose, or tedious to write by hand**:
+
+- Serialized data structures (JSON, YAML, dictionaries)
+- Error messages and exception formatting
+- CLI output and help text
+- Rendered templates or reports
+- Complex string representations (`__repr__`, `__str__`)
+
+Do **not** use snapshots for:
+
+- Simple equality checks (`assert x == 42` is clearer)
+- Output that changes frequently (timestamps, random IDs)
+- Performance-sensitive values (thresholds belong in explicit assertions)
+
+---
+
+## syrupy — Recommended Library
+
+`syrupy` is the most actively maintained snapshot library for pytest.
+
+```bash
+uv add --dev syrupy
+```
+
+### Basic usage
+
+```python
+def test_report_output(snapshot):
+    result = generate_report(year=2025, quarter=1)
+    assert result == snapshot
+```
+
+On first run, syrupy creates a snapshot file in `__snapshots__/` next to your test file.
+On subsequent runs, it compares the output against the stored snapshot.
+
+### Snapshot of a specific attribute
+
+```python
+def test_error_message(snapshot):
+    with pytest.raises(ValidationError) as exc_info:
+        validate(bad_data)
+    assert str(exc_info.value) == snapshot
+```
+
+---
+
+## Updating Snapshots
+
+When output changes intentionally, update the stored snapshots:
+
+```bash
+uv run pytest --snapshot-update
+```
+
+Always **review the diff** before committing updated snapshots. Treat snapshot updates
+like code review — the diff should make sense.
+
+---
+
+## CLI Output Snapshots
+
+Particularly useful for packages with a CLI interface:
+
+```python
+from click.testing import CliRunner
+
+def test_help_output(snapshot):
+    runner = CliRunner()
+    result = runner.invoke(cli, ["--help"])
+    assert result.output == snapshot
+
+
+def test_error_output(snapshot):
+    runner = CliRunner()
+    result = runner.invoke(cli, ["bad-command"])
+    assert result.output == snapshot
+    assert result.exit_code == 2
+```
+
+---
+
+## Snapshot File Hygiene
+
+- Commit `__snapshots__/` directories to version control
+- Run `uv run pytest --snapshot-update` to remove orphaned snapshots
+- Keep snapshots small — if a snapshot is 500 lines, consider testing individual
+  components instead
+- Add `__snapshots__/` to your `.gitattributes` as `linguist-generated` so they
+  don't clutter pull request diffs
+
+```gitattributes
+**/__snapshots__/** linguist-generated=true
+```

skills/python-package-development/references/14-faq.md

@@ -0,0 +1,90 @@
+# 14 — FAQ
+
+Pushback you'll get on these conventions, and why we made the choices we did.
+
+---
+
+## Build System
+
+### Why hatchling and not setuptools?
+
+Simpler config, sane defaults, faster builds. Setuptools requires more boilerplate and has
+legacy baggage (`setup.py`, `setup.cfg`, `MANIFEST.in`). Hatchling reads `pyproject.toml`
+natively with zero extra files.
+
+### Why not poetry?
+
+Poetry uses its own lock format and dependency resolver that conflicts with PEP standards.
+uv is faster, PEP-compliant, and gaining rapid adoption. Poetry is fine — but we pick one,
+and we pick the one aligned with standards.
+
+---
+
+## Tooling
+
+### Why uv and not pip?
+
+uv is 10-100x faster than pip, handles venvs automatically, supports workspaces, and is the
+direction the ecosystem is heading. pip still works but uv is strictly better for development.
+
+### Why no black/isort/flake8?
+
+Ruff replaces all three. It's faster, has fewer config files, and maintains compatibility.
+There's no reason to use the originals anymore.
+
+### Why PEP 735 dependency-groups instead of `[tool.uv.dev-dependencies]`?
+
+PEP 735 is the standard. `[tool.uv.dev-dependencies]` is a uv-specific legacy convention.
+Standards last longer than tool conventions.
+
+---
+
+## Code Style
+
+### Why Google docstrings and not NumPy or Sphinx style?
+
+Readable without rendering. Google style is the most compact and works well with mkdocstrings.
+NumPy style is verbose. Sphinx style uses RST which is dying.
+
+### Why rich and not just `print()`?
+
+Structured output, consistent styling, stderr separation, progress bars. When your package
+talks to users, it should speak clearly. R's `cli` package proved this matters.
+
+---
+
+## Project Structure
+
+### Why src layout?
+
+Prevents importing from the source directory instead of the installed package. Without it,
+tests can pass locally but the installed package is broken. This is a solved problem — use
+`src/`.
+
+### Why `errors.py` without underscore but `_messages.py` with underscore?
+
+`errors.py` is public API — users import and catch your exceptions directly. `_messages.py`
+is internal — users never interact with it. The underscore convention signals this.
+
+---
+
+## Scope
+
+### Why not add pandas/numpy as default dependencies?
+
+Not every package is a data science package. The scaffold includes only `rich` (for user
+communication). Add domain-specific deps yourself.
+
+### What if I need a CLI?
+
+See reference `09-cli-entry-points.md`. Use `click` for multi-command CLIs, `argparse` for
+simple ones.
+
+---
+
+## Adoption
+
+### Can I use this with an existing project?
+
+Yes. Run `/python-package-development check` to audit your project, then address the gaps
+one by one. You don't need to start from scratch.