awscrt.http¶

HTTP

All network operations in awscrt.http are asynchronous.

class awscrt.http.HttpVersion(value)¶

HTTP protocol version enumeration

Unknown = 0¶: Unknown

Http1_0 = 1¶: HTTP/1.0

Http1_1 = 2¶: HTTP/1.1

Http2 = 3¶: HTTP/2

class awscrt.http.HttpClientConnection¶

An HTTP client connection.

Use HttpClientConnection.new() to establish a new connection.

classmethod new(host_name, port, bootstrap=None, socket_options=None, tls_connection_options=None, proxy_options=None)¶

Asynchronously establish a new HttpClientConnection.

Parameters:

host_name (str) – Connect to host.
port (int) – Connect to port.
bootstrap (Optional [ClientBootstrap]) – Client bootstrap to use when initiating socket connection. If None is provided, the default singleton is used.
socket_options (Optional[SocketOptions]) – Optional socket options. If None is provided, then default options are used.
tls_connection_options (Optional[TlsConnectionOptions]) – Optional TLS connection options. If None is provided, then the connection will be attempted over plain-text.
proxy_options (Optional[HttpProxyOptions]) – Optional proxy options. If None is provided then a proxy is not used.

Returns:

concurrent.futures.Future – A Future which completes when connection succeeds or fails. If successful, the Future will contain a new HttpClientConnection. Otherwise, it will contain an exception.

property host_name¶: Remote hostname

property port¶: Remote port

request(request, on_response=None, on_body=None)¶

Create HttpClientStream to carry out the request/response exchange.

NOTE: The HTTP stream sends no data until HttpClientStream.activate() is called. Call activate() when you’re ready for callbacks and events to fire.

Parameters:

request (HttpRequest) – Definition for outgoing request.
on_response –
Optional callback invoked once main response headers are received. The function should take the following arguments and return nothing:
- http_stream (HttpClientStream): HTTP stream carrying out this request/response exchange.
- status_code (int): Response status code.
- headers (List[Tuple[str, str]]): Response headers as a list of (name,value) pairs.
- **kwargs (dict): Forward compatibility kwargs.
An exception raise by this function will cause the HTTP stream to end in error. This callback is always invoked on the connection’s event-loop thread.
on_body –
Optional callback invoked 0+ times as response body data is received. The function should take the following arguments and return nothing:
- http_stream (HttpClientStream): HTTP stream carrying out this request/response exchange.
- chunk (buffer): Response body data (not necessarily a whole “chunk” of chunked encoding).
- **kwargs (dict): Forward-compatibility kwargs.
An exception raise by this function will cause the HTTP stream to end in error. This callback is always invoked on the connection’s event-loop thread.

Returns:

HttpClientStream

close()¶

Close the connection.

Shutdown is asynchronous. This call has no effect if the connection is already closing.

Returns:: concurrent.futures.Future – This connection’s shutdown_future, which completes when shutdown has finished.

is_open()¶

Returns:: bool – True if this connection is open and usable, False otherwise. Check shutdown_future to know when the connection is completely finished shutting down.

property shutdown_future¶

Completes when this connection has finished shutting down. Future will contain a result of None, or an exception indicating why shutdown occurred. Note that the connection may have been garbage-collected before this future completes.

Type:: concurrent.futures.Future

property version¶

Protocol used by this connection

Type:: HttpVersion

class awscrt.http.HttpClientStream(connection, request, on_response=None, on_body=None)¶

HTTP stream that sends a request and receives a response.

Create an HttpClientStream with HttpClientConnection.request().

NOTE: The HTTP stream sends no data until HttpClientStream.activate() is called. Call activate() when you’re ready for callbacks and events to fire.

connection¶

This stream’s connection.

Type:: HttpClientConnection

completion_future¶

Future that will contain the response status code (int) when the request/response exchange completes. If the exchange fails to complete, the Future will contain an exception indicating why it failed.

Type:: concurrent.futures.Future

property response_status_code¶

The response status code.

This is None until a response arrives.

Type:: int

activate()¶

Begin sending the request.

The HTTP stream does nothing until this is called. Call activate() when you are ready for its callbacks and events to fire.

class awscrt.http.HttpRequest(method='GET', path='/', headers=None, body_stream=None)¶

Definition for an outgoing HTTP request.

The request may be transformed (ex: signing the request) before its data is eventually sent.

Parameters:

method (str) – HTTP request method (verb). Default value is “GET”.
path (str) – HTTP path-and-query value. Default value is “/”.
headers (Optional[HttpHeaders]) – Optional headers. If None specified, an empty HttpHeaders is created.
body_stream (Optional[Union[InputStream, io.IOBase]]) – Optional body as binary stream.

property method¶

HTTP request method (verb).

Type:: str

property path¶

HTTP path-and-query value.

Type:: str

property headers¶

Headers to send.

Type:: HttpHeaders

class awscrt.http.HttpHeaders(name_value_pairs=None)¶

Collection of HTTP headers.

A given header name may have multiple values. Header names are always treated in a case-insensitive manner. HttpHeaders can be iterated over as (name,value) pairs.

Parameters:: name_value_pairs (Optional[List[Tuple[str, str]]]) – Construct from a collection of (name,value) pairs.

add(name, value)¶

Add a name-value pair.

Parameters:

name (str) – Name.
value (str) – Value.

add_pairs(name_value_pairs)¶

Add list of (name,value) pairs.

Parameters:: name_value_pairs (List[Tuple[str, str]]) – List of (name,value) pairs.

set(name, value)¶

Set a name-value pair, any existing values for the name are removed.

Parameters:

name (str) – Name.
value (str) – Value.

get_values(name)¶

Return an iterator over the values for this name.

Parameters:: name (str) – Name.
Returns:: Iterator[Tuple[str, str]]

get(name, default=None)¶

Get the first value for this name, ignoring any additional values. Returns default if no values exist.

Parameters:

name (str) – Name.
default (Optional[str]) – If name not found, this value is returned. Defaults to None.

Returns:

str

remove(name)¶

Remove all values for this name. Raises a KeyError if name not found.

Parameters:: name (str) – Header name.

remove_value(name, value)¶

Remove a specific value for this name. Raises a ValueError if value not found.

Parameters:

name (str) – Name.
value (str) – Value.

clear()¶: Clear all headers.

class awscrt.http.HttpProxyConnectionType(value)¶

Proxy connection type enumeration

Legacy = 0¶

Use the old connection establishment logic that would use:

Forwarding if not using TLS
Tunneling if using TLS

Forwarding = 1¶

Establish a request forwarding connection to the proxy.

In this case, TLS is not a valid option.

Tunneling = 2¶: Establish a tunneling connection through the proxy to the ultimate endpoint.

class awscrt.http.HttpProxyAuthenticationType(value)¶

Proxy authentication type enumeration.

Nothing = 0¶: No authentication

Basic = 1¶: Username and password

class awscrt.http.HttpProxyOptions(host_name, port, tls_connection_options=None, auth_type=HttpProxyAuthenticationType.Nothing, auth_username=None, auth_password=None, connection_type=HttpProxyConnectionType.Legacy)¶

Proxy options for HTTP clients.

Parameters:

host_name (str) – Name of the proxy server to connect through.
port (int) – Port number of the proxy server to connect through.
tls_connection_options (Optional[TlsConnectionOptions]) – Optional TlsConnectionOptions for the Local to Proxy connection. Must be distinct from the TlsConnectionOptions provided to the HTTP connection.
auth_type (HttpProxyAuthenticationType) – Type of proxy authentication to use. Default is HttpProxyAuthenticationType.Nothing.
auth_username (Optional[str]) – Username to use when auth_type is HttpProxyAuthenticationType.Basic.
auth_password (Optional[str]) – Username to use when auth_type is HttpProxyAuthenticationType.Basic.
connection_type (Optional[HttpProxyConnectionType) – Type of proxy connection to make. Default is HttpProxyConnectionType.Legacy.