python_scripts

Imported from zlatanstajic/python_scripts (AGENTS.md). Install upstream with npx skills add zlatanstajic/python_scripts. Copyright stays with the author.

Repository Instructions

These instructions apply to every agent working in this repository.

Before editing

• Read a file before changing it.
• Search all callers before changing a function, CLI contract, or shared type. Use rg or rg --files for discovery.
• Read README.md, CONTRIBUTING.md, and the relevant Sphinx page before making non-trivial behavior changes.
• Preserve existing user changes and keep unrelated work out of the patch.

Source ownership

• scripts/ is the installable application package. It contains the CV generator and website screenshot utilities.
• tests/ contains pytest tests. Test files use the test_*.py naming convention.
• docs/ contains the Sphinx documentation.
• tools/ contains maintainer-only utilities and must not become part of the user-facing command package.
• setup/ contains development setup helpers.
• assets/img/og-image.png is generated by tools/gen-og-image.py. Change the generator, then regenerate the PNG rather than editing the image directly.

Python conventions

• Support Python 3.10 through 3.12.
• Follow PEP 8, use snake_case, and keep lines within 88 characters.
• Add type hints where practical and use Google-style docstrings.
• Keep imports compatible with the Black and isort configuration in pyproject.toml.
• Preserve documented CLI behavior and configuration-only interfaces. Do not introduce new flags or change output paths without updating tests and docs.
• Read runtime configuration through python-dotenv. Document new keys in .env.example, but never read or write a real .env file.
• Do not add a dependency or materially change packaging without explicit approval.

Dependencies and documentation

• Keep runtime dependencies synchronized between pyproject.toml and requirements.txt.
• Keep development dependencies synchronized between pyproject.toml and requirements-dev.txt.
• Update README.md and the relevant Sphinx pages whenever commands, configuration, behavior, or workflow changes.
• Use zlatanstajic as the canonical GitHub username in repository and GitHub Pages URLs. Do not infer canonical project URLs from a stale local remote.

Testing and verification

Run checks in proportion to the change. Before handing off a production code change, run:

python -m pytest tests/
python -m compileall -q scripts tests
python -m flake8 scripts/
python -m mypy scripts/
python -m pydocstyle scripts/
python -m bandit -r scripts/ -ll
python -m isort . --profile black --check-only --diff
python -m black . --check --diff
python -m sphinx -W -b html docs docs/_build/html

Tests measure coverage over scripts/. Add or update tests for every behavior change, and keep tests isolated from real network, browser, filesystem, and environment state where practical.

Treat Sphinx warnings as errors. Keep API documentation, examples, usage, and installation guidance synchronized with the implementation.

Git discipline

• Do not run git add unless the user explicitly asks.
• Never stage or commit changes on your own initiative.
• Do not discard, reset, or overwrite unrelated working-tree changes.
• If branch creation is requested, branch from master and use issues/<issue-number>-<short-description>, with the description in kebab-case (lowercase words separated by single hyphens, never snake_case).

Secrets

• Never read or write .env files.
• Never expose secrets in source code, fixtures, logs, generated files, or chat output.
• Use environment variables for sensitive values and ask the user for access when a task requires a secret.