diff options
author | Matus Valo <matusvalo@gmail.com> | 2020-11-09 00:53:50 +0100 |
---|---|---|
committer | Matus Valo <matusvalo@gmail.com> | 2020-11-10 22:29:33 +0100 |
commit | 371d2e9dde816841f4a9004b7a85efe8b58982e8 (patch) | |
tree | e114cd9f4916bfdf8b7c4ac0b1a9c0ceee92dbc9 | |
parent | 986551a9f398a32a5954662883f3b8845bf9b5be (diff) | |
download | py-amqp-371d2e9dde816841f4a9004b7a85efe8b58982e8.tar.gz |
Initial reference documentation amqp.transport
-rw-r--r-- | amqp/connection.py | 7 | ||||
-rw-r--r-- | amqp/transport.py | 185 | ||||
-rw-r--r-- | docs/reference/amqp.transport.rst | 15 |
3 files changed, 191 insertions, 16 deletions
diff --git a/amqp/connection.py b/amqp/connection.py index 0c662b1..e8aaacf 100644 --- a/amqp/connection.py +++ b/amqp/connection.py @@ -94,9 +94,10 @@ class Connection(AbstractChannel): client name. For EXTERNAL authentication both userid and password are ignored. - The 'ssl' parameter may be simply True/False, or for Python >= 3.6 - a dictionary of options to pass to ssl.SSLContext such as - requiring certain certificates. + The 'ssl' parameter may be simply True/False, or + a dictionary of options to pass to :class:`ssl.SSLContext` such as + requiring certain certificates. For details, refer ``ssl`` parameter of + :class:`~amqp.transport.SSLTransport`. The "socket_settings" parameter is a dictionary defining tcp settings which will be applied as socket options. diff --git a/amqp/transport.py b/amqp/transport.py index b183120..7838e6d 100644 --- a/amqp/transport.py +++ b/amqp/transport.py @@ -53,7 +53,36 @@ def to_host_port(host, default=AMQP_PORT): class _AbstractTransport: - """Common superclass for TCP and SSL transports.""" + """Common superclass for TCP and SSL transports. + + PARAMETERS: + host: str + + Broker address in format ``HOSTNAME:PORT``. + + connect_timeout: int + + Timeout of creating new connection. + + read_timeout: int + + sets ``SO_RCVTIMEO`` parameter of socket. + + write_timeout: int + + sets ``SO_SNDTIMEO`` parameter of socket. + + socket_settings: dict + + dictionary containing `optname` and ``optval`` passed to + ``setsockopt(2)``. + + raise_on_initial_eintr: bool + + when True, ``socket.timeout`` is raised + when exception is received during first read. See ``_read()`` for + details. + """ def __init__(self, host, connect_timeout=None, read_timeout=None, write_timeout=None, @@ -255,12 +284,14 @@ class _AbstractTransport: def read_frame(self, unpack=unpack): """Parse AMQP frame. - Frame has following format: - 0 1 3 7 size+7 size+8 - +------+---------+---------+ +-------------+ +-----------+ - | type | channel | size | | payload | | frame-end | - +------+---------+---------+ +-------------+ +-----------+ - octet short long 'size' octets octet + Frame has following format:: + + 0 1 3 7 size+7 size+8 + +------+---------+---------+ +-------------+ +-----------+ + | type | channel | size | | payload | | frame-end | + +------+---------+---------+ +-------------+ +-----------+ + octet short long 'size' octets octet + """ read = self._read read_frame_buffer = EMPTY_BUFFER @@ -328,7 +359,39 @@ class _AbstractTransport: class SSLTransport(_AbstractTransport): - """Transport that works over SSL.""" + """Transport that works over SSL. + + PARAMETERS: + host: str + + Broker address in format ``HOSTNAME:PORT``. + + connect_timeout: int + + Timeout of creating new connection. + + ssl: bool|dict + + parameters of TLS subsystem. + - when ``ssl`` is not dictionary, defaults of TLS are used + - otherwise: + - if ``ssl`` dictionary contains ``context`` key, + :attr:`~SSLTransport._wrap_context` is used for wrapping + socket. ``context`` is a dictionary passed to + :attr:`~SSLTransport._wrap_context` as context parameter. + All others items from ``ssl`` argument are passed as + ``sslopts``. + - if ``ssl`` dictionary does not contain ``context`` key, + :attr:`~SSLTransport._wrap_socket_sni` is used for + wrapping socket. All items in ``ssl`` argument are + passed to :attr:`~SSLTransport._wrap_socket_sni` as + parameters. + + kwargs: + + additional arguments of + :class:`~amqp.transport._AbstractTransport` class + """ def __init__(self, host, connect_timeout=None, ssl=None, **kwargs): self.sslopts = ssl if isinstance(ssl, dict) else {} @@ -348,6 +411,26 @@ class SSLTransport(_AbstractTransport): return self._wrap_socket_sni(sock, **sslopts) def _wrap_context(self, sock, sslopts, check_hostname=None, **ctx_options): + """Wrap socket without SNI headers. + + PARAMETERS: + sock: socket.socket + + Socket to be wrapped. + + sslopts: dict + + Parameters of :attr:`ssl.SSLContext.wrap_socket`. + + check_hostname + + Whether to match the peer cert’s hostname. See + :attr:`ssl.SSLContext.check_hostname` for details. + + ctx_options + + Parameters of :attr:`ssl.create_default_context`. + """ ctx = ssl.create_default_context(**ctx_options) ctx.check_hostname = check_hostname return ctx.wrap_socket(sock, **sslopts) @@ -359,8 +442,61 @@ class SSLTransport(_AbstractTransport): ciphers=None, ssl_version=ssl.PROTOCOL_TLS): """Socket wrap with SNI headers. - stdlib `ssl.SSLContext.wrap_socket` method augmented with support for - setting the server_hostname field required for SNI hostname header + stdlib :attr:`ssl.SSLContext.wrap_socket` method augmented with support + for setting the server_hostname field required for SNI hostname header. + + PARAMETERS: + sock: socket.socket + + Socket to be wrapped. + + keyfile: str + + path to client private key + + certfile: str + + path to client certificate + + server_side: bool + + identifies whether server-side or client-side + behavior is desired from this socket. See + :attr:`~ssl.SSLContext.wrap_socket` for details. + cert_reqs: If set, peers certificate is checked. Possible + values are :attr:`ssl.CERT_OPTIONAL` or + :attr:`ssl.CERT_REQUIRED`. + + ca_certs: str + + path to “certification authority” (CA) certificates + used to validate other peers’ certificates when ``cert_reqs`` + is other than :attr:`ssl.CERT_NONE`. + + do_handshake_on_connect: bool + + specifies whether to do the SSL + handshake automatically. See + :attr:`~ssl.SSLContext.wrap_socket` for details. + + suppress_ragged_eofs (bool): See + :attr:`~ssl.SSLContext.wrap_socket` for details. + + server_hostname: str + + specifies the hostname of the service which + we are connecting to. See :attr:`~ssl.SSLContext.wrap_socket` + for details. + + ciphers: str + + available ciphers for sockets created with this + context. See :attr:`ssl.SSLContext.set_ciphers` + + ssl_version: + + Protocol of the SSL Context. The value is one of + ``ssl.PROTOCOL_*`` constants. """ opts = { 'sock': sock, @@ -438,7 +574,10 @@ class SSLTransport(_AbstractTransport): class TCPTransport(_AbstractTransport): - """Transport that deals directly with TCP socket.""" + """Transport that deals directly with TCP socket. + + All parameters are :class:`~amqp.transport._AbstractTransport` class. + """ def _setup_transport(self): # Setup to _write() directly to the socket, and @@ -476,7 +615,29 @@ def Transport(host, connect_timeout=None, ssl=False, **kwargs): """Create transport. Given a few parameters from the Connection constructor, - select and create a subclass of _AbstractTransport. + select and create a subclass of + :class:`~amqp.transport._AbstractTransport`. + + PARAMETERS: + + host: str + + Broker address in format ``HOSTNAME:PORT``. + + connect_timeout: int + + Timeout of creating new connection. + + ssl: bool|dict + + If set, :class:`~amqp.transport.SSLTransport` is used + and ``ssl`` parameter is passed to it. Otherwise + :class:`~amqp.transport.TCPTransport` is used. + + kwargs: + + additional arguments of :class:`~amqp.transport._AbstractTransport` + class """ transport = SSLTransport if ssl else TCPTransport return transport(host, connect_timeout=connect_timeout, ssl=ssl, **kwargs) diff --git a/docs/reference/amqp.transport.rst b/docs/reference/amqp.transport.rst index 52dda1d..a6c6e45 100644 --- a/docs/reference/amqp.transport.rst +++ b/docs/reference/amqp.transport.rst @@ -6,6 +6,19 @@ :local: .. currentmodule:: amqp.transport -.. automodule:: amqp.transport +.. autoclass:: _AbstractTransport + :members: + :undoc-members: + +.. autoclass:: SSLTransport + :members: + :private-members: _wrap_context, _wrap_socket_sni + :undoc-members: + +.. autoclass:: TCPTransport + :members: + :undoc-members: + +.. autoclass:: Transport :members: :undoc-members: |