Skip to content

fcakyon/claude-codex-settings / plugins/python-skills/skills/python-guidelines

python-guidelines

Unverified

This skill should be used when writing, reviewing, or refactoring Python code. Covers code integration, idiomatic patterns, docstring formatting, anti-abstraction rules, and software engineering basics.

references/idiomatic-patterns.md

View on GitHub
# Idiomatic Python Patterns

Sources:

- PEP 8: https://peps.python.org/pep-0008/
- PEP 20: https://peps.python.org/pep-0020/
- Google Python Style Guide: https://google.github.io/styleguide/pyguide.html
- Effective Python, 3rd ed. (Brett Slatkin, Addison-Wesley, 2024, ISBN 978-0138172183)

Each pattern notes its primary source. Item numbers reference the 3rd edition.

## 1. Enumerate over indexing

Source: Effective Python Item 17, PEP 279

```python
# No
for i in range(len(items)):
    print(i, items[i])

# Yes
for i, item in enumerate(items):
    print(i, item)
```

## 2. Zip for parallel iteration

Source: Effective Python Item 18

```python
# No
for i in range(min(len(names), len(colors))):
    print(names[i], colors[i])

# Yes
for name, color in zip(names, colors):
    print(name, color)
```

## 3. Reversed for backward loops

Source: PEP 322

```python
# No
for i in range(len(items) - 1, -1, -1):
    print(items[i])

# Yes
for item in reversed(items):
    print(item)
```

## 4. List comprehensions over map/filter

Source: Effective Python Item 40, PEP 202

```python
# No
result = list(map(lambda x: x * 2, filter(lambda x: x > 0, items)))

# Yes
result = [x * 2 for x in items if x > 0]
```

## 5. Generator expressions for large data

Source: Effective Python Item 44, PEP 289

```python
# No -- builds entire list in memory
total = sum([x**2 for x in range(10**6)])

# Yes -- lazy evaluation
total = sum(x**2 for x in range(10**6))
```

## 6. Context managers for resources

Source: PEP 343, Effective Python Item 82

```python
# No
f = open("data.txt")
try:
    data = f.read()
finally:
    f.close()

# Yes
with open("data.txt") as f:
    data = f.read()
```

## 7. Keyword arguments for clarity

Source: Effective Python Items 35, 37

```python
# No -- what do these booleans mean?
search("@obama", False, 20, True)

# Yes
search("@obama", retweets=False, count=20, popular=True)
```

## 8. Dataclasses for structured data

Source: PEP 557, Effective Python Item 51

```python
# No
result = (0, 4)  # what are these?

# Yes
from dataclasses import dataclass


@dataclass
class TestResults:
    failed: int
    attempted: int
```

## 9. Tuple unpacking for state

Source: Core Python feature

```python
# No
temp = y
y = x + y
x = temp

# Yes
x, y = y, x + y
```

## 10. str.join over concatenation

Source: PEP 8, Google Style Guide

```python
# No -- O(n^2) string building
s = names[0]
for name in names[1:]:
    s += ", " + name

# Yes -- O(n)
s = ", ".join(names)
```

## 11. defaultdict/Counter for counting

Source: Effective Python Item 27, Python docs collections module

```python
# No
d = {}
for color in colors:
    if color not in d:
        d[color] = 0
    d[color] += 1

# Yes
from collections import Counter

d = Counter(colors)
```

## 12. Helper functions over complex expressions

Source: Effective Python Item 4

```python
# No -- hard to read
value = first if first is not None else (second if second is not None else default)


# Yes
def first_valid(*values, default=None):
    return next((v for v in values if v is not None), default)


value = first_valid(first, second, default=default)
```

## 13. Exceptions over returning None

Source: Effective Python Item 32

```python
# No -- caller can't distinguish None result from error
def divide(a, b):
    if b == 0:
        return None
    return a / b


# Yes
def divide(a, b):
    if b == 0:
        raise ValueError("Cannot divide by zero")
    return a / b
```

## 14. Generators for lazy sequences

Source: Effective Python Item 43, PEP 255

```python
# No -- builds entire list in memory
def read_lines(path):
    results = []
    with open(path) as f:
        for line in f:
            results.append(line.strip())
    return results


# Yes -- yields one at a time
def read_lines(path):
    with open(path) as f:
        for line in f:
            yield line.strip()
```

## 15. Plain attributes, not getters/setters

Source: Effective Python Item 58, PEP 8

```python
# No -- Java-style boilerplate
class User:
    def __init__(self, name):
        self._name = name

    def get_name(self):
        return self._name

    def set_name(self, name):
        self._name = name


# Yes -- use @property only when you need computed access
class User:
    def __init__(self, name):
        self.name = name
```

## 16. cache/lru_cache for memoization

Source: Python docs functools module, Effective Python Item 38

```python
# No
_cache = {}


def fib(n):
    if n in _cache:
        return _cache[n]
    result = fib(n - 1) + fib(n - 2) if n > 1 else n
    _cache[n] = result
    return result


# Yes (Python 3.9+: use @cache for unbounded, @lru_cache for bounded)
from functools import cache


@cache
def fib(n):
    return fib(n - 1) + fib(n - 2) if n > 1 else n
```

## 17. Functions for simple interfaces

Source: Effective Python Item 48

```python
# No -- single-method class is a function in disguise
class Validator:
    def validate(self, value):
        return value > 0


# Yes
def validate(value):
    return value > 0
```

## 18. No mutable default arguments

Source: Effective Python Item 36, Google Style Guide 2.12

```python
# No -- shared mutable state across calls
def append_to(element, target=[]):
    target.append(element)
    return target


# Yes
def append_to(element, target=None):
    if target is None:
        target = []
    target.append(element)
    return target
```
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 463kUpdated Claude CodeCodexVerifiedInstall
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 463kUpdated Claude CodeCodexVerifiedInstall
discernment-nudgeanthropics/skillsAfter you give a substantive answer or draft that the user may act on — advice or recommendations, drafted artifacts such as goals, plans, pitches, proposals, or emails, estimates or projections, analysis or interpretation of data, factual claims they may rely on, or a multi-step argument — invoke this skill BEFORE finalizing your reply and then, if it applies, append 2-3 short follow-up questions, each tied to something specific in what you just produced, that help the user check key facts, probe the reasoning or assumptions, and notice missing context. Do this at most once per conversation. Skip it when the user asked a trivial how-to or simple lookup, wants a purely educational explanation, asked you only to format, convert, or assemble a file from content they provided, is writing code they will run, is doing creative writing or casual chat, or already asked you to double-check, cite, or review — the skill file explains these boundaries and the exact output format.Stars: 195kUpdated Claude CodeCodexVerifiedInstall
internal-commsanthropics/skillsA set of resources to help me write all kinds of internal communications, using the formats that my company likes to use. Claude should use this skill whenever asked to write some sort of internal communications (status reports, leadership updates, 3P updates, company newsletters, FAQs, incident reports, project updates, etc.).Stars: 195kUpdated Claude CodeCodexVerifiedInstall