diff --git a/.github/workflows/quality.yml b/.github/workflows/quality.yml new file mode 100644 index 0000000..2d63e72 --- /dev/null +++ b/.github/workflows/quality.yml @@ -0,0 +1,43 @@ +name: Quality + +on: + push: + branches: [main] + pull_request: + +permissions: + contents: read + +concurrency: + group: quality-${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + quality: + name: Python 3.13 + runs-on: ubuntu-latest + + steps: + - name: Check out repository + uses: actions/checkout@v7 + + - name: Install uv and Python + uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0 + with: + enable-cache: true + python-version: "3.13" + + - name: Install locked dependencies + run: uv sync --locked + + - name: Lint + run: uv run --frozen ruff check . + + - name: Check formatting + run: uv run --frozen ruff format --check . + + - name: Type check + run: uv run --frozen pyright + + - name: Test + run: uv run --frozen pytest diff --git a/README.md b/README.md index d5efdb4..20cc12a 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,44 @@ +
+ # Defined Networking Python Client -`defined-client` provides two ways to work with the -[Defined Networking API](https://docs.defined.net/api/defined-networking-api/): +**One client. Two interfaces. Simple automation for Defined Networking.** + +[![Python 3.13+](https://img.shields.io/badge/Python-3.13%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/) +[![Quality](https://github.com/rrajpuro/defined-python-client/actions/workflows/quality.yml/badge.svg)](https://github.com/rrajpuro/defined-python-client/actions/workflows/quality.yml) +[![CLI: definedcli](https://img.shields.io/badge/CLI-definedcli-4C8BF5)](docs/cli.md) +[![Typed: py.typed](https://img.shields.io/badge/typing-py.typed-6F42C1)](docs/python.md) +[![License: MIT](https://img.shields.io/badge/License-MIT-2EA44F)](LICENSE.md) + +[Quick start](#quick-start) · [Install](#install) · +[CLI guide](docs/cli.md) · [Python guide](docs/python.md) · +[API reference](https://docs.defined.net/api/defined-networking-api/) + +
+ +--- + +`defined-client` is a Python toolkit for the +[Defined Networking API](https://docs.defined.net/api/defined-networking-api/). +It combines a script-friendly CLI with a typed Python package and safer +high-level services. -- `definedcli`, a script-friendly command-line interface -- `defined_client`, a typed Python package with low-level resources and safer - high-level services +| ⚡ Script-friendly CLI | 🐍 Typed Python API | 🛡️ Safer updates | +| :---: | :---: | :---: | +| JSON for automation and tables for humans | Inline types and a `py.typed` marker | GET–merge–PUT helpers preserve omitted fields | -The client covers hosts, roles, routes, tags, networks, audit logs, and public -software downloads. Python 3.13 or newer is required. +Hosts, roles, routes, tags, networks, audit logs, and public software downloads +are supported. Python 3.13 or newer is required. -## Choose an interface +> [!NOTE] +> This is an independent project and is not affiliated with, endorsed by, or +> sponsored by Defined Networking. + +

+ definedcli listing two fictional hosts in table format +

+ +## Quick start Use the CLI for shell automation and interactive administration: @@ -103,6 +131,22 @@ omitted fields. Safe updates use a GET-then-PUT sequence and can still race with another writer. +
+ +Explore the complete CLI command tree + +| Resource | Commands | +| --- | --- | +| `hosts` | `create`, `create-with-enrollment`, `list`, `get`, `get-by-name`, `find-by-name`, `update`, `replace`, `delete`, `block`, `unblock`, `debug-command`, `create-enrollment-code`, `update-tags`, `add-tag`, `remove-tag` | +| `roles` | `create`, `list`, `get`, `update`, `replace`, `delete` | +| `routes` | `create`, `list`, `get`, `get-by-name`, `find-by-name`, `update`, `replace`, `delete`, `update-router-host` | +| `tags` | `create`, `list`, `get`, `find-by-key`, `update`, `replace`, `delete`, `subscribe-route`, `unsubscribe-route` | +| `networks` | `create`, `list`, `get`, `update`, `replace` | +| `audit-logs` | `list` | +| `downloads` | `list` (public) | + +
+ ## Documentation - [CLI guide](docs/cli.md) — commands, JSON input, output, pagination, and errors diff --git a/assets/definedcli-preview.svg b/assets/definedcli-preview.svg new file mode 100644 index 0000000..b4985b7 --- /dev/null +++ b/assets/definedcli-preview.svg @@ -0,0 +1,44 @@ + + definedcli host listing + A terminal preview showing two fictional Defined Networking hosts in table output. + + + + + + + + + + + + definedcli + + + $ + definedcli + --output table + hosts list + + id + isLighthouse + name + roleID + + + + host-2F7K + true + edge-router-01 + role-router + + host-9A3M + false + web-prod-01 + role-web + + + + JSON for scripts. Tables for humans. + + diff --git a/docs/development.md b/docs/development.md index d7406f3..94094de 100644 --- a/docs/development.md +++ b/docs/development.md @@ -40,6 +40,9 @@ Apply Ruff's safe automatic fixes and formatter while developing: .venv/bin/ruff format . ``` +The `Quality` GitHub Actions workflow runs the same lint, formatting, type, and +test checks for every pull request and every push to `main`. + Run one test module while iterating: ```bash