feat(facts, operations): add OpenWrt packages, move opkg underneath openwrt and add packages and update operations

[morrison12]

Add OpenWrt facts and operations packages, move the existing opkg items there and add packages and update operations that select apk vs. opkg based on the running OpenWrt release.

The rationale for the OpenWrt package is that there are three OpenWrt -specific items (opkg, procd, uci) needed which don't need to be at the top-level. opkg exists today (even if it is being supplanted by apk), procd support will arrive soon and there are a couple of people working on uci support.

The expectation is that the top-level opkg will be removed after a suitable interval; the interval can probably be reasonably be short as the OpenWrt change from opkg to ask in their Release 25.12 means most users will switch to the release/package-management independent openwrt.packages once it is available.

Specifically changes here are:

1. add OpenWrt facts and operations packages:

• add the directories themselves
• adopt and then modify the deferred import mechanism used for operations/freebsd to allow for the equivalent of import .sub-package.something as something which is useful to avoiding unnecessarily levels in the namespace.
• modify the operations/freebsd implementation to be consistent with the openwrt implementations
• change test_facts.py to allow for packages (vs. files) by making the same change as was made for test_operations.py

2. move the existing opkg facts and operations to openwrt

• move the implementation files to the relevant directory
• rename the test folders

3. replace the now-moved opkg facts and operations with deprecated "forwarders"

• provides backwards compatibility
• add support for deprecated facts (both long and short) using same approach as taken for operations
• add limit of one warning per pyinfra run per deprecated fact as some facts are called a large number of times
• add a warning to the top of the module-level doc string about the deprecation of the top-level opkg for both facts and operations
• copy the relevant tests from openwrt.opkg

5. create an OpenWrtHasFeature fact, a general version of check needed for 6

• currently decides based on OpenWrt release but does not need to be restricted to that
• a few lines of code can be removed when test_facts.py and pyinfra_cli support enum parameters

6. add release and package-manager independent packages and update operations for OpenWrt

• useOpenWrtHasFeature to decide whether to use apk or opkg
• no corresponding Packages fact: is it is only consulted prior to doing something which is already covered for the packages and update cases

7. add facts and operations entries in pyinfra-metadata.toml for (1)
8. fixed documentation generation to work for facts and operations in packages and not just files

• meta,api: lazy load fact and operation modules #1609 broke docs: generate fact/operation docs for modules (vs files) #1606 (for operations/freebsd)
• consolidated (and parametrized) code that generates lists of facts and operations
• depends on the exact deferred import mechanism implemented at (1) and will need to be reworked when when that is replaced by lazy import mechanism in python 3.15

9. changed sorting order of operations in scripts/generation_operations_docs.py to match sorting order used for imports; this affects not just the order on the page but also the order in the sidebar

A couple of questions related to the deprecation at (3) above:
a) there is a warning in the documentation for the deprecations but is there a specific admonition for deprecation that should have been used ?
b) does the future release need to be specified now (the documentation currently doesn't specify one)

One note: at (5), i.e. the OpenWrtHasFeature fact, there is a core mechanism (ReleaseRange.contains) for which it wasn't clear where to put the (non-fixture) tests. I opted for tests/test_facts_other.py but am happy to relocate them if there is a preferred location for such tests.

• Pull request is based on the default branch (3.x at this time)
• Pull request includes tests for any new/updated operations/facts
• Pull request includes documentation for any new/updated operations/facts
• Tests pass (see scripts/dev-test.sh)
• Type checking & code style passes (see scripts/dev-lint.sh)
• Pull request title follows the
  conventional commits format

[wowi42]

Verdict: NO-GO

Well-structured PR with good deprecation handling and broad test coverage. Three issues need fixing before merge.

Issues

1. Fixture bug: has_dsa_is_false_for_19_07.json tests the wrong feature

tests/facts/openwrt.features.OpenWrtHasFeature/has_dsa_is_false_for_19_07.json has "arg": ["has_dsa"] and "command": "echo has_dsa && ...", but the first line of output is "uses_apk" instead of "has_dsa". The test passes accidentally because both features return false for release 19.07, but the fixture is not testing what its name and args claim. First output line must match the echoed feature name: "has_dsa".

2. Missing fixture: openwrt.update (i.e. openwrt.packages.update) has no tests

The update function in src/pyinfra/operations/openwrt/packages.py is a @operation that calls host.get_fact(OpenWrtHasFeature, ...). There is no tests/operations/openwrt.packages.update/ directory. Create at least two fixtures covering the apk and opkg branches.

3. Drive-by refactor of freebsd/__init__.py — out of scope

src/pyinfra/operations/freebsd/__init__.py replaces the glob-based module auto-discovery with an explicit __ALL__ dict and a getattr that splits on dots for sub-module attribute access. This is unrelated to OpenWrt. The glob approach was more maintainable (drop a new .py under freebsd/ and it's auto-discovered); the explicit dict requires manual registration. If this change is intentional, split it into its own PR with a rationale.

Notes

• Copy-paste comment errors in __getattr__ docstrings: src/pyinfra/operations/freebsd/__init__.py line 17, src/pyinfra/operations/openwrt/__init__.py line 19, and src/pyinfra/facts/openwrt/__init__.py line 19 all say "On-demand import of OpenWrt facts" but should reference the correct package (FreeBSD operations, OpenWrt operations, OpenWrt facts respectively).
• openwrt.packages has packages: str | list[str] = "" default. Per AGENTS.md new operations should use None. The "" default passes through to apk.packages._inner() which treats "" as a package name rather than nooping. Minor since the operation is always called with explicit package lists, but worth aligning with None convention.

[morrison12]

Verdict: NO-GO

Well-structured PR with good deprecation handling and broad test coverage. Three issues need fixing before merge.

Issues

1. Fixture bug: has_dsa_is_false_for_19_07.json tests the wrong feature

tests/facts/openwrt.features.OpenWrtHasFeature/has_dsa_is_false_for_19_07.json has "arg": ["has_dsa"] and "command": "echo has_dsa && ...", but the first line of output is "uses_apk" instead of "has_dsa". The test passes accidentally because both features return false for release 19.07, but the fixture is not testing what its name and args claim. First output line must match the echoed feature name: "has_dsa".

Fixed.

2. Missing fixture: openwrt.update (i.e. openwrt.packages.update) has no tests

The update function in src/pyinfra/operations/openwrt/packages.py is a @operation that calls host.get_fact(OpenWrtHasFeature, ...). There is no tests/operations/openwrt.packages.update/ directory. Create at least two fixtures covering the apk and opkg branches.

Indeed needed. Added.

3. Drive-by refactor of freebsd/__init__.py — out of scope

src/pyinfra/operations/freebsd/__init__.py replaces the glob-based module auto-discovery with an explicit __ALL__ dict and a getattr that splits on dots for sub-module attribute access. This is unrelated to OpenWrt. The glob approach was more maintainable (drop a new .py under freebsd/ and it's auto-discovered); the explicit dict requires manual registration. If this change is intentional, split it into its own PR with a rationale.

Removed.
I had changed freebsd/__init__.py in hopes of avoiding future duplicate package (e.g. the current freebsd.sysrc.sysrc); it does take some effort but IMHO that was a nudge to think about the API.
Will put a separate PR for that on my list.

Notes

• Copy-paste comment errors in __getattr__ docstrings: src/pyinfra/operations/freebsd/__init__.py line 17, src/pyinfra/operations/openwrt/__init__.py line 19, and src/pyinfra/facts/openwrt/__init__.py line 19 all say "On-demand import of OpenWrt facts" but should reference the correct package (FreeBSD operations, OpenWrt operations, OpenWrt facts respectively).

Fixed.

• openwrt.packages has packages: str | list[str] = "" default. Per AGENTS.md new operations should use None. The "" default passes through to apk.packages._inner() which treats "" as a package name rather than nooping. Minor since the operation is always called with explicit package lists, but worth aligning with None convention.

Fixed both openwrt.packages and opkg.packages (no backwards compatibility issue).
Not sure how many humans read AGENTS.md; we should look at adding some of what is desired (such changes, new fixtures in YAML, etc to CONTRIBUTING.md and/or the documents.

Also I converted the fixtures to YAML while I was here and added typing to openwrt.opkg (which predated typed pyinfra).