# Python Code Style Guide

> Style rules for Python code under `skills/ppt-master/scripts/` and any Python that ships with the skill. Derived from the de facto patterns in the existing codebase.

These rules are pragmatic, not exhaustive. They capture the conventions readers actually encounter — anything PEP 8 hands you for free is assumed.

---

## 1. File Header

Every script under `scripts/` starts with:

```python
#!/usr/bin/env python3
"""
PPT Master - Short Tool Name

One-paragraph description of what this script does.

Usage:
    python3 scripts/<name>.py <required_arg> [options]

Examples:
    python3 scripts/<name>.py projects/<project_name> -o output_dir

Dependencies:
    None (only uses standard library)        <-- or list third-party deps
"""
```

| Element | Rule |
|---|---|
| Shebang | `#!/usr/bin/env python3` (always — even for non-CLI helper modules) |
| Module docstring | Tool name + purpose + Usage + Examples + Dependencies |
| Internal helper modules | May add an early `--help` short-circuit (see §4) |

---

## 2. Imports

```python
# 1. Standard library
import os
import sys
import argparse
import re
from pathlib import Path
from typing import Optional

# 2. Third-party
import requests

# 3. Local — sometimes need sys.path injection first (see §3)
from image_sources.provider_common import (
    AssetCandidate,
    ImageSearchRequest,
)
```

| Rule | Note |
|---|---|
| Group order | std → third-party → local, blank line between groups |
| Within a group | Sorted by length when short; alphabetical when ≥ 4 imports |
| `from x import` lists | One name per line if ≥ 4 names, with trailing comma |
| `from __future__ import annotations` | Add at top when the file uses `X \| Y` union syntax (PEP 604) and may run on Python < 3.10 |

---

## 3. sys.path Injection (Project Convention)

`scripts/` is **not a Python package** — it's a flat directory of scripts. Each entry-point script that imports a sibling module injects `scripts/` onto `sys.path` itself:

```python
import sys
from pathlib import Path

_SCRIPTS_DIR = Path(__file__).resolve().parent
if str(_SCRIPTS_DIR) not in sys.path:
    sys.path.insert(0, str(_SCRIPTS_DIR))

from image_backends.backend_common import download_image  # noqa: E402
```

| Rule | Why |
|---|---|
| Inject only in entry-points | Library modules under `image_sources/` / `image_backends/` import each other normally |
| Use `Path(__file__).resolve().parent` | Robust under symlinks and aliasing |
| Annotate post-injection imports with `# noqa: E402` | Suppress the lint warning honestly, not via per-file noqa |

---

## 4. CLI Entry Points

```python
def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(
        description="One-line description.",
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )
    parser.add_argument("query", help="...")
    parser.add_argument("-o", "--output", default=".", help="...")
    return parser


def main(argv: Optional[list[str]] = None) -> int:
    parser = build_parser()
    args = parser.parse_args(argv)
    # ... do the thing ...
    return 0


if __name__ == "__main__":
    raise SystemExit(main())
```

| Rule | Note |
|---|---|
| `main(argv=None) -> int` | Returns exit code; testable by passing `argv` |
| `raise SystemExit(main())` | Preferred over `sys.exit(main())` |
| `formatter_class=argparse.RawDescriptionHelpFormatter` | Preserves docstring formatting in `--help` |
| Internal helpers `--help` | Module-level: `if __name__ == "__main__" and any(arg in {"-h", "--help", "help"} for arg in sys.argv[1:]): print(__doc__); raise SystemExit(0)` |
| Output | Progress / status to **stderr**; the script's primary output (if any) to stdout |

**Help and argument validation requirements**:

- `-h` / `--help` must be handled by `argparse` (preferred) or an explicit early helper guard before any side effect: no directory creation, file writes, network calls, package installs, or long-running servers.
- Help flags must never be accepted as positional values. Examples: `init --help` must not create a project named `--help`; `export --help` must not write a file named `--help`.
- Scripts with subcommands use `argparse` subparsers. Each subcommand must provide its own help (`<script> <subcmd> --help`) and validate its own required arguments before doing work.
- Missing required arguments and unknown flags must print a usage/error message and exit non-zero. Do not silently ignore unknown flags or continue with partial defaults.
- For internal helper modules that are directly executable only for diagnostics, non-help invocation should either run a documented diagnostic command or print a short "use via ..." message and exit non-zero; it must not fail with an import traceback.

**Console encoding**:

- Every directly-runnable entry script must call `configure_utf8_stdio()` (from `console_encoding.py`, §9) once at startup, before any user-facing print or before importing optional dependencies that may print. It forces `stdout`/`stderr` to UTF-8 with `errors="replace"` so non-UTF-8 Windows locales (e.g. GBK) do not crash on Unicode status output. On systems already using UTF-8 it leaves the effective encoding unchanged.
- Subdirectory scripts inject the scripts root onto `sys.path` first (§3), then import the helper. Pure library modules with no `__main__` entry do not need it. File I/O still passes `encoding="utf-8"` explicitly (§13); this rule only covers the console.

---

## 5. Type Hints

Required for all new public functions; optional for internal `_helpers`.

| Pattern | Use |
|---|---|
| `def f(x: str, *, y: int = 0) -> bool:` | Public functions |
| `tuple[int, int] \| None` | PEP 604 unions (with `from __future__ import annotations` if needed for compat) |
| `Optional[X]` from `typing` | Acceptable alternative to `X \| None` |
| `list[X]`, `dict[K, V]` | Built-in generics (Python 3.9+) |
| `Any` | Sparingly — only when interfacing with truly heterogeneous data (`raw: Any` in dataclasses for upstream JSON) |

**Forbidden — over-specification**:

- `Callable[[int, str], dict[str, list[Optional[Union[int, str]]]]]` — break this into typed dataclasses
- `Literal["a", "b", "c"]` everywhere — use a constant + plain `str` unless the type itself is the API

---

## 6. Naming

| Kind | Convention | Examples |
|---|---|---|
| Module file | `snake_case.py` | `image_search.py`, `svg_to_pptx.py` |
| Script entrypoint | verb or noun phrase | `finalize_svg.py`, `notes_to_audio.py` |
| Public function | `snake_case` | `download_image`, `parse_results` |
| Private helper | `_snake_case` | `_load_dotenv_if_available`, `_measure_actual_image` |
| Constant | `UPPER_SNAKE_CASE` | `API_URL`, `DEFAULT_PAGE_SIZE`, `LICENSE_TIER_NO_ATTRIBUTION` |
| Class | `PascalCase` | `AssetCandidate`, `SVGQualityChecker` |
| Dataclass field | `snake_case` | `license_tier`, `download_url` |
| Module-private regex | `_PATTERN_RE` (private + `_RE` suffix) | `_TAG_RE`, `HEADING_RE` |

---

## 7. Error Handling

| Situation | Pattern |
|---|---|
| Optional dependency | `try: import x; HAS_X = True\nexcept ImportError: HAS_X = False` |
| Optional sibling module | `try: from project_utils import CANVAS_FORMATS\nexcept ImportError: CANVAS_FORMATS = {}; print("Warning: ...")` |
| Recoverable runtime failure | Catch specific exceptions, log to stderr, return / continue — do NOT halt the pipeline |
| User-facing error | `print("...", file=sys.stderr); return 1` from `main()` |
| Programming error | Raise — don't paper over a bug |

**Hard rule**: never bare-`except:`. Always name the exception class.

**Forbidden — silent fallbacks for security-relevant code**:

- Disabling SSL verification without a domain whitelist + WARNING
- Catching all exceptions in a download path without logging the cause

---

## 8. Dependencies

| Tier | Where it can be required |
|---|---|
| Standard library | Anywhere |
| `requests`, `Pillow`, `lxml` | Common dependencies; safe to require in main scripts |
| Provider SDKs (`google-genai`, `openai`, `anthropic`, etc.) | **Lazy import inside the function that uses it**; soft-fail with `ImportError` → `RuntimeError` containing install instructions |
| `python-dotenv` | Optional — wrap the import in try/except, no-op if unavailable |

```python
def _require_api_key() -> str:
    key = os.environ.get("PEXELS_API_KEY") or ""
    if not key:
        raise RuntimeError(
            "PEXELS_API_KEY is not set. Add it to your environment or .env file. "
            "Get one at https://www.pexels.com/api/"
        )
    return key
```

Error messages **must include the fix** — "what env var to set", "where to get a key", "which package to install".

---

## 9. Shared Helpers Layer

Common functionality lives in these designated submodules. New scripts use these, not their own copies:

| Module | Owns |
|---|---|
| [`image_backends/backend_common.py`](../../skills/ppt-master/scripts/image_backends/backend_common.py) | HTTP download, retry, image format detection, save-with-Pillow-transcode |
| [`image_sources/provider_common.py`](../../skills/ppt-master/scripts/image_sources/provider_common.py) | License classification, query simplification, scoring, attribution text, dataclasses |
| [`project_utils.py`](../../skills/ppt-master/scripts/project_utils.py) | Canvas formats, project path conventions |
| [`error_helper.py`](../../skills/ppt-master/scripts/error_helper.py) | User-facing error message templates |
| [`console_encoding.py`](../../skills/ppt-master/scripts/console_encoding.py) | `configure_utf8_stdio()` — force UTF-8 console for CLI entries (§4) |

**Forbidden — duplicating logic that exists in a shared helper**. If a helper is missing a feature, extend the helper, don't fork it inside your new script.

---

## 10. Docstrings

Short and imperative. No Args/Returns/Raises sections unless the signature is genuinely complex.

```python
def classify_license(
    license_name: str,
    license_url: str = "",
    provider: str = "",
) -> Optional[str]:
    """Classify a license string into one of the two tiers, or reject it.

    Returns:
        ``"no-attribution"`` / ``"attribution-required"`` / ``None``.

    The provider hint lets us treat Pexels and Pixabay's own licenses as
    ``no-attribution`` even when the upstream API only returns a short
    label like ``"Pexels"``.
    """
```

| Use a Google/Sphinx-style block | Skip the block |
|---|---|
| Function returns multiple branches with semantic differences | One-liner that explains itself in the function name |
| Has more than 3 parameters with non-obvious roles | Single-purpose helper |
| Maintains a non-trivial invariant | Pure formatter / accessor |

---

## 11. Testing

**Hard rule**: this repository does **not** ship automated tests.

**Forbidden**:

- `tests/` directories
- `test_*.py` files
- `unittest` / `pytest` imports
- `if __name__ == "__main__":` blocks that run a self-test suite

**Use instead**:

- Inline smoke commands via `python3 -c "..."` against real project samples; show the output in the conversation / PR description
- Manual verification steps in the runbook
- Live-API smoke runs against `projects/_smoke_*` directories (gitignored)

This is a deliberate project convention. When external contributors include tests, ask them to remove tests in PR review (see [`docs/rules/prompt-style.md`](./prompt-style.md) §11 for the parallel rule on reference docs).

---

## 12. Dataclasses

Prefer plain `@dataclass` over `pydantic` / `attrs` for value types. Keep them simple:

```python
@dataclass
class AssetCandidate:
    provider: str
    title: str
    asset_id: str = ""
    license_tier: str = ""
    width: int = 0
    height: int = 0
    raw: Any = None
```

| Rule | Note |
|---|---|
| `@dataclass` | Default; no need for `frozen=True` unless mutation is a real risk |
| Fields | All required fields first, then optional with defaults |
| `field(default_factory=...)` | Only when the default needs to be a new container per instance |
| No legacy positional-arg shims | New dataclass = keyword-arg API. YAGNI on positional support |
| Methods | Keep dataclasses dumb; computation goes in module-level functions |

---

## 13. File Encoding & Line Endings

| Property | Value |
|---|---|
| Encoding | UTF-8 |
| Line endings | LF |
| Final newline | Always present |
| BOM | Forbidden |
| Indentation | 4 spaces (no tabs) |
| Max line length | Soft 100; hard 120. Prose in docstrings can flow longer |

---

## 14. Cross-references

When a Python file mirrors a reference doc, cross-link both ways:

- The script's docstring mentions the reference: `See references/image-searcher.md for the on-slide attribution rules.`
- The reference doc cites the script with a backticked relative link

This keeps `prompt-style.md` and `code-style.md` (this file) operating as a pair — neither layer drifts away from the other.

---

## 15. When This Guide Conflicts With Existing Files

Existing files take precedence. If a current script contradicts a rule here, decide whether to (a) update this guide, or (b) refactor the script. The canonical exemplars to model new scripts after:

| If you're writing... | Model after |
|---|---|
| A small CLI utility | [`total_md_split.py`](../../skills/ppt-master/scripts/total_md_split.py), [`gemini_watermark_remover.py`](../../skills/ppt-master/scripts/gemini_watermark_remover.py) |
| A multi-backend / dispatcher CLI | [`image_search.py`](../../skills/ppt-master/scripts/image_search.py), [`image_gen.py`](../../skills/ppt-master/scripts/image_gen.py) |
| A library / shared helper | [`image_sources/provider_common.py`](../../skills/ppt-master/scripts/image_sources/provider_common.py), [`image_backends/backend_common.py`](../../skills/ppt-master/scripts/image_backends/backend_common.py) |
| A class-based checker / validator | [`svg_quality_checker.py`](../../skills/ppt-master/scripts/svg_quality_checker.py) |