Optimize shell and shell2 method type hints using @overload and Literal

[Copilot]

This PR improves IDE type inference for the shell and shell2 methods by replacing Union return types with precise @overload definitions based on parameter combinations.

Problem

Previously, the shell and shell2 methods used Union return types that made it difficult for IDEs and type checkers to infer the correct return type:

# Before: IDEs couldn't determine the actual return type
def shell(...) -> Union[AdbConnection, str, bytes]:  # Ambiguous!
def shell2(...) -> Union[ShellReturn, ShellReturnRaw]:  # Ambiguous!

# Usage - IDE doesn't know what type result is
result = device.shell("pwd")  # Union[AdbConnection, str, bytes] - not helpful!

Solution

Added precise @overload definitions with Literal types that allow IDEs to understand exactly what type is returned based on the parameters:

# After: IDEs know exactly what type is returned
result1: str = device.shell("pwd")  # ✓ IDE knows this returns str
result2: bytes = device.shell("pwd", encoding=None)  # ✓ IDE knows this returns bytes  
result3: AdbConnection = device.shell("pwd", stream=True)  # ✓ IDE knows this returns AdbConnection

result4: ShellReturn = device.shell2("pwd")  # ✓ IDE knows this returns ShellReturn
result5: ShellReturnRaw = device.shell2("pwd", encoding=None)  # ✓ IDE knows this returns ShellReturnRaw

Implementation Details

• shell method overloads:

  • stream=True → returns AdbConnection
  • stream=False, encoding=None → returns bytes
  • stream=False, encoding=str → returns str
  • Default case → returns str

• shell2 method overloads:

  • encoding=None → returns ShellReturnRaw
  • encoding=str → returns ShellReturn
  • Default case → returns ShellReturn

• Used keyword-only arguments (*) to make overloads more distinct for mypy compatibility

• Added proper imports with fallback to typing_extensions for Python 3.8 support

• Updated abstract interfaces to match the new overload signatures

Benefits

• ✅ IDEs can now autocomplete methods and attributes correctly based on actual return type
• ✅ Type checkers like mypy can catch type errors at development time
• ✅ Better developer experience with precise return type information
• ✅ No more ambiguous Union[ShellReturn, ShellReturnRaw] types
• ✅ Backward compatibility maintained - existing code works unchanged

Testing

• All 18 existing tests pass
• mypy type checking passes on comprehensive test scenarios
• Verified IDE type inference works correctly for common usage patterns

Fixes #193.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[codecov]

Codecov Report

❌ Patch coverage is 56.00000% with 11 lines in your changes missing coverage. Please review.
✅ Project coverage is 34.80%. Comparing base (a19383b) to head (50102dc).
⚠️ Report is 4 commits behind head on master.

Files with missing lines	Patch %	Lines
adbutils/_device_base.py	52.63%	2 Missing and 7 partials ⚠️
adbutils/_interfaces.py	66.66%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #194      +/-   ##
==========================================
+ Coverage   34.64%   34.80%   +0.15%     
==========================================
  Files          17       17              
  Lines        2179     2201      +22     
  Branches      320      327       +7     
==========================================
+ Hits          755      766      +11     
- Misses       1386     1390       +4     
- Partials       38       45       +7     

☔ 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.