Metadata-Version: 2.1
Name: http-toolkit
Version: 0.dev0
Summary: Library for creating HTTP clients to various services with flexible transport customization
Author-email: Kontur <python@skbkontur.ru>
Project-URL: homepage, https://github.com/skbkontur/http_toolkit
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Framework :: AsyncIO
Classifier: Framework :: tox
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: System :: Networking
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: <3.14,>=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx~=0.24.1
Provides-Extra: instruments
Requires-Dist: httpx~=0.24.1; extra == "instruments"
Provides-Extra: test
Requires-Dist: pytest==7.0.0; extra == "test"
Requires-Dist: pytest-cov==3.0.0; extra == "test"
Requires-Dist: testfixtures==6.18.3; extra == "test"
Requires-Dist: pytest-asyncio==0.18.3; extra == "test"
Requires-Dist: pytest-httpx==0.22.0; extra == "test"

# http_toolkit
The httptoolkit library is a tool for working with HTTP requests in Python that allows you to easily create, customize, and send requests to various services. It provides a simple interface for working with HTTP clients. The library also allows flexible transport customization and abstraction from a particular implementation of HTTP clients.

## HTTPXService

If you don't need to use a configured transport, use HTTPXService (for async -> AsyncHttpxService)

```python
from httptoolkit import HttpxService
from httptoolkit import Header

headers = (
    Header(name="My-Header", value="my-value", is_sensitive=False),
)
httpbin = HttpxService("http://httpbin.org", headers=headers)
httpbin.get("/get")
httpbin.post("/post")
```

## Service

If you want to use a configured transport, use Service. (Service -> HttpxTransport, AsyncService -> AsyncHttpxTransport)
```python
### Sync

from httptoolkit import Service, Header
from httptoolkit.transport import HttpxTransport


class DummyService(Service):
    pass


DummyService(
    headers=(Header(name="ServiceHeader", value="service-header", is_sensitive=False),),
    transport=HttpxTransport(base_url="https://example.com:4321", proxies={"http://": "http://10.10.1.10:3128"}),
    ## base_url in this case is passed to transport
)
```

```python
### Async

from httptoolkit import AsyncService, Header
from httptoolkit.transport import AsyncHttpxTransport


class DummyService(AsyncService):
    pass


DummyService(
    headers=(Header(name="ServiceHeader", value="service-header", is_sensitive=False),),
    transport=AsyncHttpxTransport(base_url="https://example.com:4321", proxies={"http://": "http://10.10.1.10:3128"}),
    ## base_url in this case is passed to transport
)
```

### Sending a request

```python

from httptoolkit import Service, Header, HttpMethod
from httptoolkit.transport import HttpxTransport
from httptoolkit.request import Request


class DummyService(Service):
    pass


service = DummyService(
    headers=(Header(name="ServiceHeader", value="service-header", is_sensitive=False),),
    transport=HttpxTransport(base_url="https://example.com:4321", proxies={"http://": "http://10.10.1.10:3128"}),
    ## base_url in this case is passed to transport
)

# By method
service.post(
    path="/somewhere",
    headers=(Header(name="SuperSecret", value="big_secret", is_sensitive=True, create_mask=lambda value: value[-4:]),),
    params={"over": "the rainbow"},
    body="Something",
)

# By request
service.request(Request(method=HttpMethod.POST, body="Request", params={}, path=""))
```

### Sending JSON and multipart-files

```python
from httptoolkit import Service, Header
from httptoolkit.transport import HttpxTransport


class DummyService(Service):
    pass


service = DummyService(
    headers=(Header(name="ServiceHeader", value="service-header", is_sensitive=False),),
    transport=HttpxTransport(base_url="https://example.com:4321", proxies={"http://": "http://10.10.1.10:3128"}),
    ## base_url in this case is passed to transport
)

# Send JSON (json_encoder is the default, but can be changed in transport)
# Do not send with body and files
service.post(
    path="/somewhere",
    headers=(Header(name="SuperSecret", value="big_secret", is_sensitive=True, create_mask=lambda value: value[-4:]),),
    params={"over": "the rainbow"},
    json={
        "param1": 1,
        "param2": 2,
    },
)

# Send multipart-files in the format Dict[str, Union[BinaryIO, Tuple[str, BinaryIO, str]]]
# Can be sent with body, but cannot be sent with json
service.post(
    path="/somewhere",
    headers=(Header(name="SuperSecret", value="big_secret", is_sensitive=True, create_mask=lambda value: value[-4:]),),
    params={"over": "the rainbow"},
    files={"upload-file": open("report.xls", "rb")},
    # different format files = {'upload-file': ('report.xls', open('report.xls', 'rb'), 'application/vnd.ms-excel')} 
)
```

## The name of the library logger

httptoolkit

## Default logging level

logging.INFO

## Example of logging settings

```python
import logging
import httptoolkit

logging.basicConfig(level="INFO")


class MyService(httptoolkit.HttpxService):
    def test(self):
        self.get("/")


service = MyService("https://test.ru")

service.test()
```
## Output
```python
INFO:httptoolkit.transport._sync:Sending GET https://test.ru/
```

All about Transport
- [HttpxTransport](https://github.com/skbkontur/http_toolkit/tree/master/docs/TRANSPORT.md#transport)
- [Creating your own Transport](https://github.com/skbkontur/http_toolkit/tree/master/docs/TRANSPORT.md#custom-transport)

OpenTelemetry
Allows using [OpenTelemetry HTTPX](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-httpx) to add request tracing via [http_toolkit](https://github.com/skbkontur/http_toolkit) in case [HttpxTransport](https://github.com/skbkontur/http_toolkit/tree/master/docs/TRANSPORT.md#transport) is used.
