docs: add agent-readable documentation and repository metadata - #449
Open
const-cloudinary wants to merge 1 commit into
Open
docs: add agent-readable documentation and repository metadata#449const-cloudinary wants to merge 1 commit into
const-cloudinary wants to merge 1 commit into
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>
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.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.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