python

Files (1)

• SKILL.md

SKILL.md (first lines)

# Python Language Idioms

Work _with_ the language. Lean into duck typing, generators, context managers, and the standard library. Write code that reads like pseudocode — if it needs a comment to explain _what_ it does, rewrite it.

---

## Core Philosophy

- **Readability is a feature** — code is read far more than it is written; optimize for the reader
- **Explicit over implicit** — no magic, no hidden state, no clever tricks
- **Flat over nested** — avoid deep indentation; early returns, guard clauses, comprehensions
- **Composition over inheritance** — functions, protocols, and dataclasses beat class hierarchies
- **Standard library first** — reach for builtins and `stdlib` before adding dependencies

---

## Formatting

Let the formatter handle it. Pick **one** formatter project-wide and enforce it in CI.

```bash
ruff check .          # Lint
ruff format .         # Format
black .               # Alternative formatter
```

### Non-Negotiables

| Rule             | Standard                                                                                  |
| :--------------- | :---------------------------------------------------------------------------------------- |
| Indentation      | 4 spaces. Tabs are prohibited.                                                            |
| Operator spacing | `x = y * 12 + 13`, not `x=y*12+13`                                                        |
| Quote style      | Pick single or double project-wide; enforce via formatter. PEP 8 is deliberately silent.  |
| Line length      | Configure in formatter (88 for `black`/`ruff`, 79 for strict PEP 8). Don't manually wrap. |
| Imports          | `isort`-ordered: stdlib → third-party → local. One import per line for `from` imports.    |

---

## Naming

### Conventions

| Scope              | Style                 | Example                                           |
| :----------------- | :-------------------- | :------------------------------------------------ |
| Modules, packages  | `snake_case`          | `crypto_key.py`, `utils/`                         |
| Functions, methods | `snake_case` (verbs)  | `get_url()`, `calculate_checksum()`               |
| Variables          | `snake_case` (nouns)  | `raw_payload`, `user_registry`                    |
| Classes            | `PascalCase`          | `HttpClient`, `TokenParser`                       |
| Constants          | `SCREAMING_SNAKE`     | `MAX_RETRIES`, `DEFAULT_TIMEOUT`                  |
| Private            | `_leading_underscore` | `_internal_cache`, `_validate()`                  |
| Name-mangled       | `__double_leading`    | `__secret` (rarely needed)                        |
| Dunder             | `__name__`            | Reserved for the language. Never invent new ones. |

### The Verb-Noun Rule

Functions are actions → verbs. Variables are data → nouns. If a function name is a noun, it's probably a property.

### Shadowing Built-ins (Prohibited)

Redefining these names breaks built-in functionality within scope and causes non-deterministic bugs:

> `id`, `type`, `len`, `range`, `list`, `dict`, `str`, `int`, `float`, `min`, `max`, `abs`, `set`, `map`, `filter`, `input`, `open`, `hash`, `format`, `next`, `iter`, `sum`, `any`, `all`, `dir`, `vars`, `help`

Use descriptive alternatives: `user_id`, `item_type`, `name_list`, `count`.

### Natural Phrasing

| ✅ Idiomatic       | ❌ Avoid           |
| :----------------- | :----------------- |
| `if x not in y`    | `if not x in y`    |
| `if x != y`        | `if not x == y`    |
| `if x is not None` | `if not x is None` |

---

## Boolean and Comparison Idioms

| Scenario    | ❌ Wrong            | ✅ Idiomatic         | Why                                                      |
| :---------- | :------------------ | :------------------- | :------------------------------------------------------- |
| Truthiness  | `if x == True:`     | `if x:`              | `if` evaluates truthiness directly                       |
| Falsiness   | `if x == False:`    | `if not x:`          | `not` is the logical inverter                            |
| None check  | `if x == None:`     | `if x is None:`      | `is` checks identity; `==` can be overridden by `__eq__` |
| Empty check | `if len(seq) == 0:` | `if not seq:`        | Empty collections are falsy                              |
| Type check  | `type(x) == int`    | `isinstance(x, int)` | Respects inheritance                                     |

---

## Data Modeling

### When to Use What

| Type                      | Use When                       | Key Trait                                       |
| :------------------------ | :----------------------------- | :---------------------------------------------- |
| `@dataclass`              | Mutable data with behavior     | Auto-generates `__init__`, `__repr__`, `__eq__` |
| `@dataclass(frozen=True)` | Immutable value objects        | Hashable, safe as dict keys                     |
| `NamedTuple`              | Lightweight immutable records  | Tuple-compatible, unpacking works               |
| `TypedDict`               | Typed dict shapes (JSON, APIs) | Runtime is still a plain `dict`                 |
| Plain `dict`              | Dynamic/unknown keys           | No structure guarantees                         |

```python
from dataclasses import dataclass, field

@dataclass(frozen=True, slots=True)
class Token:
    kind: str
    value: str
    line: int = 0
```

### `__slots__`

Use `slots=True` on dataclasses (3.10+) or define `__slots__` manually. It prevents dynamic attribute creation, reduces memory, and speeds up attribute access:

```python
# ✅ With slots — fixed attributes, lower memory
@dataclass(slots=True)
class Point:
    x: float
    y: float

From nrdxp/predicate, MIT.

More from nrdxp/predicate