How ynput/ayon-python-api works
Project type and purpose
• This is an open-source Python client library (“ayon-python-api”) for communicating with an AYON connection server over REST and GraphQL.
• It provides both “raw” HTTP methods and higher-level entity-oriented operations (CRUD for entities, events, etc.).
File structure
• Top-level files:
• setup.py, pyproject.toml, LICENSE, README.md – packaging and metadata
• automated_api.py – glue for auto-generating API calls
• Core package “ayon_api/”:
• _api.py – low-level HTTP/GraphQL request logic (uses requests)
• server_api.py, constants.py, utils.py, exceptions.py – connection management, configuration, error handling
• graphql.py, graphql_queries.py – GraphQL client and query definitions
• operations.py – CRUD operations on AYON entities (folders, tasks, etc.)
• entity_hub.py – high-level façade that groups entity operations into domain objects
• typing.py, version.py – type stubs and version info
• docs/ – Sphinx documentation source, Makefiles, CI workflow for docs publishing
• .github/workflows – linting, publishing to PyPI, docs deployment
• tests/ – unit tests for each module, fixtures in tests/resources
README for additional insights
• Explains singleton vs. multiple‐connection model (ServerAPI vs. ServerAPIBase).
• References REST and GraphQL communications, environment variables (AYON_SERVER_URL, AYON_API_KEY).
• TODOs point toward splitting ServerAPI (currently monolithic ~4k LOC).
Components
a. Main components:
• Client Application (user’s Python code)
• AYON-Python-API Library
– Connection Manager (ServerAPIBase / singleton wrapper)
– HTTP Transport Layer (_api.py)
– REST Adapters & GraphQL Client (graphql.py + graphql_queries.py)
– CRUD Operations Module (operations.py)
– Entity Hub (entity_hub.py)
– Utilities/Config (constants.py, utils.py, exceptions.py, typing.py)
• AYON Server (external service exposing REST & GraphQL endpoints)
• CI/CD Pipeline (GitHub Actions for lint/docs/publish)
• Package Repository (PyPI)
b. Relationships & interactions:
– Developer code → imports → Connection Manager → Transport Layer
– Operations & GraphQL modules invoke Transport Layer → AYON Server
– Entity Hub aggregates Operations → returns domain objects to developer
– CI/CD pushes new versions to PyPI; docs hosted via GitHub Pages
c. Architectural patterns & principles:
– Layered architecture (EntityHub → Operations → ServerAPI → HTTP)
– Singleton pattern for default connection; factory pattern via ServerAPIBase for multiple servers
– Separation of concerns: raw API vs. prepared entity API
– Extensibility points: automated_api for code generation, placeholder for future WebSockets
d. Key technologies & libraries:
– Python requests for HTTP/GraphQL transport
– Sphinx for docs
– pytest for testing
– GitHub Actions for CI/CD
– setuptools / wheel for packaging
Detailed but focused
• Every major module and its role.