smithy-core
HostType
¶
Bases: Enum
Enumeration of possible host types.
Source code in packages/smithy-core/src/smithy_core/__init__.py
DOMAIN = 'DOMAIN'
class-attribute
instance-attribute
¶
Host type is a domain name.
IPv4 = 'IPv4'
class-attribute
instance-attribute
¶
Host is an IPv4 address.
IPv6 = 'IPv6'
class-attribute
instance-attribute
¶
Host is an IPv6 address.
UNKNOWN = 'UNKNOWN'
class-attribute
instance-attribute
¶
Host type is unknown.
URI
dataclass
¶
Bases: URI
Universal Resource Identifier, target location for a :py:class:HTTPRequest
.
Source code in packages/smithy-core/src/smithy_core/__init__.py
30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 |
|
fragment = None
class-attribute
instance-attribute
¶
Part of the URI specification, but may not be transmitted by a client.
host
instance-attribute
¶
The hostname, for example amazonaws.com
.
host_type
property
¶
Return the type of host.
netloc
property
¶
Construct netloc string in format {username}:{password}@{host}:{port}
username
, password
, and port
are only included if set. password
is ignored, unless username
is also set. Add square brackets around the host
if it is a valid IPv6 endpoint URI per :rfc:3986#section-3.2.2
.
password = None
class-attribute
instance-attribute
¶
Password part of the userinfo URI component.
path = None
class-attribute
instance-attribute
¶
Path component of the URI.
port = None
class-attribute
instance-attribute
¶
An explicit port number.
query = None
class-attribute
instance-attribute
¶
Query component of the URI as string.
scheme = 'https'
class-attribute
instance-attribute
¶
For example http
or https
.
username = None
class-attribute
instance-attribute
¶
Username part of the userinfo URI component.
__post_init__()
¶
Validate host component.
build()
¶
Construct URI string representation.
Validate host. Returns a string of the form
{scheme}://{username}:{password}@{host}:{port}{path}?{query}#{fragment}
Source code in packages/smithy-core/src/smithy_core/__init__.py
aio
¶
client
¶
ClientCall
dataclass
¶
A data class containing all the initial information about an operation invocation.
Source code in packages/smithy-core/src/smithy_core/aio/client.py
auth_scheme_resolver
instance-attribute
¶
The auth scheme resolver for the operation.
context
instance-attribute
¶
The initial context of the operation.
endpoint_resolver
instance-attribute
¶
The endpoint resolver for the operation.
input
instance-attribute
¶
The input of the operation.
interceptor
instance-attribute
¶
The interceptor to use in the course of the operation invocation.
This SHOULD be an InterceptorChain.
operation = field(repr=False)
class-attribute
instance-attribute
¶
The schema of the operation.
retry_scope = None
class-attribute
instance-attribute
¶
The retry scope for the operation.
retry_strategy
instance-attribute
¶
The retry strategy to use for the operation.
supported_auth_schemes
instance-attribute
¶
The supported auth schemes for the operation.
RequestPipeline
¶
Invokes client operations asynchronously.
Source code in packages/smithy-core/src/smithy_core/aio/client.py
91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 |
|
protocol = protocol
instance-attribute
¶
The protocol to use to serialize the request and deserialize the response.
transport = transport
instance-attribute
¶
The transport to use to send the request and receive the response (e.g. an HTTP Client).
__call__(call)
async
¶
Invoke an operation asynchronously.
:param call: The operation to invoke and associated context.
Source code in packages/smithy-core/src/smithy_core/aio/client.py
duplex_stream(call, input_event_type, output_event_type, event_deserializer)
async
¶
Invoke an input stream operation asynchronously.
:param call: The operation to invoke and associated context. :param input_event_type: The event type to send in the input stream. :param output_event_type: The event type to receive in the output stream. :param event_deserializer: The method used to deserialize events.
Source code in packages/smithy-core/src/smithy_core/aio/client.py
input_stream(call, event_type)
async
¶
Invoke an input stream operation asynchronously.
:param call: The operation to invoke and associated context. :param event_type: The event type to send in the input stream.
Source code in packages/smithy-core/src/smithy_core/aio/client.py
output_stream(call, event_type, event_deserializer)
async
¶
Invoke an input stream operation asynchronously.
:param call: The operation to invoke and associated context. :param event_type: The event type to receive in the output stream. :param event_deserializer: The method used to deserialize events.
Source code in packages/smithy-core/src/smithy_core/aio/client.py
endpoints
¶
StaticEndpointResolver
¶
Bases: EndpointResolver
A basic endpoint resolver that forwards a static URI.
Source code in packages/smithy-core/src/smithy_core/aio/endpoints.py
eventstream
¶
DuplexEventStream
¶
An event stream that both sends and receives messages.
To ensure that streams are closed upon exiting, this class may be used as an async context manager.
.. code-block:: python
async def main():
client = ChatClient()
input = StreamMessagesInput(chat_room="aws-python-sdk", username="hunter7")
async with client.stream_messages(input=input) as stream:
stream.input_stream.send(
MessageStreamMessage("Chat logger starting up.")
)
response_task = asyncio.create_task(handle_output(stream))
stream.input_stream.send(MessageStreamMessage("Chat logger active."))
await response_handler
async def handle_output(stream: EventStream) -> None:
_, output_stream = await stream.await_output()
async for event in output_stream:
match event:
case MessageStreamMessage():
print(event.value)
case MessageStreamShutdown():
return
case _:
stream.input_stream.send(
MessageStreamMessage(
"Unknown message type received. Shutting down."
)
)
return
Source code in packages/smithy-core/src/smithy_core/aio/eventstream.py
11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 |
|
input_stream = input_stream
instance-attribute
¶
An event stream that sends events to the service.
output = None
class-attribute
instance-attribute
¶
The initial response from the service.
This value may be None until await_output
has been called.
This may include context necessary to interpret output events or prepare input events. It will always be available before any events.
output_stream = None
class-attribute
instance-attribute
¶
An event stream that receives events from the service.
This value may be None until await_output
has been called.
This value will also be None if the operation has no output stream.
await_output()
async
¶
Await the operation's output.
The EventStream will be returned as soon as the input stream is ready to receive events, which may be before the initial response has been received and the service is ready to send events.
Awaiting this method will wait until the initial response was received and the
service is ready to send events. The initial response and output stream will
be returned by this operation and also cached in response
and
output_stream
, respectively.
The default implementation of this method performs the caching behavior,
delegating to the abstract _await_output
method to actually retrieve the
initial response and output stream.
:returns: A tuple containing the initial response and output stream. If the operation has no output stream, the second value will be None.
Source code in packages/smithy-core/src/smithy_core/aio/eventstream.py
close()
async
¶
Closes the event stream.
This closes both the input and output streams.
Source code in packages/smithy-core/src/smithy_core/aio/eventstream.py
InputEventStream
¶
An event stream that streams messages to the service.
To ensure that streams are closed upon exiting, this class may be used as an async context manager.
.. code-block:: python
async def main():
client = ChatClient()
input = PublishMessagesInput(chat_room="aws-python-sdk", username="hunter7")
async with client.publish_messages(input=input) as stream:
stream.input_stream.send(
MessageStreamMessage("High severity ticket alert!")
)
await stream.await_output()
Source code in packages/smithy-core/src/smithy_core/aio/eventstream.py
input_stream = input_stream
instance-attribute
¶
An event stream that sends events to the service.
output = None
class-attribute
instance-attribute
¶
The initial response from the service.
This value may be None until await_output
has been called.
This may include context necessary to interpret output events or prepare input events. It will always be available before any events.
await_output()
async
¶
Await the operation's initial response.
The EventStream will be returned as soon as the input stream is ready to receive events, which may be before the initial response has been received and the service is ready to send events.
Awaiting this method will wait until the initial response was received.
:returns: The service's initial response.
Source code in packages/smithy-core/src/smithy_core/aio/eventstream.py
OutputEventStream
¶
An event stream that streams messages from the service.
To ensure that streams are closed upon exiting, this class may be used as an async context manager.
.. code-block:: python
async def main():
client = ChatClient()
input = ReceiveMessagesInput(chat_room="aws-python-sdk")
async with client.receive_messages(input=input) as stream:
async for event in stream.output_stream:
match event:
case MessageStreamMessage():
print(event.value)
case _:
return
Source code in packages/smithy-core/src/smithy_core/aio/eventstream.py
output = output
instance-attribute
¶
The initial response from the service.
This may include context necessary to interpret output events or prepare input events. It will always be available before any events.
output_stream = output_stream
instance-attribute
¶
An event stream that receives events from the service.
This value will also be None if the operation has no output stream.
identity
¶
ChainedIdentityResolver
¶
Bases: CachingIdentityResolver[I, IP]
Attempts to resolve an identity by checking a sequence of sub-resolvers.
If a nested resolver raises a :py:class:SmithyIdentityError
, the next
resolver in the chain will be attempted.
Source code in packages/smithy-core/src/smithy_core/aio/identity.py
__init__(resolvers)
¶
Construct a ChainedIdentityResolver.
:param resolvers: The sequence of resolvers to resolve identity from.
Source code in packages/smithy-core/src/smithy_core/aio/identity.py
interfaces
¶
AsyncByteStream
¶
Bases: Protocol
A file-like object with an async read method.
Source code in packages/smithy-core/src/smithy_core/aio/interfaces/__init__.py
AsyncWriter
¶
ClientProtocol
¶
Bases: Protocol
A protocol used by a client to communicate with a server.
Source code in packages/smithy-core/src/smithy_core/aio/interfaces/__init__.py
96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 |
|
id
property
¶
The ID of the protocol.
create_event_publisher(*, operation, request, event_type, context, auth_scheme=None)
¶
Creates an event publisher for a protocol event stream.
:param operation: The event stream operation. :param request: The transport request that was sent for this stream. :param event_type: The type of event to publish. :param context: A context bag for the request. :param auth_scheme: The optional auth scheme used to sign events.
Source code in packages/smithy-core/src/smithy_core/aio/interfaces/__init__.py
create_event_receiver(*, operation, request, response, event_type, event_deserializer, context)
¶
Creates an event receiver for a protocol event stream.
:param operation: The event stream operation. :param request: The transport request that was sent for this stream. :param response: The transport response that was received for this stream. :param event_type: The type of event to publish. :param event_deserializer: The deserializer to be used to deserialize events. :param context: A context bag for the request.
Source code in packages/smithy-core/src/smithy_core/aio/interfaces/__init__.py
deserialize_response(*, operation, request, response, error_registry, context)
async
¶
Deserializes the output from the tranport response or throws an exception.
:param operation: The operation whose response is being deserialized. :param request: The transport request that was sent for this response. :param response: The response to deserialize. :param error_registry: A TypeRegistry used to deserialize errors. :param context: A context bag for the request.
Source code in packages/smithy-core/src/smithy_core/aio/interfaces/__init__.py
serialize_request(*, operation, input, endpoint, context)
¶
Serialize an operation input into a transport request.
:param operation: The operation whose request is being serialized. :param input: The input shape to be serialized. :param endpoint: The base endpoint to serialize. :param context: A context bag for the request.
Source code in packages/smithy-core/src/smithy_core/aio/interfaces/__init__.py
set_service_endpoint(*, request, endpoint)
¶
Update the endpoint of a transport request.
:param request: The request whose endpoint should be updated. :param endpoint: The endpoint to set on the request.
Source code in packages/smithy-core/src/smithy_core/aio/interfaces/__init__.py
ClientTransport
¶
Bases: Protocol
Protocol-agnostic representation of a client tranport (e.g. an HTTP client).
Source code in packages/smithy-core/src/smithy_core/aio/interfaces/__init__.py
EndpointResolver
¶
Bases: Protocol
Resolves an operation's endpoint based given parameters.
Source code in packages/smithy-core/src/smithy_core/aio/interfaces/__init__.py
resolve_endpoint(params)
async
¶
Resolve an endpoint for the given operation.
:param params: The parameters available to resolve the endpoint.
Request
¶
Bases: Protocol
Protocol-agnostic representation of a request.
Source code in packages/smithy-core/src/smithy_core/aio/interfaces/__init__.py
Response
¶
Bases: Protocol
Protocol-agnostic representation of a response.
Source code in packages/smithy-core/src/smithy_core/aio/interfaces/__init__.py
auth
¶
AuthScheme
¶
Bases: Protocol
A class that coordinates identity and auth.
Source code in packages/smithy-core/src/smithy_core/aio/interfaces/auth.py
scheme_id
instance-attribute
¶
The ID of the auth scheme.
event_signer(*, request)
¶
Construct a signer for event stream events.
:param request: The request that will initiate the event stream. The request will not have been sent when this method is called. :returns: An event signer if the scheme supports signing events, otherwise None.
Source code in packages/smithy-core/src/smithy_core/aio/interfaces/auth.py
identity_properties(*, context)
¶
Construct identity properties from the request context.
The context will always include the client's config under "config". Other
properties may be added by :py:class:smithy_core.interceptors.Interceptor
s.
:param context: The context of the request.
Source code in packages/smithy-core/src/smithy_core/aio/interfaces/auth.py
identity_resolver(*, context)
¶
Get an identity resolver for the request.
The context will always include the client's config under "config". Other
properties may be added by :py:class:smithy_core.interceptors.Interceptor
s.
:param context: The context of the request.
Source code in packages/smithy-core/src/smithy_core/aio/interfaces/auth.py
signer()
¶
signer_properties(*, context)
¶
Construct signer properties from the request context.
The context will always include the client's config under "config". Other
properties may be added by :py:class:smithy_core.interceptors.Interceptor
s.
:param context: The context of the request.
Source code in packages/smithy-core/src/smithy_core/aio/interfaces/auth.py
EventSigner
¶
Bases: Protocol
A class that signs requests before they are sent.
Source code in packages/smithy-core/src/smithy_core/aio/interfaces/auth.py
sign(*, event, identity, properties)
async
¶
Get a signed version of the event.
:param event: The event to be signed.
Signer
¶
Bases: Protocol
A class that signs requests before they are sent.
Source code in packages/smithy-core/src/smithy_core/aio/interfaces/auth.py
sign(*, request, identity, properties)
async
¶
Get a signed version of the request.
:param request: The request to be signed. :param identity: The identity to use to sign the request. :param properties: Additional properties used to sign the request.
Source code in packages/smithy-core/src/smithy_core/aio/interfaces/auth.py
eventstream
¶
EventPublisher
¶
Bases: Protocol
Asynchronously sends events to a service.
This may be used as a context manager to ensure the stream is closed before exiting.
Source code in packages/smithy-core/src/smithy_core/aio/interfaces/eventstream.py
close()
async
¶
EventReceiver
¶
Bases: Protocol
Asynchronously receives events from a service.
Events may be received via the receive
method or by using this class as
an async iterable.
This may also be used as a context manager to ensure the stream is closed before exiting.
Source code in packages/smithy-core/src/smithy_core/aio/interfaces/eventstream.py
identity
¶
IdentityResolver
¶
Bases: Protocol
Used to load a user's Identity
from a given source.
Each Identity
may have one or more resolver implementations.
Source code in packages/smithy-core/src/smithy_core/aio/interfaces/identity.py
get_identity(*, properties)
async
¶
Load the user's identity from this resolver.
:param properties: Properties used to help determine the identity to return.
types
¶
AsyncBytesProvider
¶
A buffer that allows chunks of bytes to be exchanged asynchronously.
Bytes are written in chunks to an internal buffer, that is then drained via an async iterator.
Source code in packages/smithy-core/src/smithy_core/aio/types.py
317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 |
|
closed
property
¶
Returns whether the provider is closed.
__init__(intial_data=None, max_buffered_chunks=16)
¶
Initialize the AsyncBytesProvider.
:param initial_data: An initial chunk of bytes to make available.
:param max_buffered_chunks: The maximum number of chunks of data to buffer.
Calls to write
will block until the number of chunks is less than this
number. Default is 16.
Source code in packages/smithy-core/src/smithy_core/aio/types.py
close(flush=True)
async
¶
Closes the provider.
Pending writing tasks queued after this will fail, so such tasks should be awaited before this. Write tasks queued before this may succeed, however.
:param flush: Whether to flush buffered data before closing. If false, all buffered data will be lost. Default is False.
Source code in packages/smithy-core/src/smithy_core/aio/types.py
flush()
async
¶
Waits for all buffered data to be consumed.
Source code in packages/smithy-core/src/smithy_core/aio/types.py
AsyncBytesReader
¶
A file-like object with an async read method.
Source code in packages/smithy-core/src/smithy_core/aio/types.py
21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 |
|
closed
property
¶
Returns whether the stream is closed.
__init__(data)
¶
Initializes self.
Data is read from the source on an as-needed basis and is not buffered.
:param data: The source data to read from.
Source code in packages/smithy-core/src/smithy_core/aio/types.py
close()
async
¶
Closes the stream, as well as the underlying stream where possible.
iter_chunks(chunk_size=_DEFAULT_CHUNK_SIZE)
¶
Iterate over the reader in chunks of a given size.
:param chunk_size: The maximum size of each chunk. If less than 0, the entire reader will be read into one chunk.
Source code in packages/smithy-core/src/smithy_core/aio/types.py
read(size=-1)
async
¶
Read a number of bytes from the stream.
:param size: The maximum number of bytes to read. If less than 0, all bytes will be read.
Source code in packages/smithy-core/src/smithy_core/aio/types.py
readable()
¶
seek(offset, whence=0)
async
¶
Moves the cursor to a position relatve to the position indicated by whence.
Whence can have one of three values:
-
0 => The offset is relative to the start of the stream.
-
1 => The offset is relative to the current location of the cursor.
-
2 => The offset is relative to the end of the stream.
:param offset: The amount of movement to be done relative to whence. :param whence: The location the offset is relative to. :returns: Returns the new position of the cursor.
Source code in packages/smithy-core/src/smithy_core/aio/types.py
seekable()
¶
tell()
¶
Returns the position of the cursor.
SeekableAsyncBytesReader
¶
A file-like object with async read and seek methods.
Data is written into a buffer as it is read to enable seeking non-seekable streams.
Source code in packages/smithy-core/src/smithy_core/aio/types.py
161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 |
|
closed
property
¶
Returns whether the stream is closed.
__init__(data)
¶
Initializes self.
:param data: The source data to read from.
Source code in packages/smithy-core/src/smithy_core/aio/types.py
close()
async
¶
Closes the stream, as well as the underlying stream where possible.
iter_chunks(chunk_size=_DEFAULT_CHUNK_SIZE)
¶
Iterate over the reader in chunks of a given size.
:param chunk_size: The maximum size of each chunk. If less than 0, the entire reader will be read into one chunk.
Source code in packages/smithy-core/src/smithy_core/aio/types.py
read(size=-1)
async
¶
Read a number of bytes from the stream.
:param size: The maximum number of bytes to read. If less than 0, all bytes will be read.
Source code in packages/smithy-core/src/smithy_core/aio/types.py
readable()
¶
seek(offset, whence=0)
async
¶
Moves the cursor to a position relatve to the position indicated by whence.
Whence can have one of three values:
-
0 => The offset is relative to the start of the stream.
-
1 => The offset is relative to the current location of the cursor.
-
2 => The offset is relative to the end of the stream.
:param offset: The amount of movement to be done relative to whence. :param whence: The location the offset is relative to. :returns: Returns the new position of the cursor.
Source code in packages/smithy-core/src/smithy_core/aio/types.py
seekable()
¶
tell()
¶
utils
¶
async_list(lst)
async
¶
close(stream)
async
¶
Close a stream, awaiting it if it's async.
read_streaming_blob(body)
¶
Synchronously reads a streaming blob into bytes.
:param body: The streaming blob to read from. :raises AsyncBodyError: If the body is an async type.
Source code in packages/smithy-core/src/smithy_core/aio/utils.py
read_streaming_blob_async(body)
async
¶
Asynchronously reads a streaming blob into bytes.
:param body: The streaming blob to read from.
Source code in packages/smithy-core/src/smithy_core/aio/utils.py
seek(stream, offset, whence=0)
async
¶
Seek a stream to a specified point.
Source code in packages/smithy-core/src/smithy_core/aio/utils.py
auth
¶
AuthOption
dataclass
¶
Auth scheme used for signing and identity resolution.
Source code in packages/smithy-core/src/smithy_core/auth.py
identity_properties = field(default_factory=TypedProperties)
class-attribute
instance-attribute
¶
Paramters to pass to the identity resolver method.
scheme_id
instance-attribute
¶
The ID of the auth scheme to use.
signer_properties = field(default_factory=TypedProperties)
class-attribute
instance-attribute
¶
Paramters to pass to the signing method.
AuthParams
dataclass
¶
Parameters passed to an AuthSchemeResolver's resolve_auth_scheme
method.
Source code in packages/smithy-core/src/smithy_core/auth.py
context
instance-attribute
¶
The context of the operation invocation.
operation = field(repr=False)
class-attribute
instance-attribute
¶
The schema and associated information about the operation being invoked.
protocol_id
instance-attribute
¶
The ID of the protocol being used for the operation invocation.
DefaultAuthResolver
¶
Determines which authentication scheme to use based on modeled auth schemes.
Source code in packages/smithy-core/src/smithy_core/auth.py
resolve_auth_scheme(*, auth_parameters)
¶
Resolve an ordered list of applicable auth schemes.
:param auth_parameters: The parameters required for determining which authentication schemes to potentially use.
Source code in packages/smithy-core/src/smithy_core/auth.py
NoAuthResolver
¶
Auth resolver that always returns no auth scheme options.
Source code in packages/smithy-core/src/smithy_core/auth.py
codecs
¶
Codec
¶
Bases: Protocol
A protocol for Smithy codecs.
Smithy codecs are responsible for serializing and deserializing shapes in a particular format.
Source code in packages/smithy-core/src/smithy_core/codecs.py
media_type
property
¶
The media type that the codec supports.
create_deserializer(source)
¶
Create a deserializer that reads from the given bytes reader.
:param source: The source to read bytes from. :returns: A deserializer that reads from the given source.
Source code in packages/smithy-core/src/smithy_core/codecs.py
create_serializer(sink)
¶
Create a serializer that writes to the given bytes writer.
:param sink: The output class to write to. :returns: A serializer that will write to the given output.
Source code in packages/smithy-core/src/smithy_core/codecs.py
deserialize(source, shape)
¶
Deserialize bytes into a shape.
:param source: The bytes to deserialize. :param shape: The shape class to deserialize into. :returns: An instance of the given shape class with the data from the source.
Source code in packages/smithy-core/src/smithy_core/codecs.py
serialize(shape)
¶
Serialize a shape to bytes.
:param shape: The shape to serialize. :returns: Bytes representing the shape serialized in the codec's media type.
Source code in packages/smithy-core/src/smithy_core/codecs.py
deserializers
¶
DeserializeableShape
¶
Bases: Protocol
Protocol for shapes that are deserializeable using a ShapeDeserializer.
Source code in packages/smithy-core/src/smithy_core/deserializers.py
deserialize(deserializer)
classmethod
¶
Construct an instance of this class using the given deserializer.
:param deserializer: The deserializer to read from. :returns: An instance of this class created from the deserializer.
Source code in packages/smithy-core/src/smithy_core/deserializers.py
ShapeDeserializer
¶
Bases: Protocol
Protocol used for deserializing shapes based on the Smithy data model.
If used as a base class, all non-float number methods default to calling
read_integer
and read_double
defaults to calling read_float
.
These extra numeric methods are for types in the Smithy data model that
don't have Python equivalents, but may have equivalents in the format
being read.
Source code in packages/smithy-core/src/smithy_core/deserializers.py
16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 |
|
is_null()
¶
Returns whether the next value in the underlying data represents null.
:param schema: The shape's schema.
read_big_decimal(schema)
¶
Read a big decimal (arbitrarily large float) value from the underlying data.
:param schema: The shape's schema. :returns: A big decimal from the underlying data.
Source code in packages/smithy-core/src/smithy_core/deserializers.py
read_big_integer(schema)
¶
Read a big integer (arbitrarily large integer) value from the underlying data.
:param schema: The shape's schema. :returns: A big integer from the underlying data.
Source code in packages/smithy-core/src/smithy_core/deserializers.py
read_blob(schema)
¶
Read a blob value from the underlying data.
:param schema: The shape's schema. :returns: A blob from the underlying data.
read_boolean(schema)
¶
Read a boolean value from the underlying data.
:param schema: The shape's schema. :returns: A bool from the underlying data.
read_byte(schema)
¶
Read a byte (8-bit integer) value from the underlying data.
:param schema: The shape's schema. :returns: A byte from the underlying data.
Source code in packages/smithy-core/src/smithy_core/deserializers.py
read_data_stream(schema)
¶
Read a data stream from the underlying data.
The data itself MUST NOT be read by this method. The value returned is intended to be read later by the consumer. In an HTTP implementation, for example, this would directly return the HTTP body stream. The stream MAY be wrapped to provide a more consistent interface or to avoid exposing implementation details.
Data streams are only supported at the top-level input and output for operations.
:param schema: The shape's schema. :returns: A data stream derived from the underlying data.
Source code in packages/smithy-core/src/smithy_core/deserializers.py
read_document(schema)
¶
Read a document value from the underlying data.
:param schema: The shape's schema. :returns: A document from the underlying data.
read_double(schema)
¶
Read a double (64-bit float) value from the underlying data.
:param schema: The shape's schema. :returns: A double from the underlying data.
Source code in packages/smithy-core/src/smithy_core/deserializers.py
read_float(schema)
¶
Read a float (32-bit) value from the underlying data.
:param schema: The shape's schema. :returns: A float from the underlying data.
read_integer(schema)
¶
Read an integer (32-bit) value from the underlying data.
:param schema: The shape's schema. :returns: An integer from the underlying data.
read_list(schema, consumer)
¶
Read a list value from the underlying data.
:param schema: The shape's schema. :param consumer: A callable to read list elements with.
Source code in packages/smithy-core/src/smithy_core/deserializers.py
read_long(schema)
¶
Read a long (64-bit integer) value from the underlying data.
:param schema: The shape's schema. :returns: A long from the underlying data.
Source code in packages/smithy-core/src/smithy_core/deserializers.py
read_map(schema, consumer)
¶
Read a map value from the underlying data.
:param schema: The shape's schema. :param consumer: A callable to read map values with.
Source code in packages/smithy-core/src/smithy_core/deserializers.py
read_null()
¶
read_short(schema)
¶
Read a short (16-bit integer) value from the underlying data.
:param schema: The shape's schema. :returns: A short from the underlying data.
Source code in packages/smithy-core/src/smithy_core/deserializers.py
read_string(schema)
¶
Read a string value from the underlying data.
:param schema: The shape's schema. :returns: A string from the underlying data.
read_struct(schema, consumer)
¶
Read a struct value from the underlying data.
:param schema: The shape's schema. :param consumer: A callable to read struct members with.
Source code in packages/smithy-core/src/smithy_core/deserializers.py
read_timestamp(schema)
¶
Read a timestamp value from the underlying data.
:param schema: The shape's schema. :returns: A timestamp from the underlying data.
Source code in packages/smithy-core/src/smithy_core/deserializers.py
SpecificShapeDeserializer
¶
Bases: ShapeDeserializer
Expects to deserialize a specific kind of shape, failing if other shapes are deserialized.
Source code in packages/smithy-core/src/smithy_core/deserializers.py
194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 |
|
documents
¶
DocumentValue = Mapping[str, DocumentValue] | Sequence[DocumentValue] | str | int | float | Decimal | bool | None | bytes | datetime.datetime
¶
Protocol-agnostic open content.
Document
¶
Wrapped protocol-agnostic open content.
This wrapping class facilitates serialization and deserialiazation and may contain a schema to enable serializing and deserializing protocol-specific documents into a protocol-agnostic form.
Source code in packages/smithy-core/src/smithy_core/documents.py
58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 |
|
discriminator
property
¶
The shape ID that corresponds to the contents of the document.
shape_type
property
¶
The Smithy data model type for the underlying contents of the document.
__init__(value=None, *, schema=_DOCUMENT)
¶
Initializes a document.
:param value: The underlying value of a document. :param schema: A schema defining the document's structure. The default value is a plain document schema with no traits.
Source code in packages/smithy-core/src/smithy_core/documents.py
as_blob()
¶
as_boolean()
¶
as_decimal()
¶
as_float()
¶
Asserts the document is a float and returns it.
This method is to be used for any type from the Smithy data model that translates to Python's float type. This includes float and double.
Source code in packages/smithy-core/src/smithy_core/documents.py
as_integer()
¶
Asserts the document is an integer and returns it.
This method is to be used for any type from the Smithy data model that translates to Python's int type. This includes: byte, short, integer, long, and bigInteger.
Source code in packages/smithy-core/src/smithy_core/documents.py
as_list()
¶
Asserts the document is a list and returns it.
Source code in packages/smithy-core/src/smithy_core/documents.py
as_map()
¶
Asserts the document is a map and returns it.
Source code in packages/smithy-core/src/smithy_core/documents.py
as_shape(shape_class)
¶
Converts the document to an instance of the given shape type.
:param shape_class: A class that implements the DeserializeableShape protocol.
Source code in packages/smithy-core/src/smithy_core/documents.py
as_string()
¶
as_timestamp()
¶
as_value()
¶
Converts the document to a plain, protocol-agnostic DocumentValue and returns it.
Source code in packages/smithy-core/src/smithy_core/documents.py
from_shape(shape)
classmethod
¶
Constructs a Document from a given shape.
:param shape: The shape to convert to a document. :returns: A Document representation of the given shape.
Source code in packages/smithy-core/src/smithy_core/documents.py
get(name, default=None)
¶
Gets a named member of the document or a default value.
TypeRegistry
¶
A registry for on-demand deserialization of types by using a mapping of shape IDs to their deserializers.
Source code in packages/smithy-core/src/smithy_core/documents.py
__contains__(item)
¶
Check if the registry contains the given shape.
:param item: The shape ID to check for.
Source code in packages/smithy-core/src/smithy_core/documents.py
__getitem__(shape)
¶
Get the deserializable shape for the given shape ID.
:param shape: The shape ID to get from the registry. :returns: The corresponding deserializable shape. :raises KeyError: If the shape ID is not found in the registry.
Source code in packages/smithy-core/src/smithy_core/documents.py
__init__(types, sub_registry=None)
¶
Initialize a TypeRegistry.
:param types: A mapping of ShapeID to the shapes they deserialize to. :param sub_registry: A registry to delegate to if an ID is not found in types.
Source code in packages/smithy-core/src/smithy_core/documents.py
get(shape)
¶
Get the deserializable shape for the given shape ID.
:param shape: The shape ID to get from the registry. :returns: The corresponding deserializable shape. :raises KeyError: If the shape ID is not found in the registry.
Source code in packages/smithy-core/src/smithy_core/documents.py
endpoints
¶
STATIC_ENDPOINT_CONFIG = PropertyKey(key='config', value_type=StaticEndpointConfig)
module-attribute
¶
Property containing a config that has a static endpoint.
Endpoint
dataclass
¶
Bases: Endpoint
A resolved endpoint.
Source code in packages/smithy-core/src/smithy_core/endpoints.py
EndpointResolverParams
dataclass
¶
Parameters passed into an Endpoint Resolver's resolve_endpoint method.
Source code in packages/smithy-core/src/smithy_core/endpoints.py
StaticEndpointConfig
¶
Bases: Protocol
A config that has a static endpoint.
Source code in packages/smithy-core/src/smithy_core/endpoints.py
endpoint_uri
instance-attribute
¶
A static endpoint to use for the request.
resolve_static_uri(properties)
¶
Attempt to resolve a static URI from the endpoint resolver params.
:param properties: A TypedProperties bag or EndpointResolverParams to search.
Source code in packages/smithy-core/src/smithy_core/endpoints.py
exceptions
¶
Fault = Literal['client', 'server'] | None
¶
Whether the client or server is at fault.
If None, then there was not enough information to determine fault.
AsyncBodyError
¶
Bases: SmithyError
Exception indicating that a request with an async body type was created in a sync context.
CallError
dataclass
¶
Bases: SmithyError
Base exception to be used in application-level errors.
Implements :py:class:.interfaces.retries.ErrorRetryInfo
.
Source code in packages/smithy-core/src/smithy_core/exceptions.py
fault = None
class-attribute
instance-attribute
¶
Whether the client or server is at fault.
If None, then there was not enough information to determine fault.
is_retry_safe = None
class-attribute
instance-attribute
¶
Whether the exception is safe to retry.
A value of True does not mean a retry will occur, but rather that a retry is allowed to occur.
A value of None indicates that there is not enough information available to determine if a retry is safe.
is_throttling_error = False
class-attribute
instance-attribute
¶
Whether the error is a throttling error.
message = field(default='', kw_only=False)
class-attribute
instance-attribute
¶
The message of the error.
retry_after = None
class-attribute
instance-attribute
¶
The amount of time that should pass before a retry.
Retry strategies MAY choose to wait longer.
DiscriminatorError
¶
Bases: SmithyError
Exception indicating something went wrong when attempting to find the discriminator in a document.
EndpointResolutionError
¶
Bases: SmithyError
Exception type for all exceptions raised by endpoint resolution.
ExpectationNotMetError
¶
Bases: SmithyError
Exception type for exceptions thrown by unmet assertions.
MissingDependencyError
¶
Bases: SmithyError
Exception type raised when a feature that requires a missing optional dependency is called.
ModeledError
dataclass
¶
RetryError
¶
Bases: SmithyError
Base exception type for all exceptions raised in retry strategies.
SerializationError
¶
Bases: SmithyError
Base exception type for exceptions raised during serialization.
SmithyError
¶
SmithyIdentityError
¶
Bases: SmithyError
Base exception type for all exceptions raised in identity resolution.
UnsupportedStreamError
¶
Bases: SmithyError
Indicates that a serializer or deserializer's stream method was called, but data streams are not supported.
interceptors
¶
InputContext
dataclass
¶
Source code in packages/smithy-core/src/smithy_core/interceptors.py
Interceptor
¶
Allows injecting code into the SDK's request execution pipeline.
Terminology:
- execution - An execution is one end-to-end invocation against a client.
- attempt - An attempt is an attempt at performing an execution. By default, executions are retried multiple times based on the client's retry strategy.
- hook - A hook is a single method on the interceptor, allowing injection of code into a specific part of the SDK's request execution pipeline. Hooks are either "read" hooks, which make it possible to read in-flight request or response messages, or "read/write" hooks, which make it possible to modify in-flight requests or responses.
Source code in packages/smithy-core/src/smithy_core/interceptors.py
48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 |
|
modify_before_attempt_completion(context)
¶
A hook called when an attempt is completed.
This method has the ability to modify and return a new output message or exception matching the currently-executing operation.
This will ALWAYS be called once per attempt, except when a failure occurs
before read_before_attempt
. This method may be called multiple times in the
event of retries.
The request
, response
, and transport_request
of the context will always
be available. The transport_response
will be available if a response was
received by the service for this attempt. In the event of retries, the context
will not include changes made in previous attempts (e.g. by request signers or
other interceptors).
If exceptions are thrown by this hook, execution will jump to
read_after_attempt
with the thrown exception as the response
.
Any output returned by this hook MUST match the operation being invoked. Any
exception type can be returned, replacing the response
currently in the
context.
Source code in packages/smithy-core/src/smithy_core/interceptors.py
modify_before_completion(context)
¶
A hook called when an execution is completed.
This method has the ability to modify and return a new output message or exception matching the currently-executing operation.
This will always be called once per execution.
The request
and response
of the context will always be available. The
transport_request
and transport_response
will be available if the execution
proceeded far enough for them to be generated.
If exceptions are thrown by this hook, execution will jump to
read_after_execution
with the thrown exception as the response
.
Any output returned by this hook MUST match the operation being invoked. Any
exception type can be returned, replacing the response
currently in the context.
Source code in packages/smithy-core/src/smithy_core/interceptors.py
modify_before_deserialization(context)
¶
A hook called before the transport response is deserialized.
This method has the ability to modify and return a new transport response of the same type.
This will always be called once per attempt, except when a failure occurs earlier in the request pipeline. This method may be called multiple times in the event of retries.
The request
, transport_request
, and transport_response
of the context
will always be available. Other static properties will be None. In the event of
retries, the context will not include changes made in previous attempts (e.g.
by request signers or other interceptors). The transport_response
may have
been modified by earlier modify_before_deserialization
hooks, and may be
modified further by later hooks. In the event of retries, the context will not
include changes made in previous attempts (e.g. by request signers or other
interceptors).
If exceptions are thrown by this hook, execution will jump to
modify_before_attempt_completion
with the thrown exception as the response
.
The transport response returned by this hook MUST be the same type of response passed into this hook. If not, an exception will immediately occur.
Source code in packages/smithy-core/src/smithy_core/interceptors.py
modify_before_retry_loop(context)
¶
A hook called before the retry loop is entered.
This method has the ability to modify and return a new transport request of the same type.
This will always be called once per execution, except when a failure occurs earlier in the request pipeline.
If exceptions are thrown by this hook, execution will jump to
modify_before_completion
with the thrown exception as the response
.
The transport request returned by this hook MUST be the same type of request passed into this hook. If not, an exception will immediately occur.
Source code in packages/smithy-core/src/smithy_core/interceptors.py
modify_before_serialization(context)
¶
A hook called before the request is serialized into a transport request.
This method has the ability to modify and return a new request of the same type.
This will ALWAYS be called once per execution, except when a failure occurs earlier in the request pipeline.
The request
of the context will always be available. This request
may have
been modified by earlier modify_before_serialization
hooks, and may be
modified further by later hooks. Other static properites will be None.
If exceptions are thrown by this hook, execution will jump to
modify_before_completion
with the thrown exception as the response
.
The request returned by this hook MUST be the same type of request message passed into this hook. If not, an exception will immediately occur.
Source code in packages/smithy-core/src/smithy_core/interceptors.py
modify_before_signing(context)
¶
A hook called before the transport request is signed.
This method has the ability to modify and return a new transport request of the same type.
This will always be called once per attempt, except when a failure occurs earlier in the request pipeline. This method will be called multiple times in the event of retries.
The request
and transport_request
of the context will always be available.
Other static properties will be None. The transport_request
may have been
modified by earlier modify_before_signing
hooks, and may be modified further
by later hooks. In the event of retries, the context will not include changes
made in previous attempts (e.g. by request signers or other interceptors).
If exceptions are thrown by this hook, execution will jump to
modify_before_attempt_completion
with the thrown exception as the response
.
The transport request returned by this hook MUST be the same type of request passed into this hook. If not, an exception will immediately occur.
Source code in packages/smithy-core/src/smithy_core/interceptors.py
modify_before_transmit(context)
¶
A hook called before the transport request is sent to the service.
This method has the ability to modify and return a new transport request of the same type.
This will always be called once per attempt, except when a failure occurs earlier in the request pipeline. This method may be called multiple times in the event of retries.
The request
and transport_request
of the context will always be available.
Other static properties will be None. The transport_request
may have been
modified by earlier modify_before_signing
hooks, and may be modified further
by later hooks. In the event of retries, the context will not include changes
made in previous attempts (e.g. by request signers or other interceptors).
If exceptions are thrown by this hook, execution will jump to
modify_before_attempt_completion
with the thrown exception as the response
.
The transport request returned by this hook MUST be the same type of request passed into this hook. If not, an exception will immediately occur.
Source code in packages/smithy-core/src/smithy_core/interceptors.py
read_after_attempt(context)
¶
A hook called when an attempt is completed.
Implementations MUST NOT modify the request
, response
, transport_request
,
or transport_response
in this hook.
This will ALWAYS be called once per attempt, as long as read_before_attempt
has been executed.
The request
, response
, and transport_request
of the context will always
be available. The transport_response
will be available if a response was
received by the service for this attempt. In the event of retries, the context
will not include changes made in previous attempts (e.g. by request signers or
other interceptors).
Exceptions thrown by this hook will be stored until all interceptors have had
their read_after_attempt
invoked. If multiple read_after_attempt
methods
throw exceptions, the latest will be used and earlier ones will be logged and
dropped. If the retry strategy determines that the execution is retryable,
execution will then jump to read_before_attempt
. Otherwise, execution will
jump to modify_before_completion
with the thrown exception as the response
.
Source code in packages/smithy-core/src/smithy_core/interceptors.py
read_after_deserialization(context)
¶
A hook called after the transport response is deserialized.
Implementations MUST NOT modify the request
, response
, transport_request
,
or transport_response
in this hook.
This will always be called once per attempt, except when a failure occurs
earlier in the request pipeline. This method may be called multiple times in
the event of retries. The duration between read_before_deserialization
and the invocation of this hook is very close to the amount of time spent
deserializing the service response. Depending on the protocol and operation,
the duration may include the time spent downloading the response data.
The request
, response
, transport_request
, and transport_response
of the
context will always be available. In the event of retries, the context will not
include changes made in previous attempts (e.g. by request signers or other
interceptors).
If exceptions are thrown by this hook, execution will jump to
modify_before_attempt_completion
with the thrown exception as the response
.
Source code in packages/smithy-core/src/smithy_core/interceptors.py
read_after_execution(context)
¶
A hook called when an execution is completed.
Implementations MUST NOT modify the request
, response
, transport_request
,
or transport_response
in this hook.
This will always be called once per execution. The duration between
read_before_execution
and the invocation of this hook is very close to the
full duration of the execution.
The request
and response
of the context will always be available. The
transport_request
and transport_response
will be available if the execution
proceeded far enough for them to be generated.
Exceptions thrown by this hook will be stored until all interceptors have had
their read_after_execution
invoked. The exception will then be treated as the
final response. If multiple read_after_execution
methods throw exceptions,
the latest will be used and earlier ones will be logged and dropped.
Source code in packages/smithy-core/src/smithy_core/interceptors.py
read_after_serialization(context)
¶
A hook called after the input message is serialized into a transport request.
Implementations MUST NOT modify the request
, response
, transport_request
,
or transport_response
in this hook.
This will always be called once per execution, except when a failure occurs
earlier in the request pipeline. The duration between
read_before_serialization
and the invocation of this hook is very close to
the amount of time spent serializing the request.
The request
and transport_request
of the context will always be available.
Other static properties will be None.
If exceptions are thrown by this hook, execution will jump to
modify_before_completion
with the thrown exception as the response
.
Source code in packages/smithy-core/src/smithy_core/interceptors.py
read_after_signing(context)
¶
A hook called after the transport request is signed.
Implementations MUST NOT modify the request
, response
, transport_request
,
or transport_response
in this hook.
This will always be called once per attempt, except when a failure occurs
earlier in the request pipeline. This method may be called multiple times in
the event of retries. The duration between read_before_signing
and the
invocation of this hook is very close to the amount of time spent signing the
request.
The request
and transport_request
of the context will always be available.
Other static properties will be None. In the event of retries, the context will
not include changes made in previous attempts (e.g. by request signers or other
interceptors).
If exceptions are thrown by this hook, execution will jump to
modify_before_attempt_completion
with the thrown exception as the response
.
Source code in packages/smithy-core/src/smithy_core/interceptors.py
read_after_transmit(context)
¶
A hook called after the transport request is sent to the service and a transport response is received.
Implementations MUST NOT modify the request
, response
, transport_request
,
or transport_response
in this hook.
This will always be called once per attempt, except when a failure occurs
earlier in the request pipeline. This method may be called multiple times in
the event of retries. The duration between read_before_transmit
and the
invocation of this hook is very close to the amount of time spent communicating
with the service. Depending on the protocol, the duration may not include the
time spent reading the response data.
The request
, transport_request
, and transport_response
of the context
will always be available. Other static properties will be None. In the event of
retries, the context will not include changes made in previous attempts (e.g.
by request signers or other interceptors).
If exceptions are thrown by this hook, execution will jump to
modify_before_attempt_completion
with the thrown exception as the response
.
Source code in packages/smithy-core/src/smithy_core/interceptors.py
read_before_attempt(context)
¶
A hook called before each attempt at sending the transport request to the service.
Implementations MUST NOT modify the request
, response
, transport_request
,
or transport_response
in this hook.
This will always be called once per attempt, except when a failure occurs earlier in the request pipeline. This method will be called multiple times in the event of retries.
The request
and transport_request
of the context will always be available.
Other static properties will be None. In the event of retries, the context will
not include changes made in previous attempts (e.g. by request signers or other
interceptors).
Exceptions thrown by this hook will be stored until all interceptors have had
their read_before_attempt
invoked. Other hooks will then be skipped and
execution will jump to modify_before_attempt_completion
with the thrown
exception as the response
If multiple read_before_attempt
methods throw
exceptions, the latest will be used and earlier ones will be logged and dropped.
Source code in packages/smithy-core/src/smithy_core/interceptors.py
read_before_deserialization(context)
¶
A hook called before the transport response is deserialized.
Implementations MUST NOT modify the request
, response
, transport_request
,
or transport_response
in this hook.
This will always be called once per attempt, except when a failure occurs
earlier in the request pipeline. This method may be called multiple times in
the event of retries. The duration between invocation of this hook and
read_after_deserialization
is very close to the amount of time spent
deserializing the service response. Depending on the protocol and operation,
the duration may include the time spent downloading the response data.
The request
, transport_request
, and transport_response
of the context
will always be available. Other static properties will be None. In the event of
retries, the context will not include changes made in previous attempts (e.g.
by request signers or other interceptors).
If exceptions are thrown by this hook, execution will jump to
modify_before_attempt_completion
with the thrown exception as the response
.
Source code in packages/smithy-core/src/smithy_core/interceptors.py
read_before_execution(context)
¶
A hook called at the start of an execution, before the SDK does anything else.
Implementations MUST NOT modify the request
, response
, transport_request
,
or transport_response
in this hook.
This will always be called once per execution. The duration between invocation
of this hook and read_after_execution
is very close to full duration of the
execution.
The request
of the context will always be available. Other static properties
will be None.
Exceptions thrown by this hook will be stored until all interceptors have had
their read_before_execution
invoked. Other hooks will then be skipped and
execution will jump to modify_before_completion
with the thrown exception as
the response
. If multiple read_before_execution
methods throw exceptions,
the latest will be used and earlier ones will be logged and dropped.
Source code in packages/smithy-core/src/smithy_core/interceptors.py
read_before_serialization(context)
¶
A hook called before the input message is serialized into a transport request.
Implementations MUST NOT modify the request
, response
, transport_request
,
or transport_response
in this hook.
This will always be called once per execution, except when a failure occurs
earlier in the request pipeline. The duration between invocation of this hook
and read_after_serialization
is very close to the amount of time spent
marshalling the request.
The request
of the context will always be available. Other static properties
will be None.
If exceptions are thrown by this hook, execution will jump to
modify_before_completion
with the thrown exception as the response
.
Source code in packages/smithy-core/src/smithy_core/interceptors.py
read_before_signing(context)
¶
A hook called before the transport request is signed.
Implementations MUST NOT modify the request
, response
, transport_request
,
or transport_response
in this hook.
This will always be called once per attempt, except when a failure occurs
earlier in the request pipeline. This method may be called multiple times in
the event of retries. The duration between invocation of this hook and
read_after_signing
is very close to the amount of time spent signing the
request.
The request
and transport_request
of the context will always be available.
Other static properties will be None. In the event of retries, the context will
not include changes made in previous attempts (e.g. by request signers or other
interceptors).
If exceptions are thrown by this hook, execution will jump to
modify_before_attempt_completion
with the thrown exception as the response
.
Source code in packages/smithy-core/src/smithy_core/interceptors.py
read_before_transmit(context)
¶
A hook called before the transport request is sent to the service.
Implementations MUST NOT modify the request
, response
, transport_request
,
or transport_response
in this hook.
This will always be called once per attempt, except when a failure occurs
earlier in the request pipeline. This method may be called multiple times in
the event of retries. The duration between invocation of this hook and
read_after_transmit
is very close to the amount of time spent communicating
with the service. Depending on the protocol, the duration may not include the
time spent reading the response data.
The request
and transport_request
of the context will always be available.
Other static properties will be None. In the event of retries, the context will
not include changes made in previous attempts (e.g. by request signers or other
interceptors).
If exceptions are thrown by this hook, execution will jump to
modify_before_attempt_completion
with the thrown exception as the response
.
Source code in packages/smithy-core/src/smithy_core/interceptors.py
InterceptorChain
¶
Bases: AnyInterceptor
An interceptor that contains an ordered list of delegate interceptors.
This is primarily intended for use within the client itself.
Source code in packages/smithy-core/src/smithy_core/interceptors.py
533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 |
|
__init__(chain)
¶
Construct an InterceptorChain.
:param chain: The ordered interceptors to chain together.
OutputContext
dataclass
¶
Bases: ResponseContext[Request, TransportRequest, TransportResponse]
Source code in packages/smithy-core/src/smithy_core/interceptors.py
response
instance-attribute
¶
The modeled response for the operation being invoked.
RequestContext
dataclass
¶
Bases: InputContext[Request]
Source code in packages/smithy-core/src/smithy_core/interceptors.py
transport_request
instance-attribute
¶
The transmittable request for the operation being invoked.
ResponseContext
dataclass
¶
Bases: RequestContext[Request, TransportRequest]
Source code in packages/smithy-core/src/smithy_core/interceptors.py
transport_response
instance-attribute
¶
The transmitted response for the operation being invoked.
interfaces
¶
BytesReader
¶
Bases: Protocol
A protocol for objects that support reading bytes from them.
Source code in packages/smithy-core/src/smithy_core/interfaces/__init__.py
BytesWriter
¶
Bases: Protocol
A protocol for objects that support writing bytes to them.
Source code in packages/smithy-core/src/smithy_core/interfaces/__init__.py
Endpoint
¶
Bases: Protocol
A resolved endpoint.
Source code in packages/smithy-core/src/smithy_core/interfaces/__init__.py
PropertyKey
¶
Bases: Protocol
A typed properties key.
Used with :py:class:Context
to set and get typed values.
For a concrete implementation, see :py:class:smithy_core.types.PropertyKey
.
.. code-block:: python
UNION_PROPERTY: PropertyKey[str | int] = PropertyKey(
key="union",
value_type=str | int,
)
Source code in packages/smithy-core/src/smithy_core/interfaces/__init__.py
SeekableBytesReader
¶
Bases: BytesReader
, Protocol
A synchronous bytes reader with seek and tell methods.
Source code in packages/smithy-core/src/smithy_core/interfaces/__init__.py
TypedProperties
¶
Bases: Protocol
A properties map with typed setters and getters.
Keys can be either a string or a :py:class:PropertyKey
. Using a PropertyKey instead
of a string enables type checkers to narrow to the associated value type rather
than having to use Any.
Letting the value be either a string or PropertyKey allows consumers who care about typing to get it, and those who don't care about typing to not have to think about it.
..code-block:: python
foo = PropertyKey(key="foo", value_type=str)
properties = TypedProperties()
properties[foo] = "bar"
assert assert_type(properties[foo], str) == "bar"
assert assert_type(properties["foo"], Any) == "bar"
For a concrete implementation, see :py:class:smithy_core.types.TypedProperties
.
Note that unions and other special types cannot easily be used here due to being
incompatible with type[T]
. PEP747 proposes a fix to this case, but it has not
yet been accepted. In the meantime, there is a workaround. The PropertyKey must
be assigned to an explicitly typed variable, and the value_type
parameter of
the constructor must have a # type: ignore
comment, like so:
.. code-block:: python
UNION_PROPERTY: PropertyKey[str | int] = PropertyKey(
key="union",
value_type=str | int, # type: ignore
)
properties = TypedProperties()
properties[UNION_PROPERTY] = "foo"
assert assert_type(properties[UNION_PROPERTY], str | int) == "foo"
Type checkers will be able to use such a property as expected.
Source code in packages/smithy-core/src/smithy_core/interfaces/__init__.py
143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 |
|
URI
¶
Bases: Protocol
Universal Resource Identifier, target location for a :py:class:Request
.
Source code in packages/smithy-core/src/smithy_core/interfaces/__init__.py
fragment
instance-attribute
¶
Part of the URI specification, but may not be transmitted by a client.
host
instance-attribute
¶
The hostname, for example amazonaws.com
.
netloc
property
¶
Construct netloc string in format {username}:{password}@{host}:{port}
password
instance-attribute
¶
Password part of the userinfo URI component.
path
instance-attribute
¶
Path component of the URI.
port
instance-attribute
¶
An explicit port number.
query
instance-attribute
¶
Query component of the URI as string.
scheme
instance-attribute
¶
For example http
or mqtts
.
username
instance-attribute
¶
Username part of the userinfo URI component.
build()
¶
Construct URI string representation.
Returns a string of the form
{scheme}://{username}:{password}@{host}:{port}{path}?{query}#{fragment}
is_bytes_reader(obj)
¶
Determines whether the given object conforms to the BytesReader protocol.
This is necessary to distinguish this from an async reader, since runtime_checkable doesn't make that distinction.
:param obj: The object to inspect.
Source code in packages/smithy-core/src/smithy_core/interfaces/__init__.py
is_streaming_blob(obj)
¶
Determines whether the given object is a StreamingBlob.
:param obj: The object to inspect.
Source code in packages/smithy-core/src/smithy_core/interfaces/__init__.py
auth
¶
AuthOption
¶
Bases: Protocol
Auth scheme used for signing and identity resolution.
Source code in packages/smithy-core/src/smithy_core/interfaces/auth.py
AuthSchemeResolver
¶
Bases: Protocol
Determines which authentication scheme to use for a given service.
Source code in packages/smithy-core/src/smithy_core/interfaces/auth.py
resolve_auth_scheme(*, auth_parameters)
¶
Resolve an ordered list of applicable auth schemes.
:param auth_parameters: The parameters required for determining which authentication schemes to potentially use.
Source code in packages/smithy-core/src/smithy_core/interfaces/auth.py
exceptions
¶
HasFault
¶
Bases: Protocol
A protocol for a modeled error.
All modeled errors will have a fault that is either "client" or "server".
Source code in packages/smithy-core/src/smithy_core/interfaces/exceptions.py
identity
¶
Identity
¶
Bases: Protocol
An entity available to the client representing who the user is.
Source code in packages/smithy-core/src/smithy_core/interfaces/identity.py
retries
¶
ErrorRetryInfo
¶
Bases: Protocol
A protocol for errors that have retry information embedded.
Source code in packages/smithy-core/src/smithy_core/interfaces/retries.py
is_retry_safe = None
class-attribute
instance-attribute
¶
Whether the error is safe to retry.
A value of True does not mean a retry will occur, but rather that a retry is allowed to occur.
A value of None indicates that there is not enough information available to determine if a retry is safe.
is_throttling_error = False
class-attribute
instance-attribute
¶
Whether the error is a throttling error.
retry_after = None
class-attribute
instance-attribute
¶
The amount of time that should pass before a retry.
Retry strategies MAY choose to wait longer.
RetryBackoffStrategy
¶
Bases: Protocol
Stateless strategy for computing retry delays based on retry attempt account.
Source code in packages/smithy-core/src/smithy_core/interfaces/retries.py
compute_next_backoff_delay(retry_attempt)
¶
Calculate timespan in seconds to delay before next retry.
:param retry_attempt: The index of the retry attempt that is about to be made
after the delay. The initial attempt, before any retries, is index 0
, the
first retry attempt after the initial attempt failed is index 1
, and so on.
Source code in packages/smithy-core/src/smithy_core/interfaces/retries.py
RetryStrategy
¶
Bases: Protocol
Issuer of :py:class:RetryToken
s.
Source code in packages/smithy-core/src/smithy_core/interfaces/retries.py
backoff_strategy
instance-attribute
¶
The strategy used by returned tokens to compute delay duration values.
max_attempts
instance-attribute
¶
Upper limit on total attempt count (initial attempt plus retries).
acquire_initial_retry_token(*, token_scope=None)
¶
Called before any retries (for the first attempt at the operation).
:param token_scope: An arbitrary string accepted by the retry strategy to separate tokens into scopes. :returns: A retry token, to be used for determining the retry delay, refreshing the token after a failure, and recording success after success. :raises RetryError: If the retry strategy has no available tokens.
Source code in packages/smithy-core/src/smithy_core/interfaces/retries.py
record_success(*, token)
¶
Return token after successful completion of an operation.
Upon successful completion of the operation, a user calls this function to record that the operation was successful.
:param token: The token used for the previous successful attempt.
Source code in packages/smithy-core/src/smithy_core/interfaces/retries.py
refresh_retry_token_for_retry(*, token_to_renew, error)
¶
Replace an existing retry token from a failed attempt with a new token.
After a failed operation call, this method is called to exchange a retry token
that was previously obtained by calling :py:func:acquire_initial_retry_token
or this method with a new retry token for the next attempt. This method can
either choose to allow another retry and send a new or updated token, or reject
the retry attempt and raise the error.
:param token_to_renew: The token used for the previous failed attempt. :param error: The error that triggered the need for a retry. :raises RetryError: If no further retry attempts are allowed.
Source code in packages/smithy-core/src/smithy_core/interfaces/retries.py
RetryToken
dataclass
¶
Bases: Protocol
Token issued by a :py:class:RetryStrategy
for the next attempt.
Source code in packages/smithy-core/src/smithy_core/interfaces/retries.py
prelude
¶
Shared schemas for shapes built into Smithy's prelude.
retries
¶
ExponentialBackoffJitterType
¶
Bases: Enum
Jitter mode for exponential backoff.
For use with :py:class:ExponentialRetryBackoffStrategy
.
Source code in packages/smithy-core/src/smithy_core/retries.py
DECORRELATED = 4
class-attribute
instance-attribute
¶
Truncated binary exponential backoff delay with decorrelated jitter:
.. code-block:: python
min(max_backoff, random_between(backoff_scale_value, t_(i-1) * 3))
Similar to :py:var:FULL
, but also increases the maximum jitter at each retry.
DEFAULT = 1
class-attribute
instance-attribute
¶
Truncated binary exponential backoff delay with equal jitter:
.. code-block:: python
capped = min(max_backoff, backoff_scale_value * 2 ** (retry_attempt - 1))
(capped / 2) + random_between(0, capped / 2)
Also known as "Equal Jitter". Similar to :py:var:FULL
but always keep some of the
backoff and jitters by a smaller amount.
FULL = 3
class-attribute
instance-attribute
¶
Truncated binary exponential backoff delay with full jitter:
.. code-block:: python
random_between(
max_backoff,
min(max_backoff, backoff_scale_value * 2 ** (retry_attempt - 1))
)
NONE = 2
class-attribute
instance-attribute
¶
Truncated binary exponential backoff delay without jitter:
.. code-block:: python
min(max_backoff, backoff_scale_value * 2 ** (retry_attempt - 1))
ExponentialRetryBackoffStrategy
¶
Bases: RetryBackoffStrategy
Source code in packages/smithy-core/src/smithy_core/retries.py
60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 |
|
__init__(*, backoff_scale_value=0.025, max_backoff=20, jitter_type=ExponentialBackoffJitterType.DEFAULT, random=random.random)
¶
Exponential backoff with optional jitter.
.. seealso:: https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/
:param backoff_scale_value: Factor that linearly adjusts returned backoff delay
values. See the methods _next_delay_*
for the formula used to calculate the
delay for each jitter type. If set to None
(the default), :py:attr:random
will be called to generate a value.
:param max_backoff: Upper limit for backoff delay values returned, in seconds.
:param jitter_type: Determines the formula used to apply jitter to the backoff delay.
:param random: A callable that returns random numbers between 0
and 1
.
Use the default random.random
unless you require an alternate source of
randomness or a non-uniform distribution.
Source code in packages/smithy-core/src/smithy_core/retries.py
compute_next_backoff_delay(retry_attempt)
¶
Calculate timespan in seconds to delay before next retry.
See the methods _next_delay_*
for the formula used to calculate the delay
for each jitter type for values of retry_attempt > 0
.
:param retry_attempt: The index of the retry attempt that is about to be made
after the delay. The initial attempt, before any retries, is index 0
, and
will return a delay of 0
. The first retry attempt after a failed initial
attempt is index 1
, and so on.
Source code in packages/smithy-core/src/smithy_core/retries.py
SimpleRetryStrategy
¶
Bases: RetryStrategy
Source code in packages/smithy-core/src/smithy_core/retries.py
__init__(*, backoff_strategy=None, max_attempts=5)
¶
Basic retry strategy that simply invokes the given backoff strategy.
:param backoff_strategy: The backoff strategy used by returned tokens to compute
the retry delay. Defaults to :py:class:ExponentialRetryBackoffStrategy
.
:param max_attempts: Upper limit on total number of attempts made, including initial attempt and retries.
Source code in packages/smithy-core/src/smithy_core/retries.py
acquire_initial_retry_token(*, token_scope=None)
¶
Called before any retries (for the first attempt at the operation).
:param token_scope: This argument is ignored by this retry strategy.
Source code in packages/smithy-core/src/smithy_core/retries.py
record_success(*, token)
¶
refresh_retry_token_for_retry(*, token_to_renew, error)
¶
Replace an existing retry token from a failed attempt with a new token.
This retry strategy always returns a token until the attempt count stored in
the new token exceeds the max_attempts
value.
:param token_to_renew: The token used for the previous failed attempt. :param error: The error that triggered the need for a retry. :raises RetryError: If no further retry attempts are allowed.
Source code in packages/smithy-core/src/smithy_core/retries.py
SimpleRetryToken
dataclass
¶
Basic retry token that stores only the attempt count and backoff strategy.
Retry tokens should always be obtained from an implementation of
:py:class:retries_interface.RetryStrategy
.
Source code in packages/smithy-core/src/smithy_core/retries.py
rfc3986
¶
Module vended from rfc3986 abnf_rexexp.py
and misc.py
.
https://github.com/python-hyper/rfc3986/blob/main/src/rfc3986/abnf_regexp.py https://github.com/python-hyper/rfc3986/blob/main/src/rfc3986/misc.py
schemas
¶
APIOperation
dataclass
¶
A modeled Smithy operation.
Source code in packages/smithy-core/src/smithy_core/schemas.py
effective_auth_schemes
instance-attribute
¶
A list of effective auth schemes for the operation.
error_registry
instance-attribute
¶
A TypeRegistry used to create errors.
idempotency_token_member
property
¶
The input schema member that serves as the idempotency token.
input
instance-attribute
¶
The input type of the operation.
input_schema = field(repr=False)
class-attribute
instance-attribute
¶
The schema of the operation's input shape.
input_stream_member
property
¶
The input schema member that contains an event stream or data stream.
output
instance-attribute
¶
The output type of the operation.
output_schema = field(repr=False)
class-attribute
instance-attribute
¶
The schema of the operation's output shape.
output_stream_member
property
¶
The output schema member that contains an event stream or data stream.
schema = field(repr=False)
class-attribute
instance-attribute
¶
The schema of the operation.
MemberSchema
¶
Bases: TypedDict
A simplified schema for members.
This is only used for :ref:Schema.collection
.
:param target: The target of the member. :param traits: An optional list of traits for the member.
Source code in packages/smithy-core/src/smithy_core/schemas.py
Schema
dataclass
¶
Describes a shape, its traits, and its members.
Source code in packages/smithy-core/src/smithy_core/schemas.py
17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 |
|
member_name
property
¶
The name of the member, if the shape is the MEMBER type.
__contains__(item)
¶
Returns whether the schema has the given member or trait.
Source code in packages/smithy-core/src/smithy_core/schemas.py
__init__(*, id, shape_type, traits=None, members=None, member_target=None, member_index=None)
¶
Initialize a schema.
:param id: The ID of the shape. :param shape_type: The type of the shape. :param traits: Traits applied to the shape, which describe additional metadata. :param members: Members of the shape. These correspond to list contents, dataclass properties, map keys/values, and union variants. :param member_target: The schema that the member points to, if the shape is the MEMBER type. :param member_index: The index of the member, if the shape is the MEMBER type. This is used for faster match checks when all members of a shape are known.
Source code in packages/smithy-core/src/smithy_core/schemas.py
collection(*, id, shape_type=ShapeType.STRUCTURE, traits=None, members=None)
classmethod
¶
Create a schema for a collection shape.
:param id: The ID of the shape.
:param shape_type: The type of the shape. Defaults to STRUCTURE.
:param traits: Traits applied to the shape, which describe additional metadata.
:param members: Members of the shape. These correspond to list contents, dataclass
properties, map keys/values, and union variants. In contrast to the main
constructor, this is a dict of member names to a simplified dict containing
only traits
and a target
. Member schemas will be generated from this.
If the value is None, it MUST be populated later. This is to allow a preservation
of modeled order without having to explicitly provide it and therefore generate
a ton of boilerplate.
Source code in packages/smithy-core/src/smithy_core/schemas.py
expect_member_index()
¶
Assert the schema is a member schema and return its member index.
:raises ExpectationNotMetError: If member_index wasn't set. :returns: Returns the member index.
Source code in packages/smithy-core/src/smithy_core/schemas.py
expect_member_name()
¶
Assert the schema is a member schema and return its member name.
:raises ExpectationNotMetError: If member_name wasn't set. :returns: Returns the member name.
Source code in packages/smithy-core/src/smithy_core/schemas.py
expect_member_target()
¶
Assert the schema is a member schema and return its target.
If the target is a class containing a schema, the schema is extracted and returned.
:raises ExpectationNotMetError: If member_target wasn't set. :returns: Returns the target schema.
Source code in packages/smithy-core/src/smithy_core/schemas.py
expect_trait(t)
¶
Get a trait based on its ShapeID or class.
:returns: A Trait if the trait class is known, a DynamicTrait if it isn't.
Source code in packages/smithy-core/src/smithy_core/schemas.py
get_trait(t)
¶
Get a trait based on its ShapeID or class.
:returns: A Trait if the trait class is known, a DynamicTrait if it isn't, or None if the trait is not present on the Schema.
Source code in packages/smithy-core/src/smithy_core/schemas.py
member(id, target, index, member_traits=None)
classmethod
¶
Create a schema for a member shape.
Member schemas are largely copies of the schemas they target to make it easier to use them. They contain all the members of the target and all of the traits of the target. Any traits provided to this method, will override traits of the same type on the member schema.
:param id: The member's id. :param target: The schema the member is targeting. :param index: The member's index.
Source code in packages/smithy-core/src/smithy_core/schemas.py
serializers
¶
InterceptingSerializer
¶
Bases: ShapeSerializer
A shape serializer capable of injecting data before writing.
This can, for example, be used to add in structure member keys, commas between structure members, or commas between lists.
Source code in packages/smithy-core/src/smithy_core/serializers.py
243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 |
|
MapSerializer
¶
Bases: Protocol
Protocol for serializing maps.
These are responsible for writing any data needed between keys and values as well as any data needed between entries.
Source code in packages/smithy-core/src/smithy_core/serializers.py
entry(key, value_writer)
¶
Write a map entry.
:param key: The entry's key. :param value_writer: A callable that accepts a shape serializer to write values.
Source code in packages/smithy-core/src/smithy_core/serializers.py
SerializeableShape
¶
Bases: Protocol
Protocol for shapes that are serializeable using a ShapeSerializer.
Source code in packages/smithy-core/src/smithy_core/serializers.py
serialize(serializer)
¶
Serialize the shape using the given serializer.
:param serializer: The serializer to write shape data to.
SerializeableStruct
¶
Bases: SerializeableShape
, Protocol
Protocol for structures that are serializeable using a ShapeSerializer.
Source code in packages/smithy-core/src/smithy_core/serializers.py
serialize_members(serializer)
¶
Serialize structure members using the given serializer.
:param serializer: The serializer to write member data to.
ShapeSerializer
¶
Bases: Protocol
Protocol for serializing shapes based on the Smithy data model.
If used as a base class, all non-float number methods default to calling
write_integer
and write_double
defaults to calling write_float
.
These extra numeric methods are for types in the Smithy data model that
don't have Python equivalents, but may have equivalents in the format
being written.
Source code in packages/smithy-core/src/smithy_core/serializers.py
18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 |
|
begin_list(schema, size)
¶
Open a list for writing.
The returned context manager is responsible for closing the list when the caller has finished writing elements.
The shape serializer contained in the context manager is responsible for inserting any data needed between elements.
:param schema: The schema of the list. :param size: The size of the list. :returns: A context manager containing an element serializer.
Source code in packages/smithy-core/src/smithy_core/serializers.py
begin_map(schema, size)
¶
Open a map for writing.
The returned context manager is responsible for closing the map when the caller has finished writing members.
The MapSerializer contained in the context manager is responsible for writing out any additional data needed between the entry name and value as well as any data needed between entries.
:param schema: The schema of the map. :param size: The size of the map. :returns: A context manager containing a map serializer.
Source code in packages/smithy-core/src/smithy_core/serializers.py
begin_struct(schema)
¶
Open a structure for writing.
The returned context manager is responsible for closing the structure when the caller has finished writing members.
The shape serializer contained in the context manager is responsible for writing out the member name as well as any additional data needed between the member name and value and between members.
:param schema: The schema of the structure. :returns: A context manager containing a member serializer.
Source code in packages/smithy-core/src/smithy_core/serializers.py
flush()
¶
write_big_decimal(schema, value)
¶
Write a big decimal (arbitrarily large float) value to the output.
:param schema: The shape's schema. :param value: The big decimal value to write.
Source code in packages/smithy-core/src/smithy_core/serializers.py
write_big_integer(schema, value)
¶
Write a big integer (arbirtrarily large integer) value to the output.
:param schema: The shape's schema. :param value: The big integer value to write.
Source code in packages/smithy-core/src/smithy_core/serializers.py
write_blob(schema, value)
¶
Write a blob value to the output.
:param schema: The shape's schema. :param value: The blob value to write.
write_boolean(schema, value)
¶
Write a boolean value to the output.
:param schema: The shape's schema. :param value: The boolean value to write.
write_byte(schema, value)
¶
Write a byte (8-bit integer) value to the output.
:param schema: The shape's schema. :param value: The byte value to write.
Source code in packages/smithy-core/src/smithy_core/serializers.py
write_data_stream(schema, value)
¶
Write a data stream to the output.
If the value is a stream (i.e. not bytes or bytearray) it MUST NOT be read directly by this method. Such values are intended to only be read as needed when sending a message, and so should be bound directly to the request / response type and then read by the transport.
Data streams are only supported at the top-level input and output for operations.
:param schema: The shape's schema. :param value: The streaming value to write.
Source code in packages/smithy-core/src/smithy_core/serializers.py
write_document(schema, value)
¶
Write a document value to the output.
:param schema: The shape's schema. :param value: The document value to write.
write_double(schema, value)
¶
Write a double (64-bit float) value to the output.
:param schema: The shape's schema. :param value: The double value to write.
Source code in packages/smithy-core/src/smithy_core/serializers.py
write_float(schema, value)
¶
Write a float (32-bit) value to the output.
:param schema: The shape's schema. :param value: The float value to write.
write_integer(schema, value)
¶
Write an integer (32-bit) value to the output.
:param schema: The shape's schema. :param value: The integer value to write.
write_long(schema, value)
¶
Write a long (64-bit integer) value to the output.
:param schema: The shape's schema. :param value: The long value to write.
Source code in packages/smithy-core/src/smithy_core/serializers.py
write_null(schema)
¶
write_short(schema, value)
¶
Write a short (16-bit integer) value to the output.
:param schema: The shape's schema. :param value: The short value to write.
Source code in packages/smithy-core/src/smithy_core/serializers.py
write_string(schema, value)
¶
Write a string value to the output.
:param schema: The shape's schema. :param value: The string value to write.
write_struct(schema, struct)
¶
Write a structured shape to the output.
This method is primarily intended to be used to serialize members that target structure or union shapes.
:param schema: The member schema of the structure. :param struct: The structure to serialize.
Source code in packages/smithy-core/src/smithy_core/serializers.py
write_timestamp(schema, value)
¶
Write a timestamp value to the output.
:param schema: The shape's schema. :param value: The timestamp value to write.
Source code in packages/smithy-core/src/smithy_core/serializers.py
SpecificShapeSerializer
¶
Bases: ShapeSerializer
Expects to serialize a specific kind of shape, failing if other shapes are serialized.
Source code in packages/smithy-core/src/smithy_core/serializers.py
shapes
¶
ShapeID
¶
An identifier for a Smithy shape.
Source code in packages/smithy-core/src/smithy_core/shapes.py
member
property
¶
The member name of the shape.
This is only set for member shapes.
name
property
¶
The name of the shape, or the name of the containing shape if the shape is a member.
namespace
property
¶
The namespace of the shape.
__init__(id)
¶
Initialize a ShapeID.
:param id: The string representation of the ID.
Source code in packages/smithy-core/src/smithy_core/shapes.py
expect_member()
¶
Assert the member name is set and get it.
:raises ExpectationNotMetException: If member wasn't set. :returns: Returns the member name.
Source code in packages/smithy-core/src/smithy_core/shapes.py
from_parts(*, namespace, name, member=None)
classmethod
¶
Initialize a ShapeID from component parts instead of a string whole.
:param namesapce: The shape's namespace. :param name: The shape's individual name. :param member: The shape member's name. Only set for member shapes.
Source code in packages/smithy-core/src/smithy_core/shapes.py
with_member(member)
¶
Create a new shape id from the current id with the given member name.
:param member: The member name to use on the new shape id.
Source code in packages/smithy-core/src/smithy_core/shapes.py
ShapeType
¶
Bases: Enum
The type of data that a shape represents.
Source code in packages/smithy-core/src/smithy_core/shapes.py
traits
¶
APIKeyLocation
¶
Bases: Enum
The locations that the api key could be placed in the signed request.
Source code in packages/smithy-core/src/smithy_core/traits.py
DynamicTrait
dataclass
¶
A component that can be attached to a schema to describe additional information about it.
Typed traits can be used by creating a :py:class:Trait
subclass.
Source code in packages/smithy-core/src/smithy_core/traits.py
Trait
dataclass
¶
A component that can be attached to a schema to describe additional information about it.
This is a base class that registers subclasses. Any known subclasses will
automatically be used when constructing schemas. Any unknown traits may instead be
created as a :py:class:DynamicTrait
.
The id
property of subclasses is set during subclass creation by
__init_subclass__
, so it is not necessary for subclasses to set it manually.
Source code in packages/smithy-core/src/smithy_core/traits.py
document_value = None
class-attribute
instance-attribute
¶
The value of the trait as a DocumentValue.
id
class-attribute
¶
The ID of the trait.
new(id, value=None)
staticmethod
¶
Dynamically create a new trait of the given ID.
If the ID corresponds to a known Trait class, that class will be instantiated
and returned. Otherwise, a :py:class:DynamicTrait
will be returned.
:returns: A trait of the given ID with the given value.
Source code in packages/smithy-core/src/smithy_core/traits.py
types
¶
JsonBlob
¶
Bases: bytes
Bytes that contain json data which can be lazily loaded.
Source code in packages/smithy-core/src/smithy_core/types.py
JsonString
¶
Bases: str
A string that contains json data which can be lazily loaded.
Source code in packages/smithy-core/src/smithy_core/types.py
PathPattern
dataclass
¶
A formattable URI path pattern.
The pattern may contain formattable labels, which may be normal labels or greedy labels. Normal labels forbid path separators, greedy labels allow them.
Source code in packages/smithy-core/src/smithy_core/types.py
PropertyKey
dataclass
¶
Bases: PropertyKey[T]
A typed property key.
.. code-block:: python
UNION_PROPERTY: PropertyKey[str | int] = PropertyKey(
key="union",
value_type=str | int,
)
Source code in packages/smithy-core/src/smithy_core/types.py
TimestampFormat
¶
Bases: Enum
Smithy-defined timestamp formats with serialization and deserialization helpers.
See Smithy's docs <https://smithy.io/2.0/spec/protocol-traits.html#smithy-api-timestampformat-trait>
_
for more details.
Source code in packages/smithy-core/src/smithy_core/types.py
DATE_TIME = 'date-time'
class-attribute
instance-attribute
¶
RFC3339 section 5.6 datetime with optional millisecond precision but no UTC offset.
EPOCH_SECONDS = 'epoch-seconds'
class-attribute
instance-attribute
¶
Also known as Unix time, the number of seconds that have elapsed since 00:00:00 Coordinated Universal Time (UTC), Thursday, 1 January 1970, with optional millisecond precision.
HTTP_DATE = 'http-date'
class-attribute
instance-attribute
¶
An HTTP date as defined by the IMF-fixdate production in RFC 9110 section 5.6.7.
deserialize(value)
¶
Deserializes a datetime from a value of the format.
:param value: The timestamp value to deserialize. If the format is EPOCH_SECONDS, the value must be an int or float, or a string containing an int or float. Otherwise, it must be a string. :returns: The provided value as a datetime instance.
Source code in packages/smithy-core/src/smithy_core/types.py
serialize(value)
¶
Serializes a datetime into the timestamp format.
:param value: The timestamp to serialize. :returns: A formatted timestamp. This will be a float for EPOCH_SECONDS, or a string otherwise.
Source code in packages/smithy-core/src/smithy_core/types.py
TypedProperties
¶
Bases: UserDict[str, Any]
, TypedProperties
A map with typed setters and getters.
Keys can be either a string or a :py:class:smithy_core.interfaces.PropertyKey
.
Using a PropertyKey instead of a string enables type checkers to narrow to the
associated value type rather than having to use Any.
Letting the value be either a string or PropertyKey allows consumers who care about typing to get it, and those who don't care about typing to not have to think about it.
No runtime type assertion is performed.
..code-block:: python
foo = PropertyKey(key="foo", value_type=str)
properties = TypedProperties()
properties[foo] = "bar"
assert assert_type(properties[foo], str) == "bar"
assert assert_type(properties["foo"], Any) == "bar"
Note that unions and other special types cannot easily be used here due to being
incompatible with type[T]
. PEP747 proposes a fix to this case, but it has not
yet been accepted. In the meantime, there is a workaround. The PropertyKey must
be assigned to an explicitly typed variable, and the value_type
parameter of
the constructor must have a # type: ignore
comment, like so:
.. code-block:: python
UNION_PROPERTY: PropertyKey[str | int] = PropertyKey(
key="union",
value_type=str | int, # type: ignore
)
properties = TypedProperties()
properties[UNION_PROPERTY] = "foo"
assert assert_type(properties[UNION_PROPERTY], str | int) == "foo"
Type checkers will be able to use such a property as expected.
Source code in packages/smithy-core/src/smithy_core/types.py
189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 |
|
utils
¶
ensure_utc(value)
¶
Ensures that the given datetime is a UTC timezone-aware datetime.
If the datetime isn't timezone-aware, its timezone is set to UTC. If it is aware, it's replaced with the equivalent datetime under UTC.
:param value: A datetime object that may or may not be timezone-aware. :returns: A UTC timezone-aware equivalent datetime.
Source code in packages/smithy-core/src/smithy_core/utils.py
epoch_seconds_to_datetime(value)
¶
Parse numerical epoch timestamps (seconds since 1970) into a datetime in UTC.
Falls back to using timedelta
when fromtimestamp
raises OverflowError
.
From Python's fromtimestamp
documentation: "This may raise OverflowError, if the
timestamp is out of the range of values supported by the platform C localtime()
function, and OSError on localtime() failure. It's common for this to be restricted
to years from 1970 through 2038." This affects 32-bit systems.
Source code in packages/smithy-core/src/smithy_core/utils.py
expect_type(typ, value)
¶
Asserts a value is of the given type and returns it unchanged.
This performs both a runtime assertion and type narrowing during type checking
similar to typing.cast
. If the runtime assertion is not needed, typing.cast
should be preferred.
:param typ: The expected type. :param value: The value which is expected to be the given type. :returns: The given value cast as the given type. :raises SmithyError: If the value does not match the type.
Source code in packages/smithy-core/src/smithy_core/utils.py
limited_parse_float(value)
¶
Asserts a value is a float or a limited set of non-numerical strings and returns it as a float.
:param value: An object that is expected to be a float.
:returns: The given value as a float.
:raises SmithyError: If the value is not a float or one of the strings NaN
,
Infinity
, or -Infinity
.
Source code in packages/smithy-core/src/smithy_core/utils.py
limited_serialize_float(given)
¶
Serializes non-numeric floats to strings.
Numeric floats are returned without alteration.
:param given: A float to be conditionally serialized. :returns: The given float as a float or string.
Source code in packages/smithy-core/src/smithy_core/utils.py
remove_dot_segments(path, remove_consecutive_slashes=False)
¶
Removes dot segments from a path per :rfc:3986#section-5.2.4
.
Optionally removes consecutive slashes.
:param path: The path to modify. :param remove_consecutive_slashes: Whether to remove consecutive slashes. :returns: The path with dot segments removed.
Source code in packages/smithy-core/src/smithy_core/utils.py
serialize_epoch_seconds(given)
¶
Serializes a datetime into a string containing the epoch seconds.
If microseconds
is 0, no fractional part is serialized.
:param given: The datetime to serialize. :returns: A string containing the seconds since the UNIX epoch.
Source code in packages/smithy-core/src/smithy_core/utils.py
serialize_float(given)
¶
Serializes a float to a string.
This ensures non-numeric floats are serialized correctly, and ensures that there is a fractional part.
:param given: A float or Decimal to be serialized. :returns: The string representation of the given float.
Source code in packages/smithy-core/src/smithy_core/utils.py
serialize_rfc3339(given)
¶
Serializes a datetime into an RFC3339 string representation.
If microseconds
is 0, no fractional part is serialized.
:param given: The datetime to serialize. :returns: An RFC3339 formatted timestamp.
Source code in packages/smithy-core/src/smithy_core/utils.py
split_every(given, split_char, n)
¶
Splits a string every nth instance of the given character.
:param given: The string to split. :param split_char: The character to split on. :param n: The number of instances of split_char to see before each split. :returns: A list of strings.
Source code in packages/smithy-core/src/smithy_core/utils.py
strict_parse_bool(given)
¶
Strictly parses a boolean from string.
:param given: A string that is expected to contain either "true" or "false". :returns: The given string parsed to a boolean. :raises ExpectationNotMetError: if the given string is neither "true" nor "false".
Source code in packages/smithy-core/src/smithy_core/utils.py
strict_parse_float(given)
¶
Strictly parses a float from a string.
Unlike float(), this forbids the use of "inf" and case-sensitively matches Infinity and NaN.
:param given: A string that is expected to contain a float. :returns: The given string parsed to a float. :raises ExpectationNotMetError: If the given string isn't a float.