libthumbor: Instructions file for Codex

AGENTS.md

libthumbor is a Python library for composing and signing thumbor image URLs. It provides helpers for secure URL generation, URL parsing, and integration points that other applications can use to talk to thumbor safely.

Dev environment setup

• Prerequisites: Python 3.11+ and uv

• Install project and development dependencies:

  make setup
  

  Equivalent to: uv sync

• If you prefer running commands directly, use uv run ... so the virtual environment stays consistent with CI and local development.

Running tests

• Full local validation flow:

  make test
  

• Individual targets:

  make unit
  make coverage
  make flake8
  make pylint
  

• The test suite runs with pytest and collects coverage for the libthumbor package.

Code style

• Formatter: black with line length 88 and Python 3.11 target, configured in pyproject.toml.
• Linter: flake8 with max complexity 20, configured in .flake8.
• Static analysis: pylint, configured in .pylintrc.
• Primary workflow commands live in the Makefile; prefer them over ad hoc shell commands when possible.

Project structure

libthumbor/              <- main package
  __init__.py            <- package exports
  crypto.py              <- secure URL generation helpers
  url.py                 <- URL composer and parsing utilities
tests/                   <- pytest suite
  test_cryptourl.py      <- signing and encrypted URL behavior
  test_libthumbor.py     <- package-level behavior
  test_url.py            <- URL parsing and composition
  test_url_composer.py   <- URL builder coverage
  test_generic_views.py  <- Django integration coverage
README.md                <- project overview and usage example
CONTRIBUTING.md          <- contribution workflow notes
Makefile                 <- common setup, test, and lint tasks
pyproject.toml           <- project metadata, dependencies and tool configuration
uv.lock                  <- locked dependency versions