diff --git a/.github/workflows/copilot-instructions.md b/.github/workflows/copilot-instructions.md index 665cbcc5..0fa19aed 100644 --- a/.github/workflows/copilot-instructions.md +++ b/.github/workflows/copilot-instructions.md @@ -1,43 +1,8 @@ --- -description: 'Python coding conventions and guidelines' -applyTo: '**/*.py' +description: 'Repository entry point for Copilot' +applyTo: '**' --- -# Python Coding Conventions +# Copilot Instructions -## General Instructions -- All configuration **must be provided via environment variables**. -- Do not hardcode configuration values. -- Write maintainable, readable, and predictable code. -- In `pyproject.toml`: - - Use `*` for **minor versions only** - ✅ `django==4.2.*` - ❌ `django==^4.2.2` - -- Use consistent naming conventions and follow language-specific best practices. - -## Python Instructions -- Use type annotations (PEP 484) - except in the `tests/` folder. -- All public functions, methods, and classes **must include [Google-style docstrings](https://google.github.io/styleguide/pyguide.html)**. -- **Do not add inline comments**; rely on clear code and docstrings instead. -- Function and variable names must be explicit and intention-revealing. -- `pyproject.toml` is the source of truth for code quality rules. Generated code must not violate any configured rules. -- **ruff** is the primary linter for general Python style and best practices. -- **flake8** is used exclusively to run: - - `wemake-python-styleguide` - Enforces strict Python coding standards ([docs](https://wemake-python-styleguide.readthedocs.io/en/latest/)) - - `flake8-aaa` - Validates the AAA pattern in tests -- Follow PEP 8 unless explicitly overridden by ruff. -- Prefer simple, explicit code over clever or compact implementations. - -## Testing -- Use pytest only. -- Tests must be written as **functions**, not classes. -- Test files and functions must use the `test_` prefix. -- Follow ***AAA(Arrange - Act - Assert)*** strictly. See the [flake8-aaa documentation](https://flake8-aaa.readthedocs.io/en/stable/index.html). -- Do **not** use `if` statements or branching logic inside tests. -- Prefer fixtures over mocks whenever possible. -- Avoid duplicating test logic; extract shared setup into fixtures. -- Use `mocker` only when mocking is unavoidable. -- Never use `unittest.mock` directly. -- Always use `spec` or `autospec` when mocking. -- Use `@pytest.mark.parametrize` tests when testing permutations of the same behavior. +Read [AGENTS.md](../../AGENTS.md) first. diff --git a/AGENTS.md b/AGENTS.md index e2c38161..a4c8485c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,32 +1,35 @@ # AGENTS.md -This file is the AI assistant entry point for `mpt-api-python-client`. - -## Repository Purpose - Python API client for the SoftwareONE Marketplace Platform (MPT) API. Provides synchronous (`MPTClient`) and asynchronous (`AsyncMPTClient`) clients built on httpx, with typed resource services, mixin-based HTTP operations, and an RQL query builder. ## Documentation Reading Order -1. `README.md` — project overview and quick start -2. `docs/architecture.md` — layered architecture, directory structure, key abstractions -3. `docs/testing.md` — test structure, tooling, conventions, how to run tests -4. `docs/contributing.md` — development workflow, coding conventions, linting setup -5. `docs/local-development.md` — Docker setup, Make targets, environment variables - -## Library Usage - -See `docs/PROJECT_DESCRIPTION.md` for installation and usage examples (sync and async). +1. `README.md` — repository overview, quick start, and documentation map +2. `docs/usage.md` — installation, configuration, Python usage examples, and supported Docker-based commands +3. `docs/architecture.md` — layered architecture, directory structure, and key abstractions +4. `docs/local-development.md` — Docker-only setup and execution model +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 + +Then inspect the code paths relevant to the task: + +- `mpt_api_client/mpt_client.py` — public sync and async client entry points +- `mpt_api_client/http/` — HTTP clients, services, query state, and reusable mixins +- `mpt_api_client/resources/` — domain resource groups such as catalog, commerce, billing, and integration +- `mpt_api_client/models/` — response model layer and collection wrappers +- `mpt_api_client/rql/` — fluent RQL query builder +- `tests/unit/` — unit coverage for transport, resources, models, and query builder +- `tests/e2e/` — live API coverage by domain +- `make/` and `compose.yaml` — Docker-based local command entry points ## API Reference -The upstream MPT API is described by the OpenAPI spec: +The upstream API contract is the MPT OpenAPI spec: https://api.s1.show/public/v1/openapi.json -Use this to understand available endpoints, request/response schemas, and field names. - ## Key Commands | Command | Purpose | @@ -36,6 +39,15 @@ Use this to understand available endpoints, request/response schemas, and field | `make check` | Run all linting and type checks | | `make check-all` | Run checks + tests | | `make format` | Auto-format code | +| `make bash` | Open a shell in the Docker container | +| `make run` | Start an IPython session in Docker | + +## Repository Rules + +- Prefer Docker-based `make` targets over ad hoc local Python commands. +- Keep `README.md` concise and navigational. +- Put topic-specific documentation under `docs/` instead of expanding `README.md`. +- Link shared engineering rules from `mpt-extension-skills` instead of duplicating them locally. ## Project Structure @@ -48,16 +60,3 @@ mpt_api_client/ ├── rql/ # RQL query builder └── exceptions.py # Error hierarchy ``` - -## Shared Standards - -This repository follows shared engineering standards from -[mpt-extension-skills](https://github.com/softwareone-platform/mpt-extension-skills): - -- `standards/python-style-guide.md` -- `standards/testing-standard.md` -- `standards/contributing-standard.md` -- `standards/pull-request-guidelines.md` - - - diff --git a/README.md b/README.md index f75890c7..ac708173 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,3 @@ -[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=softwareone-platform_mpt-api-python-client&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=softwareone-platform_mpt-api-python-client) -[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=softwareone-platform_mpt-api-python-client&metric=coverage)](https://sonarcloud.io/summary/new_code?id=softwareone-platform_mpt-api-python-client) -[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) - # mpt-api-python-client Python API client for the SoftwareONE Marketplace Platform (MPT) API. @@ -10,6 +6,20 @@ Provides synchronous (`MPTClient`) and asynchronous (`AsyncMPTClient`) clients b [httpx](https://www.python-httpx.org/), with typed resource services, mixin-based HTTP operations, and an RQL query builder. +## Documentation + +Start with these documents: + +- [AGENTS.md](AGENTS.md): AI-agent entry point and reading order +- [docs/usage.md](docs/usage.md): installation, configuration, Python usage examples, and Docker-based commands +- [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/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 +- [MPT OpenAPI Spec](https://api.s1.show/public/v1/openapi.json): upstream API contract + ## Quick Start ```bash @@ -18,51 +28,10 @@ make build make test ``` -## Usage - -**[Installation & Usage Guide](docs/PROJECT_DESCRIPTION.md)** - -```python -from mpt_api_client import MPTClient - -client = MPTClient() # reads MPT_API_TOKEN and MPT_API_BASE_URL from environment - -for product in client.catalog.products.iterate(): - print(product.name) -``` - -### RQL Filtering Example - -```python -from mpt_api_client import MPTClient, RQLQuery - -client = MPTClient() -products = client.catalog.products - -target_ids = RQLQuery("id").in_([ - "PRD-123-456", - "PRD-789-012", -]) -active = RQLQuery(status="active") -vendor = RQLQuery("vendor.name").eq("Microsoft") - -query = target_ids & active & vendor - -for product in products.filter(query).order_by("-audit.updated.at").select("id", "name").iterate(): - print(product.id, product.name) -``` - -## Documentation +Use `make help` to inspect all supported Docker-based commands. -| Document | Description | -|----------------------------------------------------------------|-------------------------------------------------------------| -| [Architecture](docs/architecture.md) | Layered architecture, directory structure, key abstractions | -| [RQL Guide](docs/rql.md) | Fluent builder for Resource Query Language filters | -| [Contributing](docs/contributing.md) | Development workflow, coding conventions, linting setup | -| [Testing](docs/testing.md) | Test structure, tooling, conventions | -| [Local Development](docs/local-development.md) | Docker setup, Make targets, environment variables | -| [Usage Guide](docs/PROJECT_DESCRIPTION.md) | Installation, sync and async usage examples | -| [MPT OpenAPI Spec](https://api.s1.show/public/v1/openapi.json) | Upstream API contract (endpoints, schemas) | +See [docs/usage.md](docs/usage.md) for installation details, sync and async examples, RQL +usage, and Docker-based command examples. ## Key Commands @@ -75,5 +44,3 @@ make format # auto-format code make bash # open a shell in the container make run # start an IPython session ``` - -Run `make help` to see all available commands. diff --git a/docs/PROJECT_DESCRIPTION.md b/docs/PROJECT_DESCRIPTION.md deleted file mode 100644 index e2faaf92..00000000 --- a/docs/PROJECT_DESCRIPTION.md +++ /dev/null @@ -1,52 +0,0 @@ -# mpt-api-python-client - -mpt-api-python-client is a Python client for interacting with the MPT API - -## Installation - -Install with pip or your favorite PyPI package manager: - -```bash -pip install mpt-api-client -``` - -```bash -uv add mpt-api-client -``` - -## Prerequisites - -- Python 3.12+ in your environment - -## Usage - -```python -from mpt_api_client import MPTClient - -# client = MPTClient(api_key=, base_url=) -client = MPTClient() # Reads MPT_API_TOKEN and MPT_API_BASE_URL from the environment - -for product in client.catalog.products.iterate(): - print(product.name) -``` - -## Async Usage - -```python -import asyncio -from mpt_api_client import AsyncMPTClient - - -async def main(): - # client = AsyncMPTClient(api_key=, base_url=) - client = AsyncMPTClient() # Reads MPT_API_TOKEN and MPT_API_BASE_URL from the environment - async for product in client.catalog.products.iterate(): - print(product.name) - - -asyncio.run(main()) -``` - -## Development - -For development purposes, please, check the Readme in the GitHub repository. diff --git a/docs/contributing.md b/docs/contributing.md index 469bbec6..a827b92c 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -1,15 +1,42 @@ # Contributing -This document describes the development workflow and coding conventions for -`mpt-api-python-client`. +This document captures repository-specific contribution guidance. Shared engineering rules +live in `mpt-extension-skills` and should be linked, not copied, from this repository. -- [Package architecture](./architecture.md) -- [Python coding standards](https://github.com/softwareone-platform/mpt-extension-skills/blob/main/standards/python-coding.md) -- [Extensions best practices](https://github.com/softwareone-platform/mpt-extension-skills/blob/main/standards/extensions-best-practices.md) +## Shared Standards + +- [Python coding conventions](https://github.com/softwareone-platform/mpt-extension-skills/blob/main/standards/python-coding.md) - [Packages and dependencies](https://github.com/softwareone-platform/mpt-extension-skills/blob/main/standards/packages-and-dependencies.md) -- [Testing](./testing.md) - - [Unit tests](./unit_tests.md) - - [E2E tests](./e2e_tests.md) - [Pull requests](https://github.com/softwareone-platform/mpt-extension-skills/blob/main/standards/pull-requests.md) -- [Makefiles](https://github.com/softwareone-platform/mpt-extension-skills/blob/main/standards/makefiles.md) - - [Makefile targets](https://github.com/softwareone-platform/mpt-extension-skills/blob/main/knowledge/make-targets.md) +- [Repository documentation](https://github.com/softwareone-platform/mpt-extension-skills/blob/main/standards/documentation.md) +- [Makefile structure](https://github.com/softwareone-platform/mpt-extension-skills/blob/main/standards/makefiles.md) + +## Shared Knowledge + +- [Build and checks](https://github.com/softwareone-platform/mpt-extension-skills/blob/main/knowledge/build-and-checks.md) +- [Make target meanings](https://github.com/softwareone-platform/mpt-extension-skills/blob/main/knowledge/make-targets.md) + +## Development Model + +This repository uses Docker as the default local execution model. + +- Use `make build` to build the container image. +- Use `make bash` when you need an interactive shell inside the container. +- Use `make run` for an IPython session with project dependencies available. +- Use `make test`, `make check`, and `make check-all` through the provided `make` targets. + +## Repository-Specific Expectations + +- Keep public API changes aligned with [`mpt_api_client/mpt_client.py`](../mpt_api_client/mpt_client.py) and the resource/service layout described in [architecture.md](architecture.md). +- Keep resource-specific behavior inside the matching module under [`mpt_api_client/resources/`](../mpt_api_client/resources). +- Keep transport and query behavior inside [`mpt_api_client/http/`](../mpt_api_client/http) and [`mpt_api_client/rql/`](../mpt_api_client/rql). +- Add or update tests near the affected domain under [`tests/unit/`](../tests/unit) or [`tests/e2e/`](../tests/e2e). +- When repository behavior changes, update the narrowest relevant document under [`docs/`](.). + +## Validation Before Review + +Follow the shared validation flow from +[knowledge/build-and-checks.md](https://github.com/softwareone-platform/mpt-extension-skills/blob/main/knowledge/build-and-checks.md). + +In this repository, run validation through the Docker-based targets documented in +[testing.md](testing.md). Use `make build` first when dependencies or `uv.lock` change. diff --git a/docs/documentation.md b/docs/documentation.md new file mode 100644 index 00000000..7b90d4ac --- /dev/null +++ b/docs/documentation.md @@ -0,0 +1,31 @@ +# Documentation + +This repository follows the shared documentation standard: + +- [standards/documentation.md](https://github.com/softwareone-platform/mpt-extension-skills/blob/main/standards/documentation.md) + +This file documents repository-specific documentation rules only. + +## Repository Rules + +- `README.md` must stay concise and act as the main human entry point. +- `AGENTS.md` must stay operational and tell AI agents which files to read first. +- Topic-specific documentation must live in the matching file under [`docs/`](.). +- Shared engineering rules must be linked from `mpt-extension-skills` instead of copied into this repository. +- When changing setup, usage, testing, or architecture behavior, update the corresponding document in the same change. +- `docs/usage.md` is the source of truth for installation, configuration, examples, and supported command entry points. + +## Current Documentation Map + +- [`README.md`](../README.md): overview, quick start, and documentation map +- [`AGENTS.md`](../AGENTS.md): AI-agent entry point and reading order +- [`usage.md`](usage.md): install, configure, and use the client +- [`architecture.md`](architecture.md): repository structure and major abstractions +- [`local-development.md`](local-development.md): Docker-only local setup and execution +- [`testing.md`](testing.md): repository-specific testing strategy +- [`contributing.md`](contributing.md): repository workflow and shared-standard links +- [`rql.md`](rql.md): RQL query builder guide + +## Change Rule + +Prefer updating the smallest relevant document instead of creating overlapping summary files. diff --git a/docs/local-development.md b/docs/local-development.md index 7f7ce449..7979a6f6 100644 --- a/docs/local-development.md +++ b/docs/local-development.md @@ -1,14 +1,14 @@ # Local Development -This document describes how to set up and run `mpt-api-python-client` locally. +This document describes the Docker-only local setup for `mpt-api-python-client`. -Make sure you have read the [Contributing guidelines](./contributing.md) +Read [contributing.md](./contributing.md) for the repository workflow and +[usage.md](./usage.md) for installation and runtime examples. ## Prerequisites - **Docker** and **Docker Compose** plugin (`docker compose` CLI) - **Make** -- [CodeRabbit CLI](https://www.coderabbit.ai/cli) (optional — used for running review checks locally) ## Setup @@ -33,7 +33,7 @@ Edit `.env` with your actual values. See [Environment Variables](#environment-va make build ``` -This creates the Docker images with all required dependencies and the virtual environment. +This builds the `app` image defined in [`compose.yaml`](../compose.yaml). ### 4. Verify the setup @@ -41,35 +41,22 @@ This creates the Docker images with all required dependencies and the virtual en make test ``` -## Running the Client +## Working In Docker -Start an interactive IPython session with the client available: +Use the repository make targets instead of ad hoc local Python commands. +For the full command catalog, see [usage.md](./usage.md) and [testing.md](./testing.md). ```bash -make run +make bash # open a shell in the app container +make run # start an IPython session in the app container ``` -Ensure your `.env` file is populated with valid `MPT_API_BASE_URL` and `MPT_API_TOKEN` values. - ## Environment Variables -### Application - -| Variable | Default | Example | Description | -|--------------------|---------|--------------------------------------|-----------------------------------| -| `MPT_API_BASE_URL` | — | `https://portal.softwareone.com/mpt` | SoftwareONE Marketplace API URL | -| `MPT_API_TOKEN` | — | `eyJhbGciOiJSUzI1N...` | SoftwareONE Marketplace API Token | +Docker Compose loads environment variables from `.env`. -### End-to-End Testing - -| Variable | Default | Example | Description | -|----------------------------|---------|------------------------------------|--------------------------| -| `MPT_API_TOKEN_CLIENT` | — | `eyJhbGciOiJSUzI1N...` | Client API token | -| `MPT_API_TOKEN_OPERATIONS` | — | `eyJhbGciOiJSUzI1N...` | Operations API token | -| `MPT_API_TOKEN_VENDOR` | — | `eyJhbGciOiJSUzI1N...` | Vendor API token | -| `RP_API_KEY` | — | `pytest_XXXX` | ReportPortal API key | -| `RP_ENDPOINT` | — | `https://reportportal.example.com` | ReportPortal endpoint | -| `RP_LAUNCH` | — | `dev-env` | ReportPortal launch name | +- Client variables are documented in [usage.md](./usage.md#configuration). +- E2E-specific variables are documented in [e2e_tests.md](./e2e_tests.md#environment-variables). ## Docker @@ -77,31 +64,15 @@ The development environment runs entirely inside Docker: - **Base image**: `ghcr.io/astral-sh/uv:python3.12-bookworm-slim` - **Package manager**: [uv](https://docs.astral.sh/uv/) -- **Services**: defined in `compose.yaml` — a single `app` service that mounts the project directory. +- **Service**: `app`, defined in [`compose.yaml`](../compose.yaml), with the repository mounted at `/mpt_api_client` ## Make Targets -Common development workflows are wrapped in the Makefile. Run `make help` to see all available -commands. - -[Read make targets for additional information](https://github.com/softwareone-platform/mpt-extension-skills/blob/main/knowledge/make-targets.md) - -### How the Makefile Works - -[Read the makefile architecture for python repositories](https://github.com/softwareone-platform/mpt-extension-skills/blob/main/standards/makefiles.md) - -# Additional Resources -- [Package architecture](./architecture.md) -- [Python coding standards](https://github.com/softwareone-platform/mpt-extension-skills/blob/main/standards/python-coding.md) -- [Extensions best practices](https://github.com/softwareone-platform/mpt-extension-skills/blob/main/standards/extensions-best-practices.md) -- [Packages and dependencies](https://github.com/softwareone-platform/mpt-extension-skills/blob/main/standards/packages-and-dependencies.md) -- [Testing](./testing.md) - - [Unit tests](./unit_tests.md) - - [E2E tests](./e2e_tests.md) -- [Pull requests](https://github.com/softwareone-platform/mpt-extension-skills/blob/main/standards/pull-requests.md) -- [Makefiles](https://github.com/softwareone-platform/mpt-extension-skills/blob/main/standards/makefiles.md) - - [Makefile targets](https://github.com/softwareone-platform/mpt-extension-skills/blob/main/knowledge/make-targets.md) +Run `make help` to see all available commands. +Shared references: +- [knowledge/make-targets.md](https://github.com/softwareone-platform/mpt-extension-skills/blob/main/knowledge/make-targets.md) +- [standards/makefiles.md](https://github.com/softwareone-platform/mpt-extension-skills/blob/main/standards/makefiles.md) diff --git a/docs/testing.md b/docs/testing.md index 880b8ec4..42cf5222 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -1,30 +1,55 @@ # Testing -This document provides a high-level overview of the testing strategy for -`mpt-api-python-client` and points to the detailed guides for each test type. +Shared test rules live in +[standards/unittests.md](https://github.com/softwareone-platform/mpt-extension-skills/blob/main/standards/unittests.md). +This document covers repository-specific testing behavior only. -## Guides +## Test Scope -- [Unit test guide](unit_tests.md) — structure, conventions, tooling, and examples. -- [E2E test guide](e2e_tests.md) — directory layout, execution instructions, and environment setup. +The repository has two main test layers: -For a quick validation run: `make check && make test`. +- [Unit tests](unit_tests.md) under [`tests/unit/`](../tests/unit) for transport, models, + resources, and the RQL builder +- [End-to-end tests](e2e_tests.md) under [`tests/e2e/`](../tests/e2e) for live API coverage -## Coverage +`make test` runs the unit suite by default. E2E tests are opt-in and require live credentials. -Coverage is collected automatically via `pytest-cov` with the following defaults: +## Commands + +Run all test commands through Docker-based make targets: + +```bash +make test +make test args="tests/unit/http" +make test args="tests/e2e" +make check +make check-all +``` + +Repository command mapping: + +- `make test` runs `pytest` against `tests/unit` unless `args` overrides the path +- `make check` runs `ruff format --check`, `ruff check`, `flake8`, `mypy`, and `uv lock --check` +- `make check-all` runs both `check` and `test` + +## Pytest And Coverage - Source: `mpt_api_client/` - Reports: terminal (missing lines) + XML (`coverage.xml`) - Branch coverage enabled -- `__init__.py` files excluded +- `__init__.py` files omitted from coverage reports Results are reported to SonarCloud via `sonar-project.properties`. -## Shared Standards +Repository-specific pytest settings live in [`pyproject.toml`](../pyproject.toml), including: -This repository follows the shared testing standard from -[mpt-extension-skills](https://github.com/softwareone-platform/mpt-extension-skills): +- discovery under `tests` +- repository root on `pythonpath` +- import mode `importlib` +- async fixture loop scope and warning filters -- `standards/testing-standard.md` +## Repository Constraints +- E2E suites require configured MPT credentials and optional ReportPortal settings; see [e2e_tests.md](e2e_tests.md). +- Keep live API coverage in `tests/e2e/` separate from unit-only behavior in `tests/unit/`. +- When changing public client behavior, service mixins, resource modules, or query building, update the matching unit coverage. diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 00000000..565f307f --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,158 @@ +# Usage + +This guide is for developers who need to install the library, configure the client, and use +its sync or async APIs in their own code. + +## Installation + +Install the package with `pip` or `uv`: + +```bash +pip install mpt-api-client +uv add mpt-api-client +``` + +## Prerequisites + +- Python 3.12+ +- Access to an MPT API base URL +- An MPT API token + +## Configuration + +The client reads configuration from constructor arguments or the environment. + +Environment variables: + +| Variable | Required | Description | +|--------------------|----------|------------------------------------| +| `MPT_API_BASE_URL` | yes | SoftwareONE Marketplace API URL | +| `MPT_API_TOKEN` | yes | SoftwareONE Marketplace API token | + +Example `.env` snippet: + +```env +MPT_API_BASE_URL= +MPT_API_TOKEN= +``` + +## Instantiate The Client + +You can rely on environment variables: + +```python +from mpt_api_client import MPTClient + +client = MPTClient() +``` + +Or pass configuration explicitly: + +```python +from mpt_api_client import MPTClient + +client = MPTClient.from_config( + api_token="token", + base_url="https://api.s1.show/public", +) +``` + +## Synchronous Usage Patterns + +Read a single resource: + +```python +from mpt_api_client import MPTClient + +client = MPTClient() + +product = client.catalog.products.get("PRD-123-456") +print(product.name) +``` + +Iterate through a collection: + +```python +from mpt_api_client import MPTClient + +client = MPTClient() + +for invoice in client.billing.invoices.iterate(): + print(invoice.id) +``` + +## Asynchronous Usage Patterns + +```python +import asyncio + +from mpt_api_client import AsyncMPTClient + + +async def main(): + client = AsyncMPTClient() + + product = await client.catalog.products.get("PRD-123-456") + print(product.name) + + async for item in client.catalog.products.iterate(): + print(item.id, item.name) + + +asyncio.run(main()) +``` + +## Navigate The API Surface + +The client exposes resource groups such as: + +- `client.accounts` +- `client.audit` +- `client.billing` +- `client.catalog` +- `client.commerce` +- `client.exchange` +- `client.helpdesk` +- `client.integration` +- `client.notifications` + +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) +for the upstream endpoint contract. + +## Filtering And Querying + +Use `filter()`, `order_by()`, and `select()` on queryable resources. + +The full RQL syntax and builder usage are documented in [rql.md](rql.md). Treat that file as +the source of truth for query composition. + +Typical example: + +```python +from mpt_api_client import MPTClient, RQLQuery + +client = MPTClient() + +target_ids = RQLQuery("id").in_(["PRD-123-456", "PRD-789-012"]) +active = RQLQuery(status="active") +vendor = RQLQuery("vendor.name").eq("Microsoft") + +query = target_ids & active & vendor + +for product in ( + client.catalog.products + .filter(query) + .order_by("-audit.updated.at") + .select("id", "name") + .iterate() +): + print(product.id, product.name) +``` + +## Related Documents + +- [testing.md](testing.md): validation and test command behavior +- [rql.md](rql.md): RQL builder guide +- [architecture.md](architecture.md): repository structure and abstractions +- [local-development.md](local-development.md): repository-local Docker workflow for contributors diff --git a/pyproject.toml b/pyproject.toml index 7ccab9bd..d8ad8f26 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ version = "1.0.0" description = "SoftwareOne Marketplace API Client for Python" authors = [{ name = "SoftwareOne AG" }] requires-python = ">=3.12,<4" -readme = "docs/PROJECT_DESCRIPTION.md" +readme = "README.md" license = { text = "Apache-2.0 license" } keywords = [ "openapi", @@ -53,10 +53,10 @@ dev = [ ] [tool.hatch.build.targets.sdist] -include = ["mpt_api_client", "docs/PROJECT_DESCRIPTION.md"] +include = ["mpt_api_client", "README.md"] [tool.hatch.build.targets.wheel] -include = ["mpt_api_client"] +include = ["mpt_api_client", "README.md"] [build-system] requires = ["hatchling"]