# Python Project Workflow

> Use when working on a Python project with tests, configuration files, generated artifacts, GUI code, parser/filter logic, or reporting workflows. Provides a generic workflow for scoped edits and validation.

- Skill: `iabuelruzz/python-project-workflow` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add iabuelruzz/python-project-workflow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/iabuelruzz/python-project-workflow/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: IAbuElRuzz (https://skillmd.com/u/iabuelruzz)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/iabuelruzz/python-project-workflow

---


# Python Project Workflow

Use this skill for Python code changes in a repository.

## Workflow

1. Inspect the relevant module and matching tests before editing.
2. Prefer configuration-driven behavior from existing schemas, JSON/YAML/TOML files or local helpers.
3. Keep edits scoped to the requested parser, filter, GUI, comparison, reporting or service path.
4. Add or update focused tests when behavior changes.
5. Run the narrowest relevant `pytest` command first, then broader tests if the change touches shared code.

## Validation Commands

- Focused test file: `venv/bin/python -m pytest path/to/test_file.py`
- All tests: `venv/bin/python -m pytest`
- If the repo provides scripts, prefer documented commands such as `scripts/RUN_TESTS.sh` or `scripts/RUN_COVERAGE.sh`.

## Generic Conventions

- Application code commonly lives under `src/`.
- Tests commonly live under `tests/`.
- Configuration commonly lives under `config/`, `pyproject.toml`, `setup.cfg`, `.ini`, `.json`, `.yaml` or `.toml` files.
- For generated UI/code artifacts, edit the source artifact first when identifiable, then regenerate using the existing project process.
- Avoid editing logs, generated reports, coverage HTML, or cached bytecode.

## Test Mapping Heuristic

- Parser/filter changes: look for `tests/parser/`, `tests/filter/`, or integration tests.
- Model changes: look for `tests/models/`.
- GUI logic: look for GUI-specific tests or Qt test folders.
- Reporting/comparison changes: look for tests named after the changed module or feature.