Missing Type Annotations/Stubs (.pyi files) for xero-python SDK #180
Description
Problem
The xero-python SDK lacks proper type annotations and stub files (.pyi), causing issues with static type checkers, IDE autocompletion, and making it difficult to use the SDK with modern Python development practices.
Impact
Without proper type hints:
- IDE autocompletion fails to suggest available methods/properties
- Static type checkers (mypy, pyright) report false errors
- SDK method signatures are unclear (esp. OAuth2Token and OAuth2 classes)
- Developers must use defensive programming with
hasattr()checks
Value Proposition
Adding type stubs would:
- Improve developer experience with better IDE integration
- Reduce runtime errors by catching type-related issues early
- Make API changes more visible and less breaking
- Reduce need for defensive programming patterns
Related Issues
Would help resolve:
- Unable to proceed with TypeError: update_token() argument after ** must be a mapping, not str #72 (TypeError in update_token arguments)
- to_dict generates non serializable object because of enums #93 (Non-serializable objects from to_dict)
- Option for get_invoice_as_pdf to return the PDF as bytes #55 (PDF return type ambiguity)
- refresh_oauth2_token silently fails if can_refresh_access_token fails type validation #68 (Refresh token validation issues)
- Breaking changes due to param ordering #142 (Breaking changes due to param ordering)
Proposed Solution
Add proper type annotations to the SDK or provide separate stub files (.pyi) that define the public API interface with appropriate types.