Zalohovani vsech podstatnych souboru

skills/python/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: python
+description: >
+  Python coding conventions, style, and tooling. 
+  Use for anything involving Python code.
+---
+
+# Python Coding Conventions
+
+## Tooling
+
+- **Always use `uv`** — never bare `pip`, `python`, `venv`, or `virtualenv`.
+  - Run code: `uv run script.py` (or `uv run python -m module`)
+  - Add dependencies: `uv add <pkg>`; sync: `uv sync`
+  - One-off tools: `uv run --with <pkg> ...` or `uvx <tool>`
+- **Format before done:** `uv run ruff format`
+- **Lint before done:** `uv run ruff check --fix`
+- Treat "done" as: formatted, linted clean, type hints present.
+
+## Core Principles
+
+- **Readability first** — code must be easily readable and understandable at a glance
+- **Simplicity** — prefer the simplest solution that solves the problem; avoid unnecessary abstractions and cleverness
+- **Clean Code** — meaningful names, small focused functions, single responsibility, no duplication (DRY), clear intent
+
+## Style
+
+- Follow PEP 8, but max line length **120 characters** (not the default 88)
+
+## Types and Annotations
+
+- Use Python 3.12+ built-in generics: `list[str]`, `dict[str, int]`, `tuple[int, ...]`
+- Use `X | Y` instead of `Union[X, Y]`, `str | None` instead of `Optional[str]`
+- Do not import from `typing` unless truly necessary (e.g., `Protocol`, `TypeVar`)
+- All public functions and methods must have type hints
+
+## Docstrings and Comments
+
+- Add a docstring or comment only when it explains **intent** not obvious from the code or signature
+- First line: short imperative summary; omit parameter/return docs if self-explanatory
+- Prefer clear naming over explanatory comments; never restate what the code does
+
+## Functions
+
+- Break complex functions into smaller ones; one thing at one level of abstraction
+- Keep the parameter count low (0–3)
+- No boolean flag arguments — split into two well-named functions or use an enum
+- Command-Query Separation: a function that returns a value must not mutate state
+- Handle edge cases explicitly; prefer specific exceptions over bare `except`
+
+## Control Flow
+
+- Fail fast — validate inputs up front with guard clauses and early returns
+- Avoid deep nesting (max 2–3 levels); invert conditions to return early
+- Replace magic numbers and strings with named constants
+
+## Error Handling
+
+- Never silently swallow exceptions
+- Do not unnecessarily wrap exceptions in other exception types
+
+## Paths
+
+- Prefer `pathlib.Path` over `os.path`