Adopt a systematic deprecation management library

[xingyaoww]

Summary

Currently, we use Python's built-in warnings module for deprecation warnings across the codebase. We should consider adopting a more systematic approach to managing deprecations.

Current State

Deprecation warnings are scattered across:

• openhands-sdk/openhands/sdk/agent/base.py (Agent.security_analyzer deprecation)
• openhands-sdk/openhands/sdk/llm/llm.py (multiple LLM-related deprecations)
• openhands-sdk/openhands/sdk/llm/llm_registry.py (registry deprecations)
• openhands-sdk/openhands/sdk/conversation/conversation_stats.py (stats deprecations)

Proposed Solution

Adopt one of these libraries for systematic deprecation management:

1. deprecation (Recommended)

• Lightweight, purpose-built for deprecations
• Supports version tracking (deprecated_in, removed_in)
• Integrates with standard warnings module
• Minimal dependencies
• SDK-friendly

Example:

from deprecation import deprecated

@deprecated(deprecated_in="1.0", removed_in="2.0",
            current_version="1.5",
            details="Use conversation.set_security_analyzer() instead")
def old_method():
    pass

2. Deprecated (deprecated.py)

• Feature-rich with Sphinx integration
• Simple decorator syntax
• Very popular (4M+ downloads/month)
• Excellent documentation integration

Example:

from deprecated import deprecated

@deprecated(version='1.0.0', reason="Use conversation.set_security_analyzer() instead")
def old_method():
    pass

3. debtcollector (From OpenStack)

• Comprehensive solution for technical debt tracking
• More than just deprecations
• Battle-tested in large projects
• Can track classes, methods, parameters, and more

Example:

import debtcollector

@debtcollector.removals.remove(
    message="Use conversation.set_security_analyzer() instead",
    version="2.0",
    removal_version="3.0"
)
def old_method():
    pass

Benefits

1. Consistent format - All deprecations follow the same pattern
2. Version tracking - Clear timeline for when features were deprecated and when they'll be removed
3. Better documentation - Automatic integration with docs (especially with Deprecated)
4. User-friendly - Clear, structured messages help users migrate
5. Maintainability - Easier to track and manage all deprecations across the codebase

Recommendation

I recommend starting with deprecation because:

• It's specifically designed for this purpose
• Lightweight with minimal overhead
• Version tracking fits well with our SDK versioning
• Easy migration from current warnings.warn() usage
• Forces us to think about deprecation timeline

Related

• This came up during discussion on PR Refactor: Always include risk fields #1052
• Related to the security_analyzer deprecation in Agent class