Skip to content

Commit f6ebf60

Browse files
albertsolaalbertsola
committed
MPT-19004 Documentation update
Update documentation and AGENTS.md following practices documented: https://softwareone.atlassian.net/wiki/spaces/~712020b14b6af3a5e341f9b4c936ce4cd948bb/pages/7130022026/Extensions+technical+documentation+Strategy+for+Repositories
1 parent a2b1bbd commit f6ebf60

File tree

7 files changed

+614
-99
lines changed

7 files changed

+614
-99
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: 32 additions & 99 deletions
Original file line numberDiff line numberDiff line change
@@ -5,121 +5,54 @@
55

66
# mpt-api-python-client
77

8-
A Python client for interacting with the MPT API.
8+
Python API client for the SoftwareONE Marketplace Platform (MPT) API.
99

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
27-
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
35-
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
46-
47-
```bash
48-
git clone <repository-url>
49-
```
50-
```bash
51-
cd mpt-api-python-client
52-
```
53-
54-
#### 2. Create environment configuration
10+
Provides synchronous (`MPTClient`) and asynchronous (`AsyncMPTClient`) clients built on
11+
[httpx](https://www.python-httpx.org/), with typed resource services, mixin-based HTTP
12+
operations, and an RQL query builder.
5513

56-
Copy the sample environment file and update it with your values:
57-
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
65-
66-
Build the development environment:
14+
## Quick Start
6715

6816
```bash
17+
cp .env.sample .env # configure MPT_API_BASE_URL and MPT_API_TOKEN
6918
make build
70-
```
71-
72-
This will create the Docker images with all required dependencies and the virtualenv.
73-
74-
#### 4. Verify the setup
75-
76-
Run the test suite to ensure everything is configured correctly:
77-
78-
```bash
7919
make test
8020
```
8121

82-
You're now ready to start developing! See [Running the client](#running-the-client) for next steps.
22+
## Usage
8323

24+
📚 **[Installation & Usage Guide](docs/PROJECT_DESCRIPTION.md)**
8425

85-
## Running the client
26+
```python
27+
from mpt_api_client import MPTClient
8628

87-
Before running, ensure your `.env` file is populated.
29+
client = MPTClient() # reads MPT_API_TOKEN and MPT_API_BASE_URL from environment
8830

89-
```bash
90-
make run
31+
for product in client.catalog.products.iterate():
32+
print(product.name)
9133
```
9234

93-
## Developer utilities
35+
## Documentation
36+
37+
| Document | Description |
38+
|----------------------------------------------------------------|-------------------------------------------------------------|
39+
| [Architecture](docs/architecture.md) | Layered architecture, directory structure, key abstractions |
40+
| [Contributing](docs/contributing.md) | Development workflow, coding conventions, linting setup |
41+
| [Testing](docs/testing.md) | Test structure, tooling, conventions |
42+
| [Local Development](docs/local-development.md) | Docker setup, Make targets, environment variables |
43+
| [Usage Guide](docs/PROJECT_DESCRIPTION.md) | Installation, sync and async usage examples |
44+
| [MPT OpenAPI Spec](https://api.s1.show/public/v1/openapi.json) | Upstream API contract (endpoints, schemas) |
9445

95-
Useful helper targets during development:
46+
## Key Commands
9647

9748
```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
49+
make build # build Docker development environment
50+
make test # run unit tests
51+
make check # run all quality checks (ruff, flake8, mypy)
52+
make check-all # run checks + tests
53+
make format # auto-format code
54+
make bash # open a shell in the container
55+
make run # start an IPython session
10356
```
10457

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 |
58+
Run `make help` to see all available commands.

0 commit comments

Comments
 (0)