BUG-HUNT: [consistency] Redundant legacy alias methods in `ActorRegistry` #3341

New issue

Closed

opened 2026-04-05 10:19:40 +00:00 by freemo · 1 comment

freemo commented

2026-04-05 10:19:40 +00:00

Owner

Metadata

Branch: fix/actor-registry-deprecate-legacy-aliases
Commit Message: fix(actor): deprecate legacy alias methods in ActorRegistry
Milestone: Backlog (no milestone — see backlog note below)
Parent Epic: #392

Background and Context

The ActorRegistry class in src/cleveragents/actor/registry.py exposes several methods that are undocumented aliases for canonical methods. These aliases are commented as "legacy" but are not formally deprecated, increasing the API surface area, creating confusion for developers, and adding maintenance burden.

Affected method pairs (lines 327–374):

get_actor → alias for get
list_actors → alias for list
remove_actor → alias for remove

Current Behavior

The legacy alias methods (get_actor, list_actors, remove_actor) exist alongside their canonical counterparts (get, list, remove) with no formal deprecation warning. Developers may use either form without any guidance to prefer the canonical API, leading to inconsistent usage across the codebase.

def get(self, name: str) -> Actor:
    """Retrieve an actor by its namespaced name."""
    self.ensure_built_in_actors()
    return self._actor_service.get_actor(self._ensure_namespaced(name))

def get_actor(self, name: str) -> Actor:
    """Retrieve an actor by name (legacy alias for :meth:`get`)."""
    self.ensure_built_in_actors()
    return self._actor_service.get_actor(name)

def list(self, namespace: str | None = None) -> list[Actor]:
    # ...
    return actors

def list_actors(self) -> list[Actor]:
    """Return all actors (legacy alias for :meth:`list`).
    # ...
    """
    return self._actor_service.list_actors()

def remove(self, name: str) -> None:
    """Remove an actor by its namespaced name."""
    self.ensure_built_in_actors()
    self._actor_service.remove_actor(self._ensure_namespaced(name))

def remove_actor(self, name: str) -> None:
    """Remove a custom actor (legacy alias for :meth:`remove`)."""
    self.ensure_built_in_actors()
    self._actor_service.remove_actor(name)

Expected Behavior

The legacy alias methods should be formally deprecated using a @deprecated decorator (e.g., from the deprecation library), issuing a DeprecationWarning at call time and directing developers to the canonical methods. This makes the deprecation machine-readable, visible in IDEs, and sets a clear removal timeline.

from deprecation import deprecated

@deprecated(deprecated_in="1.1.0", removed_in="2.0.0",
            current_version=__version__,
            details="Use the get() method instead")
def get_actor(self, name: str) -> Actor:
    ...

# ... and similarly for list_actors() and remove_actor()

Acceptance Criteria

get_actor, list_actors, and remove_actor are decorated with @deprecated (or equivalent) and emit DeprecationWarning when called.
Docstrings on the alias methods are updated to reference the canonical method and state the deprecation version and planned removal version.
No existing callers of the alias methods remain in the production codebase (or they are updated to use canonical methods).
BDD scenarios cover the deprecation warning behaviour.
All nox stages pass; coverage ≥ 97%.

Supporting Information

File: src/cleveragents/actor/registry.py
Class: ActorRegistry
Lines: 327–374
Category: consistency
Discovered during automated bug-hunting on the codebase.

Subtasks

Add deprecation (or equivalent) library as a dependency if not already present
Decorate get_actor with @deprecated, update its docstring
Decorate list_actors with @deprecated, update its docstring
Decorate remove_actor with @deprecated, update its docstring
Audit codebase for callers of the alias methods and migrate them to canonical methods
Tests (Behave): Add BDD scenarios verifying DeprecationWarning is emitted for each alias
Tests (Behave): Verify canonical methods continue to work correctly
Verify coverage ≥ 97% via nox -s coverage_report
Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly (fix(actor): deprecate legacy alias methods in ActorRegistry), followed by a blank line, then additional lines providing relevant details about the implementation.
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly (fix/actor-registry-deprecate-legacy-aliases).
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.
All nox stages pass and coverage ≥ 97%.

Backlog note: This issue was discovered during autonomous operation
on milestone v3.2.0. It does not block milestone completion and has been
placed in the backlog for human review and future milestone assignment.

Automated by CleverAgents Bot
Supervisor: Bug Hunting | Agent: ca-new-issue-creator

## Metadata - **Branch**: `fix/actor-registry-deprecate-legacy-aliases` - **Commit Message**: `fix(actor): deprecate legacy alias methods in ActorRegistry` - **Milestone**: Backlog (no milestone — see backlog note below) - **Parent Epic**: #392 ## Background and Context The `ActorRegistry` class in `src/cleveragents/actor/registry.py` exposes several methods that are undocumented aliases for canonical methods. These aliases are commented as "legacy" but are not formally deprecated, increasing the API surface area, creating confusion for developers, and adding maintenance burden. Affected method pairs (lines 327–374): - `get_actor` → alias for `get` - `list_actors` → alias for `list` - `remove_actor` → alias for `remove` ## Current Behavior The legacy alias methods (`get_actor`, `list_actors`, `remove_actor`) exist alongside their canonical counterparts (`get`, `list`, `remove`) with no formal deprecation warning. Developers may use either form without any guidance to prefer the canonical API, leading to inconsistent usage across the codebase. ```python def get(self, name: str) -> Actor: """Retrieve an actor by its namespaced name.""" self.ensure_built_in_actors() return self._actor_service.get_actor(self._ensure_namespaced(name)) def get_actor(self, name: str) -> Actor: """Retrieve an actor by name (legacy alias for :meth:`get`).""" self.ensure_built_in_actors() return self._actor_service.get_actor(name) def list(self, namespace: str | None = None) -> list[Actor]: # ... return actors def list_actors(self) -> list[Actor]: """Return all actors (legacy alias for :meth:`list`). # ... """ return self._actor_service.list_actors() def remove(self, name: str) -> None: """Remove an actor by its namespaced name.""" self.ensure_built_in_actors() self._actor_service.remove_actor(self._ensure_namespaced(name)) def remove_actor(self, name: str) -> None: """Remove a custom actor (legacy alias for :meth:`remove`).""" self.ensure_built_in_actors() self._actor_service.remove_actor(name) ``` ## Expected Behavior The legacy alias methods should be formally deprecated using a `@deprecated` decorator (e.g., from the `deprecation` library), issuing a `DeprecationWarning` at call time and directing developers to the canonical methods. This makes the deprecation machine-readable, visible in IDEs, and sets a clear removal timeline. ```python from deprecation import deprecated @deprecated(deprecated_in="1.1.0", removed_in="2.0.0", current_version=__version__, details="Use the get() method instead") def get_actor(self, name: str) -> Actor: ... # ... and similarly for list_actors() and remove_actor() ``` ## Acceptance Criteria - [ ] `get_actor`, `list_actors`, and `remove_actor` are decorated with `@deprecated` (or equivalent) and emit `DeprecationWarning` when called. - [ ] Docstrings on the alias methods are updated to reference the canonical method and state the deprecation version and planned removal version. - [ ] No existing callers of the alias methods remain in the production codebase (or they are updated to use canonical methods). - [ ] BDD scenarios cover the deprecation warning behaviour. - [ ] All nox stages pass; coverage ≥ 97%. ## Supporting Information - **File**: `src/cleveragents/actor/registry.py` - **Class**: `ActorRegistry` - **Lines**: 327–374 - **Category**: consistency - Discovered during automated bug-hunting on the codebase. ## Subtasks - [ ] Add `deprecation` (or equivalent) library as a dependency if not already present - [ ] Decorate `get_actor` with `@deprecated`, update its docstring - [ ] Decorate `list_actors` with `@deprecated`, update its docstring - [ ] Decorate `remove_actor` with `@deprecated`, update its docstring - [ ] Audit codebase for callers of the alias methods and migrate them to canonical methods - [ ] Tests (Behave): Add BDD scenarios verifying `DeprecationWarning` is emitted for each alias - [ ] Tests (Behave): Verify canonical methods continue to work correctly - [ ] Verify coverage ≥ 97% via `nox -s coverage_report` - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly (`fix(actor): deprecate legacy alias methods in ActorRegistry`), followed by a blank line, then additional lines providing relevant details about the implementation. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly (`fix/actor-registry-deprecate-legacy-aliases`). - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done. - All nox stages pass and coverage ≥ 97%. > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.2.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. --- **Automated by CleverAgents Bot** Supervisor: Bug Hunting | Agent: ca-new-issue-creator

freemo commented

2026-04-05 16:28:32 +00:00

Author

Owner

Closing as duplicate of #3354.

Both issues address the same problem: redundant legacy alias methods (get_actor, list_actors, remove_actor) in ActorRegistry. Issue #3354 was filed as a refactor to remove them; this issue (#3341) was filed as a bug to deprecate them. The approach in #3354 (removal) is preferred over deprecation since these are internal APIs with no external consumers.

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: ca-project-owner

Closing as duplicate of #3354. Both issues address the same problem: redundant legacy alias methods (`get_actor`, `list_actors`, `remove_actor`) in `ActorRegistry`. Issue #3354 was filed as a refactor to remove them; this issue (#3341) was filed as a bug to deprecate them. The approach in #3354 (removal) is preferred over deprecation since these are internal APIs with no external consumers. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo closed this issue

2026-04-05 16:28:54 +00:00

freemo referenced this issue

2026-04-05 16:29:38 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 #3377

freemo referenced this issue

2026-04-05 17:02:33 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 #3377