docs: add agent-readable documentation and repository metadata - #450
Merged
Conversation
Bring the repository up to the Cloudinary agent-readable documentation standard established in cloudinary_npm (PRs #742, #744). - Restructure README around the standard section order, with a runnable quick start and a stated read path for coding agents. - Add 15 task docs under cloudinary/docs/, shipped inside the published package so they install to site-packages/cloudinary/docs/ and are version-matched with the code. Includes a Django page, which has no equivalent in the Node SDK. - Add examples/ with 8 complete runnable files, one per "doing" task, cross-linked with their task docs. - Add AGENTS.md, CLAUDE.md, SECURITY.md, and context7.json. - Replace the three-line LICENSE.txt stub with canonical MIT text at LICENSE, preserving the vendored poster attribution. This is what GitHub and license scanners need to detect the license. - Ship docs via MANIFEST.in plus package-data; keep examples/ repo-only. - Set the PyPI summary to match the README one-liner. - Correct stale facts in CONTRIBUTING.md (Travis, setup.py test, and the supported version matrix). Every doc snippet and all 8 examples were executed against a live cloud. Documented behavior that differs from a first reading of the code, and is now stated in the docs: upload_large defaults to resource_type="raw" and silently stores a video as an opaque blob; re-uploading to the same public_id overwrites by default; the upload result exposes a moderation list rather than a flat moderation_status; undefined structured-metadata keys are rejected rather than ignored; the dict form of the video poster option ignores secure=True; Search rejects leading wildcards. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Co-authored-by: Eitan Peer <eitan.peer@cloudinary.com>
Address review feedback on delivery behavior, and align the shared task docs with the corrections verified in cloudinary_npm PR #742. Moderation: a pending asset is deliverable by default — the status is metadata to gate on, not an access control. Blocking non-approved assets is configured per product environment by support, not by an upload parameter. Statuses are queued, pending, approved, rejected, and aborted. Fixes the intro, the statuses line, the troubleshooting entry (which had the behavior inverted), and the example. Adds the full add-on table and pipe-combination semantics. Size limits: separate the 100 MB per-request ceiling from the plan-dependent environment maximum, which chunking does not raise, and show api.usage()["media_limits"] for reading the real values. Troubleshooting: document 423 while processing, noting it is absent from this SDK's EXCEPTION_CODES map and so raises a plain Exception rather than a cloudinary.exceptions.Error subclass. Add the platform status page. Also note IPv4/IPv6 support for delivery_ips. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Brings pycloudinary in line with the agent-readable documentation standard already shipped in
cloudinary_npm.Supersedes #449, which was closed and reopened so review starts from the current state of the branch. All feedback from that review is applied here.
What this adds
README.mdrestructured to the npm section layout (Install, Quick start, Common tasks, When to use this SDK, Status and compatibility, Documentation, For AI coding agents, Support, Security, License).AGENTS.md(6 sections) plusCLAUDE.md→@AGENTS.md, matching npm.cloudinary/docs/— 15 task pages shipped inside the PyPI package, so they are version-matched to the installed release. Wired up viaMANIFEST.inand[tool.setuptools.package-data].examples/— 9 complete runnable scripts, repo-only (excluded from the wheel).SECURITY.md,context7.json, canonicalLICENSEat root.Python-specific deviations from npm
cloudinary/docs/, not rootdocs/— only an in-package directory installs deterministically from a wheel. Maps 1:1 to npm'snode_modules/cloudinary/docs/.examples/is not shipped in the wheel. Loose.pyfiles inside the importable package risk import shadowing. Every doc page carries the complete runnable flow, so the agent read path is intact.use-with-django.md, coveringCloudinaryField, the form fields, and migrations.Review feedback applied
Corrections from the #449 review, cross-checked against the equivalent fixes already verified in
cloudinary_npmPR #742:pendingasset is deliverable by default — the status is metadata to gate on, not an access control. Blocking non-approved assets is configured per product environment by Cloudinary support, not by an upload parameter. Statuses arequeued,pending,approved,rejected,aborted(five, not three). This fixed the page intro, the statuses line, a troubleshooting entry that had the behavior inverted, andexamples/moderate-upload.py. The add-on table was completed (aws_rek_video,webpurify,duplicate:<threshold>) with pipe-combination semantics.api.usage()["media_limits"]snippet so readers get real values for their own environment.423while processing documented, including a Python-specific caveat: 423 is absent from this SDK'sEXCEPTION_CODESmap (cloudinary/api_client/execute_request.py), so it raises a plainExceptionrather than acloudinary.exceptions.Errorsubclass.delivery_ips— IPv4 and IPv6 both accepted; CIDR ranges are not.create_cloud()reference inconfigure-cloudinary.md.One suggestion was not applied: nesting the claimable-cloud response under
cloud["claim"]["url"]. The API returnsclaim_url,delivery_ips, andexpires_atflat at the top level — confirmed intest/test_provisioning_api.pyandexamples/provision-claimable-cloud.py. The docs match the actual response shape.secure=Truein the explicit-config example is intentional: this is the v1 SDK, which is not secure by default.Verification
cloudinary.*calls resolve against the real SDK, and all arguments bind to actual signatures.CLOUDINARY_URLall examples print a friendly message and exit 1; with bad credentials all API examples surface the real error and exit 1..mdfiles present in both wheel and sdist;examples/correctly absent.Notes for review
CHANGELOG.mdintentionally untouched — the npm reference PRs added no changelog entries for docs work.AGENTS.md.🤖 Generated with Claude Code