Skip to content

AscenderTeam/ascender-httpclient

Repository files navigation

Ascender HTTP Client (aschttp)

ascender-httpclient (aschttp) is a powerful and extendable HTTP client for the Ascender Framework. It supports synchronous, asynchronous, and streaming HTTP requests with clean dependency injection, interceptors, and multi-instance configurations.

Features

  • Dependency Injection: Easily inject HTTPClient into any service.
  • Interceptor Support: Create and manage interceptors to customize request handling.
  • Multiple HTTPClient Instances: Use custom HTTP client classes alongside the default singleton.
  • Async and Streaming Requests: Built-in support for asynchronous and streaming HTTP requests.
  • Command Line Integration: Generate interceptors with a simple CLI command.

Installation

To install the package, in your project type:

poetry add ascender-httpclient

Ensure that the Ascender Framework is installed and properly configured.


Initialization

To initialize aschttp, configure ProvideHTTPClient() in your bootstrap.py:

...
from aschttp import ProvideHTTPClient

appBootstrap: IBootstrap = {
    "providers": [
        DatabaseProvider(ORMEnum.SQLALCHEMY, DATABASE_CONNECTION),
        ProvideControllers([
            ControllersModule
        ]),
        ProvideHTTPClient()
    ]
}

Usage

Injecting HTTPClient

To inject the HTTP client into any service:

from ascender.common import Injectable
from ascender.contrib.services import Service
from aschttp import HTTPClient

@Injectable()
class MainService(Service):
    def __init__(self, http: HTTPClient):
        self.http = http

Making Requests

GET Request

from controllers.dtos.test_dto import TestDTO

@Injectable()
class MainService(Service):
    def __init__(self, http: HTTPClient):
        self.http = http
    
    async def make_get_request(self):
        response = await self.http.get(TestDTO, url="http://api.example.com/get")
        assert isinstance(response, TestDTO)
        return response

POST Request

from controllers.dtos.test_dto import TestDTO

@Injectable()
class MainService(Service):
    def __init__(self, http: HTTPClient):
        self.http = http
    
    async def make_post_request(self, dto: TestDTO):
        response = await self.http.post(str, url="http://api.example.com/post", content=dto)
        assert isinstance(response, str)
        return response

Streaming Request

@Injectable()
class MainService(Service):
    def __init__(self, http: HTTPClient):
        self.http = http
    
    def make_streaming_request(self):
        self.http.stream(str, method="GET", url="http://api.example.com/stream").subscribe(
            on_next=lambda r: print(r),
            on_error=lambda err: print(err)
        )

Custom HTTP Clients

To use multiple HTTP client instances:

  1. Define a custom HTTP client class:
from aschttp import HTTPClient

class MyHTTP(HTTPClient):
    pass
  1. Register the custom HTTP client in bootstrap.py:
from myclient import MyHTTP

appBootstrap: IBootstrap = {
    "providers": [
        ProvideHTTPClient(),
        ProvideHTTPClient(client_instance=MyHTTP)
    ]
}

Interceptors

Interceptors allow you to modify HTTP requests before they are sent.

Generate an Interceptor

Use the Ascender CLI to generate an interceptor:

ascender run aschttp:generate interceptor interceptors/custom

Output:

$ CREATE interceptors/custom_interceptor.py (164 bytes)

Implementing an Interceptor

Example custom interceptor:

from httpx import Request
from aschttp.types.interceptors import Interceptor

class CustomInterceptor(Interceptor):
    def __init__(self) -> None:  # for dependency injection, REQUIRED
        pass

    async def handle_request(self, request: Request) -> Request:
        # Modify the request here...
        print("custom interceptor works!")
        return request

Registering an Interceptor

Register the interceptor in bootstrap.py:

from processes.custom_interceptor import MyInterceptor

appBootstrap: IBootstrap = {
    "providers": [
        ProvideHTTPClient(interceptors=[
            MyInterceptor
        ])
    ]
}

Key Concepts

Singleton HTTPClient

The HTTPClient is a singleton by default, ensuring a single instance throughout the framework. However, you can register multiple clients using the ProvideHTTPClient factory, all you need is to change it's client_instance parameter into your custom, example provided in Custom HTTP Clients section.

Interceptors

Interceptors allow request modification before sending. Use them for:

  • Adding headers
  • Logging requests
  • Transforming request payloads

Streaming

The stream() method uses an observable pattern to handle streaming responses efficiently utilizing RxPY.


Command Reference

Generate Interceptor

ascender run aschttp:generate interceptor <path/to/interceptor>

Examples Repository

Find more examples and best practices in the official Ascender Framework examples repository.


Contribution

Contributions are welcome! Submit issues, feature requests, or pull requests via GitHub.


License

The ascender-httpclient package is licensed under the MIT License.

About

Main HTTP client module for the Ascender Framework

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages