feat(proxy): add attrs_mapping to deprecated_class for fine attribute deprecation

[Borda]

Before submitting

• Was this discussed/approved via a Github issue? (no need for typos and docs improvements)
• Did you make sure to update the docs?
• Did you write any new necessary tests?

What does this PR do?

• Add attrs_mapping: Optional[dict[str, Optional[str]]] to deprecated_class() and _DeprecatedProxy
• __getattr__/__setattr__/__delattr__ warn only for listed attribute names; unlisted attrs pass through silently
• Redirect reads/writes/deletes to canonical attribute name when value is non-None; warn-only when value is None
• Reuse existing _warn(arg_name=...) per-key budget path for per-attribute warning counters
• Raise ValueError at decoration time for circular mappings (key also appears as a redirect target)
• Store attrs_mapping in both DeprecationConfig (audit visibility) and _ProxyConfig (runtime)
• Add TestDeprecatedAttrs with 10 tests covering read/write/delete redirect, notify-only, per-attr budget, enum, message content, circular validation

PR review

Anyone in the community is free to review the PR once the tests have passed.
If we didn't discuss your PR in Github issues there's a high chance it will not be merged.

Did you have fun?

Make sure you had fun coding 🙃

[Copilot]

Pull request overview

This PR extends deprecated_class() / _DeprecatedProxy with an attrs_mapping option to selectively deprecate individual attribute names (warn + optional redirect) while allowing all other attribute access to pass through silently. This fits pyDeprecate’s proxy-based class deprecation model by enabling fine-grained attribute-level migrations without changing the class-level deprecation mechanism.

Changes:

• Add attrs_mapping: Optional[dict[str, Optional[str]]] support end-to-end (runtime proxy config + __deprecated__ metadata) with decoration-time circular mapping validation.
• Implement selective warning/redirect behavior in _DeprecatedProxy.__getattr__, __setattr__, and __delattr__, plus corresponding warning message formatting in _warn().
• Add new fixtures + unit tests for read/write/delete redirect, warn-only behavior, per-attribute warning budgets, enum member redirect, and metadata visibility; update docs with examples.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/deprecate/proxy.py	Adds attrs_mapping plumbing, validation, selective attr forwarding, and per-attr warning formatting.
src/deprecate/_types.py	Extends DeprecationConfig / _ProxyConfig to store attrs_mapping for audit/runtime visibility.
tests/unittests/test_proxy.py	Adds a dedicated TestDeprecatedAttrs suite to validate selective attribute deprecation behavior.
tests/collection_targets.py	Introduces TargetPalette / TargetPaletteEnum as targets for attribute-mapping proxy tests.
tests/collection_deprecate.py	Adds module-level deprecated_class(..., attrs_mapping=...) fixtures for the new tests.
README.md	Documents attrs_mapping as a deprecated_class() option and provides a runnable example.
docs/llms.txt	Updates LLM-oriented usage notes and decision guide to mention attrs_mapping.
docs/guide/use-cases.md	Adds a “Selective attribute deprecation” section with an example (needs correction per review comments).

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (1)

src/deprecate/proxy.py:431

• __getattr__'s read-only mutator guarding (append, update, etc.) is bypassed whenever attrs_mapping is set because the method returns early for both deprecated and non-deprecated attribute lookups. This breaks the class docstring contract for _DeprecatedProxy (“In read-only mode, common mutating methods … are wrapped …”) and makes read_only=True ineffective for method accesses in the attrs_mapping mode.

        attrs_mapping = self._cfg.attrs_mapping
        if attrs_mapping is not None:
            if name in attrs_mapping:
                self._warn(arg_name=f"__attr__:{name}")
                redirect = attrs_mapping[name]
                active = self._get_active()
                return getattr(active, redirect if redirect is not None else name)
            # Not a deprecated attr — silent passthrough, no warning.
            return getattr(self._get_active(), name)
        self._warn()
        attr = getattr(self._get_active(), name)
        # In read-only mode, guard common mutating methods accessed via attribute lookup.
        if self._cfg.read_only and callable(attr) and self._is_potential_mutator(name):

            def _guarded_mutator(*args: Any, **kwargs: Any) -> None:  # noqa: ANN401
                self._check_read_only(f"Calling mutating method '{name}'")

            return _guarded_mutator
        return attr

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Files Reviewed (2 files)

• src/deprecate/proxy.py — fixed legacy bool target validation and added read-only mutator guard in attrs_mapping path
• tests/ — added regression tests for legacy bool target and read-only attrs_mapping

---

_{Reviewed by step-3.7-flash-20260528 · 650,677 tokens}

[Copilot]

Pull request overview

Copilot reviewed 20 out of 20 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 20 out of 20 changed files in this pull request and generated 6 comments.