Designing a Python SDK for Cloud TTS Services: Critique and Refactoring of Volcengine's SDK

Recently the author created a TTS library called Tetos to unify various cloud TTS service APIs, allowing users to switch services by only changing parameters.

The article then critiques Volcengine's Python SDK, pointing out its overly complex inheritance, unnecessary static methods, and convoluted request signing implementation that wraps a custom request object before finally using requests .

Key problematic code from the original SDK is shown, including the class SAMIService(Service) definition, the common_json_handler() method that manually serialises JSON, and the json() method that builds a signed request via SignerV4.sign() .

To simplify, the author suggests extracting the signing logic into a standalone function and using standard requests calls directly, e.g., res = requests.post(url, json=body) .

Two refactoring approaches are discussed: overriding Session.send() in a custom VolcSession to inject signatures, and a more elegant solution using requests.auth.AuthBase to create a VolcAuth class that adds the signature in its __call__ method.

Example implementation of VolcAuth is provided, showing how to initialise it with service_info and credentials and then use it in requests: auth = VolcAuth(service_info, credentials); res = requests.post(url, json=body, auth=auth) .

The author also mentions a similar implementation for the httpx library and compares the line count reduction achieved by using the library's extension points instead of duplicating large code bases.

In conclusion, the article argues that the SDK appears to be a direct translation from another language, and recommends minimal invasive modifications that leverage existing extension mechanisms like AuthBase for cleaner, more maintainable backend code.