SY-3768: Oracle Prep 10: Fix Mypy Type Checking in Python Client

[emilbon99]

Issue Pull Request

Linear Issue

SY-####

Description

Basic Readiness

• I have performed a self-review of my code.
• I have added relevant, automated tests to cover the changes.
• I have updated documentation to reflect the changes.

Greptile Overview

Greptile Summary

This PR systematically addresses mypy type checking issues across the Python client codebase by adding proper type annotations, casts, and assertions throughout 70 files.

Key Changes

• Type Safety Improvements: Added explicit type casts using cast(), assertions, and proper type annotations across all modules
• Naming Conflict Resolution: Resolved conflict between arc.Task and task.Task by renaming to ArcTask
• Simplified Overloads: Removed complex overload signatures in CLI console code in favor of simpler Any types
• Parameter Validation: Added has_params() helper function and improved parameter checking logic
• Exception Handling: Changed exception types from Exception to BaseException where appropriate
• Property Guards: Added property getters with proper null checks in ranger/client.py
• TypeAlias Definitions: Moved Params TypeAlias definition to after helper functions for proper ordering

Impact

The changes are purely type-checking improvements without behavioral modifications. The PR enhances code maintainability and catches potential type errors at development time rather than runtime.

Confidence Score: 5/5

• This PR is safe to merge with minimal risk
• The changes are purely type annotation improvements focused on making mypy pass. All modifications add type safety without altering runtime behavior. The changes include proper casts, assertions, null checks, and type annotations that make the codebase more maintainable and catch potential errors earlier.
• No files require special attention

Important Files Changed

Filename	Overview
client/py/synnax/init.py	Resolves naming conflict between arc.Task and task.Task by renaming arc.Task to ArcTask
client/py/synnax/channel/payload.py	Adds proper type annotations, casts, and TypeAlias definition; adds has_params helper function
client/py/synnax/framer/writer.py	Improves type safety with explicit casts, assertions, and proper exception handling
client/py/synnax/ranger/client.py	Major refactor with better type annotations, property guards, and overload signatures
client/py/synnax/cli/console/sugared.py	Simplified by removing complex overload signatures in favor of Any types
client/py/synnax/control/controller.py	Enhanced type safety with better parameter checks, casts, and return type annotations
client/py/synnax/signals/signals.py	Refactored internal attributes and improved type annotations for handlers and channels
client/py/synnax/channel/retrieve.py	Better type checking with explicit casts and parameter validation
client/py/synnax/framer/client.py	Improved type annotations and removed unnecessary complexity
client/py/synnax/framer/adapter.py	Enhanced type safety with better casts and parameter handling

Sequence Diagram

sequenceDiagram
    participant Dev as Developer
    participant Code as Python Code
    participant Mypy as Type Checker
    participant Runtime as Runtime

    Dev->>Code: Write code with type hints
    Code->>Mypy: Run type checking
    
    Note over Mypy: Before PR: Type errors found
    
    Dev->>Code: Add explicit casts
    Dev->>Code: Add assertions
    Dev->>Code: Fix type annotations
    Dev->>Code: Add property guards
    
    Code->>Mypy: Re-run type checking
    
    Note over Mypy: After PR: All type checks pass
    
    Mypy->>Dev: ✓ Type checking successful
    Code->>Runtime: Deploy with confidence

Loading

_{Last reviewed commit: 6fb0f80}

[greptile-apps]

_{70 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}

[codecov]

Codecov Report

❌ Patch coverage is 81.40590% with 164 lines in your changes missing coverage. Please review.
✅ Project coverage is 53.04%. Comparing base (66ba49b) to head (1c08380).
⚠️ Report is 1 commits behind head on rc.

Files with missing lines	Patch %	Lines
client/py/synnax/signals/signals.py	44.44%	20 Missing ⚠️
client/py/synnax/cli/check_timing.py	0.00%	17 Missing ⚠️
client/py/synnax/framer/writer.py	75.51%	12 Missing ⚠️
client/py/synnax/cli/ingest.py	47.61%	11 Missing ⚠️
client/py/synnax/ranger/client.py	85.89%	11 Missing ⚠️
client/py/synnax/state/state.py	52.63%	9 Missing ⚠️
client/py/synnax/user/client.py	25.00%	9 Missing ⚠️
client/py/synnax/channel/payload.py	82.35%	6 Missing ⚠️
client/py/synnax/cli/populate.py	0.00%	6 Missing ⚠️
client/py/synnax/cli/telem.py	57.14%	6 Missing ⚠️
... and 22 more

Additional details and impacted files

@@            Coverage Diff             @@
##               rc    #1991      +/-   ##
==========================================
- Coverage   53.51%   53.04%   -0.47%     
==========================================
  Files        2406     2413       +7     
  Lines      138508   138433      -75     
  Branches     7106     7102       -4     
==========================================
- Hits        74121    73437     -684     
- Misses      62582    63246     +664     
+ Partials     1805     1750      -55     

Flag	Coverage Δ
alamos-py	83.72% <ø> (ø)
client-py	86.51% <81.40%> (-0.54%)	⬇️
freighter-py	79.47% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[pjdotson]

Approved after last comments are addressed

[pjdotson]

but we seem to use list (without an underscore) for most of the types in here?