mreg-api 0.2.3__tar.gz → 0.4.0__tar.gz

mreg_api-0.4.0/.github/workflows/docs.yml

@@ -0,0 +1,29 @@
+name: Documentation
+on:
+  push:
+    branches:
+      - main
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/configure-pages@v6
+      - uses: actions/checkout@v6
+      - name: Install uv
+        uses: astral-sh/setup-uv@v2
+      - name: Set up Python 3.12
+        run: uv python install 3.12
+      - run: uv sync --only-group docs
+      - run: uv run zensical build --clean
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: site
+      - uses: actions/deploy-pages@v5
+        id: deployment

mreg_api-0.4.0/.github/workflows/test.yml

@@ -0,0 +1,52 @@
+on:
+  push:
+  pull_request:
+
+env:
+  UV_FROZEN: 1
+
+name: Tests
+jobs:
+  unit:
+    name: Unit tests
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version:
+          - "3.11"
+          - "3.12"
+          - "3.13"
+          - "3.14"
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v2
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: uv sync
+      - name: Run unit tests
+        run: bash ci/run_tests.sh --unit-only --no-cov
+
+  integration:
+    name: Integration tests
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version:
+          - "3.11"
+          - "3.12"
+          - "3.13"
+          - "3.14"
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v2
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: uv sync
+      - name: Run integration tests
+        run: bash ci/run_tests.sh --integration-only --no-cov

{mreg_api-0.2.3 → mreg_api-0.4.0}/.gitignore

@@ -110,3 +110,8 @@ venv.bak/
 mreg/.idea
 
 *.log
+
+# Claude
+.claude/settings.local.json
+CLAUDE.local.md
+!.claude/CLAUDE.md

{mreg_api-0.2.3 → mreg_api-0.4.0}/.markdownlint.json

@@ -5,5 +5,9 @@
     },
     "line-length": false,
     "no-bare-urls": false,
-    "no-inline-html": false
+    "no-inline-html": false,
+    "MD046": false,
+    "MD056": {
+        "severity": "warning"
+    }
 }

{mreg_api-0.2.3 → mreg_api-0.4.0}/CHANGELOG.md

@@ -7,6 +7,54 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 <!-- ## Unreleased -->
 
+## [0.4.0](https://github.com/unioslo/mreg-api/releases/tag/0.4.0) - 2026-08-24
+
+### Added
+
+- `MregClient.community` property to access the `CommunityManager` for managing communities.
+  - Still exists via `MregClient.network.community`.
+- `EventLog.get(subject=..., kind=..., level=..., min_level=...)` method to support retrieving events and filtering by a combination of subject, kind, and level. This replaces the existing `get_for`, `get_by_kind`, `get_by_level`, and `get_at_or_above` methods, and allows one to combine all their filters in a single call. Currently, only intersections of filters are supported (i.e. events must match all filters to be returned). Future releases may support unions of filters (i.e. events matching any filter will be returned).
+- `MregClient.policy` property that groups the existing `MregClient.atom`, `MregClient.role`, `MregClient.label` into a common namespace as `MregClient.policy.role`, `MregClient.policy.atom`, and `MregClient.policy.label`.
+
+### Changed
+
+- `MregClient.*.create()` semantics and return type changes:
+  - POST requests now prefer to return the created object found in the response, rather than fetching the object again from the API via the location header. The manager falls back on fetching via location header if the response does not contain the created object.
+  - `create()` method return type changed from `T | None` to `T`. Never returns None.
+  - `create(fetch_after_create)` parameter removed.
+- `models.LDAPHealth` now defines `status` as a `Literal["OK", "Down", "Unknown"]` type instead of a generic string.
+- `models.UserInfo` now has defaults for all its fields.
+- `MregClient.community.create()` now returns the created `Community` object instead of a boolean indicating success.
+- Default limit of 500 for `list()` calls has been changed to `None` (unrestricted).
+
+### Removed
+
+- **BREAKING:** `create(fetch_after_create)` parameter. No longer has any meaning as each endpoint returns a valid object representation in the response body after creation.
+
+### Deprecated
+
+- `EventLog.get_all()` -> `EventLog.get()`
+- `EventLog.get_for()` -> `EventLog.get(subject=...)`
+- `EventLog.get_by_kind()` -> `EventLog.get(kind=...)`
+- `EventLog.get_by_level()` -> `EventLog.get(level=...)`
+- `EventLog.get_at_or_above()` -> `EventLog.get(min_level=...)`
+
+## [0.3.0](https://github.com/unioslo/mreg-api/releases/tag/0.3.0) - 2026-08-12
+
+### Added
+
+- `Host.get_community_associations(name: str)` method to retrieve all ipaddress->community associations for the host with the given community name.
+- `Network.get_communities(name: str)` method to retrieve all communities with the given name.
+
+### Changed
+
+- **BREAKING**: `MregClient` is no longer a singleton. Each instance is independent and maintains its own state. The `MregClient.get_instance()` method has been removed. Each instantiation of `MregClient` is now independent and maintains its own state, including history, events and cache.
+- `Network.get_community()` now ignores case when searching for communities by name. It returns the first community with the given name, or None if not found.
+
+### Removed
+
+- **BREAKING**: `MregClient.reset_instance` removed because the singleton pattern has been removed.
+
 ## [0.2.3](https://github.com/unioslo/mreg-api/releases/tag/0.2.3) - 2026-05-21
 
 ### Fixed

{mreg_api-0.2.3 → mreg_api-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mreg-api
-Version: 0.2.3
+Version: 0.4.0
 Summary: MREG API
 Author-email: Terje Kvernes <terjekv@uio.no>
 Maintainer-email: Peder Hovdan Andresen <pederhan@uio.no>
@@ -692,7 +692,7 @@ Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: httpx[socks]>=0.28.1
-Requires-Dist: typing_extensions>=4.12.0
+Requires-Dist: typing-extensions>=4.16.0
 Requires-Dist: pydantic>=2.12
 Requires-Dist: pydantic-extra-types>=2.1.0
 Requires-Dist: diskcache>=5.6.3
@@ -701,7 +701,28 @@ Dynamic: license-file
 
 # MREG API [![Build Status](https://github.com/unioslo/mreg-api/actions/workflows/test.yml/badge.svg)](https://github.com/unioslo/mreg-api/actions/workflows/test.yml)
 
-## Pre-commit Hooks
+`mreg-api` is a Python client library for the [MREG](https://github.com/unioslo/mreg)
+REST API. It gives you a typed, ergonomic interface to every MREG
+resource through a single client
+object with scoped namespaces for each resource type.
+
+It provides optional caching of resources, automatic FQDN expansion of hostnames, and a consistent interface for all resource types. The client is compatible with Python 3.11 and later.
+
+
+## Documentation
+
+https://unioslo.github.io/mreg-api/
+
+## Development
+
+Set up a development environment with `uv`:
+
+```bash
+git clone git@github.com:unioslo/mreg-api.git
+uv sync
+```
+
+### Pre-commit Hooks
 
 This project uses `prek` to manage pre-commit hooks for code quality and formatting. To set up the pre-commit hooks, run the following command:
 

mreg_api-0.4.0/README.md

@@ -0,0 +1,44 @@
+# MREG API [![Build Status](https://github.com/unioslo/mreg-api/actions/workflows/test.yml/badge.svg)](https://github.com/unioslo/mreg-api/actions/workflows/test.yml)
+
+`mreg-api` is a Python client library for the [MREG](https://github.com/unioslo/mreg)
+REST API. It gives you a typed, ergonomic interface to every MREG
+resource through a single client
+object with scoped namespaces for each resource type.
+
+It provides optional caching of resources, automatic FQDN expansion of hostnames, and a consistent interface for all resource types. The client is compatible with Python 3.11 and later.
+
+
+## Documentation
+
+https://unioslo.github.io/mreg-api/
+
+## Development
+
+Set up a development environment with `uv`:
+
+```bash
+git clone git@github.com:unioslo/mreg-api.git
+uv sync
+```
+
+### Pre-commit Hooks
+
+This project uses `prek` to manage pre-commit hooks for code quality and formatting. To set up the pre-commit hooks, run the following command:
+
+```bash
+uv tool install prek
+```
+
+Then, install the pre-commit hooks with:
+
+```bash
+prek install
+```
+
+Run the pre-commit checks manually with:
+
+```bash
+prek run
+# Optionally for all files:
+prek run --all-files
+```

mreg_api-0.4.0/TESTING.md

@@ -0,0 +1,152 @@
+# Testing
+
+mreg-api has two types of tests:
+
+- **Unit tests** — Unit testing of functions and methods used by the package. No interaction with a live mreg server is required.
+- **Integration tests** — Run against a live (containerized) mreg server. Skipped automatically when no server URL is configured.
+
+## Unit tests
+
+Unit tests use `pytest-httpserver` to mock MREG server responses for any tests that require HTTP interactions. No external services required.
+
+Bare `pytest` invocations ignore integration tests (skipped automatically when no server URL is configured):
+
+```bash
+uv run pytest
+```
+
+In case some configuration defines `MREG_URL`, unit tests can still be run exclusively by ignoring the integration tests via markers:
+
+```bash
+uv run pytest -m "not integration"
+```
+
+## Integration tests
+
+Integration tests run against a live mreg server. They are **skipped automatically** when no server URL is configured, so `uv run pytest` never fails due to a missing server.
+
+### Prerequisites
+
+A running mreg instance (and PostgreSQL). The fastest way is the containerized setup:
+
+```bash
+bash ci/run_tests.sh
+
+# If port 8000 is already in use (e.g., a local mreg dev server):
+MREG_PORT=8081 bash ci/run_tests.sh
+```
+
+This starts containers, creates a superuser, then runs both unit and integration tests with combined coverage output in `htmlcov/`.
+
+Flags:
+
+| Flag | Effect |
+|---|---|
+| `--unit-only` | Skip integration tests (no containers started) |
+| `--integration-only` | Skip unit tests |
+| `--no-cov` | Disable coverage. Used in CI |
+| `-h`, `--help` | Show usage |
+| `-- ARGS...` | Pass everything after `--` to pytest |
+
+Unknown flags are an error (exit code 2) — the script never silently ignores them.
+
+Container setup (`ci/run_tests.sh` only, not read by pytest):
+
+| Env var | Default | Description |
+|---|---|---|
+| `MREG_IMAGE` | `ghcr.io/unioslo/mreg:master` | mreg container image |
+| `MREG_IMAGE_PULL_POLICY` | `missing` | Compose pull policy: `missing`, `always`, `never` |
+| `MREG_PORT` | `8000` | Host port the mreg container is exposed on |
+
+`master` is a mutable tag, so a local image can go stale. Use `MREG_IMAGE_PULL_POLICY=always` to pull the current one.
+
+
+
+### Running manually against a local server
+
+```bash
+# Minimal — username/password default to "test"
+MREG_URL=http://127.0.0.1:8000 uv run pytest tests/integration/
+
+# All options explicit
+MREG_URL=http://127.0.0.1:8000 \
+MREG_USERNAME=myuser \
+MREG_PASSWORD=secret \
+MREG_DOMAIN=example.com \
+MREG_CACHE=0 \
+MREG_TEST_NETWORK=10.0.0.0/8 \
+  uv run pytest tests/integration/ -v
+
+# Via CLI flags instead of env vars
+uv run pytest tests/integration/ \
+  --mreg-url http://127.0.0.1:8000 \
+  --mreg-username myuser \
+  --mreg-password secret
+```
+
+### Configuration
+
+| Env var | CLI flag | Default | Description |
+|---|---|---|---|
+| `MREG_URL` | `--mreg-url` | *(none — required to activate integration tests)* | mreg server base URL |
+| `MREG_USERNAME` | `--mreg-username` | `test` | Login username |
+| `MREG_PASSWORD` | `--mreg-password` | `test` | Login password |
+| `MREG_DOMAIN` | `--mreg-domain` | `example.com` | Default domain for the client. Controls the main zone used in integration tests |
+| `MREG_CACHE` | `--mreg-cache` | `false` | Enable mreg client cache (`1`/`true`/`yes` = on) |
+| `MREG_TEST_NETWORK` | `--test-network` | `10.0.0.0/8` | Network CIDR created as shared test network |
+| `MREG_TEST_IP` | `--test-ip` | `10.0.0.1` | IP address used in IP-related tests |
+
+CLI flags take precedence over env vars.
+
+
+### Subset and extra arguments
+
+
+```bash
+# Fast run without coverage
+bash ci/run_tests.sh --no-cov
+
+# Single module
+bash ci/run_tests.sh --integration-only -- tests/integration/test_labels.py
+
+# Stop on first failure, filter by name
+bash ci/run_tests.sh --integration-only -- -x -k labels
+```
+
+Each pass selects its tests by marker (`-m integration` / `-m "not integration"`) rather than by
+path, so a path after `--` narrows the run. When both suites run, the arguments go to both pytest
+invocations.
+
+## Coverage
+
+### Unit tests only
+
+```bash
+uv run pytest tests/ --ignore=tests/integration \
+  --cov=mreg_api --cov-report=term-missing
+```
+
+### Combined unit + integration
+
+Run `ci/run_tests.sh` (uses `--cov-append` to merge both passes), or manually:
+
+```bash
+# Pass 1: unit tests — write .coverage
+uv run pytest tests/ --ignore=tests/integration \
+  --cov=mreg_api --cov-report=
+
+# Pass 2: integration tests — append to .coverage
+MREG_URL=http://127.0.0.1:8000 MREG_USERNAME=test MREG_PASSWORD=test \
+  uv run pytest tests/integration/ \
+  --cov=mreg_api --cov-append --cov-report=html --cov-report=term
+
+# Open report
+open htmlcov/index.html
+```
+
+## Markers
+
+| Marker | Meaning |
+|---|---|
+| `integration` | Requires live mreg server — skipped without `MREG_URL` |
+| `readonly` | Test only reads data, safe against staging/production servers |

mreg_api-0.4.0/ci/Dockerfile

@@ -0,0 +1,15 @@
+FROM ubuntu:latest
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    curl \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN curl -LsSf https://astral.sh/uv/install.sh | sh
+ENV PATH="/root/.local/bin:$PATH"
+
+RUN uv python install 3.12
+
+WORKDIR /build
+COPY . .
+RUN uv sync -q

mreg_api-0.4.0/ci/docker-compose.yml

@@ -0,0 +1,40 @@
+services:
+  postgres:
+    image: postgres
+    environment:
+      POSTGRES_USER: mreg
+      POSTGRES_DB: mreg
+      POSTGRES_PASSWORD: mreg
+    healthcheck:
+      test: ["CMD", "pg_isready", "--username=mreg"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+
+  mreg:
+    image: ${MREG_IMAGE:-ghcr.io/unioslo/mreg:master}
+    pull_policy: ${MREG_IMAGE_PULL_POLICY:-missing}
+    container_name: mreg
+    depends_on:
+      postgres:
+        condition: service_healthy
+    ports:
+      - "${MREG_PORT:-8000}:8000"
+    environment:
+      MREG_DB_HOST: postgres
+      MREG_DB_NAME: mreg
+      MREG_DB_USER: mreg
+      MREG_DB_PASSWORD: mreg
+      MREG_MAP_GLOBAL_COMMUNITY_NAMES: "1"
+      CI: "yes"
+    healthcheck:
+      test: ["CMD", "test", "-f", "/var/run/gunicorn.pid"]
+      interval: 5s
+      timeout: 5s
+      retries: 20
+
+  wait:
+    image: hello-world
+    depends_on:
+      mreg:
+        condition: service_healthy

mreg_api-0.4.0/ci/run_tests.sh

@@ -0,0 +1,121 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(dirname "$SCRIPT_DIR")"
+
+RUN_UNIT=true
+RUN_INTEGRATION=true
+RUN_COVERAGE=true
+MREG_IMAGE="${MREG_IMAGE:-ghcr.io/unioslo/mreg:master}"
+MREG_IMAGE_PULL_POLICY="${MREG_IMAGE_PULL_POLICY:-missing}"
+# Host port the mreg container is exposed on. Override if 8000 is already in use.
+MREG_PORT="${MREG_PORT:-8000}"
+MREG_URL="${MREG_URL:-http://127.0.0.1:${MREG_PORT}}"
+MREG_USERNAME="${MREG_USERNAME:-test}"
+MREG_PASSWORD="${MREG_PASSWORD:-test}"
+MREG_CACHE="${MREG_CACHE:-0}"
+
+usage() {
+    cat <<'EOF'
+Usage: bash ci/run_tests.sh [--unit-only|--integration-only] [--no-cov] [-- pytest args...]
+
+Everything after -- is passed to pytest:
+
+  bash ci/run_tests.sh --integration-only -- tests/integration/test_labels.py
+  bash ci/run_tests.sh --integration-only -- -x -k labels
+EOF
+}
+
+# Extra arguments passed to pytest (everything after --).
+EXTRA_ARGS=()
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --unit-only)        RUN_INTEGRATION=false; shift ;;
+        --integration-only) RUN_UNIT=false; shift ;;
+        --no-cov)           RUN_COVERAGE=false; shift ;;
+        -h|--help)          usage; exit 0 ;;
+        --)                 shift; EXTRA_ARGS=("$@"); break ;;
+        *)
+            echo "ERROR: unknown option: $1" >&2
+            usage >&2
+            exit 2
+            ;;
+    esac
+done
+
+if command -v podman &>/dev/null && ! command -v docker &>/dev/null; then
+    DOCKER=podman
+else
+    DOCKER=docker
+fi
+
+if [[ "$RUN_INTEGRATION" == "true" ]]; then
+    # Check if port is already in use before starting containers
+    if lsof -i ":${MREG_PORT}" 2>/dev/null | grep -q LISTEN; then
+        echo "ERROR: Port ${MREG_PORT} is already in use." >&2
+        echo "Set MREG_PORT to a free port: MREG_PORT=8081 bash ci/run_tests.sh" >&2
+        exit 1
+    fi
+
+    cleanup() {
+        cd "$SCRIPT_DIR"
+        $DOCKER compose down --remove-orphans 2>/dev/null || true
+    }
+    trap cleanup EXIT
+
+    cd "$SCRIPT_DIR"
+
+    echo "Starting mreg and postgres on port ${MREG_PORT}..."
+    MREG_IMAGE="$MREG_IMAGE" MREG_PORT="$MREG_PORT" \
+    MREG_IMAGE_PULL_POLICY="$MREG_IMAGE_PULL_POLICY" \
+        $DOCKER compose up -d
+
+    echo "Creating superuser..."
+    $DOCKER exec mreg uv run /app/manage.py create_mreg_superuser \
+        --username "$MREG_USERNAME" --password "$MREG_PASSWORD" 2>/dev/null \
+        || $DOCKER exec mreg /app/manage.py create_mreg_superuser \
+            --username "$MREG_USERNAME" --password "$MREG_PASSWORD"
+
+
+fi
+
+cd "$REPO_ROOT"
+
+UNIT_EXIT=0
+INTEGRATION_EXIT=0
+
+if [[ "$RUN_UNIT" == "true" ]]; then
+    echo "Running unit tests..."
+    # No path here: pytest falls back to testpaths (tests/) from pyproject.toml,
+    # so a path in EXTRA_ARGS narrows the run instead of being added to it.
+    UNIT_ARGS=(-m "not integration" -v)
+    if [[ "$RUN_COVERAGE" == "true" ]]; then
+        UNIT_ARGS+=(--cov=mreg_api --cov-report=)
+    else
+        UNIT_ARGS+=(--no-cov)
+    fi
+    UNIT_ARGS+=(${EXTRA_ARGS[@]+"${EXTRA_ARGS[@]}"})
+    uv run pytest "${UNIT_ARGS[@]}" || UNIT_EXIT=$?
+fi
+
+if [[ "$RUN_INTEGRATION" == "true" ]]; then
+    echo "Running integration tests..."
+    INTEGRATION_ARGS=(-m integration -v)
+    if [[ "$RUN_COVERAGE" == "true" ]]; then
+        INTEGRATION_ARGS+=(--cov=mreg_api --cov-append --cov-report=html --cov-report=term)
+    else
+        INTEGRATION_ARGS+=(--no-cov)
+    fi
+    INTEGRATION_ARGS+=(${EXTRA_ARGS[@]+"${EXTRA_ARGS[@]}"})
+    MREG_URL="$MREG_URL" \
+    MREG_USERNAME="$MREG_USERNAME" \
+    MREG_PASSWORD="$MREG_PASSWORD" \
+        uv run pytest "${INTEGRATION_ARGS[@]}" || INTEGRATION_EXIT=$?
+fi
+
+if [[ $UNIT_EXIT -ne 0 || $INTEGRATION_EXIT -ne 0 ]]; then
+    exit 1
+fi
+exit 0

mreg_api-0.4.0/docs/guides/authentication.md

@@ -0,0 +1,62 @@
+---
+icon: lucide/key-round
+---
+
+# Authentication
+
+The client does not authenticate on construction and never reads credentials from the
+environment or a token file on its own — authentication is always explicit. There are two
+ways to authenticate.
+
+## Username and password
+
+[`login()`][mreg_api.client.MregClient.login] exchanges credentials for a token, stores
+it on the client, and returns it. Reading credentials from the environment is a common
+pattern:
+
+```python
+import os
+from mreg_api import MregClient
+
+client = MregClient(url="https://mreg.example.com", domain="example.com")
+client.login(
+    username=os.environ["MREG_USERNAME"],
+    password=os.environ["MREG_PASSWORD"],
+)
+```
+
+`login()` raises [`LoginFailedError`][mreg_api.exceptions.LoginFailedError] on a
+connection failure or bad credentials.
+
+## Existing token
+
+!!! note
+
+    Token auth is primarily relevant to persistent sessions for applications such as [mreg-cli](https://github.com/unioslo/mreg-cli), not for scripts or ephemeral sessions.
+
+If you already have a token, set it directly with
+[`set_token()`][mreg_api.client.MregClient.set_token] — no `login()` call needed:
+
+```python
+client = MregClient(url="https://mreg.example.com")
+client.set_token(os.environ["MREG_TOKEN"])
+```
+
+## Managing the token
+
+```python
+client.get_token()    # current token, or None
+client.test_auth()    # raises InvalidAuthTokenError if the token is invalid
+client.unset_token()  # clear the token locally
+client.logout()       # invalidate the token on the server
+```
+
+## Correlation IDs
+
+To make requests easier to trace in server logs, attach a correlation ID that is sent
+with every subsequent request:
+
+```python
+client.set_correlation_id("nightly-sync")
+client.get_correlation_id()
+```