Merge pull request #54 from icgood/doc

icgood · web-flow · commit 4b9fec7747e0 · 2023-05-11T20:40:59.000-04:00
Improve docs and error messages
diff --git a/.github/workflows/python-check.yml b/.github/workflows/python-check.yml
@@ -27,7 +27,7 @@ jobs:
           3.11
     - name: Install build tools
       run: |
-        python -m pip install hatch coveralls
+        python -m pip install hatch
     - name: Run test suites, type checks, and linters
       run: |
         hatch run all:check
diff --git a/README.md b/README.md
@@ -4,14 +4,13 @@ proxy-protocol
 PROXY protocol library with [asyncio][2] server implementation.
 
 [![build](https://github.com/icgood/proxy-protocol/actions/workflows/python-check.yml/badge.svg)](https://github.com/icgood/proxy-protocol/actions/workflows/python-check.yml)
-[![Coverage Status](https://coveralls.io/repos/icgood/proxy-protocol/badge.svg)](https://coveralls.io/r/icgood/proxy-protocol)
 [![PyPI](https://img.shields.io/pypi/v/proxy-protocol.svg)](https://pypi.python.org/pypi/proxy-protocol)
 [![PyPI](https://img.shields.io/pypi/pyversions/proxy-protocol.svg)](https://pypi.python.org/pypi/proxy-protocol)
 ![platforms](https://img.shields.io/badge/platform-linux%20%7C%20macOS%20%7C%20windows-blueviolet)
 [![PyPI](https://img.shields.io/pypi/l/proxy-protocol.svg)](https://pypi.python.org/pypi/proxy-protocol)
 
 #### [Specification](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt)
-#### [API Documentation](http://icgood.github.io/proxy-protocol/)
+#### [API Reference](http://icgood.github.io/proxy-protocol/)
 #### [Docker Image](https://github.com/icgood/proxy-protocol/pkgs/container/proxy-protocol)
 
 ### Table of Contents
@@ -41,8 +40,7 @@ from proxyprotocol.sock import SocketInfo
 
 async def run(host: str, port: int) -> None:
     pp_detect = ProxyProtocolDetect()
-    pp_reader = ProxyProtocolReader(pp_detect)
-    callback = reader.get_callback(on_connection)
+    callback = ProxyProtocolReader(pp_detect).get_callback(on_connection)
     server = await asyncio.start_server(callback, host, port)
     async with server:
         await server.serve_forever()
@@ -59,7 +57,7 @@ read from a string.
 ```python
 from proxyprotocol.version import ProxyProtocolVersion
 
-pp_noop = ProxyProtocolVersion.get()
+pp_noop = ProxyProtocolVersion.get(None)
 pp_detect = ProxyProtocolVersion.get('detect')
 pp_v1 = ProxyProtocolVersion.get('v1')
 pp_v2 = ProxyProtocolVersion.get('v2')
@@ -148,4 +146,4 @@ hinting to the extent possible and common in the rest of the codebase.
 [4]: https://github.com/icgood/proxy-protocol/blob/main/proxyprotocol/server/echo.py
 [6]: https://www.python.org/dev/peps/pep-0484/
 [7]: http://mypy-lang.org/
-[8]: https://icgood.github.io/proxy-protocol/proxyprotocol.html#proxyprotocol.server.Address
+[8]: https://icgood.github.io/proxy-protocol/proxyprotocol.server.html#proxyprotocol.server.Address
diff --git a/doc/source/index.rst b/doc/source/index.rst
@@ -23,6 +23,7 @@ Table of Contents
    proxyprotocol.dnsbl
    proxyprotocol.tlv
    proxyprotocol.reader
+   proxyprotocol.server
 
 
 Indices and tables
diff --git a/doc/source/proxyprotocol.server.rst b/doc/source/proxyprotocol.server.rst
@@ -0,0 +1,6 @@
+
+``proxyprotocol.server``
+========================
+
+.. automodule:: proxyprotocol.server
+   :members:
diff --git a/proxyprotocol/__about__.py b/proxyprotocol/__about__.py
@@ -1,2 +1,2 @@
 #: The package version string.
-__version__ = '0.11.0'
+__version__ = '0.11.1'
diff --git a/proxyprotocol/build.py b/proxyprotocol/build.py
@@ -23,6 +23,8 @@ def build_socket_result(sock: socket.socket, *,
 
     Args:
         sock: A connected socket object.
+        unique_id: A unique ID to associate with the connection.
+        dnsbl: The DNSBL lookup result for the connection.
 
     """
     peername: SockAddr = sock.getpeername()
@@ -41,6 +43,8 @@ def build_transport_result(transport: TransportProtocol, *,
 
     Args:
         transport: A connected transport object.
+        unique_id: A unique ID to associate with the connection.
+        dnsbl: The DNSBL lookup result for the connection.
 
     """
     sock: socket.socket = transport.get_extra_info('socket')
diff --git a/proxyprotocol/noop.py b/proxyprotocol/noop.py
@@ -10,7 +10,7 @@
 
 
 class ProxyProtocolNoop(ProxyProtocol):
-    """Implements :class:`~proxyprotocol.base.ProxyProtocol` but does not read
+    """Implements :class:`~proxyprotocol.ProxyProtocol` but does not read
     anything from the stream. A
     :class:`~proxyprotocol.result.ProxyResultLocal` result is always
     returned.
diff --git a/proxyprotocol/result.py b/proxyprotocol/result.py
@@ -2,7 +2,6 @@
 from __future__ import annotations
 
 import socket
-import sys
 from abc import abstractmethod, ABCMeta
 from enum import Enum
 from ipaddress import IPv4Address, IPv6Address
@@ -77,19 +76,32 @@ class ProxyResultType(Enum):
     """The type of proxy result."""
 
     #: The connection is not proxied at all.
-    LOCAL = 1
+    LOCAL = 1, 'AF_UNSPEC'
 
     #: The connection is proxied from an unknown address family.
-    UNKNOWN = 2
+    UNKNOWN = 2, 'AF_UNSPEC'
 
     #: The connection is proxied from an IPv4 address.
-    IPv4 = 3
+    IPv4 = 3, 'AF_INET'
 
     #: The connection is proxied from an IPv6 address.
-    IPv6 = 4
+    IPv6 = 4, 'AF_INET6'
 
     #: The connection is proxied from a UNIX socket.
-    UNIX = 5
+    UNIX = 5, 'AF_UNIX'
+
+    @property
+    def family(self) -> AddressFamily:
+        """The address family corresponding to the proxy result type.
+
+        Raises:
+            AttributeError: The address family does not exist on the current
+                platform, e.g. :data:`~socket.AF_UNIX` on Windows.
+
+        """
+        family_attr = self.value[1]
+        family: AddressFamily = getattr(socket, family_attr)
+        return family
 
 
 class ProxyResult(metaclass=ABCMeta):
@@ -126,8 +138,17 @@ def dest(self) -> Address:
 
     @property
     def family(self) -> AddressFamily:
-        """The original socket address family."""
-        return socket.AF_UNSPEC
+        """The original socket address family.
+
+        See Also:
+            :attr:`ProxyResultType.family`
+
+        Raises:
+            AttributeError: An address family was proxied to a platform that
+                does not support it. Use :attr:`.type` instead when possible.
+
+        """
+        return self.type.family
 
     @property
     def protocol(self) -> Optional[SocketKind]:
@@ -324,10 +345,6 @@ def source(self) -> Tuple[IPv4Address, int]:
     def dest(self) -> Tuple[IPv4Address, int]:
         return self._dest
 
-    @property
-    def family(self) -> AddressFamily:
-        return socket.AF_INET
-
     @property
     def protocol(self) -> Optional[SocketKind]:
         return self._protocol
@@ -384,10 +401,6 @@ def source(self) -> Tuple[IPv6Address, int]:
     def dest(self) -> Tuple[IPv6Address, int]:
         return self._dest
 
-    @property
-    def family(self) -> AddressFamily:
-        return socket.AF_INET6
-
     @property
     def protocol(self) -> Optional[SocketKind]:
         return self._protocol
@@ -443,12 +456,6 @@ def source(self) -> str:
     def dest(self) -> str:
         return self._dest
 
-    @property
-    def family(self) -> AddressFamily:
-        if sys.platform == 'win32':  # pragma: no cover
-            raise AttributeError('AF_UNIX')
-        return socket.AF_UNIX
-
     @property
     def protocol(self) -> Optional[SocketKind]:
         return self._protocol
diff --git a/proxyprotocol/server/__init__.py b/proxyprotocol/server/__init__.py
@@ -62,7 +62,7 @@ def pp(self) -> ProxyProtocol:
 
     @property
     def ssl(self) -> Optional[SSLContext]:
-        """The: class:`~ssl.SSLContext` to use on the address."""
+        """The :class:`~ssl.SSLContext` to use on the address."""
         if self.url.scheme == 'ssl':
             if self._ssl is None:
                 if self.server:
diff --git a/proxyprotocol/sock.py b/proxyprotocol/sock.py
@@ -105,7 +105,7 @@ def sockname(self) -> SockAddr:
         """The local address of the socket.
 
         See Also:
-            :meth:`~socket.socket.getsockname`
+            :meth:`socket.socket.getsockname`
 
         """
         ...
@@ -142,7 +142,7 @@ def peername(self) -> SockAddr:
         """The remote address of the socket.
 
         See Also:
-            :meth:`~socket.socket.getpeername`
+            :meth:`socket.socket.getpeername`
 
         """
         ...
@@ -224,7 +224,8 @@ def cipher(self) -> Optional[Cipher]:
     @property
     @abstractmethod
     def peercert(self) -> Optional[PeerCert]:
-        """The :meth:`~ssl.SSLSocket.peercert` value for encrypted connections.
+        """The :meth:`~ssl.SSLSocket.getpeercert` value for encrypted
+        connections.
 
         Note:
             For proxied connections, this data may be unavailable, depending on
@@ -284,6 +285,8 @@ class SocketInfoProxy(SocketInfo):
     protocol result.
 
     Args:
+        transport: The :class:`~asyncio.BaseTransport` or
+            :class:`~asyncio.StreamWriter` for the connection.
         result: The PROXY protocol result.
 
     """
@@ -376,8 +379,7 @@ class SocketInfoLocal(SocketInfo):
 
     __slots__ = ['_transport', '_unique_id', '_dnsbl']
 
-    def __init__(self, transport: TransportProtocol,
-                 result: Optional[ProxyResult] = None, *,
+    def __init__(self, transport: TransportProtocol, *,
                  unique_id: bytes = b'', dnsbl: Optional[str] = None) -> None:
         super().__init__(transport)
         self._unique_id = unique_id
diff --git a/proxyprotocol/tlv.py b/proxyprotocol/tlv.py
@@ -11,12 +11,17 @@
 from .checksum import crc32c
 from .typing import PeerCert
 
-__all__ = ['Type', 'SSLClient', 'TLV', 'ProxyProtocolTLV',
+__all__ = ['Type', 'SSLClient', 'ExtType', 'TLV', 'ProxyProtocolTLV',
            'ProxyProtocolSSLTLV', 'ProxyProtocolExtTLV']
 
 
 class Type(IntEnum):
-    """The PROXY protocol TLV standard type values."""
+    """The PROXY protocol TLV standard type values.
+
+    See Also:
+        :class:`ProxyProtocolTLV`
+
+    """
 
     PP2_TYPE_ALPN = 0x01
     PP2_TYPE_AUTHORITY = 0x02
@@ -38,23 +43,33 @@ class Type(IntEnum):
     PP2_TYPE_MAX_FUTURE = 0xFF
 
 
-class ExtType(IntEnum):
-    """Non-standard extension TLV types."""
-
-    PP2_TYPE_EXT_COMPRESSION = 0x01
-    PP2_TYPE_EXT_SECRET_BITS = 0x02
-    PP2_TYPE_EXT_PEERCERT = 0x03
-    PP2_TYPE_EXT_DNSBL = 0x04
+class SSLClient(IntFlag):
+    """The PROXY protocol ``PP2_TYPE_SSL`` client flags.
 
+    See Also:
+        :class:`ProxyProtocolSSLTLV`
 
-class SSLClient(IntFlag):
-    """The PROXY protocol ``PP2_TYPE_SSL`` client flags."""
+    """
 
     PP2_CLIENT_SSL = 0x01
     PP2_CLIENT_CERT_CONN = 0x02
     PP2_CLIENT_CERT_SESS = 0x04
 
 
+class ExtType(IntEnum):
+    """Non-standard extension TLV types.
+
+    See Also:
+        :class:`ProxyProtocolExtTLV`
+
+    """
+
+    PP2_TYPE_EXT_COMPRESSION = 0x01
+    PP2_TYPE_EXT_SECRET_BITS = 0x02
+    PP2_TYPE_EXT_PEERCERT = 0x03
+    PP2_TYPE_EXT_DNSBL = 0x04
+
+
 class TLV(Mapping[int, bytes], Hashable):
     """Defines the basic parsing and structure of a PROXY protocol TLV vector.
     The unpacked TLV values are available as dict-style keys of this object,
@@ -454,8 +469,8 @@ def key_alg(self) -> Optional[str]:
 
 
 class ProxyProtocolExtTLV(TLV):
-    """Non-standard extension TLV, which is hidden inside a ``PP2_TYPE_NOOP``
-    and must start with :attr:`.MAGIC_PREFIX`.
+    """Non-standard extension TLV, which is hidden inside a
+    :attr:`~Type.PP2_TYPE_NOOP` and must start with :attr:`.MAGIC_PREFIX`.
 
     Args:
         data: TLV data to parse.
@@ -464,8 +479,8 @@ class ProxyProtocolExtTLV(TLV):
 
     """
 
-    #: The ``PP2_TYPE_NOOP`` value must begin with this byte sequence to be
-    #: parsed as a :class:`ProxyProtocolExtTLV`.
+    #: The :attr:`~Type.PP2_TYPE_NOOP` value must begin with this byte sequence
+    #: to be parsed as a :class:`ProxyProtocolExtTLV`.
     MAGIC_PREFIX: ClassVar[bytes] = b'\x88\x1b\x79\xc1\xce\x96\x85\xb0'
 
     _secret_bits_fmt = Struct('!H')
@@ -503,8 +518,8 @@ def _pack(self) -> bytes:
 
     @property
     def compression(self) -> Optional[str]:
-        """The ``PP2_TYPE_EXT_COMPRESSION`` value. This is used by the
-        :attr:`~proxyprotocol.sock.SocketInfo.compression` value.
+        """The :attr:`~ExtType.PP2_TYPE_EXT_COMPRESSION` value. This is used by
+        the :attr:`~proxyprotocol.sock.SocketInfo.compression` value.
 
         """
         val = self.get(ExtType.PP2_TYPE_EXT_COMPRESSION)
@@ -514,9 +529,9 @@ def compression(self) -> Optional[str]:
 
     @property
     def secret_bits(self) -> Optional[int]:
-        """The ``PP2_TYPE_EXT_SECRET_BITS`` value. This is used to populate
-        the third member of the: attr:`~proxyprotocol.sock.SocketInfo.cipher`
-        tuple.
+        """The :attr:`~ExtType.PP2_TYPE_EXT_SECRET_BITS` value. This is used to
+        populate the third member of the
+        :attr:`~proxyprotocol.sock.SocketInfo.cipher` tuple.
 
         """
         val = self.get(ExtType.PP2_TYPE_EXT_SECRET_BITS)
@@ -527,8 +542,8 @@ def secret_bits(self) -> Optional[int]:
 
     @property
     def peercert(self) -> Optional[PeerCert]:
-        """The ``PP2_TYPE_EXT_PEERCERT`` value. This is used by the
-        :attr:`~proxyprotocol.sock.SocketInfo.peercert` value.
+        """The :attr:`~ExtType.PP2_TYPE_EXT_PEERCERT` value. This is used by
+        the :attr:`~proxyprotocol.sock.SocketInfo.peercert` value.
 
         """
         val = self.get(ExtType.PP2_TYPE_EXT_PEERCERT)
@@ -540,9 +555,9 @@ def peercert(self) -> Optional[PeerCert]:
 
     @property
     def dnsbl(self) -> Optional[str]:
-        """The ``PP2_TYPE_EXT_DNSBL`` value. This is the hostname or other
-        identifier that reports a status or reputation of the connecting IP
-        address.
+        """The :attr:`~ExtType.PP2_TYPE_EXT_DNSBL` value. This is the hostname
+        or other identifier that reports a status or reputation of the
+        connecting IP address.
 
         """
         val = self.get(ExtType.PP2_TYPE_EXT_DNSBL)
diff --git a/pyproject.toml b/pyproject.toml
diff --git a/test/test_build.py b/test/test_build.py
diff --git a/test/test_result.py b/test/test_result.py
diff --git a/test/test_sock.py b/test/test_sock.py
diff --git a/test/test_v2.py b/test/test_v2.py

Original file line number	Diff line number	Diff line change
`@@ -1,2 +1,2 @@`
`1`	`1`	`#: The package version string.`
`2`		`-__version__ = '0.11.0'`
	`2`	`+__version__ = '0.11.1'`