Skip to content

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

python-guidelines

Verified

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/google-style-guide.md

View on GitHub
# Google Python Style Guide -- Key Sections

Source: https://google.github.io/styleguide/pyguide.html
Maintainer: Google
License: CC-BY 3.0

Each section links to the specific guide section for full context.

## Exceptions

Source: https://google.github.io/styleguide/pyguide.html#24-exceptions

- Raise `ValueError` for programming mistakes like violated preconditions
- Never use catch-all `except:` statements, or catch `Exception` unless re-raising or creating an isolation point
- Minimize the amount of code in a `try`/`except` block
- Do not use `assert` in place of conditionals for critical logic

```python
# Yes
if minimum < 1024:
    raise ValueError(f"Min. port must be at least 1024, not {minimum}.")

# No
assert minimum >= 1024, "Minimum port must be at least 1024."
```

## Default Argument Values

Source: https://google.github.io/styleguide/pyguide.html#212-default-argument-values

Do not use mutable objects as default values.

```python
# Yes
def foo(a, b=None):
    if b is None:
        b = []


# No
def foo(a, b=[]): ...
def foo(a, b=time.time()): ...
```

## Import Ordering

Source: https://google.github.io/styleguide/pyguide.html#313-imports-formatting

Imports grouped from most generic to least:

1. `from __future__` imports
2. Python standard library
3. Third-party modules
4. Local/project imports

Within each group, sort lexicographically. Use `import x` for packages, `from x import y` where `x` is the package prefix. No relative imports.

```python

```

## Naming Conventions

Source: https://google.github.io/styleguide/pyguide.html#316-naming

| Type               | Style              | Example                 |
| ------------------ | ------------------ | ----------------------- |
| Packages/Modules   | `lower_with_under` | `my_module`             |
| Classes/Exceptions | `CapWords`         | `MyClass`, `InputError` |
| Functions/Methods  | `lower_with_under` | `calculate_total`       |
| Constants          | `CAPS_WITH_UNDER`  | `MAX_RETRIES`           |
| Variables          | `lower_with_under` | `user_count`            |

Avoid: single-char names (except `i`, `j`, `k`, `e`, `f`), dashes in names, type-in-name (`id_to_name_dict`).

## Adapting to Existing Code

These Google Style Guide rules are defaults. When working in an existing codebase, always match the existing patterns for:

- **Type hints**: Follow the repo's existing annotation style (presence/absence, `X | None` vs `Optional[X]`, etc.)
- **Naming**: Match the existing naming conventions in the file/module you're editing
- **Import style**: Follow the repo's existing import organization
- **Docstrings**: Match the existing docstring style in the project

The rules above are for greenfield code or when the existing codebase has no clear convention.

## Comments

Source: https://google.github.io/styleguide/pyguide.html#385-block-and-inline-comments

- Never describe the code. Assume the reader knows Python.
- Comments start at least 2 spaces from the code
- Use them to explain WHY, not WHAT
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: 465kUpdated 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: 465kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 318kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 318kUpdated Claude CodeCodexVerifiedInstall