refactor: Standardize deprecation strategy (Phase 6)

- Create standardized deprecation utilities in utils/deprecation.py
- Provide consistent @deprecated and @deprecated_class decorators
- Update all existing deprecations to use standard approach
- Replace inconsistent warnings.warn() calls with decorators
- Update CLAUDE.md with new deprecation guidelines
- Ensure all deprecations include version, removal version, and replacement

This standardizes deprecation handling across the SDK, making it easier
for users to understand migration paths and for maintainers to manage
deprecated features consistently.

Author: TexasCoding

CLAUDE.md

@@ -27,27 +27,43 @@ Example approach:
 - ❌ DON'T: Remove deprecated features without proper notice period
 
 ### Deprecation Process
-1. Mark as deprecated with `warnings.warn()` and `@deprecated` decorator
-2. Document replacement in deprecation message
+1. Use the standardized `@deprecated` decorator from `project_x_py.utils.deprecation`
+2. Provide clear reason, version info, and replacement path
 3. Keep deprecated feature for at least 2 minor versions
 4. Remove only in major version releases (4.0.0, 5.0.0, etc.)
 
 Example:
 ```python
-import warnings
-from typing import deprecated
-
-@deprecated("Use new_method() instead. Will be removed in v4.0.0")
+from project_x_py.utils.deprecation import deprecated, deprecated_class
+
+# For functions/methods
+@deprecated(
+    reason="Method renamed for clarity",
+    version="3.1.14",  # When deprecated
+    removal_version="4.0.0",  # When it will be removed
+    replacement="new_method()"  # What to use instead
+)
 def old_method(self):
-    warnings.warn(
-        "old_method() is deprecated, use new_method() instead. "
-        "Will be removed in v4.0.0",
-        DeprecationWarning,
-        stacklevel=2
-    )
     return self.new_method()
+
+# For classes
+@deprecated_class(
+    reason="Integrated into TradingSuite",
+    version="3.1.14",
+    removal_version="4.0.0",
+    replacement="TradingSuite"
+)
+class OldManager:
+    pass
 ```
 
+The standardized deprecation utilities provide:
+- Consistent warning messages across the SDK
+- Automatic docstring updates with deprecation info
+- IDE support through the `deprecated` package
+- Metadata tracking for deprecation management
+- Support for functions, methods, classes, and parameters
+
 ## Development Commands
 
 ### Package Management (UV)

src/project_x_py/client/trading.py

@@ -66,15 +66,14 @@ async def main():
 
 import datetime
 import logging
-import warnings
 from datetime import timedelta
 from typing import TYPE_CHECKING
 
 import pytz
-from deprecated import deprecated  # type: ignore
 
 from project_x_py.exceptions import ProjectXError
 from project_x_py.models import Position, Trade
+from project_x_py.utils.deprecation import deprecated
 
 if TYPE_CHECKING:
     from project_x_py.types import ProjectXClientProtocol
@@ -85,8 +84,11 @@ async def main():
 class TradingMixin:
     """Mixin class providing trading functionality."""
 
-    @deprecated(  # type: ignore[misc]
-        "Use search_open_positions() instead. This method will be removed in v4.0.0."
+    @deprecated(
+        reason="Method renamed for API consistency",
+        version="3.0.0",
+        removal_version="4.0.0",
+        replacement="search_open_positions()",
     )
     async def get_positions(self: "ProjectXClientProtocol") -> list[Position]:
         """
@@ -102,12 +104,7 @@ async def get_positions(self: "ProjectXClientProtocol") -> list[Position]:
         Returns:
             A list of Position objects representing current holdings.
         """
-        warnings.warn(
-            "get_positions() is deprecated, use search_open_positions() instead. "
-            "This method will be removed in v4.0.0.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
+        # Deprecation warning handled by decorator
         return await self.search_open_positions()
 
     async def search_open_positions(

src/project_x_py/order_manager/tracking.py

@@ -54,6 +54,8 @@ def on_order_fill(order_data):
 from collections.abc import Callable
 from typing import TYPE_CHECKING, Any
 
+from project_x_py.utils.deprecation import deprecated
+
 if TYPE_CHECKING:
     from project_x_py.types import OrderManagerProtocol
 
@@ -317,6 +319,12 @@ async def get_tracked_order_status(
         async with self.order_lock:
             return self.tracked_orders.get(order_id)
 
+    @deprecated(
+        reason="Use TradingSuite.on() with EventType enum for event handling",
+        version="3.1.0",
+        removal_version="4.0.0",
+        replacement="TradingSuite.on(EventType.ORDER_FILLED, callback)",
+    )
     def add_callback(
         self,
         event_type: str,
@@ -327,9 +335,8 @@ def add_callback(
 
         This method is provided for backward compatibility only and will be removed in v4.0.
         """
-        logger.warning(
-            "add_callback is deprecated. Use TradingSuite.on() with EventType enum instead."
-        )
+        # Deprecation warning handled by decorator
+        pass
 
     async def _trigger_callbacks(self, event_type: str, data: Any) -> None:
         """

src/project_x_py/order_tracker.py

@@ -57,24 +57,24 @@
 
 import asyncio
 import logging
-import warnings
 from types import TracebackType
 from typing import TYPE_CHECKING, Any, Union
 
-from typing_extensions import deprecated
-
 from project_x_py.event_bus import EventType
 from project_x_py.models import BracketOrderResponse, Order, OrderPlaceResponse
+from project_x_py.utils.deprecation import deprecated, deprecated_class
 
 if TYPE_CHECKING:
     from project_x_py.trading_suite import TradingSuite
 
 logger = logging.getLogger(__name__)
 
 
-@deprecated(
-    "OrderTracker is deprecated. Use TradingSuite.track_order() instead. "
-    "Will be removed in v4.0.0"
+@deprecated_class(
+    reason="Use TradingSuite.track_order() for integrated order tracking",
+    version="3.1.14",
+    removal_version="4.0.0",
+    replacement="TradingSuite.track_order()",
 )
 class OrderTracker:
     """
@@ -370,9 +370,11 @@ def is_terminal(self) -> bool:
         )  # FILLED, CANCELLED, EXPIRED, REJECTED
 
 
-@deprecated(
-    "OrderChainBuilder is deprecated. Use TradingSuite.order_chain() instead. "
-    "Will be removed in v4.0.0"
+@deprecated_class(
+    reason="Use TradingSuite.order_chain() for integrated order chain building",
+    version="3.1.14",
+    removal_version="4.0.0",
+    replacement="TradingSuite.order_chain()",
 )
 class OrderChainBuilder:
     """
@@ -621,7 +623,10 @@ class OrderLifecycleError(Exception):
 
 # Convenience function for creating order trackers
 @deprecated(
-    "Use TradingSuite.track_order() instead. This function will be removed in v4.0.0."
+    reason="Use TradingSuite.track_order() for integrated tracking",
+    version="3.1.14",
+    removal_version="4.0.0",
+    replacement="TradingSuite.track_order()",
 )
 def track_order(
     trading_suite: "TradingSuite",
@@ -645,12 +650,7 @@ def track_order(
             filled = await tracker.wait_for_fill()
         ```
     """
-    warnings.warn(
-        "track_order() is deprecated, use TradingSuite.track_order() instead. "
-        "This function will be removed in v4.0.0",
-        DeprecationWarning,
-        stacklevel=2,
-    )
+    # Deprecation warning handled by decorator
     tracker = OrderTracker(trading_suite)
     if order:
         if isinstance(order, Order | OrderPlaceResponse):

src/project_x_py/orderbook/__init__.py

@@ -114,6 +114,7 @@ async def on_depth_update(event):
     OrderbookAnalysisResponse,
 )
 from project_x_py.types.stats_types import OrderbookStats
+from project_x_py.utils.deprecation import deprecated
 
 __all__ = [
     # Types
@@ -464,6 +465,12 @@ async def cleanup(self) -> None:
         await super().cleanup()
 
 
+@deprecated(
+    reason="Use TradingSuite.create() with orderbook feature for integrated orderbook",
+    version="3.1.0",
+    removal_version="4.0.0",
+    replacement='TradingSuite.create(instrument, features=["orderbook"])',
+)
 def create_orderbook(
     instrument: str,
     event_bus: Any,

src/project_x_py/orderbook/base.py

@@ -91,6 +91,7 @@ async def on_depth(data):
     ProjectXLogger,
     handle_errors,
 )
+from project_x_py.utils.deprecation import deprecated
 from project_x_py.utils.stats_tracking import StatsTrackingMixin
 
 logger = ProjectXLogger.get_logger(__name__)
@@ -663,6 +664,12 @@ async def get_order_type_statistics(self) -> dict[str, int]:
         async with self.orderbook_lock:
             return self.order_type_stats.copy()
 
+    @deprecated(
+        reason="Use TradingSuite.on() with EventType enum for event handling",
+        version="3.1.0",
+        removal_version="4.0.0",
+        replacement="TradingSuite.on(EventType.MARKET_DEPTH_UPDATE, callback)",
+    )
     @handle_errors("add callback", reraise=False)
     async def add_callback(self, event_type: str, callback: CallbackType) -> None:
         """
@@ -707,21 +714,23 @@ async def add_callback(self, event_type: str, callback: CallbackType) -> None:
             >>> # Events automatically flow through EventBus
         """
         async with self._callback_lock:
-            logger.warning(
-                "add_callback is deprecated. Use TradingSuite.on() with EventType enum instead."
-            )
+            # Deprecation warning handled by decorator
             logger.debug(
                 LogMessages.CALLBACK_REGISTERED,
                 extra={"event_type": event_type, "component": "orderbook"},
             )
 
+    @deprecated(
+        reason="Use TradingSuite.off() with EventType enum for event handling",
+        version="3.1.0",
+        removal_version="4.0.0",
+        replacement="TradingSuite.off(EventType.MARKET_DEPTH_UPDATE, callback)",
+    )
     @handle_errors("remove callback", reraise=False)
     async def remove_callback(self, event_type: str, callback: CallbackType) -> None:
         """Remove a registered callback."""
         async with self._callback_lock:
-            logger.warning(
-                "remove_callback is deprecated. Use TradingSuite.off() with EventType enum instead."
-            )
+            # Deprecation warning handled by decorator
             logger.debug(
                 LogMessages.CALLBACK_REMOVED,
                 extra={"event_type": event_type, "component": "orderbook"},

src/project_x_py/position_manager/tracking.py

@@ -67,6 +67,7 @@ async def on_position_closed(data):
 
 from project_x_py.models import Position
 from project_x_py.types.trading import PositionType
+from project_x_py.utils.deprecation import deprecated
 
 if TYPE_CHECKING:
     from asyncio import Lock
@@ -489,6 +490,12 @@ async def _trigger_callbacks(self, event_type: str, data: Any) -> None:
 
         # Legacy callbacks have been removed - use EventBus
 
+    @deprecated(
+        reason="Use TradingSuite.on() with EventType enum for event handling",
+        version="3.1.0",
+        removal_version="4.0.0",
+        replacement="TradingSuite.on(EventType.POSITION_UPDATED, callback)",
+    )
     async def add_callback(
         self,
         event_type: str,