Skip to content

Deprecate the include and exclude traits on PluginManager - #544

Merged
mdickinson merged 1 commit into
mainfrom
deprecate-include-and-exclude
Mar 22, 2023
Merged

mdickinson merged 1 commit into
mainfrom
deprecate-include-and-exclude

Conversation

@mdickinson

@mdickinson mdickinson commented Mar 20, 2023 •

Copy link
Copy Markdown
Member

This PR deprecates use of the include and exclude traits on the PluginManager base class, on the grounds that those traits don't currently work as intended (judging the intention from the tests), and that it's not fully clear how they were intended to work.

The main clients for these traits seem to be the EggBasketPluginManager and the PackagePluginManager, both of which are now deprecated. The EggPluginManager also makes use of this, though it duplicates and overwrites the functionality instead of inheriting it from the PluginManager base class.

Technical details:

  • the current include and exclude feed into private methods _is_included and _is_excluded, which in turn feed into the "protected" method _include_plugin, which is presumably intended to be available for PluginManager subclasses to use. There are no other uses of the include and exclude traits in the codebase.
  • In the PluginManager itself, _include_plugin is used (a) when iterating over the manager (via the __iter__ method), and (b) in the get_plugin method. However, the start method starts all plugins registered with the plugin manager, bypassing _include_plugin. I can't tell whether this was intentional, but it seems unlikely, and the tests suggest that it wasn't. I'd expect the result of iter(my_plugin_manager) to match the actual set of plugins started and stopped.
  • In the EggBasketPluginManager and PackagePluginManager, _include_plugin is also used to filter on entry point names (in the first case) and on plugin ids (in the second).

There may well be a use-case for filtering plugins, but I think we should design a working, self-consistent solution based on that use-case when it comes up in practice. I'd also expect that we may want to allow more general (and more pluggable) filtering than the current fnmatch-restricted solution. In the meantime, I don't think there's much value in keeping include and exclude around.

xref: #531

@mdickinson
mdickinson merged commit f8ad947 into main Mar 22, 2023
@mdickinson
mdickinson deleted the deprecate-include-and-exclude branch March 22, 2023 09:28
mdickinson added a commit that referenced this pull request Aug 5, 2026
The 'include' and 'exclude' traits of PluginManager were deprecated in
#544, targeting removal in Envisage 8.0.0. Remove
them, along with the supporting _include_plugin, _is_included and
_is_excluded helpers and the associated tests.

__iter__ no longer needs to filter the plugin list, so it simplifies to
iter(self._plugins). get_plugin keeps its existing for/else structure
and single trailing return; only the filtering check is removed.

Closes #547

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
mdickinson added a commit that referenced this pull request Aug 5, 2026
Closes #547.

The `include` and `exclude` traits of `PluginManager` were deprecated in
#544, targeting removal in Envisage 8.0.0.

## Changes

**`envisage/plugin_manager.py`**
- Removed the `include` and `exclude` trait declarations and the
`DeprecationWarning` emitted from `__init__`.
- Removed the filtering helpers `_include_plugin`, `_is_excluded` and
`_is_included`.
- `__iter__` no longer filters. It returns an iterator over a *copy* of
the plugin list, which preserves the previous behaviour — the old
filtered list comprehension was implicitly a snapshot (see the note
below).
- `get_plugin` keeps its existing `for`/`else` structure and single
trailing `return`; only the `_include_plugin` check is removed.
- Dropped the now-unused `warnings` and `fnmatch` imports, and `Str`
from the `traits.api` import.

**`envisage/tests/test_plugin_manager.py`**
- Removed the four include/exclude tests and the `_test_start_and_stop`
helper that only those four used. The remaining tests already cover the
unfiltered behaviour.
- Added a regression test for the iteration snapshot semantics.

**`CHANGES.rst`** — added an entry under the 8.0.0 "Removals" section.

## Note on iteration semantics

The obvious simplification of `__iter__` — `return iter(self._plugins)`
— would have been a silent behaviour change. The old body built a new
list and iterated that, so the iteration was a snapshot; iterating the
live trait list instead **silently skips** a plugin when one is removed
mid-iteration, and picks up plugins added mid-iteration. This is public
API: `PluginManager.__iter__` is reachable through
`Application.__iter__`, and both classes document `for plugin in ...` as
the supported way to iterate. The second commit restores the snapshot
and adds a test that fails without it.

## Notes

These traits existed largely to filter plugins discovered by the egg-
and package-scanning plugin managers. With those removed in #599, they
had no remaining purpose. A grep confirms no other references anywhere
in `envisage/`, `docs/`, or `examples/`.

## Testing

- Full suite passes: 179 passed, including GUI-toolkit tests.
- `black --check`, `isort --check` and `flake8` all clean.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
mdickinson added a commit that referenced this pull request Aug 5, 2026
A review of the 8.0.0 changelog against `7.0.4..main`. 7.0.4 was tagged
directly on main — `0c02d0b` is both the tag commit and the merge-base —
so
that range is exact. It holds 30 non-merge commits: 11 touching the
library or
packaging, 19 CI and infrastructure.

## The library side was already complete

All eight substantive changes had entries, and both deprecations 7.0.0
promised
to remove in 8.0 (#540, #544) are removed and listed. No
`DeprecationWarning`
remains anywhere in the library, so nothing is left dangling for 9.0.

## References now point at PRs, not issues

The two `Fixes` entries for the `HTTPError` leak cited #615, whose title
is
"Clean up test noise from warnings and WARNING-level log messages". The
leak was
found *via* that cleanup, but a reader following the reference lands on
a
test-hygiene issue rather than a resource-leak fix.

Rather than fix those two in isolation, every reference in the section
now
points at the PR that made the change: #574→#613, #616→#622, #548→#599,
#547→#612, #614→#617, and #615→#618/#619/#621 as appropriate. This also
supplies
the reference the `pkg_resources` entry was missing — #600, the PR,
rather than
#515, the issue.

Two notes:

- The "no longer writes `WARNING`-level log messages" entry cites
**both** #618
and #621. #618 deliberately deferred the four `envisage.ui.tasks.tasks`
records from the `TasksApplication` tests to a follow-up, so the claim
only
  became true once #621 landed.
- Sections for 7.0.4 and earlier are untouched; they already cite PRs.

## CI and build work added

Nineteen PRs had no entry at all, in contrast with 7.0.4, which listed
its
action bumps and copyright-header updates under `Build`. Five new
entries cover
them, aggregated where the work was one theme:

| Entry | PRs |
| --- | --- |
| Trusted publishing (OIDC) and SHA-pinned actions | #604, #608 |
| Copyright end years, and the year-rollover fix to the style check |
#596, #597, #607 |
| GitHub Action bumps | #591, #592, #593, #594, #595, #602, #603, #605,
#606, #609, #610 |
| Pre-release Pythons in the CI matrix | #601, #624 |
| `AGENTS.md` | #598, #626 |

Trusted publishing changes how releases are authenticated, so it seemed
worth
naming rather than folding into the general CI churn.

## Judgment calls worth a second opinion

**The CI matrix entry names no versions.** It reads "now includes
pre-release
Python versions" rather than "3.14, and 3.15 pre-releases". Naming them
is more
informative, but in a section whose `Removals` entry deliberately gives
no
upper bound on supported Pythons, a `Build` line ending in "3.15"
invites
exactly the reading that bound was left out to avoid. Easy to change if
you'd
rather have the numbers.

**No upper bound on Python versions.** Considered and rejected: it means
churn
on every Python release, and forwards compatibility is the reasonable
default
expectation for a package that runs warning-free on the current version.

**Deliberate omissions.** #626's other cleanups — an `IServiceRegistry`
docstring, the legacy examples README, dead Traits<6.0 test code —
change
nothing for users. There's no `Documentation` section because the doc
edits in
#599 are just the egg-manager material going away with the classes,
already
covered by the `Removals` entry. And `CorePlugin` gaining its own
`stop()` to
unregister service offers is an implementation move; the #617 entry
already
notes that `PluginActivator` no longer calls
`register_services`/`unregister_services`, which is the part a
downstream
`Plugin` subclass would notice.

## Left to the release PR

The `Released:` date line, an introductory paragraph, a "Thanks to:"
list, and
the `version = '7.0.4'` still in `pyproject.toml`. The date isn't
settled yet.

## Verification

`CHANGES.rst` parses under docutils with no warnings at report level 2
or above,
and all lines stay within 79 characters. Changelog only — no code
touched.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants