Improve introspection data manipulation

[mulkieran]

Related stratis-storage/stratis-docs#390

[mulkieran]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 74ee4e0e-c692-424e-92ca-cdaaa55aa7aa

📥 Commits

Reviewing files that changed from the base of the PR and between 7800088 and 714242f.

📒 Files selected for processing (1)

• misc_scripts/update_introspection_data.py

🚧 Files skipped from review as they are similar to previous changes (1)

• misc_scripts/update_introspection_data.py

---

Walkthrough

The script centralizes D-Bus interface naming and revision handling via new helpers and a shared _add_data introspection routine. _make_python_spec and _make_docs_spec are refactored to be revision-aware and use the shared logic. Docs output now writes one XML file per fully-qualified interface name. The CLI exposes --revision-number as a top-level option and removes per-doc filename flags.

Changes

Introspection Revision Refactoring

Layer / File(s)	Summary
Type Imports Update misc_scripts/update_introspection_data.py	Removes Optional from typing imports and adds MutableMapping and union-style typing support.
Revision Helpers and Python Spec misc_scripts/update_introspection_data.py	Adds helper functions to compute the revision extension (r<minor>) and construct fully-qualified interface names; introduces shared _add_data introspection routine; refactors _make_python_spec to accept `revision_number: int
Docs Spec and Per-Interface Output misc_scripts/update_introspection_data.py	Refactors _make_docs_spec to accept revision_number and use shared introspection; updates _print_docs_spec to create the output directory and write one XML file per interface_name named <interface_name>.xml; _docs_output now passes revision_number through.
CLI Parser Updates misc_scripts/update_introspection_data.py	Promotes --revision-number to a top-level option (applies to python and docs) and removes per-doc filename CLI flags from the docs subcommand, leaving only output_dir.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title 'Improve introspection data manipulation' is vague and generic, using non-descriptive language that doesn't clearly convey what specific change was made to the introspection data handling.	Consider a more specific title that captures the main change, such as 'Centralize D-Bus interface naming and revision handling in introspection script' or 'Refactor introspection spec generation with helper functions and revision support'.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

• Generate code and open pull requests
• Plan features and break down work
• Investigate incidents and troubleshoot customer tickets together
• Automate recurring tasks and respond to alerts with triggers
• Summarize progress and report instantly

Built for teams:

• Shared memory across your entire org—no repeating context
• Per-thread sandboxes to safely plan and execute work
• Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

misc_scripts/update_introspection_data.py (1)

220-315: 💤 Low value

Optional: lift the four shared _add_data calls into a helper.

_make_python_spec and _make_docs_spec now share the same (proxy, prefix-list) pairings for manager/pool/blockdev/filesystem — only the leading OBJECT_MANAGER_INTERFACE introspect differs. A small table-driven helper would keep them from drifting if a new interface family is added later.

♻️ Sketch

_PROXY_INTERFACE_PREFIXES: list[tuple[ProxyType, Sequence[str]]] = [
    (ProxyType.MANAGER, TOP_OBJECT_INTERFACE_PREFIXES),
    (ProxyType.POOL, POOL_OBJECT_INTERFACE_PREFIXES),
    (ProxyType.BLOCKDEV, BLOCKDEV_OBJECT_INTERFACE_PREFIXES),
    (ProxyType.FILESYSTEM, FILESYSTEM_OBJECT_INTERFACE_PREFIXES),
]

def _add_revisioned_interfaces(
    specs: MutableMapping[str, str],
    proxies: Mapping[ProxyType, ProxyObject],
    revision_ext: str,
) -> None:
    for proxy_type, prefixes in _PROXY_INTERFACE_PREFIXES:
        _add_data(specs, proxies[proxy_type], _get_current_interfaces(revision_ext, prefixes))

Then both _make_python_spec and _make_docs_spec collapse to a single call (plus the manager-only OBJECT_MANAGER_INTERFACE introspect in the python case).

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@misc_scripts/update_introspection_data.py` around lines 220 - 315, Introduce
a small table-driven helper (e.g. a constant _PROXY_INTERFACE_PREFIXES:
list[tuple[ProxyType, Sequence[str]]] and a function
_add_revisioned_interfaces(specs, proxies, revision_ext)) that iterates the four
pairs (ProxyType.MANAGER/ TOP_OBJECT_INTERFACE_PREFIXES, ProxyType.POOL/
POOL_OBJECT_INTERFACE_PREFIXES, ProxyType.BLOCKDEV/
BLOCKDEV_OBJECT_INTERFACE_PREFIXES, ProxyType.FILESYSTEM/
FILESYSTEM_OBJECT_INTERFACE_PREFIXES) and calls _add_data for each; then replace
the four repeated _add_data(...) calls in _make_python_spec and _make_docs_spec
with a single call to _add_revisioned_interfaces(specs, proxies, revision_ext),
keeping the extra _add_data(specs, proxies[ProxyType.MANAGER],
OBJECT_MANAGER_INTERFACE) only in _make_python_spec.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@misc_scripts/update_introspection_data.py`:
- Around line 285-287: Update the stale type annotations and docstring to
reflect that docs specs are keyed by interface name strings, not ProxyType:
change the return type of _make_docs_spec from dict[ProxyType, str] to dict[str,
str] (and its parameter/usage if necessary), update the parameter type of
_print_docs_spec from Mapping[ProxyType, str] to Mapping[str, str], and edit the
docstring that currently says "dict of ProxyType * XML object" to indicate "dict
of interface name (str) -> XML string" so annotations and docs match the code
paths that set specs[interface_name].

---

Nitpick comments:
In `@misc_scripts/update_introspection_data.py`:
- Around line 220-315: Introduce a small table-driven helper (e.g. a constant
_PROXY_INTERFACE_PREFIXES: list[tuple[ProxyType, Sequence[str]]] and a function
_add_revisioned_interfaces(specs, proxies, revision_ext)) that iterates the four
pairs (ProxyType.MANAGER/ TOP_OBJECT_INTERFACE_PREFIXES, ProxyType.POOL/
POOL_OBJECT_INTERFACE_PREFIXES, ProxyType.BLOCKDEV/
BLOCKDEV_OBJECT_INTERFACE_PREFIXES, ProxyType.FILESYSTEM/
FILESYSTEM_OBJECT_INTERFACE_PREFIXES) and calls _add_data for each; then replace
the four repeated _add_data(...) calls in _make_python_spec and _make_docs_spec
with a single call to _add_revisioned_interfaces(specs, proxies, revision_ext),
keeping the extra _add_data(specs, proxies[ProxyType.MANAGER],
OBJECT_MANAGER_INTERFACE) only in _make_python_spec.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: d276fad8-1fca-4b66-ad1a-4331fa301ce5

📥 Commits

Reviewing files that changed from the base of the PR and between 2af03a5 and 7800088.

📒 Files selected for processing (1)

• misc_scripts/update_introspection_data.py

[mulkieran]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.