From 338bd28490100f559d48888d5f08d752e27f58d8 Mon Sep 17 00:00:00 2001 From: Pavel Lonkin Date: Thu, 11 Jun 2026 15:52:20 +0200 Subject: [PATCH] docs: correct collection/resources/mixins and add test docs to map architecture.md: fix the models entry (model_collection.py / ModelCollection, not collection.py / Collection); add exchange, integration, program, and spotlight resource domains to the tree; add StreamJSONLMixin and FilesOperationsMixin to the mixins table. usage.md: list client.program and client.spotlight and note the timeout argument on from_config. README.md and AGENTS.md: add docs/unit_tests.md and docs/e2e_tests.md to the documentation map. Note: the AsyncService 'stub' finding was not actioned (http/async_service.py defines a real AsyncService(ServiceBase) and the docs already describe it correctly). docs/e2e.md / docs/migrations.md not added (e2e is covered by e2e_tests.md; the client has no migrations). MPT-22057 Co-Authored-By: Claude Opus 4.8 --- AGENTS.md | 2 ++ README.md | 2 ++ docs/architecture.md | 13 ++++++++----- docs/usage.md | 4 ++++ 4 files changed, 16 insertions(+), 5 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 8c53df76..c8a07e22 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -23,6 +23,8 @@ When applicable, read the repository documentation in this order: 5. `docs/testing.md` — repository-specific testing strategy and command mapping 6. `docs/contributing.md` — repository-specific workflow and links to shared standards 7. `docs/documentation.md` — repository-specific documentation rules +8. `docs/unit_tests.md` — unit test structure and guidance +9. `docs/e2e_tests.md` — end-to-end test setup and execution Then inspect the code paths relevant to the task: diff --git a/README.md b/README.md index ac708173..d21f9667 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,8 @@ Start with these documents: - [docs/architecture.md](docs/architecture.md): repository structure, layers, and key abstractions - [docs/local-development.md](docs/local-development.md): Docker-only local setup and execution model - [docs/testing.md](docs/testing.md): repository-specific test strategy and commands +- [docs/unit_tests.md](docs/unit_tests.md): unit test structure and guidance +- [docs/e2e_tests.md](docs/e2e_tests.md): end-to-end test setup and execution - [docs/contributing.md](docs/contributing.md): repository-specific workflow and links to shared standards - [docs/documentation.md](docs/documentation.md): repository-specific documentation rules - [docs/rql.md](docs/rql.md): fluent RQL query builder guide diff --git a/docs/architecture.md b/docs/architecture.md index ec5b2b91..bcb924b0 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -50,7 +50,7 @@ mpt_api_client/ │ ├── models/ # Response models │ ├── model.py # Model base class (camelCase ↔ snake_case mapping) -│ ├── collection.py # Collection[Model] — paginated result set +│ ├── model_collection.py # ModelCollection — paginated result set │ ├── meta.py # Meta / Pagination metadata │ └── file_model.py # FileModel for binary responses │ @@ -60,8 +60,12 @@ mpt_api_client/ │ ├── billing/ # Invoices, Ledgers, Journals, Statements, Credit memos, … │ ├── catalog/ # Products, Listings, Price lists, Authorizations, … │ ├── commerce/ # Agreements, Orders, Subscriptions, Assets +│ ├── exchange/ # Exchange resources │ ├── helpdesk/ # Cases, Chats, Queues, Forms, … -│ └── notifications/ # Messages, Batches, Subscribers, … +│ ├── integration/ # Integration resources +│ ├── notifications/ # Messages, Batches, Subscribers, … +│ ├── program/ # Program resources +│ └── spotlight/ # Spotlight resources │ └── rql/ # RQL query builder ├── query_builder.py # RQLQuery, RQLProperty, RQLValue @@ -129,6 +133,8 @@ Services are composed using **mixins** that add HTTP operations: | `DownloadFileMixin` | download binary content | | `EnableMixin` / `DisableMixin` | enable/disable actions | | `QueryableMixin` | `filter()`, `order_by()`, `select()` — RQL query chaining | +| `StreamJSONLMixin` | `stream()` — stream JSONL records line by line (e.g. billing charges) | +| `FilesOperationsMixin` | combined file create / update / download operations | Example service definition: @@ -183,6 +189,3 @@ MPTError ├── MPTHttpError # generic HTTP error (status_code, message, body) │ └── MPTAPIError # structured API error (payload, title, detail, trace_id) ``` - - - diff --git a/docs/usage.md b/docs/usage.md index 565f307f..ee6327d6 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -57,6 +57,8 @@ client = MPTClient.from_config( ) ``` +`from_config` also accepts a `timeout` argument (HTTP request timeout in seconds, default `60.0`). + ## Synchronous Usage Patterns Read a single resource: @@ -115,6 +117,8 @@ The client exposes resource groups such as: - `client.helpdesk` - `client.integration` - `client.notifications` +- `client.program` +- `client.spotlight` See [architecture.md](architecture.md) for the repository structure and the [MPT OpenAPI spec](https://docs.platform.softwareone.com/developer-resources/rest-api/openapi-specification)