<< All versions
Skill v1.0.1
currentAutomated scan100/100b33eep/claude-code-setup/standards-python
3 files
──Details
PublishedMay 25, 2026 at 09:45 PM
Content Hashsha256:f0daa540aa139ead...
Git SHA7e8cc42fb508
Bump Typepatch
──Files
Files (1 file, 5.9 KB)
SKILL.md5.9 KBactive
SKILL.md · 192 lines · 5.9 KB
version: "1.0.1" name: standards-python description: This skill provides Python coding standards and is automatically loaded for Python projects. It includes naming conventions, best practices, and recommended tooling. type: context applies_to: [python, fastapi, django, flask, pytest, pydantic, sqlalchemy, celery, poetry, asyncio, aiohttp, httpx] file_extensions: [".py"]
Python Coding Standards
Core Principles
- Simplicity: Simple, understandable code
- Readability: Readability over cleverness
- Maintainability: Code that's easy to maintain
- Testability: Code that's easy to test
- DRY: Don't Repeat Yourself - but don't overdo it
General Rules
- Early Returns: Use early returns to avoid nesting
- Descriptive Names: Meaningful names for variables and functions
- Minimal Changes: Only change relevant code parts
- No Over-Engineering: No unnecessary complexity
- Minimal Comments: Code should be self-explanatory. No redundant comments!
Naming Conventions
| Element | Convention | Example | |
|---|---|---|---|
| Variables/Functions | snake_case | get_user_by_id, is_active | |
| Classes | PascalCase | UserService, ApiClient | |
| Constants | UPPER_SNAKE_CASE | MAX_RETRY_COUNT | |
| Private | Prefix with _ | _internal_method | |
| Files/Modules | snake_case | user_service.py |
Project Structure
myproject/├── src/│ ├── __init__.py│ ├── main.py # Entry point│ ├── config.py # Settings, env vars│ ├── models.py # Domain models (dataclasses/Pydantic)│ ├── schemas.py # Request/response DTOs│ ├── services/│ │ ├── __init__.py│ │ └── user_service.py # Business logic│ └── repositories/│ ├── __init__.py│ └── user_repo.py # Data access├── tests/│ ├── __init__.py│ ├── test_services.py│ └── test_repositories.py├── pyproject.toml└── README.md
Code Style (PEP 8 + PEP 484)
python
from dataclasses import dataclass@dataclassclass User:id: strname: stremail: strage: int | None = None # Python 3.10+ union syntaxdef get_user_by_id(user_id: str) -> User | None:if not user_id:raise ValueError("user_id cannot be empty")# implementation...
Best Practices
python
# Type hints everywheredef process_items(items: list[str]) -> dict[str, int]:return {item: len(item) for item in items}# Pydantic v2 for validationfrom pydantic import BaseModel, Field, field_validator, EmailStrclass UserCreate(BaseModel):name: str = Field(..., min_length=2, max_length=50)email: EmailStrage: int | None = Field(None, ge=0, le=150)@field_validator('name')@classmethoddef name_must_be_alphanumeric(cls, v: str) -> str:if not v.replace(' ', '').isalnum():raise ValueError('Name must be alphanumeric')return v.strip()# Context managerswith open('file.txt', 'r') as f:content = f.read()# Prefer pathlib over os.pathfrom pathlib import Pathconfig_path = Path(__file__).parent / 'config.yaml'
Async/Await
python
# Async function with proper typingasync def fetch_user(user_id: str) -> User | None:async with httpx.AsyncClient() as client:response = await client.get(f"/users/{user_id}")return User(**response.json()) if response.status_code == 200 else None# Don't block async functionsasync def process_data():# BAD - blocks the event looptime.sleep(1)# GOOD - async sleepawait asyncio.sleep(1)# Gather for concurrent operationsasync def fetch_all_users(user_ids: list[str]) -> list[User]:tasks = [fetch_user(uid) for uid in user_ids]return await asyncio.gather(*tasks)
Exception Handling
python
# Custom exceptions for domain errorsclass UserNotFoundError(Exception):def __init__(self, user_id: str):self.user_id = user_idsuper().__init__(f"User not found: {user_id}")# Raise vs Return Nonedef get_user_strict(user_id: str) -> User:"""Raises if not found - use when user MUST exist."""user = repository.get(user_id)if not user:raise UserNotFoundError(user_id)return userdef get_user_optional(user_id: str) -> User | None:"""Returns None if not found - use when absence is expected."""return repository.get(user_id)
Comments - Less is More
python
# BAD - redundant comment# Get the user from databaseuser = repository.get_user(user_id)# GOOD - self-explanatory code, no comment neededuser = repository.get_user(user_id)# GOOD - comment explains WHY (not obvious)# Rate limit: Azure API allows max 1000 requests/minawait rate_limiter.acquire()
Recommended Tooling
| Tool | Purpose | |
|---|---|---|
uv | Package manager (faster than pip/poetry) | |
ruff | Linting (replaces flake8, isort, black) | |
mypy or pyright | Type checking | |
pytest | Testing with pytest-cov, pytest-asyncio |
Production Best Practices
- Type hints everywhere - Parameters, return types, variables where helpful
- Pydantic for validation - Don't validate manually, use Pydantic models
- Async for I/O - Use async/await for network, database, file operations
- No blocking in async - Never use
time.sleep()or sync I/O in async functions - Structured logging - Use
loggingmodule with JSON format, not print() - Environment variables - Use
pydantic-settingsfor config, never hardcode secrets - Dependency injection - Pass dependencies explicitly, makes testing easier
- Custom exceptions - Domain-specific errors, not generic Exception
- Connection pooling - Reuse database/HTTP connections, don't create per request
- Graceful shutdown - Handle SIGTERM, close connections properly