Skip to main content

Lightweight Python asyncio HTTP client

Project description

lowhaio CircleCI Test Coverage

A lightweight Python asyncio HTTP/1.1 client. No additional tasks are created; all code is in a single module; and other than the standard library only a single dependency is required, aiodnsresolver

Lowhaio has a deliberately limited scope: it includes just enough code to be a useful HTTP client and allow more complex behaviour to be added on top if required.

Connections are DNS-aware, in that they are only re-used if they match a current A record for the domain.

Installation

pip install lowhaio

Usage

The API is streaming-first: for both request and response bodies, asynchronous iterators are used.

import asyncio
from lowhaio import Pool

async def main():
    request, close = Pool()

    async def request_body():
        yield b'a'
        yield b'bc'

    code, headers, response_body = await request(
        b'POST', 'https://postman-echo.com/post',
        headers=((b'content-length', b'3'), (b'content-type', b'text/plain'),),
        body=request_body,
    )
    async for chunk in response_body:
        print(chunk)

    await close()

loop = asyncio.get_event_loop()
loop.run_until_complete(main())

However, there are helper functions streamed and buffered when this isn't required or possible.

import asyncio
from lowhaio import Pool, streamed, buffered

async def main():
    request, close = Pool()

    request_body = streamed(b'abc')

    code, headers, response_body = await request(
        b'POST', 'https://postman-echo.com/post',
        headers=((b'content-length', b'3'), (b'content-type', b'text/plain'),),
        body=request_body,
    )
    print(await buffered(response_body))

    await close()

loop = asyncio.get_event_loop()
loop.run_until_complete(main())

Headers

The only header automatically added to requests is the host header, which is the idna/punycode-encoded domain name from the requested URL.

Exceptions

Exceptions raised are subclasses of HttpError. If a lower-level exception caused this, it is set in the __cause__ attribute of the HttpError

Exceptions before any data is sent are instances of HttpConnectionError, and after data is sent, HttpDataError. This is to make it possible to know if non-idempotent requests can be retried.

Custom SSL context

Lowhaio can be used with an custom SSL context through through the get_ssl_context parameter to Pool. For example, to use the certifi CA bundle, you can install it by

pip install certifi

and use it as below.

import asyncio
import ssl

import certifi
from lowhaio import Pool, buffered, streamed

async def main():
    request, close = Pool(
        get_ssl_context=lambda: ssl.create_default_context(cafile=certifi.where()),
    )

    request_body = streamed(b'abc')

    code, headers, response_body = await request(
        b'POST', 'https://postman-echo.com/post',
        headers=((b'content-length', b'3'), (b'content-type', b'text/plain'),),
        body=request_body,
    )
    print(await buffered(response_body))

    await close()

loop = asyncio.get_event_loop()
loop.run_until_complete(main())

Scope

The scope of the core functions is restricted to:

  • (TLS) connection opening, closing and pooling;
  • passing and receiving HTTP headers and streaming bodies;
  • decoding chunked responses;
  • raising exceptions on timeouts.

This is to make the core behaviour useful to a reasonable range of uses, but to not include what can be added by layer(s) on top. Specifically not included:

Project details


Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

lowhaio-0.0.80.tar.gz (6.6 kB view details)

Uploaded Source

Built Distribution

lowhaio-0.0.80-py3-none-any.whl (7.4 kB view details)

Uploaded Python 3

File details

Details for the file lowhaio-0.0.80.tar.gz.

File metadata

  • Download URL: lowhaio-0.0.80.tar.gz
  • Upload date:
  • Size: 6.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.12.1 pkginfo/1.4.2 requests/2.22.0 setuptools/40.4.3 requests-toolbelt/0.8.0 tqdm/4.28.1 CPython/3.7.1

File hashes

Hashes for lowhaio-0.0.80.tar.gz
Algorithm Hash digest
SHA256 c1997dd63446d2900f06e72e9a2c2e0d96183f829a8d4ead14c9ad2ac8b183d2
MD5 927b548da7bc0c09da332a2c886ecb59
BLAKE2b-256 fc45f5656105e19c80cfc2750eef633e67f02878f14509ddc0b43a6b47a6422f

See more details on using hashes here.

File details

Details for the file lowhaio-0.0.80-py3-none-any.whl.

File metadata

  • Download URL: lowhaio-0.0.80-py3-none-any.whl
  • Upload date:
  • Size: 7.4 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.12.1 pkginfo/1.4.2 requests/2.22.0 setuptools/40.4.3 requests-toolbelt/0.8.0 tqdm/4.28.1 CPython/3.7.1

File hashes

Hashes for lowhaio-0.0.80-py3-none-any.whl
Algorithm Hash digest
SHA256 23154eae41c026012afdd843f5e197692e2035ff35c12f917382931720c9de8c
MD5 3c79b3ff0659bf4bc10478ed346c0bff
BLAKE2b-256 3f3d57fd31852914da2807988024ccef79f6c2571064921a4333b41bc71eaacd

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page