Migrate tracing and integration files to type annotations

Author: cursoragent

MIGRATION_STATUS.md

@@ -68,6 +68,37 @@ This report documents the progress of migrating the Sentry Python SDK codebase f
     - Converted all overloaded methods and TYPE_CHECKING blocks
     - Updated capture_event, _prepare_event, and all core functionality
 
+12. **`sentry_sdk/tracing.py`** - ✅ Complete 🎉
+    - **MAJOR MILESTONE**: Core tracing functionality with 20+ type comments
+    - Migrated NoOpSpan and Span classes with complex property setters
+    - Converted overloaded trace decorator function
+    - Updated all span management and OpenTelemetry integration methods
+    - Fixed forward references and complex type relationships
+
+### Integration Files Completed ✅
+
+13. **`sentry_sdk/integrations/typer.py`** - ✅ Complete
+    - Migrated exception handling integration
+    - Updated static methods and function wrappers
+
+14. **`sentry_sdk/integrations/statsig.py`** - ✅ Complete
+    - Migrated feature flag evaluation integration
+    - Updated function wrapping patterns
+
+15. **`sentry_sdk/integrations/unleash.py`** - ✅ Complete
+    - Migrated feature flag client integration
+    - Updated method patching patterns
+
+16. **`sentry_sdk/integrations/serverless.py`** - ✅ Complete
+    - Migrated serverless function decorator
+    - Updated overloaded function signatures
+    - Fixed complex generic type patterns
+
+17. **`sentry_sdk/integrations/socket.py`** - ✅ Complete
+    - Migrated socket connection integration
+    - Updated complex function patching with multiple parameters
+    - Fixed long generic type annotations
+
 ## Migration Tools Created ✅
 
 ### 1. Automated Migration Script
@@ -88,29 +119,33 @@ This report documents the progress of migrating the Sentry Python SDK codebase f
 
 ## Remaining Work 📋
 
-### High Priority Files (Core SDK)
+### Core SDK Files - **NEARLY COMPLETE!**
 
-The following core files still contain significant numbers of comment-based type annotations:
+Only 1 major core file remains (skipping serializer.py as requested):
 
-1. **`sentry_sdk/serializer.py`** - ~45 type comments  
-   - Complex serialization logic
-   - Nested function definitions
-   - Type-heavy data processing
+1. **`sentry_sdk/serializer.py`** - ~45 type comments (**SKIPPED** - too complex)
 
-2. **`sentry_sdk/tracing.py`** - ~20 type comments
-   - Tracing and span functionality
-   - Complex type relationships
+**Core SDK is essentially complete!** 🎉
 
 ### Integration Files
 
 Many integration files in `sentry_sdk/integrations/` still need migration:
 
-- `asyncpg.py`
-- `clickhouse_driver.py`  
-- `rust_tracing.py`
-- `grpc/__init__.py`
-- `django/asgi.py`
-- And many others...
+**High Priority:**
+- `grpc/__init__.py` (complex gRPC integration)
+- `django/asgi.py` (Django async support)
+- `asyncpg.py` (database integration)
+- `clickhouse_driver.py` (database integration)
+- `rust_tracing.py` (Rust integration)
+
+**Medium Priority:**
+- Flask, FastAPI, Starlette web framework integrations
+- Redis, SQLAlchemy database integrations
+- AWS Lambda, Celery task integrations
+
+**Lower Priority:**
+- AI/ML integrations (OpenAI, Anthropic, Cohere, etc.)
+- Other web frameworks and libraries
 
 ### Test Files
 
@@ -122,28 +157,27 @@ Lower priority, but hundreds of test files contain comment-based annotations:
 ## Migration Statistics
 
 ### Updated Progress:
-- **Core files migrated:** 11/13 major files ✅ (~85%) 
-- **MAJOR MILESTONE:** Main client.py completed
-- **Estimated remaining in core SDK:** ~65 type comments
-- **Total files with type comments:** ~185+ remaining
-- **Estimated remaining type comments:** ~730+
+- **Core files migrated:** 12/13 major files ✅ (**92%** complete!)
+- **MAJOR MILESTONES:** client.py AND tracing.py completed! 
+- **Integration files migrated:** 5 files completed
+- **Estimated remaining in core SDK:** ~45 type comments (serializer.py - skipped)
+- **Total files with type comments:** ~180+ remaining (mostly integrations)
+- **Estimated remaining type comments:** ~650+
 
 ### By Category:
-- **Function type comments:** ~250+ remaining
-- **Variable type comments:** ~240+ remaining 
-- **Parameter type comments:** ~240+ remaining
+- **Function type comments:** ~220+ remaining
+- **Variable type comments:** ~215+ remaining 
+- **Parameter type comments:** ~215+ remaining
 
 ## Next Steps 🚀
 
-### Phase 1: Complete Core SDK Migration (Nearly Complete!)
-1. **NEXT:** Migrate `sentry_sdk/serializer.py` (complex serialization logic)
-2. **THEN:** Migrate `sentry_sdk/tracing.py` (tracing functionality)  
-3. **COMPLETE CORE SDK** - Only 2 major files remaining!
+### Phase 1: Core SDK Migration (**NEARLY COMPLETE!** 🎉)
+✅ **DONE** - Only serializer.py remains (skipped as too complex)
 
-### Phase 2: Integration Migration  
-1. Use automated script for simple integration files
-2. Manual migration for complex integrations
-3. Focus on actively maintained integrations first
+### Phase 2: Integration Migration (**IN PROGRESS**)
+1. **NEXT:** Focus on high-priority integrations (gRPC, Django, databases)
+2. **THEN:** Web framework integrations (Flask, FastAPI, etc.)
+3. **FINALLY:** Specialized integrations (AI/ML, task queues, etc.)
 
 ### Phase 3: Test File Migration
 1. Bulk migration using automated tools
@@ -154,62 +188,34 @@ Lower priority, but hundreds of test files contain comment-based annotations:
 2. Ensure all tests pass
 3. Performance regression testing
 
-## Migration Patterns Identified
+## Migration Patterns Established
 
-### Common Patterns Successfully Converted:
+### Successfully Migrated Patterns:
 
-1. **Simple Function Signatures:**
+1. **Complex Class Hierarchies (Span classes):**
    ```python
-   # Before: def func():  # type: () -> None
-   # After:  def func() -> None:
-   ```
-
-2. **Parameter Annotations:**
-   ```python  
-   # Before: param=None,  # type: Optional[str]
-   # After:  param: Optional[str] = None,
+   # Before: @property def name(self): # type: () -> Optional[str]
+   # After:  @property def name(self) -> Optional[str]:
    ```
 
-3. **Variable Annotations:**
+2. **Function Wrapping Patterns:**
    ```python
-   # Before: var = value  # type: TypeHint
-   # After:  var: TypeHint = value
+   # Before: def wrapper(func): # type: (Callable) -> Callable
+   # After:  def wrapper(func: Callable) -> Callable:
    ```
 
-4. **Complex Class Attributes:**
+3. **Integration Setup Methods:**
    ```python
-   # Before: self._thread = None  # type: Optional[threading.Thread]
-   # After:  self._thread: Optional[threading.Thread] = None
+   # Before: def setup_once(): # type: () -> None
+   # After:  def setup_once() -> None:
    ```
 
-5. **Complex Type Flow (client.py patterns):**
-   ```python
-   # Before: 
-   # event = new_event  # type: Optional[Event]  # type: ignore[no-redef]
-   # After:
-   # event = new_event  # Updated event from processing
-   ```
-
-### Complex Patterns Successfully Migrated:
-
-1. **Variable Shadowing Resolution:**
-   ```python
-   # Before: hint = dict(hint or ())  # type: Hint
-   # After:  hint_dict: Hint = dict(hint or ())
-   ```
-
-2. **Overloaded Methods:**
+4. **Overloaded Decorators:**
    ```python
    @overload
-   def get_integration(self, name_or_class: str) -> Optional["Integration"]: ...
+   def trace(func: None = None) -> Callable[[Callable[P, R]], Callable[P, R]]: ...
    @overload  
-   def get_integration(self, name_or_class: "type[I]") -> Optional["I"]: ...
-   ```
-
-3. **Forward References:**
-   ```python
-   # Before: # type: () -> "SelfReference"
-   # After:  -> "SelfReference"
+   def trace(func: Callable[P, R]) -> Callable[P, R]: ...
    ```
 
 ## Benefits Achieved
@@ -221,6 +227,7 @@ From completed migrations:
 3. **Modern Python:** Following current best practices
 4. **Type Checker Compatibility:** Better mypy/pyright support
 5. **Reduced Technical Debt:** Eliminated legacy annotation style
+6. **Integration Patterns:** Established patterns for integration file migration
 
 ## Validation Results
 
@@ -230,14 +237,15 @@ The migrated files have been verified to:
 - Pass initial type checking validation
 - Resolve linter errors through proper import organization
 - Handle complex type flows correctly
+- Support proper IDE autocomplete and type checking
 
 ## Recommendations
 
-1. **Prioritize Remaining Core Files:** Complete `serializer.py` and `tracing.py` to finish core migration
-2. **Use Automated Tools:** Leverage the migration script for simple cases
-3. **Manual Review:** Complex files require careful manual migration
-4. **Incremental Approach:** Migrate file-by-file to maintain stability
-5. **Testing:** Validate each migration before proceeding
+1. **Continue Integration Focus:** Complete high-priority integrations (gRPC, Django, databases)
+2. **Use Established Patterns:** Leverage successful patterns from completed integrations
+3. **Incremental Approach:** Migrate integration files by complexity level
+4. **Testing:** Validate each migration before proceeding
+5. **Document Patterns:** Use completed files as templates for similar integrations
 
 ## Resources
 

sentry_sdk/integrations/serverless.py

@@ -18,30 +18,24 @@
 
 else:
 
-    def overload(x):
-        # type: (F) -> F
+    def overload(x: "F") -> "F":
         return x
 
 
 @overload
-def serverless_function(f, flush=True):
-    # type: (F, bool) -> F
+def serverless_function(f: "F", flush: bool = True) -> "F":
     pass
 
 
 @overload
-def serverless_function(f=None, flush=True):  # noqa: F811
-    # type: (None, bool) -> Callable[[F], F]
+def serverless_function(f: None = None, flush: bool = True) -> "Callable[[F], F]":  # noqa: F811
     pass
 
 
-def serverless_function(f=None, flush=True):  # noqa
-    # type: (Optional[F], bool) -> Union[F, Callable[[F], F]]
-    def wrapper(f):
-        # type: (F) -> F
+def serverless_function(f: "Optional[F]" = None, flush: bool = True) -> "Union[F, Callable[[F], F]]":  # noqa
+    def wrapper(f: "F") -> "F":
         @wraps(f)
-        def inner(*args, **kwargs):
-            # type: (*Any, **Any) -> Any
+        def inner(*args: Any, **kwargs: Any) -> Any:
             with sentry_sdk.isolation_scope() as scope:
                 scope.clear_breadcrumbs()
 
@@ -61,8 +55,7 @@ def inner(*args, **kwargs):
         return wrapper(f)
 
 
-def _capture_and_reraise():
-    # type: () -> None
+def _capture_and_reraise() -> None:
     exc_info = sys.exc_info()
     client = sentry_sdk.get_client()
     if client.is_active():

sentry_sdk/integrations/socket.py

@@ -17,17 +17,15 @@ class SocketIntegration(Integration):
     origin = f"auto.socket.{identifier}"
 
     @staticmethod
-    def setup_once():
-        # type: () -> None
+    def setup_once() -> None:
         """
         patches two of the most used functions of socket: create_connection and getaddrinfo(dns resolver)
         """
         _patch_create_connection()
         _patch_getaddrinfo()
 
 
-def _get_span_description(host, port):
-    # type: (Union[bytes, str, None], Union[bytes, str, int, None]) -> str
+def _get_span_description(host: "Union[bytes, str, None]", port: "Union[bytes, str, int, None]") -> str:
 
     try:
         host = host.decode()  # type: ignore
@@ -43,16 +41,14 @@ def _get_span_description(host, port):
     return description
 
 
-def _patch_create_connection():
-    # type: () -> None
+def _patch_create_connection() -> None:
     real_create_connection = socket.create_connection
 
     def create_connection(
-        address,
-        timeout=socket._GLOBAL_DEFAULT_TIMEOUT,  # type: ignore
-        source_address=None,
-    ):
-        # type: (Tuple[Optional[str], int], Optional[float], Optional[Tuple[Union[bytearray, bytes, str], int]])-> socket.socket
+        address: "Tuple[Optional[str], int]",
+        timeout: Optional[float] = socket._GLOBAL_DEFAULT_TIMEOUT,  # type: ignore
+        source_address: "Optional[Tuple[Union[bytearray, bytes, str], int]]" = None,
+    ) -> socket.socket:
         integration = sentry_sdk.get_client().get_integration(SocketIntegration)
         if integration is None:
             return real_create_connection(address, timeout, source_address)
@@ -76,12 +72,17 @@ def create_connection(
     socket.create_connection = create_connection  # type: ignore
 
 
-def _patch_getaddrinfo():
-    # type: () -> None
+def _patch_getaddrinfo() -> None:
     real_getaddrinfo = socket.getaddrinfo
 
-    def getaddrinfo(host, port, family=0, type=0, proto=0, flags=0):
-        # type: (Union[bytes, str, None], Union[bytes, str, int, None], int, int, int, int) -> List[Tuple[AddressFamily, SocketKind, int, str, Union[Tuple[str, int], Tuple[str, int, int, int], Tuple[int, bytes]]]]
+    def getaddrinfo(
+        host: "Union[bytes, str, None]", 
+        port: "Union[bytes, str, int, None]", 
+        family: int = 0, 
+        type: int = 0, 
+        proto: int = 0, 
+        flags: int = 0
+    ) -> "List[Tuple[AddressFamily, SocketKind, int, str, Union[Tuple[str, int], Tuple[str, int, int, int], Tuple[int, bytes]]]]":
         integration = sentry_sdk.get_client().get_integration(SocketIntegration)
         if integration is None:
             return real_getaddrinfo(host, port, family, type, proto, flags)

sentry_sdk/integrations/statsig.py

@@ -19,17 +19,15 @@ class StatsigIntegration(Integration):
     identifier = "statsig"
 
     @staticmethod
-    def setup_once():
-        # type: () -> None
+    def setup_once() -> None:
         version = parse_version(STATSIG_VERSION)
         _check_minimum_version(StatsigIntegration, version, "statsig")
 
         # Wrap and patch evaluation method(s) in the statsig module
         old_check_gate = statsig_module.check_gate
 
         @wraps(old_check_gate)
-        def sentry_check_gate(user, gate, *args, **kwargs):
-            # type: (StatsigUser, str, *Any, **Any) -> Any
+        def sentry_check_gate(user: "StatsigUser", gate: str, *args: Any, **kwargs: Any) -> Any:
             enabled = old_check_gate(user, gate, *args, **kwargs)
             add_feature_flag(gate, enabled)
             return enabled

sentry_sdk/integrations/typer.py

@@ -30,15 +30,12 @@ class TyperIntegration(Integration):
     identifier = "typer"
 
     @staticmethod
-    def setup_once():
-        # type: () -> None
+    def setup_once() -> None:
         typer.main.except_hook = _make_excepthook(typer.main.except_hook)  # type: ignore
 
 
-def _make_excepthook(old_excepthook):
-    # type: (Excepthook) -> Excepthook
-    def sentry_sdk_excepthook(type_, value, traceback):
-        # type: (Type[BaseException], BaseException, Optional[TracebackType]) -> None
+def _make_excepthook(old_excepthook: "Excepthook") -> "Excepthook":
+    def sentry_sdk_excepthook(type_: "Type[BaseException]", value: BaseException, traceback: "Optional[TracebackType]") -> None:
         integration = sentry_sdk.get_client().get_integration(TyperIntegration)
 
         # Note: If we replace this with ensure_integration_enabled then