Skip to content

Setup Development Environment

Prerequisites

Clone

git clone https://github.com/oqtopus-team/oqtopus-client.git
cd oqtopus-client

Install dependencies

uv sync --all-extras

Source module structure

Under src/oqtopus_client, modules are separated into low-level and high-level interfaces.

  • Low-level interface: rest
  • Code under src/oqtopus_client/rest/ is generated by OpenAPI Generator.
  • The OQTOPUS Cloud OpenAPI Specification is designed as a RESTful API, so the module name is rest.
  • High-level interface: services
  • Code under src/oqtopus_client/services/ combines low-level APIs to provide service-level functionality.
  • For that reason, the module name is services.

Generate API models from OpenAPI

Source of truth

  • spec/openapi.yaml is the source-of-truth for generated API client models.
  • Do not manually edit generated files under src/oqtopus_client/rest/.

Update flow

make download-oas
make generate-models

If needed, you can override the source URL and output destination.

make -C spec download-oas OAS_URL=https://raw.githubusercontent.com/oqtopus-team/oqtopus-cloud/main/backend/oas/user/openapi.yaml
make -C spec generate-models OAS_FILE=openapi.yaml MODEL_OUTPUT_DIR=../src/oqtopus_client/rest

Notes:

  • make generate-models uses Docker (openapitools/openapi-generator-cli) internally.
  • Keep generated diffs minimal and aligned with intended OAS changes.

Validate changes

Run the following checks from the repository root.

Lint

make lint
  • Runs uv run ruff check.
  • Rule configuration is managed in pyproject.toml under [tool.ruff].

Type check

make typecheck
  • Runs uv run mypy.
  • Target paths and excludes are managed in pyproject.toml under [tool.mypy].

Test

make test
  • Runs uv run pytest.
  • Test options are managed in pyproject.toml under [tool.pytest.ini_options].

Combined check

make check
  • Executes lint, typecheck, and test in order.

Documentation checks

make docs
make docs-serve
  • make docs builds docs with strict checks.
  • make docs-serve runs local preview server.