python-socks 2.8.1__py3-none-any.whl → 3.0.0__py3-none-any.whl

python_socks/_helpers.py

@@ -1,44 +1,45 @@
+from __future__ import annotations
+
 import functools
 import re
-from typing import Optional, Tuple
-from urllib.parse import urlparse, unquote
+from urllib.parse import unquote, urlparse
 
 from ._types import ProxyType
 
-# pylint:disable-next=invalid-name
 _ipv4_pattern = (
-    r'^(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}'
-    r'(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$'
+    r"^(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}"
+    r"(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$"
 )
 
-# pylint:disable-next=invalid-name
 _ipv6_pattern = (
-    r'^(?:(?:(?:[A-F0-9]{1,4}:){6}|(?=(?:[A-F0-9]{0,4}:){0,6}'
-    r'(?:[0-9]{1,3}\.){3}[0-9]{1,3}$)(([0-9A-F]{1,4}:){0,5}|:)'
-    r'((:[0-9A-F]{1,4}){1,5}:|:)|::(?:[A-F0-9]{1,4}:){5})'
-    r'(?:(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9]?[0-9])\.){3}'
-    r'(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9]?[0-9])|(?:[A-F0-9]{1,4}:){7}'
-    r'[A-F0-9]{1,4}|(?=(?:[A-F0-9]{0,4}:){0,7}[A-F0-9]{0,4}$)'
-    r'(([0-9A-F]{1,4}:){1,7}|:)((:[0-9A-F]{1,4}){1,7}|:)|(?:[A-F0-9]{1,4}:){7}'
-    r':|:(:[A-F0-9]{1,4}){7})$'
+    r"^(?:(?:(?:[A-F0-9]{1,4}:){6}|(?=(?:[A-F0-9]{0,4}:){0,6}"
+    r"(?:[0-9]{1,3}\.){3}[0-9]{1,3}$)(([0-9A-F]{1,4}:){0,5}|:)"
+    r"((:[0-9A-F]{1,4}){1,5}:|:)|::(?:[A-F0-9]{1,4}:){5})"
+    r"(?:(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9]?[0-9])\.){3}"
+    r"(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9]?[0-9])|(?:[A-F0-9]{1,4}:){7}"
+    r"[A-F0-9]{1,4}|(?=(?:[A-F0-9]{0,4}:){0,7}[A-F0-9]{0,4}$)"
+    r"(([0-9A-F]{1,4}:){1,7}|:)((:[0-9A-F]{1,4}){1,7}|:)|(?:[A-F0-9]{1,4}:){7}"
+    r":|:(:[A-F0-9]{1,4}){7})$"
 )
 
 _ipv4_regex = re.compile(_ipv4_pattern)
 _ipv6_regex = re.compile(_ipv6_pattern, flags=re.IGNORECASE)
-_ipv4_regexb = re.compile(_ipv4_pattern.encode('ascii'))
-_ipv6_regexb = re.compile(_ipv6_pattern.encode('ascii'), flags=re.IGNORECASE)
+_ipv4_regexb = re.compile(_ipv4_pattern.encode("ascii"))
+_ipv6_regexb = re.compile(_ipv6_pattern.encode("ascii"), flags=re.IGNORECASE)
 
 
-def _is_ip_address(regex, regexb, host):
-    # if host is None:
-    #     return False
+def _is_ip_address(
+    regex: re.Pattern[str],
+    regexb: re.Pattern[bytes],
+    host: str | bytes | bytearray | memoryview,
+) -> bool:
     if isinstance(host, str):
         return bool(regex.match(host))
-    elif isinstance(host, (bytes, bytearray, memoryview)):
+    elif isinstance(host, (bytes, bytearray, memoryview)):  # noqa: RET505
         return bool(regexb.match(host))
     else:
-        raise TypeError(
-            '{} [{}] is not a str or bytes'.format(host, type(host))  # pragma: no cover
+        raise TypeError(  # pragma: no cover
+            f"{host} [{type(host)}] is not a str or bytes"
         )
 
 
@@ -46,36 +47,38 @@ is_ipv4_address = functools.partial(_is_ip_address, _ipv4_regex, _ipv4_regexb)
 is_ipv6_address = functools.partial(_is_ip_address, _ipv6_regex, _ipv6_regexb)
 
 
-def is_ip_address(host):
+def is_ip_address(host: str | bytes) -> bool:
     return is_ipv4_address(host) or is_ipv6_address(host)
 
 
-def parse_proxy_url(url: str) -> Tuple[ProxyType, str, int, Optional[str], Optional[str]]:
+def parse_proxy_url(
+    url: str,
+) -> tuple[ProxyType, str, int, str | None, str | None]:
     parsed = urlparse(url)
 
     scheme = parsed.scheme
-    if scheme == 'socks5':
+    if scheme == "socks5":
         proxy_type = ProxyType.SOCKS5
-    elif scheme == 'socks4':
+    elif scheme == "socks4":
         proxy_type = ProxyType.SOCKS4
-    elif scheme == 'http':
+    elif scheme == "http":
         proxy_type = ProxyType.HTTP
     else:
-        raise ValueError(f'Invalid scheme component: {scheme}')  # pragma: no cover
+        raise ValueError(f"Invalid scheme component: {scheme}")  # pragma: no cover
 
     host = parsed.hostname
     if not host:
-        raise ValueError('Empty host component')  # pragma: no cover
+        raise ValueError("Empty host component")  # pragma: no cover
 
     try:
         port = parsed.port
         assert port is not None
     except (ValueError, TypeError, AssertionError) as e:  # pragma: no cover
-        raise ValueError('Invalid port component') from e
+        raise ValueError("Invalid port component") from e
 
     try:
-        username, password = (unquote(parsed.username), unquote(parsed.password))
+        username, password = (unquote(parsed.username), unquote(parsed.password))  # type:ignore[arg-type]
     except (AttributeError, TypeError):
-        username, password = '', ''
+        username, password = "", ""
 
     return proxy_type, host, port, username, password

python_socks/_protocols/errors.py

@@ -1,4 +1,13 @@
+from __future__ import annotations
+
+from typing import Any
+
+
 class ReplyError(Exception):
-    def __init__(self, message, error_code=None):
+    def __init__(
+        self,
+        message: Any,
+        error_code: int | None = None,
+    ) -> None:
         super().__init__(message)
         self.error_code = error_code

python_socks/_protocols/http.py

@@ -1,85 +1,82 @@
-import sys
-from dataclasses import dataclass
+from __future__ import annotations
+
 import base64
 import binascii
-from collections import namedtuple
-from typing import Optional
+import sys
+from dataclasses import dataclass
 
+from .._helpers import is_ipv6_address
 from .._version import __title__, __version__
-
 from .errors import ReplyError
 
-DEFAULT_USER_AGENT = 'Python/{0[0]}.{0[1]} {1}/{2}'.format(
-    sys.version_info,
-    __title__,
-    __version__,
+DEFAULT_USER_AGENT = (
+    f"Python/{sys.version_info[0]}.{sys.version_info[1]} {__title__}/{__version__}"
 )
-
-CRLF = '\r\n'
+CRLF = "\r\n"
 
 
-class BasicAuth(namedtuple('BasicAuth', ['login', 'password', 'encoding'])):
-    """Http basic authentication helper."""
+@dataclass
+class BasicAuth:
+    login: str
+    password: str
+    encoding: str = "latin1"
 
-    def __new__(cls, login: str, password: str = '', encoding: str = 'latin1') -> 'BasicAuth':
-        if login is None:
-            raise ValueError('None is not allowed as login value')
+    def __post_init__(self) -> None:
+        if self.login is None:
+            raise ValueError("None is not allowed as login value")
 
-        if password is None:
-            raise ValueError('None is not allowed as password value')
+        if self.password is None:
+            raise ValueError("None is not allowed as password value")
 
-        if ':' in login:
+        if ":" in self.login:
             raise ValueError('A ":" is not allowed in login (RFC 1945#section-11.1)')
 
-        # noinspection PyTypeChecker,PyArgumentList
-        return super().__new__(cls, login, password, encoding)
-
     @classmethod
-    def decode(cls, auth_header: str, encoding: str = 'latin1') -> 'BasicAuth':
+    def decode(cls, auth_header: str, encoding: str = "latin1") -> BasicAuth:
         """Create a BasicAuth object from an Authorization HTTP header."""
         try:
-            auth_type, encoded_credentials = auth_header.split(' ', 1)
+            auth_type, encoded_credentials = auth_header.split(" ", 1)
         except ValueError:
-            raise ValueError('Could not parse authorization header.')
+            raise ValueError("Could not parse authorization header.")  # noqa: B904
 
-        if auth_type.lower() != 'basic':
-            raise ValueError('Unknown authorization method %s' % auth_type)
+        if auth_type.lower() != "basic":
+            raise ValueError(f"Unknown authorization method {auth_type}")
 
         try:
-            decoded = base64.b64decode(encoded_credentials.encode('ascii'), validate=True).decode(
-                encoding
-            )
+            decoded = base64.b64decode(
+                encoded_credentials.encode("ascii"),
+                validate=True,
+            ).decode(encoding)
         except binascii.Error:
-            raise ValueError('Invalid base64 encoding.')
+            raise ValueError("Invalid base64 encoding.")  # noqa: B904
 
         try:
             # RFC 2617 HTTP Authentication
             # https://www.ietf.org/rfc/rfc2617.txt
             # the colon must be present, but the username and password may be
             # otherwise blank.
-            username, password = decoded.split(':', 1)
+            username, password = decoded.split(":", 1)
         except ValueError:
-            raise ValueError('Invalid credentials.')
+            raise ValueError("Invalid credentials.")  # noqa: B904
 
-        # noinspection PyTypeChecker
-        return cls(username, password, encoding=encoding)
+        return cls(login=username, password=password, encoding=encoding)
 
     def encode(self) -> str:
         """Encode credentials."""
-        creds = ('%s:%s' % (self.login, self.password)).encode(self.encoding)
-        return 'Basic %s' % base64.b64encode(creds).decode(self.encoding)
+        creds = f"{self.login}:{self.password}".encode(self.encoding)
+        return f"Basic {base64.b64encode(creds).decode(self.encoding)}"
 
 
 class _Buffer:
-    def __init__(self, encoding: str = 'utf-8'):
+    def __init__(self, encoding: str = "utf-8") -> None:
         self._encoding = encoding
         self._buffer = bytearray()
 
-    def append_line(self, line: str = ""):
+    def append_line(self, line: str = "") -> None:
         if line:
             self._buffer.extend(line.encode(self._encoding))
 
-        self._buffer.extend(CRLF.encode('ascii'))
+        self._buffer.extend(CRLF.encode("ascii"))
 
     def dumps(self) -> bytes:
         return bytes(self._buffer)
@@ -89,18 +86,27 @@ class _Buffer:
 class ConnectRequest:
     host: str
     port: int
-    username: Optional[str]
-    password: Optional[str]
+    username: str | None
+    password: str | None
 
     def dumps(self) -> bytes:
         buff = _Buffer()
-        buff.append_line(f'CONNECT {self.host}:{self.port} HTTP/1.1')
-        buff.append_line(f'Host: {self.host}:{self.port}')
-        buff.append_line(f'User-Agent: {DEFAULT_USER_AGENT}')
+        # RFC 3986 § 3.2.2 / RFC 7230 § 5.4: a literal IPv6 address in an
+        # authority component must be enclosed in square brackets so the
+        # `:` between literal and port is unambiguous. Without brackets,
+        # `2001:db8::1:443` could be parsed as either the address
+        # `2001:db8::1` with port `443` or the address `2001:db8::1:443`
+        # with no port — proxies disagree, and several misroute the
+        # unbracketed form (typically returning `200 Connection
+        # established` against a connection that was never actually made).
+        host = f"[{self.host}]" if is_ipv6_address(self.host) else self.host
+        buff.append_line(f"CONNECT {host}:{self.port} HTTP/1.1")
+        buff.append_line(f"Host: {host}:{self.port}")
+        buff.append_line(f"User-Agent: {DEFAULT_USER_AGENT}")
 
         if self.username and self.password:
             auth = BasicAuth(self.username, self.password)
-            buff.append_line(f'Proxy-Authorization: {auth.encode()}')
+            buff.append_line(f"Proxy-Authorization: {auth.encode()}")
 
         buff.append_line()
 
@@ -113,33 +119,32 @@ class ConnectReply:
     message: str
 
     @classmethod
-    def loads(cls, data: bytes) -> 'ConnectReply':
+    def loads(cls, data: bytes) -> ConnectReply:
         if not data:
-            raise ReplyError('Invalid proxy response')  # pragma: no cover
+            raise ReplyError("Invalid proxy response")  # pragma: no cover
 
-        line = data.split(CRLF.encode('ascii'), 1)[0]
-        line = line.decode('utf-8', 'surrogateescape')
+        line = data.split(CRLF.encode("ascii"), 1)[0]
+        line = line.decode("utf-8", "surrogateescape")
 
         try:
-            version, code, *reason = line.split()
-        except ValueError:  # pragma: no cover
-            raise ReplyError(f'Invalid status line: {line}')
+            _version, code, *reason = line.split()
+        except ValueError as e:  # pragma: no cover
+            raise ReplyError(f"Invalid status line: {line}") from e
 
         try:
             status_code = int(code)
-        except ValueError:  # pragma: no cover
-            raise ReplyError(f'Invalid status code: {code}')
+        except ValueError as e:  # pragma: no cover
+            raise ReplyError(f"Invalid status code: {code}") from e
 
         status_message = " ".join(reason)
 
-        if status_code != 200:
-            msg = f'{status_code} {status_message}'
+        if status_code != 200:  # noqa: PLR2004
+            msg = f"{status_code} {status_message}"
             raise ReplyError(msg, error_code=status_code)
 
         return cls(status_code=status_code, message=status_message)
 
 
-# noinspection PyMethodMayBeStatic
 class Connection:
     def send(self, request: ConnectRequest) -> bytes:
         return request.dumps()

python_socks/_protocols/socks4.py

@@ -1,11 +1,12 @@
+from __future__ import annotations
+
 import enum
 import ipaddress
 import socket
 from dataclasses import dataclass
-from typing import Optional
 
-from .errors import ReplyError
 from .._helpers import is_ipv4_address
+from .errors import ReplyError
 
 RSV = NULL = 0x00
 SOCKS_VER = 0x04
@@ -24,14 +25,10 @@ class ReplyCode(enum.IntEnum):
 
 
 ReplyMessages = {
-    ReplyCode.REQUEST_GRANTED: 'Request granted',
-    ReplyCode.REQUEST_REJECTED_OR_FAILED: 'Request rejected or failed',
-    ReplyCode.CONNECTION_FAILED: (
-        'Request rejected because SOCKS server cannot connect to identd on the client'
-    ),
-    ReplyCode.AUTHENTICATION_FAILED: (
-        'Request rejected because the client program and identd report different user-ids'
-    ),
+    ReplyCode.REQUEST_GRANTED: "Request granted",
+    ReplyCode.REQUEST_REJECTED_OR_FAILED: "Request rejected or failed",
+    ReplyCode.CONNECTION_FAILED: "Request rejected because SOCKS server cannot connect to identd on the client",  # noqa: E501
+    ReplyCode.AUTHENTICATION_FAILED: "Request rejected because the client program and identd report different user-ids",  # noqa: E501,
 }
 
 
@@ -39,10 +36,10 @@ ReplyMessages = {
 class ConnectRequest:
     host: str  # hostname or IPv4 address
     port: int
-    user_id: Optional[str]
+    user_id: str | None
 
-    def dumps(self):
-        port_bytes = self.port.to_bytes(2, 'big')
+    def dumps(self) -> bytes:
+        port_bytes = self.port.to_bytes(2, "big")
         include_hostname = False
 
         if is_ipv4_address(self.host):
@@ -56,12 +53,12 @@ class ConnectRequest:
         data += host_bytes
 
         if self.user_id:
-            data += self.user_id.encode('ascii')
+            data += self.user_id.encode("ascii")
 
         data.append(NULL)
 
         if include_hostname:
-            data += self.host.encode('idna')
+            data += self.host.encode("idna")
             data.append(NULL)
 
         return bytes(data)
@@ -77,37 +74,36 @@ class ConnectReply:
     port: int  # should be ignored when using Command.CONNECT
 
     @classmethod
-    def loads(cls, data: bytes) -> 'ConnectReply':
+    def loads(cls, data: bytes) -> ConnectReply:
         if len(data) != cls.SIZE:
-            raise ReplyError('Malformed connect reply')
+            raise ReplyError("Malformed connect reply")
 
         rsv = data[0]
         if rsv != RSV:  # pragma: no cover
-            raise ReplyError(f'Unexpected reply version: {data[0]:#02X}')
+            raise ReplyError(f"Unexpected reply version: {data[0]:#02X}")
 
         try:
             reply = ReplyCode(data[1])
-        except ValueError:
-            raise ReplyError(f'Invalid reply code: {data[1]:#02X}')
+        except ValueError as e:
+            raise ReplyError(f"Invalid reply code: {data[1]:#02X}") from e
 
         if reply != ReplyCode.REQUEST_GRANTED:  # pragma: no cover
-            msg = ReplyMessages.get(reply, 'Unknown error')
+            msg = ReplyMessages.get(reply, "Unknown error")
             raise ReplyError(msg, error_code=reply)
 
         try:
             port = int.from_bytes(data[2:4], byteorder="big")
-        except ValueError:
-            raise ReplyError('Invalid port data')
+        except ValueError as e:
+            raise ReplyError("Invalid port data") from e
 
         try:
             host = socket.inet_ntop(socket.AF_INET, data[4:8])
-        except ValueError:
-            raise ReplyError('Invalid port data')
+        except ValueError as e:
+            raise ReplyError("Invalid port data") from e
 
         return cls(rsv=rsv, reply=reply, host=host, port=port)
 
 
-# noinspection PyMethodMayBeStatic
 class Connection:
     def send(self, request: ConnectRequest) -> bytes:
         return request.dumps()