mreg-api 0.3.0__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.3.0 → 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.3.0 → mreg_api-0.4.0}/CHANGELOG.md

@@ -7,6 +7,38 @@ 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
@@ -19,7 +51,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **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.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mreg-api
-Version: 0.3.0
+Version: 0.4.0
 Summary: MREG API
 Author-email: Terje Kvernes <terjekv@uio.no>
 Maintainer-email: Peder Hovdan Andresen <pederhan@uio.no>
@@ -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.3.0 → mreg_api-0.4.0}/TESTING.md

@@ -45,11 +45,22 @@ Flags:
 | `--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.
+
 
-```bash
-# Fast run without coverage
-bash ci/run_tests.sh --no-cov
-```
 
 ### Running manually against a local server
 
@@ -88,19 +99,24 @@ uv run pytest tests/integration/ \
 CLI flags take precedence over env vars.
 
 
-### Subset runs
+### Subset and extra arguments
+
 
 ```bash
-# Read-only tests only (safe against staging/production)
-uv run pytest tests/integration/ -m readonly
+# Fast run without coverage
+bash ci/run_tests.sh --no-cov
 
-# Single resource type
-uv run pytest tests/integration/test_labels.py
+# Single module
+bash ci/run_tests.sh --integration-only -- tests/integration/test_labels.py
 
-# Specific test
-uv run pytest tests/integration/test_labels.py::test_delete_by_name
+# 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

{mreg_api-0.3.0 → mreg_api-0.4.0}/ci/docker-compose.yml

@@ -13,6 +13,7 @@ services:
 
   mreg:
     image: ${MREG_IMAGE:-ghcr.io/unioslo/mreg:master}
+    pull_policy: ${MREG_IMAGE_PULL_POLICY:-missing}
     container_name: mreg
     depends_on:
       postgres:

{mreg_api-0.3.0 → mreg_api-0.4.0}/ci/run_tests.sh

@@ -8,6 +8,7 @@ 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}}"
@@ -15,12 +16,32 @@ 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 ;;
-        *) shift ;;
+        -h|--help)          usage; exit 0 ;;
+        --)                 shift; EXTRA_ARGS=("$@"); break ;;
+        *)
+            echo "ERROR: unknown option: $1" >&2
+            usage >&2
+            exit 2
+            ;;
     esac
 done
 
@@ -47,7 +68,9 @@ if [[ "$RUN_INTEGRATION" == "true" ]]; then
     cd "$SCRIPT_DIR"
 
     echo "Starting mreg and postgres on port ${MREG_PORT}..."
-    MREG_IMAGE="$MREG_IMAGE" MREG_PORT="$MREG_PORT" $DOCKER compose up -d
+    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 \
@@ -65,23 +88,27 @@ INTEGRATION_EXIT=0
 
 if [[ "$RUN_UNIT" == "true" ]]; then
     echo "Running unit tests..."
-    UNIT_ARGS=(tests/ --ignore=tests/integration -v)
+    # 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=(tests/integration/ -v)
+    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" \

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()
+```

mreg_api-0.4.0/docs/guides/caching.md

@@ -0,0 +1,63 @@
+---
+icon: lucide/database
+---
+
+# Caching
+
+The client can cache `GET` responses on disk to avoid refetching unchanged data. Caching
+is **off by default**. Any successful `POST`/`PATCH`/`DELETE` clears the cache, so writes
+never leave you reading stale data.
+
+## Enabling at construction
+
+Pass `cache=True` for defaults, or a [`CacheConfig`][mreg_api.cache.CacheConfig] to
+customize:
+
+```python
+from mreg_api import MregClient, CacheConfig
+
+# Defaults
+client = MregClient(url="https://mreg.example.com", cache=True)
+
+# Custom configuration
+client = MregClient(
+    url="https://mreg.example.com",
+    cache=CacheConfig(ttl=600, directory="/var/tmp/mreg-cache"),
+)
+```
+
+## `CacheConfig` options
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `enable` | `bool` | `True` | Whether the cache is active. |
+| `ttl` | `int` | `300` | Time-to-live for cached entries, in seconds. |
+| `tag` | `str` | `"mreg-api"` | Tag used to namespace cache entries. |
+| `timeout` | `int` | `60` | Open timeout for the underlying disk cache. |
+| `directory` | `str | None` | `None` | Cache directory. `None` uses a system temp directory. |
+
+## Controlling the cache at runtime
+
+```python
+client.enable_cache()                       # turn caching on
+client.enable_cache(CacheConfig(ttl=60))    # reconfigure and turn on
+client.disable_cache()                      # turn off (clears by default)
+client.disable_cache(clear=False)           # turn off, keep cached data
+client.clear_cache()                        # drop all cached entries
+```
+
+Use the [`caching()`][mreg_api.client.MregClient.caching] context manager to toggle
+caching for a block:
+
+```python
+with client.caching(enable=True):
+    client.host.list()  # served from / stored in the cache
+```
+
+## Inspecting the cache
+
+```python
+info = client.get_cache_info()  # CacheInfo, or None if caching is disabled
+if info:
+    print(info.items, info.hits, info.misses, info.size)
+```

mreg_api-0.4.0/docs/guides/configuration.md

@@ -0,0 +1,64 @@
+---
+icon: lucide/settings
+---
+
+# Client configuration
+
+Everything starts with an [`MregClient`][mreg_api.client.MregClient]. Constructing one
+sets up the HTTP session but does **not** authenticate or make any network requests — see
+[Authentication](authentication.md) for that.
+
+```python
+from mreg_api import MregClient
+
+client = MregClient(
+    url="https://mreg.example.com",
+    domain="example.com",
+)
+```
+
+## Constructor options
+
+| Argument | Type | Default | Description |
+|---|---|---|---|
+| `url` | `str` | *required* | Base URL of the MREG server. All request paths are joined onto it. |
+| `domain` | `str | None` | `None` | Default DNS domain used to expand bare hostnames into FQDNs. See [Domain handling](#domain-handling). |
+| `user` | `str | None` | `None` | Informational username stored on the client. Does **not** authenticate. |
+| `timeout` | `int | float | None` | `60` | Request timeout in seconds, passed to the underlying HTTP client. |
+| `cache` | `CacheConfig | bool` | `False` | Enable GET-response caching. `True` uses defaults; pass a [`CacheConfig`][mreg_api.cache.CacheConfig] to customize. See [Caching](caching.md). |
+| `follow_redirects` | `bool` | `False` | Whether the HTTP client follows redirects. |
+| `page_size` | `int | None` | `None` | Default pagination page size sent as a query parameter on GET requests. |
+| `history_size` | `int | None` | `100` | Maximum number of request/response records kept in `client.history`. |
+| `event_log_size` | `int | None` | `100` | Maximum number of entries kept in the [event log](../reference/events.md). |
+| `user_agent` | `str | None` | `None` | Custom `User-Agent` header. Defaults to `mreg-api-<version>`. |
+
+## Domain handling
+
+When `domain` is set, bare hostnames are expanded to FQDNs automatically by resource
+methods. You can also expand a name explicitly or override the domain temporarily:
+
+```python
+client.fqdn("web")  # -> "web.example.com"
+
+with client.domain_override("other.example.com"):
+    client.fqdn("web")  # -> "web.other.example.com"
+```
+
+## Timeout
+
+`timeout` is also available as a settable property after construction:
+
+```python
+client.timeout = 120
+```
+
+## Request history
+
+Every request/response pair is recorded in a bounded deque, sized by `history_size`:
+
+```python
+for record in client.get_client_history():
+    print(record.method, record.status, record.url)
+
+client.clear_client_history()
+```

mreg_api-0.4.0/docs/guides/eventlog.md

@@ -0,0 +1,52 @@
+---
+icon: lucide/chart-no-axes-gantt
+---
+
+# Event Log
+
+The client records an event log of resolutions, mutations, and notices that happen in-between requests for complex queries and multi-step operations. Typically, such events are things like CNAME and PTR resolution that happen when resolving Host or host records.
+
+!!! note
+
+    The event log system is a new feature and is still under development. The API may change in future releases. As of 0.3.0, it only records CNAME and PTR resolution events, but future releases will include more event types.
+
+## Accessing the event log
+
+The event log is accessible via the `client.events` property, which returns an [`EventLog`][mreg_api.events.EventLog] instance. The size of the log is controlled by the `event_log_size` argument to [`MregClient`][mreg_api.client.MregClient].
+
+```python
+client = MregClient(...)
+events = client.events.get()
+```
+
+## Filtering by event kind
+
+Each event is categorized by kind ([`EventKind`][mreg_api.events.EventKind]). You can filter the event log by kind using the `get` method with the `kind` argument:
+
+```python
+from mreg_api.events import EventKind
+
+client.events.get(kind=EventKind.RESOLUTION)
+client.events.get(kind=EventKind.MUTATION)
+client.events.get(kind=EventKind.NOTICE)
+```
+
+## Filtering by event level
+
+Each event is also categorized by level ([`EventLevel`][mreg_api.events.EventLevel]). You can filter the event log by level using the `get` method with the `level` argument:
+
+```python
+from mreg_api.events import EventLevel
+
+client.events.get(level=EventLevel.DEBUG)
+client.events.get(level=EventLevel.INFO)
+client.events.get(level=EventLevel.WARNING)
+client.events.get(level=EventLevel.ERROR)
+client.events.get(level=EventLevel.CRITICAL)
+```
+
+The `min_level` argument can be used to retrieve events at or above a certain severity level instead of exactly matching a level:
+
+```python
+client.events.get(min_level=EventLevel.WARNING)
+```

mreg_api-0.4.0/docs/guides/requesthistory.md

@@ -0,0 +1,15 @@
+---
+icon: lucide/timeline
+---
+
+# Request/Response History
+
+The client records a request/response history of each interaction with the server. The history is a bounded deque, sized by the `history_size` argument to [`MregClient`][mreg_api.client.MregClient]. You can access the history via the `client.history` property, which returns a list of [`RequestRecord`][mreg_api.client.RequestRecord] instances, which contain the request and response objects for each interaction, as well as shortcuts for the request method, URL, data and json payloads, as well as response status code.
+
+```python
+client = MregClient(...)
+for record in client.get_client_history():
+    print(record.request.method, record.request.url, record.status)
+    assert record.status == record.response.status_code
+    print("Request payload:", record.data or record.json)
+```