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

Open
albertsola wants to merge 1 commit into
base: main
Choose a base branch
from
Open

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

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



131 changes: 32 additions & 99 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,121 +5,54 @@

# mpt-api-python-client

A Python client for interacting with the MPT API.
Python API client for the SoftwareONE Marketplace Platform (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

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


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

```bash
git clone <repository-url>
```
```bash
cd mpt-api-python-client
```

#### 2. Create environment configuration
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.

Copy the sample environment file and update it with your values:

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

Build the development environment:
## Quick Start

```bash
cp .env.sample .env # configure MPT_API_BASE_URL and MPT_API_TOKEN
make build
```

This will create the Docker images with all required dependencies and the virtualenv.

#### 4. Verify the setup

Run the test suite to ensure everything is configured correctly:

```bash
make test
```

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

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

## Running the client
```python
from mpt_api_client import MPTClient

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

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

## Developer utilities
## Documentation

| Document | Description |
|---|---|
| [Architecture](docs/architecture.md) | Layered architecture, directory structure, key abstractions |
| [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) |

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