Skip to content

feat: package orderers as configurable plugins with config-arg-passing - #2165

Open
maxnbk wants to merge 12 commits into
AcademySoftwareFoundation:mainfrom
maxnbk:feat/package-orderers-as-configurable-plugins
Open

maxnbk wants to merge 12 commits into
AcademySoftwareFoundation:mainfrom
maxnbk:feat/package-orderers-as-configurable-plugins

Conversation

@maxnbk

@maxnbk maxnbk commented Jul 21, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Rebases and fixes #1787 by @cfxegbert
Moves the 5 built-in package-orderers from src/rez/package_order.py to src/rezplugins/package_order/ as proper rez plugins.
Adds runtime configuration support via REZ_PACKAGE_ORDERERS_JSON and cache invalidation, creating a platform for PRs #1706 + #1709 to land in a usable manner with minimal changes.

What changed (on top of the PR #1787 rebase+fixing)

  1. Moves PackageOrderers into plugins.
  2. Registers PackageOrderPluginType in plugin_managers.py
  3. Replaces refactor: move package_order to rezplugin system #1787 's function-based backward-compat shims with PEP-562 __getattr__ lazy aliases, so isinstance, from_pod, type(x) is checks all work against the imported class names, while avoiding a circular import that module-level aliases would cause (plugin files import from package_order.py, which would call _find_orderer -> plugin system at load time)
  4. Keeps register_orderer() and the _orderers dict as a means to subclass/apply orderers programmatically.
  5. ruff-compatible reformatting of touched files ends up affecting many lines of code generically. It may be easiest to review commit by commit for this reason.

Runtime configuration of Package Orderers

  1. Documents that REZ_PACKAGE_ORDERERS_JSON works end-to-end using the existing _JSON env-var configuration pathway that then feeds into config.package_orderers -> PackageOrderList.singleton -> from_pod()
  2. Adds PackageOrderList.clear_singleton_cache() classmethod to invalidate the cached singleton, so runtime config changes can take effect without restarting, or API-based-usage of the feature can be correctly managed.

Documentation

  1. Adds REZ_PACKAGE_ORDERERS_JSON usage section to docs/source/package_orderers.rst
  2. Updates custom orderers section to recommend the plugin approach over register_orderer()

Design Notes

  1. The original plan was SortedOrder = _find_orderer('sorted') at module level, but this causes a circular import (package_order.py -> _find_orderer() -> plugin system -> rezplugins/package_order/sorted.py -> from rez.package_order import PackageOrder -> still importing). The __getattr__ approach defers resolution to the first attribute access, breaking the cycle.
  2. The locked config used by the test framework blocks env-var reads, so the runtime config tests simulate the REZ_PACKAGE_ORDERERS_JSON path by parsing JSON and using config.override() which is what the _JSON path does internally.
  3. Needed a lazy class resolution to survive test_plugin_manager's plugin manager reset

Testing

  1. 46 orderer tests + 2 completion tests
  2. Pre-flight tests were added before the refactor to catch potential regressions: from_pod round-trip, isinstance against imported classes, get_orderer default fallback
  3. New tests: plugin loading of all five built-in orderers, to_pod / from_pod round-trip through the plugin system, legacy register_orderer fallback, runtime config via config.override (simulating the _JSON path), cache invalidation, and a test-only kwarg-orderer that validates the pattern used in Add a package orderer that matches Python's version specifier spec (PEP440) #1706 / Added CustomPackageOrder #1709 (constructor kwargs configured at runtime).

Credit

Original refactor by @cfxegbert . Rebased on to current main, conflicts resolved, backward-compat shims fixed, and runtime configuration support added by me.

Follow-on work (not here)

  1. Possibly perform an API-breaking change from usage of PackageOrder class names (and other namings/imports/etc) to PackageOrderer for making-more-sense?
  2. PRs Add a package orderer that matches Python's version specifier spec (PEP440) #1706 and Added CustomPackageOrder #1709 could land as-is or could be migrated into rezplugins to join the rest.

Disclosure: This PR was assisted by GLM-5.2 for docstrings, documentation, and test generation.

@maxnbk
maxnbk requested a review from a team as a code owner July 21, 2026 20:58
@maxnbk
maxnbk force-pushed the feat/package-orderers-as-configurable-plugins branch 2 times, most recently from 1951153 to 39a2d37 Compare July 22, 2026 04:09
@codecov

codecov Bot commented Jul 22, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 91.69550% with 24 lines in your changes missing coverage. Please review.
✅ Project coverage is 62.82%. Comparing base (c463aab) to head (748797f).

Files with missing lines Patch % Lines
src/rez/plugin_managers.py 58.06% 12 Missing and 1 partial ⚠️
src/rezplugins/package_order/soft_timestamp.py 95.65% 1 Missing and 2 partials ⚠️
src/rezplugins/package_order/no_order.py 90.90% 1 Missing and 1 partial ⚠️
src/rezplugins/package_order/per_family.py 97.10% 1 Missing and 1 partial ⚠️
src/rezplugins/package_order/sorted.py 92.85% 1 Missing and 1 partial ⚠️
src/rezplugins/package_order/version_split.py 92.30% 1 Missing and 1 partial ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main    #2165      +/-   ##
==========================================
+ Coverage   62.64%   62.82%   +0.17%     
==========================================
  Files         165      171       +6     
  Lines       20792    20867      +75     
  Branches     3621     3627       +6     
==========================================
+ Hits        13026    13109      +83     
+ Misses       6886     6877       -9     
- Partials      880      881       +1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@JeanChristopheMorinPerso JeanChristopheMorinPerso left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think I'm generally good with this but would like to see some changes before we merge this. I think it's going in the right direction. Note that this review was a manual review from me with no LLM assistance.

Comment thread src/rez/package_order.py Resolved
Comment thread src/rez/tests/test_completion.py Resolved
Comment thread src/rez/package_order.py Resolved
Comment thread src/rez/package_order.py Outdated
Use this when runtime configuration (e.g. REZ_PACKAGE_ORDERERS_JSON)
has changed and you want the new config to take effect. Note that
the config-level cache must also be cleared via
``config._uncache("package_orderers")``.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

config._uncache("package_orderers")

This makes me feel uneasy as it's a private method. Also, why is this method needed? Are we doing something similar in other places and this just keeps things consistent? API users have access to rez.config.config.copy/override/remove_override to change the condig at runtime...

@maxnbk maxnbk Nov 15, 2026 •

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Addressed, but, in addressing it, I note/noticed that PackageFilterList has an identical cached-singleton-over-a-config-setting pattern, but doesn't have any invalidation story, so once .singleton gets touched, config.override("package_filter", ...) is invisible for the process lifetime. We might want to follow-up / re-validate config-backed singleton invalidations for a cohesive approach.

Leaving this conversation marked un-resolved so that it serves as a stub for a potential investigation/issue-creation before resolving fully, even though the code-level comment is addressed.

Comment thread src/rez/package_order.py Resolved
Comment thread src/rez/package_order.py Resolved
Comment thread src/rez/package_order.py Resolved
Comment thread src/rez/plugin_managers.py Resolved
Comment thread src/rez/package_order.py Resolved
Comment thread docs/source/package_orderers.rst Resolved
@JeanChristopheMorinPerso

Copy link
Copy Markdown
Member

Oh, I'm also wondering if we should deprecate config.package_orderers in favor of configuring them through the plugins?

maxnbk and others added 9 commits November 14, 2026 23:03
Add tests for:
- from_pod module-level function round-trip (the code path the plugin
  refactor will change)
- isinstance checks against imported class names (will catch function-shim
  breakage)
- get_orderer default fallback to SortedOrder(descending=True)

Signed-off-by: Stephen Mackenzie <maxnbk@users.noreply.github.com>
…ySoftwareFoundation#1787)

Move the five built-in package orderers (NullPackageOrder, SortedOrder,
PerFamilyOrder, VersionSplitPackageOrder, TimestampPackageOrder) from
src/rez/package_order.py into src/rezplugins/package_order/ as proper
rez plugins.

Register PackageOrderPluginType in plugin_managers.py.

Replace PR AcademySoftwareFoundation#1787's function shims with lazy module-level __getattr__
aliases (PEP 562) so isinstance, from_pod, and type(x) is checks all
work, while avoiding circular imports at module load time.

Keep _orderers dict and register_orderer() as legacy fallback, marked
with deprecation comments.

Original work by Robert Minsk (PR AcademySoftwareFoundation#1787). Rebased, conflicts resolved,
and fixed by Stephen Mackenzie.

Signed-off-by: Robert Minsk <robertminsk@yahoo.com>
Signed-off-by: Stephen Mackenzie <maxnbk@users.noreply.github.com>
Add tests for:
- Plugin system loads all five built-in orderers
- to_pod/from_pod round-trip through the plugin system
- Legacy register_orderer fallback
- REZ_PACKAGE_ORDERERS_JSON end-to-end configuration (simulated via
  config.override since the test framework uses a locked config)
- Cache invalidation for config changes
- Test-only kwarg-orderer validates the AcademySoftwareFoundation#1706/AcademySoftwareFoundation#1709 pattern

Signed-off-by: Stephen Mackenzie <maxnbk@users.noreply.github.com>
Add documentation for:
- REZ_PACKAGE_ORDERERS_JSON environment variable configuration
- Plugin-based custom orderer approach (preferred over register_orderer)
- Cache invalidation for runtime config changes

Signed-off-by: Stephen Mackenzie <maxnbk@users.noreply.github.com>
Update plugin files to match main's post-AcademySoftwareFoundation#1761 code:
- Add type annotations (Version, SupportsLessThan, Package, etc.)
- Add missing imports (each plugin now self-contained)
- Use 'is' instead of '==' for type comparisons (no E721)
- Fix E203 whitespace before ':' in soft_timestamp.py slice
- Match __eq__, to_pod, from_pod, __init__ signatures from main

Signed-off-by: Stephen Mackenzie <maxnbk@users.noreply.github.com>
…r resets

test_plugin_manager resets the plugin manager between test runs, which
deletes rezplugins.* from sys.modules and re-registers all plugin types.
This creates new class objects for orderer plugins. Tests that imported
orderer classes at module level (from rez.package_order import SortedOrder)
were bound to stale class objects, causing isinstance and __eq__ failures
when the full test suite ran in CI.

Fix: resolve orderer classes in setUp() via _find_orderer() so each test
method gets the current class objects.

Signed-off-by: Stephen Mackenzie <maxnbk@users.noreply.github.com>
…methods

Covers: sort_key with VersionRange/None/invalid types, FallbackComparable
fallback path, _find_orderer with unknown name, __getattr__ AttributeError,
register_orderer valid/invalid, PackageOrderList dirty-flag methods,
to_pod/from_pod round-trip, PerFamilyOrder sort_key_implementation with
default_order fallback and RuntimeError path.

Raises orderer test coverage from 85% to 97%.

Signed-off-by: Stephen Mackenzie <maxnbk@users.noreply.github.com>
…gin docs

Addresses review threads on package_order.py: the legacy registry dict
was defined twice (the second definition silently reset nothing but
confused readers), and the register_orderer docstring now cross-references
the plugin documentation properly.

Signed-off-by: Stephen Mackenzie <maxnbk@users.noreply.github.com>
get_plugin_class now raises PluginNotFoundError (a RezPluginError
subclass) instead of the generic RezPluginError, so callers can
distinguish a missing plugin from other plugin-system failures without
breaking existing broad handlers. package_order._find_orderer uses the
specific class for its registry-fallback logic, and the unknown-name
test asserts both the specific class and the subclass relationship.

Addresses review feedback suggesting a more specific plugin error class.

Signed-off-by: Stephen Mackenzie <maxnbk@users.noreply.github.com>
@maxnbk
maxnbk force-pushed the feat/package-orderers-as-configurable-plugins branch from 540b0d8 to cdade03 Compare November 14, 2026 23:07
@maxnbk maxnbk changed the title Draft: feat: package orderers as configurable plugins with config-arg-passing feat: package orderers as configurable plugins with config-arg-passing Nov 14, 2026
PackageOrderList.singleton caches a snapshot of config.package_orderers,
and runtime changes need both the singleton snapshot AND the config-level
cache invalidated. The two runtime pathways differ:

- config.override()/remove_override() invalidate the config-level cache
  themselves;
- the environment-variable pathway (REZ_PACKAGE_ORDERERS_JSON set after
  first access) has no public invalidation hook - only the private
  config._uncache() reaches it (verified: clear-only left a stale list).

clear_singleton_cache() now calls config._uncache("package_orderers")
internally, so users have a single public entry point covering both
pathways and never touch the private API. Verified end-to-end for both
the API-override and env-var pathways.

Addresses review concern about requiring a private API for runtime
reconfiguration.

Signed-off-by: Stephen Mackenzie <maxnbk@users.noreply.github.com>
…ntation

PR AcademySoftwareFoundation#2189 added generic documentation for the REZ_XXX_JSON configuration
pathway (configuring_rez.rst, environment.rst), so the package-orderers
page now links to it instead of re-documenting the mechanism, keeping
only an orderer-specific example. The runtime note now points at
PackageOrderList.clear_singleton_cache() as the single invalidation
entry point.

Addresses review feedback about documenting JSON environment variables.

Signed-off-by: Stephen Mackenzie <maxnbk@users.noreply.github.com>
The legacy module-level aliases (NullPackageOrder, PerFamilyOrder,
SortedOrder, TimestampPackageOrder, VersionSplitPackageOrder) now emit a
RezDeprecationWarning when accessed, nudging users towards the plugin
system - as requested in review. This was blocked by the AcademySoftwareFoundation#2230 circular
import (importing rez.deprecations from package_order's lazy __getattr__
broke under REZ_LOG_DEPRECATION_WARNINGS=1); AcademySoftwareFoundation#2238 fixed that, and this
was verified warning-and-import clean on the rebased branch.

Signed-off-by: Stephen Mackenzie <maxnbk@users.noreply.github.com>
@maxnbk
maxnbk force-pushed the feat/package-orderers-as-configurable-plugins branch from cdade03 to 748797f Compare November 14, 2026 23:59

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants