Skip to content

Commit 15cbec0

Browse files
albertsolaalbertsola
authored
MPT-19004 Documentation update (#254)
2 parents 3cdd0d1 + 560ecea commit 15cbec0

File tree

10 files changed

+633
-95
lines changed

10 files changed

+633
-95
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Copilot Instructions
2+
3+
This repository is `mpt-api-python-client` — a Python API client for the SoftwareONE
4+
Marketplace Platform API.
5+
6+
Read `AGENTS.md` in the repository root for the full documentation index, reading order,
7+
key commands, and project structure.
8+
9+
Quick validation: `make check && make test`

‎AGENTS.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# AGENTS.md
2+
3+
This file is the AI assistant entry point for `mpt-api-python-client`.
4+
5+
## Repository Purpose
6+
7+
Python API client for the SoftwareONE Marketplace Platform (MPT) API. Provides synchronous
8+
(`MPTClient`) and asynchronous (`AsyncMPTClient`) clients built on httpx, with typed
9+
resource services, mixin-based HTTP operations, and an RQL query builder.
10+
11+
## Documentation Reading Order
12+
13+
1. `README.md` — project overview and quick start
14+
2. `docs/architecture.md` — layered architecture, directory structure, key abstractions
15+
3. `docs/testing.md` — test structure, tooling, conventions, how to run tests
16+
4. `docs/contributing.md` — development workflow, coding conventions, linting setup
17+
5. `docs/local-development.md` — Docker setup, Make targets, environment variables
18+
19+
## Library Usage
20+
21+
See `docs/PROJECT_DESCRIPTION.md` for installation and usage examples (sync and async).
22+
23+
## API Reference
24+
25+
The upstream MPT API is described by the OpenAPI spec:
26+
https://api.s1.show/public/v1/openapi.json
27+
28+
Use this to understand available endpoints, request/response schemas, and field names.
29+
30+
## Key Commands
31+
32+
| Command | Purpose |
33+
|------------------|------------------------------------------|
34+
| `make build` | Build the Docker development environment |
35+
| `make test` | Run unit tests |
36+
| `make check` | Run all linting and type checks |
37+
| `make check-all` | Run checks + tests |
38+
| `make format` | Auto-format code |
39+
40+
## Project Structure
41+
42+
```text
43+
mpt_api_client/
44+
├── mpt_client.py # MPTClient / AsyncMPTClient entry points
45+
├── http/ # HTTP transport, services, mixins
46+
├── resources/ # API domain modules (catalog, commerce, billing, …)
47+
├── models/ # Response model classes
48+
├── rql/ # RQL query builder
49+
└── exceptions.py # Error hierarchy
50+
```
51+
52+
## Shared Standards
53+
54+
This repository follows shared engineering standards from
55+
[mpt-extension-skills](https://github.com/softwareone-platform/mpt-extension-skills):
56+
57+
- `standards/python-style-guide.md`
58+
- `standards/testing-standard.md`
59+
- `standards/contributing-standard.md`
60+
- `standards/pull-request-guidelines.md`
61+
62+
63+

‎README.md‎

Lines changed: 49 additions & 95 deletions
Original file line numberDiff line numberDiff line change
@@ -1,125 +1,79 @@
11
[![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)
22
[![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)
3-
43
[![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)
54

65
# mpt-api-python-client
76

8-
A Python client for interacting with the MPT API.
9-
10-
## Documentation
11-
12-
📚 **[Complete Usage Guide](docs/PROJECT_DESCRIPTION.md)**
13-
14-
## Getting started
15-
16-
### Prerequisites
17-
18-
- Docker and Docker Compose plugin (`docker compose` CLI)
19-
- `make`
20-
- [CodeRabbit CLI](https://www.coderabbit.ai/cli) (optional. Used for running review check locally)
21-
22-
### Make targets overview
23-
24-
Common development workflows are wrapped in the `Makefile`. Run `make help` to see the list of available commands.
25-
26-
### How the Makefile works
7+
Python API client for the SoftwareONE Marketplace Platform (MPT) API.
278

28-
The project uses a modular Makefile structure that organizes commands into logical groups:
29-
- **Main Makefile** (`Makefile`): Entry point that automatically includes all `.mk` files from the `make/` directory
30-
- **Modular includes** (`make/*.mk`): Commands are organized by category:
31-
- `common.mk` - Core development commands (build, test, format, etc.)
32-
- `repo.mk` - Repository management and dependency commands
33-
- `migrations.mk` - Database migration commands (Only available in extension repositories)
34-
- `external_tools.mk` - Integration with external tools
9+
Provides synchronous (`MPTClient`) and asynchronous (`AsyncMPTClient`) clients built on
10+
[httpx](https://www.python-httpx.org/), with typed resource services, mixin-based HTTP
11+
operations, and an RQL query builder.
3512

36-
37-
You can extend the Makefile with your own custom commands creating a `local.mk` file inside make folder. This file is
38-
automatically ignored by git, so your personal commands won't affect other developers or appear in version control.
39-
40-
41-
### Setup
42-
43-
Follow these steps to set up the development environment:
44-
45-
#### 1. Clone the repository
13+
## Quick Start
4614

4715
```bash
48-
git clone <repository-url>
49-
```
50-
```bash
51-
cd mpt-api-python-client
16+
cp .env.sample .env # configure MPT_API_BASE_URL and MPT_API_TOKEN
17+
make build
18+
make test
5219
```
5320

54-
#### 2. Create environment configuration
21+
## Usage
5522

56-
Copy the sample environment file and update it with your values:
23+
**[Installation & Usage Guide](docs/PROJECT_DESCRIPTION.md)**
5724

58-
```bash
59-
cp .env.sample .env
60-
```
61-
62-
Edit the `.env` file with your actual configuration values. See the [Configuration](#configuration) section for details on available variables.
63-
64-
#### 3. Build the Docker images
25+
```python
26+
from mpt_api_client import MPTClient
6527

66-
Build the development environment:
28+
client = MPTClient() # reads MPT_API_TOKEN and MPT_API_BASE_URL from environment
6729

68-
```bash
69-
make build
30+
for product in client.catalog.products.iterate():
31+
print(product.name)
7032
```
7133

72-
This will create the Docker images with all required dependencies and the virtualenv.
34+
### RQL Filtering Example
7335

74-
#### 4. Verify the setup
75-
76-
Run the test suite to ensure everything is configured correctly:
77-
78-
```bash
79-
make test
80-
```
36+
```python
37+
from mpt_api_client import MPTClient, RQLQuery
8138

82-
You're now ready to start developing! See [Running the client](#running-the-client) for next steps.
39+
client = MPTClient()
40+
products = client.catalog.products
8341

42+
target_ids = RQLQuery("id").in_([
43+
"PRD-123-456",
44+
"PRD-789-012",
45+
])
46+
active = RQLQuery(status="active")
47+
vendor = RQLQuery("vendor.name").eq("Microsoft")
8448

85-
## Running the client
49+
query = target_ids & active & vendor
8650

87-
Before running, ensure your `.env` file is populated.
88-
89-
```bash
90-
make run
51+
for product in products.filter(query).order_by("-audit.updated.at").select("id", "name").iterate():
52+
print(product.id, product.name)
9153
```
9254

93-
## Developer utilities
55+
## Documentation
9456

95-
Useful helper targets during development:
57+
| Document | Description |
58+
|----------------------------------------------------------------|-------------------------------------------------------------|
59+
| [Architecture](docs/architecture.md) | Layered architecture, directory structure, key abstractions |
60+
| [RQL Guide](docs/rql.md) | Fluent builder for Resource Query Language filters |
61+
| [Contributing](docs/contributing.md) | Development workflow, coding conventions, linting setup |
62+
| [Testing](docs/testing.md) | Test structure, tooling, conventions |
63+
| [Local Development](docs/local-development.md) | Docker setup, Make targets, environment variables |
64+
| [Usage Guide](docs/PROJECT_DESCRIPTION.md) | Installation, sync and async usage examples |
65+
| [MPT OpenAPI Spec](https://api.s1.show/public/v1/openapi.json) | Upstream API contract (endpoints, schemas) |
66+
67+
## Key Commands
9668

9769
```bash
98-
make bash # open a bash shell in the app container
99-
make check # run ruff, flake8, and lockfile checks
100-
make check-all # run checks and tests
101-
make format # auto-format code and imports
102-
make review # check the code in the cli by running CodeRabbit
70+
make build # build Docker development environment
71+
make test # run unit tests
72+
make check # run all quality checks (ruff, flake8, mypy)
73+
make check-all # run checks + tests
74+
make format # auto-format code
75+
make bash # open a shell in the container
76+
make run # start an IPython session
10377
```
10478

105-
## Configuration
106-
107-
The following environment variables are typically set in `.env`. Docker Compose reads them when using the Make targets described above.
108-
109-
### Application
110-
111-
| Environment Variable | Default | Example | Description |
112-
|---------------------------------|---------|-------------------------------------------|-------------------------------------------------------------------------------------------|
113-
| `MPT_API_BASE_URL` | - | `https://portal.softwareone.com/mpt` | SoftwareONE Marketplace API URL |
114-
| `MPT_API_TOKEN` | - | eyJhbGciOiJSUzI1N... | SoftwareONE Marketplace API Token |
115-
116-
### E2E
117-
118-
| Environment Variable | Default | Example | Description |
119-
|----------------------------|---------|--------------------------------------|----------------------------------------------|
120-
| `MPT_API_TOKEN_CLIENT` | - | eyJhbGciOiJSUzI1N... | SoftwareONE Marketplace API Client Token |
121-
| `MPT_API_TOKEN_OPERATIONS` | - | eyJhbGciOiJSUzI1N... | SoftwareONE Marketplace API Operations Token |
122-
| `MPT_API_TOKEN_VENDOR` | - | eyJhbGciOiJSUzI1N... | SoftwareONE Marketplace API Vendor Token |
123-
| `RP_API_KEY` | - | pytest_XXXXXXXXXXXXXX | ReportPortal API key |
124-
| `RP_ENDPOINT` | - | `https://reportportal.example.com` | ReportPortal endpoint |
125-
| `RP_LAUNCH` | - | `dev-env` | ReportPortal launch |
79+
Run `make help` to see all available commands.

0 commit comments

Comments
 (0)