python-patterns · diff
v1.0 to v1.0
19 added, 58 removed. Audit B to A.
---
name: python-patterns
version: "1.0"
- description: Team-specific Python conventions for credential management with dotenv. Covers .env file structure, loading patterns, and secure defaults.
+ description: Team conventions for Python development — credentials, API clients, LLM response parsing, testing patterns, and data pipeline structure. Covers dotenv loading, retry logic, secret validation, and pipeline anti-patterns.
---
# Python Patterns — Team Conventions
- Team-specific conventions that go beyond what Claude knows by default.
+ Unified conventions for team Python projects: credential management, API clients, testing discipline, and data pipeline structure. Supplements standard patterns with team-specific rules.
## When to Activate
- - When writing code that uses environment variables or credentials
- - When creating or modifying `.env` files
- - When setting up a new project or script that needs API keys
-
- ## Credential Management with dotenv
-
- ### .env File Structure
-
- ```bash
- # Required credentials
- JIRA_URL=https://issues.redhat.com
- JIRA_TOKEN=your_jira_token_here
- GOOGLE_API_KEY=your_gemini_api_key_here
-
- # Optional overrides
- GEMINI_MODEL=gemini-3-flash-preview
- JIRA_MAX_RESULTS=250
- ```
-
- ### Loading Pattern
-
- ```python
- from pathlib import Path
- from dotenv import load_dotenv
-
- # Load from project root (not current directory)
- env_path = Path(__file__).parent.parent / ".env"
- load_dotenv(env_path)
-
- # Access with no default for secrets (fail if missing)
- api_key = os.getenv("GOOGLE_API_KEY")
- if not api_key:
- print("Error: GOOGLE_API_KEY not set in .env file")
- sys.exit(1)
+ - Writing credential/secret handling code or `.env` files
+ - Creating or modifying API clients (GitHub, Stripe, LLM APIs)
+ - Parsing LLM responses or structured API outputs
+ - Writing or reviewing tests (TDD workflow, mocking external APIs)
+ - Building or debugging data pipeline stages
+ - Reviewing code that handles HTTP responses or LLM output
- # Optional values can have defaults
- model_name = os.getenv("GEMINI_MODEL", "gemini-3-flash-preview")
- ```
+ ## Quick Rules
- ### Rules
+ **Credentials:**
+ - Never hardcode or use real defaults. Fail fast if missing. Always create `.env.example`.
- - **Never** use real values as defaults: `os.getenv("KEY", "AIza...")` exposes the key in code
- - **Always** create `.env.example` with placeholder values for team distribution
- - **Always** add `.env` to `.gitignore`
- - **Never** commit `.env` files — only `.env.example`
- - **Load early** — call `load_dotenv()` at the top of entry points, not deep in utility code
- - **Validate required vars** — fail fast if a required credential is missing, don't let it fail later with a confusing error
+ **APIs:**
+ - Always timeout (30s). Only retry transient errors (429, 5xx). Always validate response structure.
- ### .env.example Template
+ **Tests:**
+ - Mock external APIs. Set `random_state=42`. Target 80%+ coverage. Test behavior, not internals.
- ```bash
- # Copy this file to .env and fill in your credentials:
- # cp .env.example .env
+ **Pipelines:**
+ - Each stage is independently runnable. Validate input before processing. Include metadata in every output. Fail fast on invalid data.
- # Required
- JIRA_URL=https://issues.redhat.com
- JIRA_TOKEN=your_jira_personal_access_token_here
- GOOGLE_API_KEY=your_google_gemini_api_key_here
+ ## Details
- # Optional
- GEMINI_MODEL=gemini-3-flash-preview
- JIRA_MAX_RESULTS=250
- ```
+ Read `references/credentials.md`, `references/api-clients.md`, `references/testing.md`, and `references/pipelines.md` for full examples and anti-patterns.