Skip to content

MPT-19004 Documentation update #254

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
albertsola merged 1 commit into from
Mar 31, 2026
Merged

MPT-19004 Documentation update #254

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions .github/copilot-instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
# Copilot Instructions

This repository is `mpt-api-python-client` — a Python API client for the SoftwareONE
Marketplace Platform API.

Read `AGENTS.md` in the repository root for the full documentation index, reading order,
key commands, and project structure.

Quick validation: `make check && make test`
63 changes: 63 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
# 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).

## API Reference

The upstream MPT API is described by the 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 |
|------------------|------------------------------------------|
| `make build` | Build the Docker development environment |
| `make test` | Run unit tests |
| `make check` | Run all linting and type checks |
| `make check-all` | Run checks + tests |
| `make format` | Auto-format code |

## Project Structure

```text
mpt_api_client/
├── mpt_client.py # MPTClient / AsyncMPTClient entry points
├── http/ # HTTP transport, services, mixins
├── resources/ # API domain modules (catalog, commerce, billing, …)
├── models/ # Response model classes
├── 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`



144 changes: 49 additions & 95 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,125 +1,79 @@
[![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

A Python client for interacting with the MPT API.

## Documentation

📚 **[Complete Usage Guide](docs/PROJECT_DESCRIPTION.md)**

## Getting started

### Prerequisites

- Docker and Docker Compose plugin (`docker compose` CLI)
- `make`
- [CodeRabbit CLI](https://www.coderabbit.ai/cli) (optional. Used for running review check locally)

### Make targets overview

Common development workflows are wrapped in the `Makefile`. Run `make help` to see the list of available commands.

### How the Makefile works
Python API client for the SoftwareONE Marketplace Platform (MPT) API.

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


You can extend the Makefile with your own custom commands creating a `local.mk` file inside make folder. This file is
automatically ignored by git, so your personal commands won't affect other developers or appear in version control.


### Setup

Follow these steps to set up the development environment:

#### 1. Clone the repository
## Quick Start

```bash
git clone <repository-url>
```
```bash
cd mpt-api-python-client
cp .env.sample .env # configure MPT_API_BASE_URL and MPT_API_TOKEN
make build
make test
```

#### 2. Create environment configuration
## Usage

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

```bash
cp .env.sample .env
```

Edit the `.env` file with your actual configuration values. See the [Configuration](#configuration) section for details on available variables.

#### 3. Build the Docker images
```python
from mpt_api_client import MPTClient

Build the development environment:
client = MPTClient() # reads MPT_API_TOKEN and MPT_API_BASE_URL from environment

```bash
make build
for product in client.catalog.products.iterate():
print(product.name)
```

This will create the Docker images with all required dependencies and the virtualenv.
### RQL Filtering Example

#### 4. Verify the setup

Run the test suite to ensure everything is configured correctly:

```bash
make test
```
```python
from mpt_api_client import MPTClient, RQLQuery

You're now ready to start developing! See [Running the client](#running-the-client) for next steps.
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")

## Running the client
query = target_ids & active & vendor

Before running, ensure your `.env` file is populated.

```bash
make run
for product in products.filter(query).order_by("-audit.updated.at").select("id", "name").iterate():
print(product.id, product.name)
```

## Developer utilities
## Documentation

Useful helper targets during development:
| 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) |

## Key Commands

```bash
make bash # open a bash shell in the app container
make check # run ruff, flake8, and lockfile checks
make check-all # run checks and tests
make format # auto-format code and imports
make review # check the code in the cli by running CodeRabbit
make build # build Docker development environment
make test # run unit tests
make check # run all quality checks (ruff, flake8, mypy)
make check-all # run checks + tests
make format # auto-format code
make bash # open a shell in the container
make run # start an IPython session
```

## Configuration

The following environment variables are typically set in `.env`. Docker Compose reads them when using the Make targets described above.

### Application

| Environment 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 |

### E2E

| Environment Variable | Default | Example | Description |
|----------------------------|---------|--------------------------------------|----------------------------------------------|
| `MPT_API_TOKEN_CLIENT` | - | eyJhbGciOiJSUzI1N... | SoftwareONE Marketplace API Client Token |
| `MPT_API_TOKEN_OPERATIONS` | - | eyJhbGciOiJSUzI1N... | SoftwareONE Marketplace API Operations Token |
| `MPT_API_TOKEN_VENDOR` | - | eyJhbGciOiJSUzI1N... | SoftwareONE Marketplace API Vendor Token |
| `RP_API_KEY` | - | pytest_XXXXXXXXXXXXXX | ReportPortal API key |
| `RP_ENDPOINT` | - | `https://reportportal.example.com` | ReportPortal endpoint |
| `RP_LAUNCH` | - | `dev-env` | ReportPortal launch |
Run `make help` to see all available commands.
Loading
Loading