modern-python-guidance 0.1.0__py3-none-any.whl

modern_python_guidance/skills/modern-python-guidance/guides/stdlib/tomllib-builtin.md

@@ -0,0 +1,59 @@
+---
+id: tomllib-builtin
+title: Use Built-in tomllib Instead of Third-Party toml
+category: stdlib
+layer: 1
+tags:
+  - toml
+  - config
+  - stdlib
+aliases:
+  - toml
+  - tomli
+  - tomllib
+python: ">=3.11"
+frequency: medium
+pep: 680
+---
+
+# Use Built-in tomllib
+
+Since Python 3.11, use the built-in `tomllib` module for reading TOML files instead of third-party packages like `toml` or `tomli`.
+
+## BAD
+
+```python
+import toml  # third-party, unmaintained
+
+with open("pyproject.toml") as f:
+    config = toml.load(f)
+```
+
+## GOOD
+
+```python
+import tomllib
+
+with open("pyproject.toml", "rb") as f:
+    config = tomllib.load(f)
+
+# Or from a string:
+config = tomllib.loads(toml_string)
+```
+
+## Why
+
+- No external dependency needed for TOML reading
+- `tomllib` is TOML 1.0 compliant
+- Based on `tomli` (battle-tested implementation adopted into stdlib)
+- Read-only by design — use `tomli-w` or `tomlkit` for writing
+
+## Version Notes
+
+- 3.11+: `import tomllib`
+- Pre-3.11: `pip install tomli` (same API as `tomllib`)
+- `tomllib.load()` requires binary mode (`"rb"`), not text mode
+
+## References
+
+- [PEP 680 — tomllib: Support for Parsing TOML in the Standard Library](https://peps.python.org/pep-0680/)

modern_python_guidance/skills/modern-python-guidance/guides/toolchain/no-pickle.md

@@ -0,0 +1,79 @@
+---
+id: no-pickle
+title: Avoid pickle for Untrusted Data
+category: toolchain
+layer: 3
+tags:
+  - security
+  - serialization
+  - pickle
+aliases:
+  - pickle
+  - unpickle
+  - pickle.load
+  - shelve
+python: ">=3.9"
+frequency: medium
+---
+
+# Avoid pickle for Untrusted Data
+
+`pickle.load()` executes arbitrary code during deserialization. Never use it with untrusted data.
+
+## BAD
+
+```python
+import pickle
+
+def load_model(path: str):
+    with open(path, "rb") as f:
+        return pickle.load(f)  # arbitrary code execution
+
+def cache_result(data, path: str):
+    with open(path, "wb") as f:
+        pickle.dump(data, f)
+```
+
+## GOOD
+
+```python
+import json
+
+def load_config(path: str) -> dict:
+    with open(path) as f:
+        return json.load(f)
+
+# For structured data
+import msgpack  # or orjson, cbor2
+
+def load_data(path: str) -> dict:
+    with open(path, "rb") as f:
+        return msgpack.unpack(f)
+
+# For ML models — use framework-native formats
+import torch
+model = torch.load(path, weights_only=True)  # safe mode
+```
+
+## Why
+
+- `pickle.load()` can execute arbitrary Python code — a known RCE vector
+- Applies to `pickle`, `shelve`, `marshal`, and any library using pickle internally
+- JSON, MessagePack, CBOR are safe — they only deserialize data, not code
+- ML frameworks provide safe alternatives (`weights_only=True`, ONNX, SafeTensors)
+- Python's own docs warn: "Never unpickle data received from an untrusted source"
+
+## Safe Alternatives
+
+| Use case | Recommended format |
+|----------|-------------------|
+| Configuration | JSON, TOML, YAML |
+| Structured data | JSON, MessagePack, Protocol Buffers |
+| DataFrames | Parquet, CSV |
+| ML models | SafeTensors, ONNX, `weights_only=True` |
+| Caching | JSON + compression, Redis |
+
+## References
+
+- [Python docs — pickle security](https://docs.python.org/3/library/pickle.html#restricting-globals)
+- [CWE-502: Deserialization of Untrusted Data](https://cwe.mitre.org/data/definitions/502.html)

modern_python_guidance/skills/modern-python-guidance/guides/toolchain/pyproject-toml-over-setup.md

@@ -0,0 +1,69 @@
+---
+id: pyproject-toml-over-setup
+title: Use pyproject.toml Instead of setup.py
+category: toolchain
+layer: 3
+tags:
+  - packaging
+  - pyproject
+  - setup.py
+  - build
+aliases:
+  - setup.py
+  - setup.cfg
+  - setuptools
+python: ">=3.7"
+frequency: high
+pep: 621
+---
+
+# Use pyproject.toml Instead of setup.py
+
+PEP 621 standardizes project metadata in `pyproject.toml`. `setup.py` and `setup.cfg` are legacy.
+
+## BAD
+
+```python
+# setup.py
+from setuptools import setup, find_packages
+
+setup(
+    name="my-package",
+    version="0.1.0",
+    packages=find_packages(),
+    install_requires=["requests>=2.28"],
+    python_requires=">=3.11",
+)
+```
+
+## GOOD
+
+```toml
+# pyproject.toml
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "my-package"
+version = "0.1.0"
+requires-python = ">=3.11"
+dependencies = ["requests>=2.28"]
+```
+
+## Why
+
+- `setup.py` executes arbitrary code at install time (security risk)
+- `pyproject.toml` is declarative and statically analyzable
+- All modern tools (pip, uv, hatch, flit, PDM) support PEP 621
+- `setup.py` is no longer needed for pure-Python packages
+
+## Version Notes
+
+- PEP 621 is supported by pip since 21.3 (2021-10)
+- Python version doesn't matter — this is a tooling decision
+
+## References
+
+- [PEP 621 — Storing project metadata in pyproject.toml](https://peps.python.org/pep-0621/)
+- [PEP 517 — Build system interface](https://peps.python.org/pep-0517/)

modern_python_guidance/skills/modern-python-guidance/guides/toolchain/ruff-over-flake8.md

@@ -0,0 +1,90 @@
+---
+id: ruff-over-flake8
+title: Use Ruff Instead of Flake8 + isort + Black
+category: toolchain
+layer: 3
+tags:
+  - ruff
+  - linting
+  - formatting
+  - flake8
+  - isort
+  - black
+aliases:
+  - flake8
+  - isort
+  - black
+  - ruff
+  - linter
+  - formatter
+python: ">=3.7"
+frequency: high
+---
+
+# Use Ruff Instead of Flake8 + isort + Black
+
+Ruff replaces Flake8, isort, Black, pyupgrade, and dozens of other tools in a single Rust binary.
+
+## BAD
+
+```toml
+# pyproject.toml — multiple tools to configure separately
+[tool.flake8]
+max-line-length = 88
+
+[tool.isort]
+profile = "black"
+
+[tool.black]
+line-length = 88
+target-version = ["py311"]
+```
+
+```bash
+flake8 src/
+isort src/
+black src/
+```
+
+## GOOD
+
+```toml
+# pyproject.toml — single tool
+[tool.ruff]
+target-version = "py311"
+line-length = 88
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.ruff.format]
+docstring-code-format = true
+```
+
+```bash
+ruff check src/ --fix
+ruff format src/
+```
+
+## Why
+
+- 10-100x faster than Flake8 (Rust implementation)
+- Single tool replaces Flake8, isort, Black, pyupgrade, pydocstyle, and 50+ plugins
+- `--fix` auto-fixes most lint violations
+- `ruff format` is a drop-in replacement for Black
+- Configured entirely in `pyproject.toml`
+
+## Rule Selection Guide
+
+| Rule prefix | Replaces | Purpose |
+|-------------|----------|---------|
+| `E`, `F` | Flake8 (pycodestyle + pyflakes) | Core errors and style |
+| `I` | isort | Import sorting |
+| `UP` | pyupgrade | Python version upgrades |
+| `B` | flake8-bugbear | Common bug patterns |
+| `SIM` | flake8-simplify | Code simplification |
+
+## References
+
+- [Ruff documentation](https://docs.astral.sh/ruff/)
+- [Ruff Rules](https://docs.astral.sh/ruff/rules/)

modern_python_guidance/skills/modern-python-guidance/guides/toolchain/safe-subprocess.md

@@ -0,0 +1,79 @@
+---
+id: safe-subprocess
+title: Use subprocess Safely with List Arguments
+category: toolchain
+layer: 3
+tags:
+  - security
+  - subprocess
+  - shell-injection
+aliases:
+  - subprocess
+  - os.system
+  - shell=True
+  - subprocess.run
+python: ">=3.9"
+frequency: high
+---
+
+# Use subprocess Safely
+
+Always pass commands as a list of arguments. Never use `shell=True` or `os.system()` with user input.
+
+## BAD
+
+```python
+import os
+import subprocess
+
+def convert(input_path: str, output_path: str) -> None:
+    os.system(f"ffmpeg -i {input_path} {output_path}")
+
+def run_tool(filename: str) -> str:
+    result = subprocess.run(
+        f"grep -r {filename} src/",
+        shell=True, capture_output=True, text=True,
+    )
+    return result.stdout
+```
+
+## GOOD
+
+```python
+import subprocess
+
+def convert(input_path: str, output_path: str) -> None:
+    subprocess.run(
+        ["ffmpeg", "-i", input_path, output_path],
+        check=True,
+    )
+
+def run_tool(filename: str) -> str:
+    result = subprocess.run(
+        ["grep", "-r", filename, "src/"],
+        capture_output=True, text=True, check=True,
+    )
+    return result.stdout
+```
+
+## Why
+
+- `shell=True` passes the command through the shell — user input can inject arbitrary commands
+- `os.system()` always uses the shell and is even worse (no output capture, no error handling)
+- List arguments bypass the shell entirely — each element is a separate argv entry
+- `check=True` raises `CalledProcessError` on non-zero exit instead of silently continuing
+- `capture_output=True` is a shorthand for `stdout=PIPE, stderr=PIPE`
+
+## When shell=True Is Acceptable
+
+| Scenario | Acceptable? | Alternative |
+|----------|-------------|-------------|
+| Hardcoded command, no user input | Tolerable | Still prefer list form |
+| Pipes (`cmd1 | cmd2`) | Acceptable | Use `subprocess.PIPE` between two `Popen` calls |
+| Glob expansion (`*.txt`) | Acceptable | Use `pathlib.Path.glob()` |
+| User-provided input in command | Never | List form only |
+
+## References
+
+- [subprocess — Security Considerations](https://docs.python.org/3/library/subprocess.html#security-considerations)
+- [CWE-78: OS Command Injection](https://cwe.mitre.org/data/definitions/78.html)

modern_python_guidance/skills/modern-python-guidance/guides/toolchain/uv-over-pip.md

@@ -0,0 +1,68 @@
+---
+id: uv-over-pip
+title: Use uv Instead of pip for Package Management
+category: toolchain
+layer: 3
+tags:
+  - uv
+  - pip
+  - packaging
+  - virtual-env
+aliases:
+  - pip install
+  - pip
+  - uv
+  - virtualenv
+  - venv
+python: ">=3.8"
+frequency: high
+---
+
+# Use uv Instead of pip
+
+`uv` is a drop-in replacement for `pip`, `pip-tools`, `virtualenv`, and `pyenv` — written in Rust, 10-100x faster.
+
+## BAD
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+pip install -e ".[dev]"
+pip freeze > requirements.txt
+```
+
+## GOOD
+
+```bash
+uv venv
+source .venv/bin/activate
+uv pip install -r requirements.txt
+uv pip install -e ".[dev]"
+
+# Or use uv's project workflow (pyproject.toml-native)
+uv init my-project
+uv add requests httpx
+uv add --dev pytest ruff
+uv run pytest
+uv lock
+```
+
+## Why
+
+- 10-100x faster than pip (Rust implementation with global cache)
+- Replaces pip, pip-tools, virtualenv, pyenv in a single binary
+- `uv.lock` provides reproducible, cross-platform lockfiles
+- `uv run` auto-creates virtualenv and installs dependencies
+- Compatible with existing `requirements.txt` and `pyproject.toml`
+
+## Version Notes
+
+- `uv` is a third-party tool by Astral (same team as Ruff)
+- Works with Python 3.8+
+- `uv init` generates `pyproject.toml` (PEP 621 compliant)
+
+## References
+
+- [uv documentation](https://docs.astral.sh/uv/)
+- [uv GitHub](https://github.com/astral-sh/uv)

modern_python_guidance/skills/modern-python-guidance/guides/typing/override-decorator.md

@@ -0,0 +1,65 @@
+---
+id: override-decorator
+title: Use @override to Mark Method Overrides
+category: typing
+layer: 1
+tags:
+  - type-hints
+  - inheritance
+  - override
+aliases:
+  - typing.override
+python: ">=3.12"
+frequency: medium
+pep: 698
+---
+
+# Use @override to Mark Method Overrides
+
+Since Python 3.12, use `@override` from `typing` to explicitly mark methods that override a parent class method. Type checkers will flag errors if the parent method doesn't exist.
+
+## BAD
+
+```python
+class Animal:
+    def speak(self) -> str:
+        return ""
+
+class Dog(Animal):
+    def spek(self) -> str:  # typo goes unnoticed
+        return "woof"
+```
+
+## GOOD
+
+```python
+from typing import override
+
+class Animal:
+    def speak(self) -> str:
+        return ""
+
+class Dog(Animal):
+    @override
+    def speak(self) -> str:
+        return "woof"
+
+    @override
+    def spek(self) -> str:  # type checker flags: no parent method 'spek'
+        return "woof"
+```
+
+## Why
+
+- Catches typos and missing parent methods at type-check time
+- Documents intent — clearly shows which methods are overrides
+- Prevents silent breakage when parent class renames a method
+
+## Version Notes
+
+- 3.12+: `from typing import override`
+- 3.11 and below: `from typing_extensions import override`
+
+## References
+
+- [PEP 698 — Override Decorator for Static Typing](https://peps.python.org/pep-0698/)

modern_python_guidance/skills/modern-python-guidance/guides/typing/paramspec-decorators.md

@@ -0,0 +1,81 @@
+---
+id: paramspec-decorators
+title: Use ParamSpec for Typed Decorators
+category: typing
+layer: 1
+tags:
+  - type-hints
+  - decorators
+  - paramspec
+aliases:
+  - ParamSpec
+  - typing.ParamSpec
+  - Callable
+python: ">=3.10"
+frequency: medium
+pep: 612
+---
+
+# Use ParamSpec for Typed Decorators
+
+Since Python 3.10, use `ParamSpec` to preserve the parameter types of decorated functions. Without it, decorators erase all type information.
+
+## BAD
+
+```python
+from typing import Any, Callable, TypeVar
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+def retry(func: F) -> F:  # loses parameter info in practice
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        for _ in range(3):
+            try:
+                return func(*args, **kwargs)
+            except Exception:
+                pass
+        return func(*args, **kwargs)
+    return wrapper  # type: ignore
+```
+
+## GOOD
+
+```python
+from collections.abc import Callable
+from functools import wraps
+from typing import ParamSpec, TypeVar
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+def retry(func: Callable[P, R]) -> Callable[P, R]:
+    @wraps(func)
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+        for _ in range(3):
+            try:
+                return func(*args, **kwargs)
+            except Exception:
+                pass
+        return func(*args, **kwargs)
+    return wrapper
+
+# 3.12+ with PEP 695:
+# def retry[**P, R](func: Callable[P, R]) -> Callable[P, R]: ...
+```
+
+## Why
+
+- Preserves full parameter types through decoration
+- Type checkers can verify argument types at call sites
+- No more `# type: ignore` on decorator return
+- `P.args` and `P.kwargs` capture positional and keyword args separately
+
+## Version Notes
+
+- 3.10+: `from typing import ParamSpec`
+- 3.12+: `def retry[**P, R](func): ...` syntax (PEP 695)
+- Pre-3.10: `from typing_extensions import ParamSpec`
+
+## References
+
+- [PEP 612 — Parameter Specification Variables](https://peps.python.org/pep-0612/)

modern_python_guidance/skills/modern-python-guidance/guides/typing/type-parameter-syntax.md

@@ -0,0 +1,66 @@
+---
+id: type-parameter-syntax
+title: Use PEP 695 Type Parameter Syntax for Generics
+category: typing
+layer: 1
+tags:
+  - type-hints
+  - generics
+  - typevar
+aliases:
+  - TypeVar
+  - typing.TypeVar
+  - type alias
+python: ">=3.12"
+frequency: medium
+pep: 695
+---
+
+# Use PEP 695 Type Parameter Syntax
+
+Since Python 3.12, use the bracket syntax for type parameters instead of `TypeVar`, `TypeVarTuple`, and `ParamSpec` from `typing`.
+
+## BAD
+
+```python
+from typing import Generic, TypeVar
+
+T = TypeVar("T")
+K = TypeVar("K")
+V = TypeVar("V")
+
+class Stack(Generic[T]):
+    def push(self, item: T) -> None: ...
+    def pop(self) -> T: ...
+
+MyList = list[T]  # not a proper type alias
+```
+
+## GOOD
+
+```python
+class Stack[T]:
+    def push(self, item: T) -> None: ...
+    def pop(self) -> T: ...
+
+type MyList[T] = list[T]
+
+def first[T](items: list[T]) -> T:
+    return items[0]
+```
+
+## Why
+
+- No boilerplate `TypeVar("T")` declarations
+- Scope is explicit — type params are local to their class/function/alias
+- `type` statement creates proper type aliases with lazy evaluation
+- Cleaner syntax for bounded types: `class Num[T: (int, float)]`
+
+## Version Notes
+
+- 3.12+: `class C[T]`, `def f[T]()`, `type Alias[T] = ...`
+- Pre-3.12: Must use `TypeVar`, `Generic`, and `TypeAlias`
+
+## References
+
+- [PEP 695 — Type Parameter Syntax](https://peps.python.org/pep-0695/)