systemd-search 1.1.0__py3-none-any.whl

systemd_search/__init__.py

@@ -0,0 +1,275 @@
+"""systemd-search — Query systemd units by custom section labels.
+
+Relies on `systemctl cat` for effective unit config (handles .d/ drop-ins).
+"""
+
+import argparse
+import configparser
+import json
+import subprocess
+import sys
+
+
+def run(cmd):
+    return subprocess.run(cmd, capture_output=True, text=True)
+
+
+def list_unit_files(types):
+    """Return [(unit_name, enabled_state)] for the given unit types."""
+    args = ["systemctl", "list-unit-files", "--no-legend", "--no-pager"]
+    if types:
+        args.append("--type=" + ",".join(types))
+    result = run(args)
+    units = []
+    for line in result.stdout.splitlines():
+        parts = line.split()
+        if len(parts) >= 2:
+            units.append((parts[0], parts[1]))
+    return units
+
+
+def parse_cat_output(output):
+    """Parse systemctl cat output into {section: {key: value}}.
+
+    Uses configparser so the full INI grammar is handled correctly.
+    strict=False lets duplicate sections (base file + drop-ins) merge and
+    duplicate keys resolve to the last definition, matching systemd semantics.
+    delimiters=('=',) avoids treating ':' as a separator (systemd never does).
+    optionxform=str preserves key casing.
+    """
+    parser = configparser.RawConfigParser(
+        strict=False,
+        delimiters=("=",),
+    )
+    parser.optionxform = str  # preserve key case (e.g. ExecStart, not execstart)
+    parser.read_string(output)
+    return {section: dict(parser.items(section)) for section in parser.sections()}
+
+
+def get_unit_config(unit):
+    result = run(["systemctl", "cat", "--", unit])
+    if result.returncode != 0:
+        return {}
+    return parse_cat_output(result.stdout)
+
+
+def is_active(unit):
+    result = run(["systemctl", "is-active", "--", unit])
+    return result.stdout.strip() == "active"
+
+
+def build_parser():
+    p = argparse.ArgumentParser(
+        prog="systemd-search",
+        description="Query systemd units by custom section labels",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+examples:
+  systemd-search --label Project
+  systemd-search --verbose --label Project
+  systemd-search --label Project=myapp
+  systemd-search --label Project=myapp --type service --type timer
+  systemd-search --label Project=myapp --type service --enabled
+  systemd-search --label Project=myapp --type service --enabled --active
+  systemd-search --label Project=myapp --type service --disabled --dead
+  systemd-search --label Project=myapp --exclude Domain
+  systemd-search --label Project=myapp --exclude Env=staging --type service --enabled
+""",
+    )
+    p.add_argument(
+        "--section",
+        default="X-Labels",
+        metavar="SECTION",
+        help="Unit file section to inspect (default: X-Labels)",
+    )
+    p.add_argument(
+        "--label",
+        action="append",
+        default=[],
+        metavar="KEY[=VALUE]",
+        help="Filter by label key, or key=value. Repeatable (all must match).",
+    )
+    p.add_argument(
+        "--exclude",
+        action="append",
+        default=[],
+        metavar="KEY[=VALUE]",
+        help=(
+            "Exclude units where KEY exists, or where KEY=VALUE matches. "
+            "Repeatable. Units that lack the section entirely are always excluded."
+        ),
+    )
+    p.add_argument(
+        "--type",
+        action="append",
+        default=[],
+        dest="unit_types",
+        metavar="TYPE",
+        help="Unit type to include (default: service). Repeatable.",
+    )
+
+    state = p.add_argument_group("state filters")
+    enabled_grp = state.add_mutually_exclusive_group()
+    enabled_grp.add_argument(
+        "--enabled", action="store_true", default=False, help="Only enabled units"
+    )
+    enabled_grp.add_argument(
+        "--disabled", action="store_true", default=False, help="Only disabled units"
+    )
+
+    active_grp = state.add_mutually_exclusive_group()
+    active_grp.add_argument(
+        "--active", action="store_true", default=False, help="Only active (running) units"
+    )
+    active_grp.add_argument(
+        "--dead", action="store_true", default=False, help="Only inactive/dead units"
+    )
+
+    output_grp = p.add_mutually_exclusive_group()
+    output_grp.add_argument(
+        "--verbose",
+        "-v",
+        action="store_true",
+        default=False,
+        help="Print matched label key=value pairs alongside unit name",
+    )
+    output_grp.add_argument(
+        "--json",
+        action="store_true",
+        default=False,
+        help="Emit results as a JSON array with name, enabled, is-active, and labels",
+    )
+    return p
+
+
+def parse_label_filters(raw_labels):
+    """Return [(key, value_or_None)] from raw --label arguments."""
+    filters = []
+    for item in raw_labels:
+        if "=" in item:
+            k, _, v = item.partition("=")
+            filters.append((k.strip(), v.strip()))
+        else:
+            filters.append((item.strip(), None))
+    return filters
+
+
+def section_matches(section_data, label_filters):
+    """Return True if section_data satisfies all label_filters."""
+    for key, value in label_filters:
+        if key not in section_data:
+            return False
+        if value is not None and section_data[key] != value:
+            return False
+    return True
+
+
+def section_excluded(section_data, exclude_filters):
+    """Return True if section_data triggers any exclude_filter.
+
+    --exclude KEY   → exclude when KEY is present in the section.
+    --exclude KEY=VALUE → exclude when KEY is present and equals VALUE.
+    """
+    for key, value in exclude_filters:
+        if value is None:
+            if key in section_data:
+                return True
+        else:
+            if section_data.get(key) == value:
+                return True
+    return False
+
+
+def format_json_entry(unit_name, enabled_state, active, section_data):
+    """Build one JSON result object."""
+    return {
+        "name": unit_name,
+        "enabled": enabled_state in ENABLED_STATES,
+        "is-active": active,
+        "labels": dict(section_data),
+    }
+
+
+def format_verbose(unit_name, section_data, label_filters):
+    """Build the output line when --verbose is set."""
+    if label_filters:
+        keys_to_show = [k for k, _ in label_filters]
+    else:
+        keys_to_show = list(section_data.keys())
+
+    pairs = " ".join(
+        f"{k}={section_data[k]}" for k in keys_to_show if k in section_data
+    )
+    return f"{unit_name}\t{pairs}" if pairs else unit_name
+
+
+# States that count as "enabled" per systemctl semantics
+ENABLED_STATES = {"enabled", "enabled-runtime", "static", "alias", "generated", "transient"}
+DISABLED_STATES = {"disabled", "masked", "masked-runtime", "indirect"}
+
+
+def main():
+    parser = build_parser()
+    args = parser.parse_args()
+
+    unit_types = args.unit_types if args.unit_types else ["service"]
+    label_filters = parse_label_filters(args.label)
+    exclude_filters = parse_label_filters(args.exclude)
+
+    units = list_unit_files(unit_types)
+    json_results = []
+    found = False
+
+    for unit_name, enabled_state in units:
+        # --- enabled/disabled filter ---
+        if args.enabled and enabled_state not in ENABLED_STATES:
+            continue
+        if args.disabled and enabled_state not in DISABLED_STATES:
+            continue
+
+        # --- section gate (always enforced) ---
+        # Units without the section are outside the scope of this tool entirely.
+        config = get_unit_config(unit_name)
+        if args.section not in config:
+            continue
+        section_data = config[args.section]
+
+        # --- label / exclude filters ---
+        if label_filters and not section_matches(section_data, label_filters):
+            continue
+
+        if exclude_filters and section_excluded(section_data, exclude_filters):
+            continue
+
+        # --- active/dead filter + active state resolution ---
+        # JSON always needs the active state; other modes only fetch it when filtering.
+        if args.json or args.active or args.dead:
+            active = is_active(unit_name)
+            if args.active and not active:
+                continue
+            if args.dead and active:
+                continue
+        else:
+            active = None
+
+        found = True
+
+        # --- output ---
+        if args.json:
+            json_results.append(
+                format_json_entry(unit_name, enabled_state, active, section_data)
+            )
+        elif args.verbose:
+            print(format_verbose(unit_name, section_data, label_filters))
+        else:
+            print(unit_name)
+
+    if args.json:
+        print(json.dumps(json_results, indent=2))
+
+    if not found:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

systemd_search-1.1.0.dist-info/METADATA

@@ -0,0 +1,550 @@
+Metadata-Version: 2.4
+Name: systemd-search
+Version: 1.1.0
+Summary: Query systemd units by custom section labels
+License: Apache-2.0
+Project-URL: Repository, https://github.com/leventyalcin/systemd-search
+Keywords: systemd,systemctl,units,labels,search
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Topic :: System :: Systems Administration
+Classifier: Environment :: Console
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# systemd-search
+
+A CLI tool for finding systemd units by custom labels embedded directly in the unit files.
+
+## The problem
+
+Tracking which units belong to which project or domain on a busy system has no good native solution. The usual approach — browsing `/etc/systemd/system/`, grepping file contents, running `systemctl cat` on anything suspicious — is slow and error-prone. There is no built-in way to tag a unit and query by that tag.
+
+`systemd-search` fills that gap. Labels are embedded in a dedicated section inside the unit file itself. The tool reads those labels and filters units by them, covering type, enabled state, and active state in a single command.
+
+## How it works — the `X-` section trick
+
+The `systemd.unit(5)` man page explicitly states:
+
+> *Sections whose name is prefixed with `X-` are ignored by systemd.*
+> *Such sections can be used by applications to store additional information in the unit files.*
+
+— [systemd.unit(5)](https://www.freedesktop.org/software/systemd/man/latest/systemd.unit.html#%5BUnit%5D%20Section%20Options)
+
+An `[X-Labels]` section (or any `[X-*]` section) can be added to any unit file and systemd will load and run the unit exactly as if that section were not there. `systemd-search` reads those sections and uses them as a lightweight tagging system on top of systemd.
+
+The tool resolves the final merged configuration through `systemctl cat` before reading any labels, so drop-in override files (`.d/*.conf`) are always taken into account — the search never operates on stale or partial file content.
+
+## Example unit file
+
+```ini
+# /etc/systemd/system/myapp-worker.service
+[Unit]
+Description=My Application Worker
+After=network.target
+
+[Service]
+User=myapp
+ExecStart=/opt/myapp/bin/worker
+Restart=on-failure
+
+[X-Labels]
+Project=myapp
+Domain=backend
+Component=worker
+Environment=production
+ManagedBy=ansible
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Any section name starting with `X-` is valid. The default section `systemd-search` reads is `X-Labels`. A different section can be specified with `--section`.
+
+## Installation
+
+### pip
+
+The simplest installation on any system with Python 3.9+:
+
+```bash
+pip install systemd-search
+```
+
+For a user-local install without root:
+
+```bash
+pip install --user systemd-search
+```
+
+### From GitHub Releases
+
+Each release ships a self-contained zipapp executable, native packages, and checksums:
+
+```bash
+# Self-contained zipapp — runs on any host with Python 3.9+, no pip needed
+curl -LO https://github.com/leventyalcin/systemd-search/releases/latest/download/systemd-search-1.0.0
+chmod +x systemd-search-1.0.0
+sudo mv systemd-search-1.0.0 /usr/local/bin/systemd-search
+
+# RPM (Rocky Linux 9)
+sudo rpm -i systemd-search-1.0.0-rocky9.noarch.rpm
+
+# DEB (Debian 12)
+sudo dpkg -i systemd-search-1.0.0-debian12.all.deb
+
+# Verify checksum before installing
+sha256sum -c systemd-search-1.0.0-rocky9.noarch.rpm.sha256
+```
+
+### Manual
+
+Copy the script to any directory on the system `PATH`:
+
+```bash
+sudo cp systemd-search /usr/local/bin/systemd-search
+```
+
+**Requirements:** Python 3.9+ with no third-party packages. On Rocky Linux 9 this is the system default Python and requires no additional installation.
+
+## Usage
+
+```text
+systemd-search [--section SECTION] [--label KEY[=VALUE]] [--type TYPE]
+               [--enabled | --disabled] [--active | --dead] [--verbose]
+```
+
+| Flag                  | Default    | Description                                                                 |
+|-----------------------|------------|-----------------------------------------------------------------------------|
+| `--label KEY`         | —          | Matches units that have this key in the section                             |
+| `--label KEY=VALUE`   | —          | Matches units where the key equals the value                                |
+| `--exclude KEY`       | —          | Skips units that have this key in the section. Repeatable.                  |
+| `--exclude KEY=VALUE` | —          | Skips units where the key equals the value. Repeatable.                     |
+| `--section NAME`      | `X-Labels` | Section to read labels from                                                 |
+| `--type TYPE`         | `service`  | Unit type to include (`service`, `timer`, `path`, `socket`, …). Repeatable. |
+| `--enabled`           | —          | Limits results to enabled units                                             |
+| `--disabled`          | —          | Limits results to disabled units                                            |
+| `--active`            | —          | Limits results to active (running) units                                    |
+| `--dead`              | —          | Limits results to inactive or failed units                                  |
+| `--verbose` / `-v`    | —          | Prints matched label key=value pairs alongside each unit name               |
+
+`--enabled` and `--disabled` are mutually exclusive. So are `--active` and `--dead`. Omitting either pair includes all units regardless of that state.
+
+When `--exclude` is active, units that lack the section entirely are silently dropped — the filter only operates on units that carry the section in their configuration.
+
+## Examples
+
+### Find all services that belong to a project
+
+```bash
+systemd-search --label Project=myapp
+```
+
+```text
+myapp-worker.service
+myapp-scheduler.service
+myapp-cleanup.service
+```
+
+### Print the label values alongside each unit name
+
+```bash
+systemd-search --verbose --label Project=myapp
+```
+
+```text
+myapp-worker.service       Project=myapp
+myapp-scheduler.service    Project=myapp
+myapp-cleanup.service      Project=myapp
+```
+
+### Search across multiple unit types
+
+```bash
+systemd-search --label Project=myapp --type service --type timer --type path
+```
+
+```text
+myapp-worker.service
+myapp-cleanup.service
+myapp-refresh.timer
+myapp-trigger.path
+```
+
+### Narrow by a specific label and type
+
+```bash
+systemd-search --label Component=worker --type service
+```
+
+### Find only the running services for a project
+
+```bash
+systemd-search --label Project=myapp --type service --enabled --active
+```
+
+### Find services that are enabled but not running
+
+Useful for spotting crashed or failed units:
+
+```bash
+systemd-search --label Project=myapp --type service --enabled --dead
+```
+
+### Find services that are installed but not enabled
+
+```bash
+systemd-search --label Project=myapp --disabled
+```
+
+### Use a custom section name
+
+Labels do not have to live in `[X-Labels]`. Any `[X-*]` section works:
+
+```ini
+[X-Meta]
+Project=myapp
+Team=platform
+```
+
+```bash
+systemd-search --section X-Meta --label Team=platform
+```
+
+### Match on multiple labels simultaneously
+
+All supplied `--label` filters must match for a unit to appear in the results:
+
+```bash
+systemd-search --label Project=myapp --label Environment=production --type service
+```
+
+### Exclude units that have a specific key
+
+`--exclude KEY` skips any unit in the section that carries that key, regardless of its value:
+
+```bash
+systemd-search --label Project=myapp --exclude Domain
+```
+
+Only units labelled with `Project=myapp` that have no `Domain` key are returned.
+
+### Exclude units where a key matches a specific value
+
+`--exclude KEY=VALUE` skips units only when the key exists and holds that exact value. Units where the key is absent or holds a different value still appear:
+
+```bash
+systemd-search --label Project=myapp --exclude Env=staging
+```
+
+Returns all `myapp` services except those explicitly labelled `Env=staging`.
+
+### Combine positive and negative filters
+
+`--label` and `--exclude` compose freely. All `--label` conditions must hold and no `--exclude` condition must trigger for a unit to appear:
+
+```bash
+systemd-search \
+  --label Project=myapp \
+  --label Domain=backend \
+  --exclude Component=worker \
+  --exclude Env=staging \
+  --type service \
+  --enabled
+```
+
+Reads as: *services for the myapp backend, enabled, excluding workers and staging instances.*
+
+### Verbose output with multiple label filters
+
+```bash
+systemd-search --verbose --label Project=myapp --label Domain=backend
+```
+
+```text
+myapp-worker.service    Project=myapp Domain=backend
+```
+
+## Monitoring integration
+
+`systemd-search --json` produces machine-readable output that can be piped directly into monitoring agents. Any combination of filters can precede it — label filters, state filters, unit types — and the result carries enough context for downstream tools to slice and count however the use case demands.
+
+A few possibilities:
+
+```bash
+# All dead services for a project, as JSON
+systemd-search --json --label Project=myapp --dead
+
+# Count of enabled-but-dead units across all labelled services
+systemd-search --json | jq '[.[] | select(.enabled and (.["is-active"] | not))] | length'
+
+# Feed into a monitoring agent as a metric
+systemd-search --json --label Project=myapp | jq '.[] | select(.["is-active"] | not) | .name'
+```
+
+The examples below show one way to wire this into three common monitoring agents. They are starting points, not prescriptions.
+
+---
+
+### Telegraf
+
+The `exec` input plugin runs an arbitrary command on a schedule and parses its output as metrics. A small wrapper script calls `systemd-search --json` once per project and uses `jq` to derive all counters from the single result, avoiding repeated invocations. The output is [InfluxDB line protocol](https://docs.influxdata.com/influxdb/v2/reference/syntax/line-protocol/).
+
+**`/usr/local/bin/systemd-search-metrics.sh`**
+
+```bash
+#!/bin/bash
+# Emits one influx line per project with unit state counts.
+# Add or remove projects to match the labels used on this host.
+
+set -euo pipefail
+
+PROJECTS=(myapp payments auth)
+
+for project in "${PROJECTS[@]}"; do
+  units=$(systemd-search --json \
+    --label Project="$project" \
+    --type service --type timer --type path)
+
+  dead=$(    echo "$units" | jq '[.[] | select(.enabled     and (.["is-active"] | not))] | length')
+  active=$(  echo "$units" | jq '[.[] | select(.enabled     and  .["is-active"]       )] | length')
+  disabled=$(echo "$units" | jq '[.[] | select(.enabled | not)                         ] | length')
+
+  echo "systemd_units,project=${project} dead=${dead}i,active=${active}i,disabled=${disabled}i"
+done
+```
+
+**`/etc/telegraf/telegraf.d/systemd-search.conf`**
+
+```toml
+[[inputs.exec]]
+  ## Script must be executable: chmod +x /usr/local/bin/systemd-search-metrics.sh
+  commands = ["/usr/local/bin/systemd-search-metrics.sh"]
+  timeout = "15s"
+  interval = "60s"
+  data_format = "influx"
+```
+
+The resulting measurement `systemd_units` carries a `project` tag and `dead`/`active`/`disabled` fields. An alert fires when `dead > 0` for any project.
+
+---
+
+### Datadog
+
+The Datadog Agent supports [custom Python checks](https://docs.datadoghq.com/developers/custom_checks/write_agent_check/) that emit arbitrary metrics. The check below calls `systemd-search --json` once per configured project and derives all counters from the single JSON result.
+
+**`/etc/datadog-agent/checks.d/systemd_labels.py`**
+
+```python
+import json
+import subprocess
+from datadog_checks.base import AgentCheck
+
+
+class SystemdLabelsCheck(AgentCheck):
+    __NAMESPACE__ = "systemd"
+
+    def check(self, instance):
+        project   = instance["project"]
+        section   = instance.get("section", "X-Labels")
+        label_key = instance.get("label_key", "Project")
+        types     = instance.get("types", ["service"])
+
+        type_args = []
+        for t in types:
+            type_args += ["--type", t]
+
+        cmd = [
+            "systemd-search", "--json",
+            "--section", section,
+            "--label", f"{label_key}={project}",
+        ] + type_args
+
+        result = subprocess.run(cmd, capture_output=True, text=True)
+        units = json.loads(result.stdout) if result.returncode == 0 else []
+
+        dead     = sum(1 for u in units if     u["enabled"] and not u["is-active"])
+        active   = sum(1 for u in units if     u["enabled"] and     u["is-active"])
+        disabled = sum(1 for u in units if not u["enabled"])
+
+        tags = [f"project:{project}"]
+        self.gauge("units.dead",     dead,     tags=tags)
+        self.gauge("units.active",   active,   tags=tags)
+        self.gauge("units.disabled", disabled, tags=tags)
+```
+
+**`/etc/datadog-agent/conf.d/systemd_labels.d/conf.yaml`**
+
+```yaml
+instances:
+  - project: myapp
+    types: [service, timer, path]
+
+  - project: payments
+    types: [service]
+
+  - project: auth
+    section: X-Meta        # override if a different section name is used
+    label_key: Application
+    types: [service, timer]
+```
+
+The check emits `systemd.units.dead`, `systemd.units.active`, and `systemd.units.disabled` with a `project` tag. A monitor on `systemd.units.dead > 0` grouped by `project` covers all labelled projects in a single alert rule.
+
+---
+
+### Dynatrace
+
+Dynatrace ingests custom metrics through its [Metrics Ingest v2 API](https://docs.dynatrace.com/docs/dynatrace-api/environment-api/metric-v2/metric-ingest). A script pushed by a systemd timer calls `systemd-search --json` once per project and uses `jq` to compute all counters before pushing a single batch payload.
+
+**`/usr/local/bin/systemd-search-dynatrace.sh`**
+
+```bash
+#!/bin/bash
+# Push unit state metrics for labelled projects to Dynatrace Metrics Ingest v2.
+
+set -euo pipefail
+
+DT_URL="${DYNATRACE_URL}"          # e.g. https://abc12345.live.dynatrace.com
+DT_TOKEN="${DYNATRACE_API_TOKEN}"  # Ingest Metrics (metrics.ingest) scope required
+PROJECTS=(myapp payments auth)
+
+payload=""
+
+for project in "${PROJECTS[@]}"; do
+  units=$(systemd-search --json \
+    --label Project="$project" \
+    --type service --type timer --type path)
+
+  dead=$(    echo "$units" | jq '[.[] | select(.enabled     and (.["is-active"] | not))] | length')
+  active=$(  echo "$units" | jq '[.[] | select(.enabled     and  .["is-active"]       )] | length')
+  disabled=$(echo "$units" | jq '[.[] | select(.enabled | not)                         ] | length')
+
+  # Dynatrace line protocol: metric.key,dimensions gauge,value
+  payload+="systemd.units.dead,project=${project} gauge,${dead}"$'\n'
+  payload+="systemd.units.active,project=${project} gauge,${active}"$'\n'
+  payload+="systemd.units.disabled,project=${project} gauge,${disabled}"$'\n'
+done
+
+curl -sf -X POST "${DT_URL}/api/v2/metrics/ingest" \
+  -H "Authorization: Api-Token ${DT_TOKEN}" \
+  -H "Content-Type: text/plain; charset=utf-8" \
+  --data-raw "${payload}"
+```
+
+**`/etc/systemd/system/systemd-search-dynatrace.service`**
+
+```ini
+[Unit]
+Description=Push systemd label metrics to Dynatrace
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=oneshot
+EnvironmentFile=/etc/systemd-search/dynatrace.env
+ExecStart=/usr/local/bin/systemd-search-dynatrace.sh
+```
+
+**`/etc/systemd/system/systemd-search-dynatrace.timer`**
+
+```ini
+[Unit]
+Description=Run Dynatrace metric push every 60 seconds
+
+[Timer]
+OnBootSec=30s
+OnUnitActiveSec=60s
+AccuracySec=5s
+
+[Install]
+WantedBy=timers.target
+```
+
+**`/etc/systemd-search/dynatrace.env`**
+
+```bash
+DYNATRACE_URL=https://abc12345.live.dynatrace.com
+DYNATRACE_API_TOKEN=dt0c01.XXXXXXXXXXXX...
+```
+
+Enable the timer:
+
+```bash
+systemctl enable --now systemd-search-dynatrace.timer
+```
+
+The metric `systemd.units.dead` is then available in Dynatrace with a `project` dimension. An anomaly detection rule or a fixed threshold alert on that metric covers all labelled projects without any per-service configuration in Dynatrace itself.
+
+---
+
+## Development
+
+All development dependencies are managed with [Pipenv](https://pipenv.pypa.io). The `Pipfile` pins Python 3.9 to match the system Python on Rocky Linux 9 — the primary deployment target.
+
+### First-time setup
+
+Install Pipenv if not already present:
+
+```bash
+pip install --user pipenv
+```
+
+Then create the virtual environment and install all dev dependencies:
+
+```bash
+pipenv install --dev
+```
+
+This creates a Python 3.9 virtual environment under `.venv/` (or the Pipenv default location) and installs pytest, Molecule, Ansible, and the Docker driver.
+
+### Entering the environment
+
+```bash
+pipenv shell
+```
+
+All subsequent commands in this section assume the environment is active. Alternatively, prefix any single command with `pipenv run`:
+
+```bash
+pipenv run pytest tests/ -v
+```
+
+### Unit tests
+
+```bash
+pytest tests/ -v
+```
+
+The unit tests target **Python 3.9** — the system Python on Rocky Linux 9. That version ships as the default on Rocky Linux 9 and will not change for the lifetime of the distribution. Running tests against 3.9 ensures the tool works on that platform without any additional Python installation and catches accidental use of language or stdlib features introduced in later versions.
+
+### Integration tests
+
+Molecule tests install the tool inside real systemd containers and exercise every search combination against live units. Docker must be running.
+
+```bash
+molecule test -s rocky   # tests Rocky Linux 9 and 10 in parallel
+molecule test -s debian  # tests Debian 12 and 13 in parallel
+```
+
+The scenarios use the `geerlingguy/docker-*-ansible` images, which are systemd-capable images built for this kind of testing.
+
+### Updating dependencies
+
+```bash
+# Add or upgrade a dev dependency
+pipenv install --dev some-package
+```
+
+### CI/CD
+
+Pull requests must pass unit tests and both molecule scenarios before merging. Pushing a semver tag triggers the packaging and release jobs, which build RPM and DEB packages, publish the wheel to PyPI, and create a GitHub Release. The tag is the version — there is no separate version file.
+
+```bash
+git tag 1.2.0
+git push origin 1.2.0
+```

systemd_search-1.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+systemd_search/__init__.py,sha256=zYts7usaEEr5URAly7B6xO1CZlajOLrBW61oGSk0Byo,8669
+systemd_search-1.1.0.dist-info/licenses/LICENSE,sha256=SItcyiWGgtkaNWqFjRplx4-DHIJpG0CkC3hhST0U4gQ,10284
+systemd_search-1.1.0.dist-info/METADATA,sha256=XtdGySID9RUvx--kzASJCFzVvJe0ujtcOL3nhxGMh5A,18285
+systemd_search-1.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+systemd_search-1.1.0.dist-info/entry_points.txt,sha256=6Nwyh2llLgkxANHGmzZD4_Bh9MEmsCaBhBAFFlInnjY,55
+systemd_search-1.1.0.dist-info/scm_file_list.json,sha256=nEgmRnxad1o4o8PA_h36ATGAjYWA7l4pEiyRhHPHlWg,973
+systemd_search-1.1.0.dist-info/scm_version.json,sha256=pm8QrB-GPU67W-3le1ff9XoV62k4gcY8B6jwgUxQHBg,160
+systemd_search-1.1.0.dist-info/top_level.txt,sha256=xi-TLvNd02JOhaN4XChkpRwXHsqD3pV6QexfU-dDcS0,15
+systemd_search-1.1.0.dist-info/RECORD,,

systemd_search-1.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

systemd_search-1.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+systemd-search = systemd_search:main

systemd_search-1.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,184 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" shall mean an individual or Legal Entity exercising
+      permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship made available under
+      the License, as indicated by a copyright notice that is included in
+      or attached to the work (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean, as submitted to the Licensor for inclusion
+      in the Work by the copyright owner or by an individual or Legal Entity
+      authorized to submit on behalf of the copyright owner. For the purposes
+      of this definition, "submitted" means any form of electronic, verbal,
+      or written communication sent to the Licensor or its representatives,
+      including but not limited to communication on electronic mailing lists,
+      source code control systems, and issue tracking systems that are managed
+      by, or on behalf of, the Licensor for the purpose of discussing and
+      improving the Work, but excluding communication that is conspicuously
+      marked or designated in writing by the copyright owner as
+      "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any Legal Entity on behalf of
+      whom a Contribution has been received by the Licensor and incorporated
+      within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by the combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a cross-claim
+      or counterclaim in a lawsuit) alleging that the Work or any Contributor
+      Contribution constitutes patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate as of
+      the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, You must include a readable copy of the
+          attribution notices contained within such NOTICE file, in
+          at least one of the following places: within a NOTICE text
+          file distributed as part of the Derivative Works; within
+          the Source form or documentation, if provided along with the
+          Derivative Works; or, within a display generated by the
+          Derivative Works, if and wherever such third-party notices
+          normally appear. The contents of the NOTICE file are for
+          informational purposes only and do not modify the License.
+          You may add Your own attribution notices within Derivative
+          Works that You distribute, alongside or as an addendum to
+          the NOTICE text from the Work, provided that such additional
+          attribution notices cannot be construed as modifying the License.
+
+      You may add Your own license statement for Your modifications and
+      may provide additional grant of rights to use, copy, modify, merge,
+      publish, distribute, sublicense, and/or sell copies of the Work,
+      and to permit persons to whom the Work is furnished to do so, subject
+      to the following conditions, provided that such modifications are
+      clearly labeled as such.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any conditions of TITLE,
+      MERCHANTABLITY, or FITNESS FOR A PARTICULAR PURPOSE. You are
+      solely responsible for determining the appropriateness of using or
+      redistributing the Work and assume any risks associated with Your
+      exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or exemplary damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or all other
+      commercial damages or losses), even if such Contributor has been
+      advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 systemd-search contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

systemd_search-1.1.0.dist-info/scm_file_list.json

@@ -0,0 +1,33 @@
+{
+  "files": [
+    "README.md",
+    "LICENSE",
+    "systemd-search",
+    "ARCHITECTURE.md",
+    "pyproject.toml",
+    "Pipfile.lock",
+    "Pipfile",
+    ".gitignore",
+    "scripts/build-standalone.sh",
+    "scripts/build-rpm.sh",
+    "scripts/build-deb.sh",
+    "scripts/release-notes.md",
+    "src/systemd_search/__init__.py",
+    "molecule/rocky/molecule.yml",
+    "molecule/debian/molecule.yml",
+    "molecule/common/verify.yml",
+    "molecule/common/prepare.yml",
+    "molecule/common/converge.yml",
+    "molecule/common/files/fixture-single.service",
+    "molecule/common/files/fixture-multi.timer",
+    "molecule/common/files/fixture-multi-a.service",
+    "molecule/common/files/fixture-multi.path",
+    "molecule/common/files/fixture-disabled.service",
+    "molecule/common/files/fixture-failing.service",
+    "tests/test_unit.py",
+    "tests/conftest.py",
+    ".github/workflows/release.yml",
+    ".github/workflows/tests.yml",
+    ".github/workflows/pr.yml"
+  ]
+}

systemd_search-1.1.0.dist-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "1.1.0",
+  "distance": 0,
+  "node": "g1a40283a850c0dfe2ac3f553d1cf3ca6289d2ca8",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-06-29"
+}

systemd_search-1.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+systemd_search