Skip to content

Commit

Permalink
Update docs (#242)
Browse files Browse the repository at this point in the history 
Adds pages for: common, s3, eventstream
Did a formatting prettiness pass on the source files
  • Loading branch information
@graebm
graebm authored Feb 24, 2021
1 parent d0a2498 commit 34e68fa
Show file tree
Hide file tree
Showing 62 changed files with 5,034 additions and 16,784 deletions.
36 changes: 20 additions & 16 deletions awscrt/auth.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -115,8 +115,8 @@ class AwsCredentialsProvider(AwsCredentialsProviderBase):
"""
Credentials providers source the AwsCredentials needed to sign an authenticated AWS request.
This class provides `new()` functions for several built-in provider types.
To define a custom provider, use the `new_delegate()` function.
This class provides `new_X()` functions for several built-in provider types.
To define a custom provider, use the :meth:`new_delegate()` function.
"""
__slots__ = ()

Expand Down Expand Up @@ -179,7 +179,7 @@ def new_profile(
loaded from the aws credentials file.
Args:
client_bootstrap: Client bootstrap to use when initiating socket connection.
client_bootstrap (ClientBootstrap): Client bootstrap to use when initiating socket connection.
profile_name (Optional[str]): Name of profile to use.
If not set, uses value from AWS_PROFILE environment variable.
Expand Down Expand Up @@ -212,18 +212,22 @@ def new_process(cls, profile_to_use=None):
The command to run is sourced from a profile in the AWS config file, using the standard
profile selection rules. The profile key the command is read from is "credential_process."
E.g.:
[default]
credential_process=/opt/amazon/bin/my-credential-fetcher --argsA=abc
Example::
[default]
credential_process=/opt/amazon/bin/my-credential-fetcher --argsA=abc
On successfully running the command, the output should be a json data with the following
format:
{
"Version": 1,
"AccessKeyId": "accesskey",
"SecretAccessKey": "secretAccessKey"
"SessionToken": "....",
"Expiration": "2019-05-29T00:21:43Z"
}
format::
{
"Version": 1,
"AccessKeyId": "accesskey",
"SecretAccessKey": "secretAccessKey"
"SessionToken": "....",
"Expiration": "2019-05-29T00:21:43Z"
}
Version here identifies the command output format version.
This provider is not part of the default provider chain.
Expand Down Expand Up @@ -440,7 +444,7 @@ class AwsSigningConfig(NativeResource):
Default is to not add a header.
expiration_in_seconds (Optional[int]): If set, and signature_type is
`HTTP_REQUEST_QUERY_PARAMS`, then signing will add "X-Amz-Expires"
:attr:`AwsSignatureType.HTTP_REQUEST_QUERY_PARAMS`, then signing will add "X-Amz-Expires"
to the query string, equal to the value specified here.
omit_session_token (bool): If set True, the "X-Amz-Security-Token"
Expand Down Expand Up @@ -627,7 +631,7 @@ def signed_body_header_type(self):
@property
def expiration_in_seconds(self):
"""
Optional[int]: If set, and signature_type is `HTTP_REQUEST_QUERY_PARAMS`,
Optional[int]: If set, and signature_type is :attr:`AwsSignatureType.HTTP_REQUEST_QUERY_PARAMS`,
then signing will add "X-Amz-Expires" to the query string, equal to the
value specified here. Otherwise, this is None has no effect.
"""
Expand Down
181 changes: 102 additions & 79 deletions awscrt/awsiot_mqtt_connection_builder.py
View file
Original file line number Diff line number Diff line change
@@ -1,83 +1,89 @@
"""
Builder functions to create a awscrt.mqtt.Connection, configured for use with AWS IoT.
The following arguments are common to all builder functions:
Builder functions to create a :class:`awscrt.mqtt.Connection`, configured for use with AWS IoT Core.
The following keyword arguments are common to all builder functions:
Required Arguments:
Required Keyword Arguments:
endpoint (str): Host name of AWS IoT server.
**endpoint** (`str`): Host name of AWS IoT server.
client_bootstrap (awscrt.io.ClientBootstrap): Client bootstrap used to establish connection.
**client_bootstrap** (:class:`awscrt.io.ClientBootstrap`): Client bootstrap used to establish connection.
client_id (str): ID to place in CONNECT packet. Must be unique across all devices/clients.
**client_id** (`str`): ID to place in CONNECT packet. Must be unique across all devices/clients.
If an ID is already in use, the other client will be disconnected.
Optional Arguments:
Optional Keyword Arguments:
on_connection_interrupted (function): Callback with signature:
(awscrt.mqtt.Connection, awscrt.exceptions.AwsCrtError) -> None
Invoked when the MQTT connection is lost.
The MQTT client will automatically attempt to reconnect.
**on_connection_interrupted** (`Callable`): Callback invoked whenever the MQTT connection is lost.
The MQTT client will automatically attempt to reconnect.
The function should take the following arguments return nothing:
on_connection_resumed (function): Callback with signature:
(awscrt.mqtt.Connection, awscrt.mqtt.ConnectReturnCode, session_present: bool) -> None
Invoked when the MQTT connection is automatically resumed.
* `connection` (:class:`awscrt.mqtt.Connection`): This MQTT Connection.
clean_session (bool): Whether or not to start a clean session with each reconnect.
Default is true, the server will forget all subscriptions with each reconnect.
Set False to request that the server resume an existing session
or start a new session that may be resumed after a connection loss.
The `session_present` bool in the connection callback informs
whether an existing session was successfully resumed.
If an existing session is resumed, the server remembers previous subscriptions
and sends mesages (with QoS1 or higher) that were published while the client was offline.
* `error` (:class:`awscrt.exceptions.AwsCrtError`): Exception which caused connection loss.
reconnect_min_timeout_secs (int): Minimum time to wait between reconnect attempts.
Wait starts at min and doubles with each attempt until max is reached.
* `**kwargs` (dict): Forward-compatibility kwargs.
reconnect_max_timeout_secs (int): Maximum time to wait between reconnect attempts.
Wait starts at min and doubles with each attempt until max is reached.
**on_connection_resumed** (`Callable`): Callback invoked whenever the MQTT connection
is automatically resumed. Function should take the following arguments and return nothing:
keep_alive_secs (int): The keep alive value, in seconds, to send in CONNECT packet.
A PING will automatically be sent at this interval.
The server will assume the connection is lost if no PING is received after 1.5X this value.
Default is 1200sec (20 minutes). This duration must be longer than ping_timeout_ms.
* `connection` (:class:`awscrt.mqtt.Connection`): This MQTT Connection
ping_timeout_ms (int): Milliseconds to wait for ping response before client assumes
the connection is invalid and attempts to reconnect.
Default is 3000ms (3 seconds). This duration must be shorter than keep_alive_secs.
Alternatively, TCP keep-alive may accomplish this in a more efficient (low-power) scenario,
but keep-alive options may not work the same way on every platform and OS version.
* `return_code` (:class:`awscrt.mqtt.ConnectReturnCode`): Connect return
code received from the server.
will (awscrt.mqtt.Will): Will to send with CONNECT packet. The will is
published by the server when its connection to the client
is unexpectedly lost.
* `session_present` (bool): True if resuming existing session. False if new session.
Note that the server has forgotten all previous subscriptions if this is False.
Subscriptions can be re-established via resubscribe_existing_topics().
username (str): Username to connect with.
* `**kwargs` (dict): Forward-compatibility kwargs.
password (str): Password to connect with.
**clean_session** (`bool`): Whether or not to start a clean session with each reconnect.
If True, the server will forget all subscriptions with each reconnect.
Set False to request that the server resume an existing session
or start a new session that may be resumed after a connection loss.
The `session_present` bool in the connection callback informs
whether an existing session was successfully resumed.
If an existing session is resumed, the server remembers previous subscriptions
and sends mesages (with QoS1 or higher) that were published while the client was offline.
port (int): Override default server port.
Default port is 443 if system supports ALPN or websockets are being used.
Otherwise, default port is 8883.
**reconnect_min_timeout_secs** (`int`): Minimum time to wait between reconnect attempts.
Must be <= `reconnect_max_timeout_secs`.
Wait starts at min and doubles with each attempt until max is reached.
**reconnect_max_timeout_secs** (`int`): Maximum time to wait between reconnect attempts.
Must be >= `reconnect_min_timeout_secs`.
Wait starts at min and doubles with each attempt until max is reached.
tcp_connect_timeout_ms (int): Milliseconds to wait for TCP connect response. Default is 5000ms (5 seconds).
**keep_alive_secs** (`int`): The keep alive value, in seconds, to send in CONNECT packet.
A PING will automatically be sent at this interval.
The server will assume the connection is lost if no PING is received after 1.5X this value.
Default is 1200sec (20 minutes). This duration must be longer than ping_timeout_ms.
tcp_keep_alive (bool): Whether to use TCP keep-alive. Default is False. If True, periodically transmit messages
for detecting a disconnected peer.
**ping_timeout_ms** (`int`): Milliseconds to wait for ping response before client assumes
the connection is invalid and attempts to reconnect.
Default is 3000ms (3 seconds). This duration must be shorter than `keep_alive_secs`.
tcp_keep_alive_interval_secs (int): Interval, in seconds, for TCP keep-alive.
**will** (:class:`awscrt.mqtt.Will`): Will to send with CONNECT packet. The will is
published by the server when its connection to the client is unexpectedly lost.
tcp_keep_alive_timeout_secs (int): Timeout, in seconds, for TCP keep-alive.
**username** (`str`): Username to connect with.
tcp_keep_alive_max_probes (int): Number of probes allowed to fail before the connection is considered lost.
**password** (`str`): Password to connect with.
ca_filepath (str): Override default trust store with CA certificates from this PEM formatted file.
**port** (`int`): Override default server port.
Default port is 443 if system supports ALPN or websockets are being used.
Otherwise, default port is 8883.
ca_dirpath (str): Override default trust store with CA certificates loaded from this directory (Unix only).
**tcp_connect_timeout_ms** (`int`): Milliseconds to wait for TCP connect response. Default is 5000ms (5 seconds).
ca_bytes (bytes): Override default trust store with CA certificates from these PEM formatted bytes.
**ca_filepath** (`str`): Override default trust store with CA certificates from this PEM formatted file.
enable_metrics_collection (bool): Whether to send the SDK version number in the CONNECT packet. Default is True.
**ca_dirpath** (`str`): Override default trust store with CA certificates loaded from this directory (Unix only).
**ca_bytes** (`bytes`): Override default trust store with CA certificates from these PEM formatted bytes.
**enable_metrics_collection** (`bool`): Whether to send the SDK version number in the CONNECT packet.
Default is True.
"""

# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
Expand Down Expand Up @@ -184,53 +190,60 @@ def _builder(
)


def mtls_from_path(cert_filepath, pri_key_filepath, **kwargs):
def mtls_from_path(cert_filepath, pri_key_filepath, **kwargs) -> awscrt.mqtt.Connection:
"""
This builder creates an awscrt.mqtt.Connection, configured for an mTLS MQTT connection to AWS IoT.
This builder creates an :class:`awscrt.mqtt.Connection`, configured for an mTLS MQTT connection to AWS IoT.
TLS arguments are passed as filepaths.
Arguments:
This function takes all :mod:`common arguments<awscrt.awsiot_mqtt_connection_builder>`
described at the top of this doc, as well as...
Keyword Args:
cert_filepath (str): Path to certificate file.
pri_key_filepath (str): Path to private key file.
All other required and optional arguments are explained in this module's docs.
"""
_check_required_kwargs(**kwargs)
tls_ctx_options = awscrt.io.TlsContextOptions.create_client_with_mtls_from_path(cert_filepath, pri_key_filepath)
return _builder(tls_ctx_options, **kwargs)


def mtls_from_bytes(cert_bytes, pri_key_bytes, **kwargs):
def mtls_from_bytes(cert_bytes, pri_key_bytes, **kwargs) -> awscrt.mqtt.Connection:
"""
This builder creates an awscrt.mqtt.Connection, configured for an mTLS MQTT connection to AWS IoT.
This builder creates an :class:`awscrt.mqtt.Connection`, configured for an mTLS MQTT connection to AWS IoT.
TLS arguments are passed as in-memory bytes.
Arguments:
cert_bytes (bytes): Certificate file.
This function takes all :mod:`common arguments<awscrt.awsiot_mqtt_connection_builder>`
described at the top of this doc, as well as...
pri_key_bytes (bytes): Private key.
Keyword Args:
cert_bytes (bytes): Certificate file bytes.
All other required and optional arguments are explained in this module's docs.
pri_key_bytes (bytes): Private key bytes.
"""
_check_required_kwargs(**kwargs)
tls_ctx_options = awscrt.io.TlsContextOptions.create_client_with_mtls(cert_bytes, pri_key_bytes)
return _builder(tls_ctx_options, **kwargs)


def websockets_with_default_aws_signing(region, credentials_provider, websocket_proxy_options=None, **kwargs):
def websockets_with_default_aws_signing(
region,
credentials_provider,
websocket_proxy_options=None,
**kwargs) -> awscrt.mqtt.Connection:
"""
This builder creates an awscrt.mqtt.Connection, configured for an MQTT connection over websockets to AWS IoT.
This builder creates an :class:`awscrt.mqtt.Connection`, configured for an MQTT connection over websockets to AWS IoT.
The websocket handshake is signed using credentials from the credentials_provider.
Arguments:
This function takes all :mod:`common arguments<awscrt.awsiot_mqtt_connection_builder>`
described at the top of this doc, as well as...
Keyword Args:
region (str): AWS region to use when signing.
credentials_provider (awscrt.auth.AwsCredentialsProvider): Source of AWS credentials to use when signing.
websocket_proxy_options (awscrt.http.HttpProxyOptions): If specified, a proxy is used when connecting.
All other required and optional arguments are explained in this module's docs.
"""
_check_required_kwargs(**kwargs)

Expand All @@ -254,21 +267,31 @@ def _sign_websocket_handshake_request(transform_args, **kwargs):
return websockets_with_custom_handshake(_sign_websocket_handshake_request, websocket_proxy_options, **kwargs)


def websockets_with_custom_handshake(websocket_handshake_transform, websocket_proxy_options=None, **kwargs):
def websockets_with_custom_handshake(
websocket_handshake_transform,
websocket_proxy_options=None,
**kwargs) -> awscrt.mqtt.Connection:
"""
This builder creates an awscrt.mqtt.Connection, configured for an MQTT connection over websockets,
This builder creates an :class:`awscrt.mqtt.Connection`, configured for an MQTT connection over websockets,
with a custom function to transform the websocket handshake request before it is sent to the server.
Arguments:
websocket_handshake_transform: Function with signature:
(awscrt.mqtt.WebsocketHandshakeTransformArgs) -> None
Function is called each time a websocket connection is attempted.
The function may modify the websocket handshake request, and MUST call set_done() when complete.
See awscrt.mqtt.WebsocketHandshakeTransformArgs for more info.
This function takes all :mod:`common arguments<awscrt.awsiot_mqtt_connection_builder>`
described at the top of this doc, as well as...
websocket_proxy_options (awscrt.http.HttpProxyOptions): If specified, a proxy is used when connecting.
Keyword Args:
websocket_handshake_transform (Callable): Function to transform websocket handshake request.
If provided, function is called each time a websocket connection is attempted.
The function may modify the HTTP request before it is sent to the server.
See :class:`awscrt.mqtt.WebsocketHandshakeTransformArgs` for more info.
Function should take the following arguments and return nothing:
* `transform_args` (:class:`awscrt.mqtt.WebsocketHandshakeTransformArgs`):
Contains HTTP request to be transformed. Function must call
`transform_args.done()` when complete.
All other required and optional arguments are explained in this module's docs.
* `**kwargs` (dict): Forward-compatibility kwargs.
websocket_proxy_options (awscrt.http.HttpProxyOptions): If specified, a proxy is used when connecting.
"""
_check_required_kwargs(**kwargs)
tls_ctx_options = awscrt.io.TlsContextOptions()
Expand Down
Loading

0 comments on commit 34e68fa

Please sign in to comment.