pycloudinary: Instructions file for Codex

AGENTS.md

This file is for agents contributing to this repository. If you are using the installed cloudinary package in another project, read the bundled docs in the installed package's cloudinary/docs/ directory instead.

Commands

pip install -e .                                  # install for development
pip install tox pytest                            # test tooling
python -m pytest test                             # core test suite
python -m pytest test/test_uploader.py             # a single module
tox                                               # full matrix (Python 3.10-3.14, Django 4.2-6.0)
tox -e py312-core                                 # one environment, as CI runs it
DJANGO_SETTINGS_MODULE=django_tests.settings \
  django-admin test -v2 django_tests              # Django integration suite
python -m build                                   # build sdist + wheel

Every suite needs a working CLOUDINARY_URL in the environment — there is no offline or mocked tier. CI allocates a throwaway cloud per job via tools/get_test_cloud.sh; locally, export your own or provision one with python -c "from cloudinary.provisioning import create_cloud; print(create_cloud())".

Testing

• test/ is the core suite and hits the live API. Tests namespace their assets with UNIQUE_TEST_ID from test/helper_test.py and clean up after themselves — follow that pattern rather than leaving fixtures behind.
• django_tests/ runs as a real Django app (django_tests.settings, in-memory sqlite). It covers CloudinaryField, the form fields, and migrations; the templatetags have no coverage yet.
• Provisioning tests (test/test_provisioning_api.py) additionally need CLOUDINARY_ACCOUNT_URL; they are skipped without it.
• Add-on tests (test/addon_types.py) require paid add-ons. Guard anything new with the existing skip decorators rather than making the default suite fail.
• Nondeterministic AI output (auto-tagging, captioning, moderation verdicts) must be asserted by request shape, state transition, and response schema — never exact values.
• There is no lint tooling in this repo. Do not add a linter or reformat files wholesale as part of an unrelated change.