# Skill: Generate idiomatic, readable Python with type hints, specific error handling, and PEP 8 style

> Apply this skill when generating any Python code -- it ensures the output uses descriptive names, type hints, honest error handling, and Pythonic constructs so the code stays readable, growable, and debuggable.

Source: sodigi·learn -- vibecoding/python-krasivo · https://sodigi.io/learn/vibecoding/python-krasivo

## When to use
- Generating any new Python function, class, or script.
- Reviewing agent-produced Python before accepting it -- check for one-letter names and bare except blocks.
- Extending an existing Python codebase -- request that new additions match the quality bar.
- Debugging a script that fails silently with no useful error message (almost always a bare except issue).

## Core rules
- Names must be self-explanatory. "get_active_users" is correct; "g(u)" is not. Read the name aloud -- if it needs a comment to explain it, rename it.
- All function signatures must include type hints: parameter types and return type. "def process(items: list[str]) -> dict[str, int]" tells you everything without reading the body.
- Never use a bare "except:" or "except Exception: pass". Always catch a specific exception and print or log a clear message explaining what went wrong and where.
- Use Pythonic constructs: f-strings for formatting, list comprehensions for simple transforms, "with" for file/resource handling, "pathlib" for file paths.
- Follow PEP 8 naming: snake_case for functions and variables, PascalCase for classes, UPPER_SNAKE_CASE for constants.
- Functions should stay small and focused. If a function does more than one thing, split it.
- A "working but ugly" script is a future maintenance cost -- ugliness compounds when the agent has to extend it.

## Procedure
1. Before writing, list the functions needed and choose descriptive names for each.
2. Write each function with type hints on all parameters and the return value.
3. Wrap every I/O or network operation in a specific try/except. Print or log a message that identifies the exact operation that failed.
4. Replace any manual string concatenation with f-strings.
5. Replace any "open(...)" without "with" with a "with open(...) as f:" block.
6. Replace any string-glued file paths with pathlib.Path operations.
7. After writing, briefly explain what each function does and where shared logic lives.

## Ready-to-use prompt
```
Write this Python code beautifully and Pythonically:

1. Give functions and variables clear names -- the name must make it obvious
   what the function does. No one-letter names.
2. Add type hints to all functions: what goes in and what comes out.
3. Catch errors specifically (for example, FileNotFoundError or
   ConnectionError) and print a clear message about exactly what went wrong.
   No bare "except:" that silently swallows everything.
4. Use Pythonic constructs: f-strings for text, "with" for files,
   pathlib for paths, list comprehensions for simple transforms.
5. Follow the PEP 8 style standard.

At the end, briefly explain in plain words what each function does.
```

## Pitfalls
- Being satisfied that the script "works" without checking how it looks -- working-but-ugly code is a time bomb when you try to extend it.
- Not asking for type hints -- the agent will happily produce untyped functions by default.
- Using a bare "except:" or "except Exception: pass" -- bugs become invisible, and the agent debugs blind on the next visit.
- Chasing "clever" one-liners -- Python values readability over showing off. If the one-liner needs a comment, write two lines.
- Writing monster functions that do ten things -- they are hard to read for both you and the agent; split them.
- Not specifying "by PEP 8" -- without the standard the agent uses inconsistent style across the file.