hmdev-cli 1.0.0

package/python/.venv/Lib/site-packages/anyio/_core/_sockets.py

@@ -0,0 +1,1003 @@
+from __future__ import annotations
+
+import errno
+import os
+import socket
+import ssl
+import stat
+import sys
+from collections.abc import Awaitable
+from dataclasses import dataclass
+from ipaddress import IPv4Address, IPv6Address, ip_address
+from os import PathLike, chmod
+from socket import AddressFamily, SocketKind
+from typing import TYPE_CHECKING, Any, Literal, cast, overload
+
+from .. import ConnectionFailed, to_thread
+from ..abc import (
+    ByteStreamConnectable,
+    ConnectedUDPSocket,
+    ConnectedUNIXDatagramSocket,
+    IPAddressType,
+    IPSockAddrType,
+    SocketListener,
+    SocketStream,
+    UDPSocket,
+    UNIXDatagramSocket,
+    UNIXSocketStream,
+)
+from ..streams.stapled import MultiListener
+from ..streams.tls import TLSConnectable, TLSStream
+from ._eventloop import get_async_backend
+from ._resources import aclose_forcefully
+from ._synchronization import Event
+from ._tasks import create_task_group, move_on_after
+
+if TYPE_CHECKING:
+    from _typeshed import FileDescriptorLike
+else:
+    FileDescriptorLike = object
+
+if sys.version_info < (3, 11):
+    from exceptiongroup import ExceptionGroup
+
+if sys.version_info >= (3, 12):
+    from typing import override
+else:
+    from typing_extensions import override
+
+if sys.version_info < (3, 13):
+    from typing_extensions import deprecated
+else:
+    from warnings import deprecated
+
+IPPROTO_IPV6 = getattr(socket, "IPPROTO_IPV6", 41)  # https://bugs.python.org/issue29515
+
+AnyIPAddressFamily = Literal[
+    AddressFamily.AF_UNSPEC, AddressFamily.AF_INET, AddressFamily.AF_INET6
+]
+IPAddressFamily = Literal[AddressFamily.AF_INET, AddressFamily.AF_INET6]
+
+
+# tls_hostname given
+@overload
+async def connect_tcp(
+    remote_host: IPAddressType,
+    remote_port: int,
+    *,
+    local_host: IPAddressType | None = ...,
+    ssl_context: ssl.SSLContext | None = ...,
+    tls_standard_compatible: bool = ...,
+    tls_hostname: str,
+    happy_eyeballs_delay: float = ...,
+) -> TLSStream: ...
+
+
+# ssl_context given
+@overload
+async def connect_tcp(
+    remote_host: IPAddressType,
+    remote_port: int,
+    *,
+    local_host: IPAddressType | None = ...,
+    ssl_context: ssl.SSLContext,
+    tls_standard_compatible: bool = ...,
+    tls_hostname: str | None = ...,
+    happy_eyeballs_delay: float = ...,
+) -> TLSStream: ...
+
+
+# tls=True
+@overload
+async def connect_tcp(
+    remote_host: IPAddressType,
+    remote_port: int,
+    *,
+    local_host: IPAddressType | None = ...,
+    tls: Literal[True],
+    ssl_context: ssl.SSLContext | None = ...,
+    tls_standard_compatible: bool = ...,
+    tls_hostname: str | None = ...,
+    happy_eyeballs_delay: float = ...,
+) -> TLSStream: ...
+
+
+# tls=False
+@overload
+async def connect_tcp(
+    remote_host: IPAddressType,
+    remote_port: int,
+    *,
+    local_host: IPAddressType | None = ...,
+    tls: Literal[False],
+    ssl_context: ssl.SSLContext | None = ...,
+    tls_standard_compatible: bool = ...,
+    tls_hostname: str | None = ...,
+    happy_eyeballs_delay: float = ...,
+) -> SocketStream: ...
+
+
+# No TLS arguments
+@overload
+async def connect_tcp(
+    remote_host: IPAddressType,
+    remote_port: int,
+    *,
+    local_host: IPAddressType | None = ...,
+    happy_eyeballs_delay: float = ...,
+) -> SocketStream: ...
+
+
+async def connect_tcp(
+    remote_host: IPAddressType,
+    remote_port: int,
+    *,
+    local_host: IPAddressType | None = None,
+    tls: bool = False,
+    ssl_context: ssl.SSLContext | None = None,
+    tls_standard_compatible: bool = True,
+    tls_hostname: str | None = None,
+    happy_eyeballs_delay: float = 0.25,
+) -> SocketStream | TLSStream:
+    """
+    Connect to a host using the TCP protocol.
+
+    This function implements the stateless version of the Happy Eyeballs algorithm (RFC
+    6555). If ``remote_host`` is a host name that resolves to multiple IP addresses,
+    each one is tried until one connection attempt succeeds. If the first attempt does
+    not connected within 250 milliseconds, a second attempt is started using the next
+    address in the list, and so on. On IPv6 enabled systems, an IPv6 address (if
+    available) is tried first.
+
+    When the connection has been established, a TLS handshake will be done if either
+    ``ssl_context`` or ``tls_hostname`` is not ``None``, or if ``tls`` is ``True``.
+
+    :param remote_host: the IP address or host name to connect to
+    :param remote_port: port on the target host to connect to
+    :param local_host: the interface address or name to bind the socket to before
+        connecting
+    :param tls: ``True`` to do a TLS handshake with the connected stream and return a
+        :class:`~anyio.streams.tls.TLSStream` instead
+    :param ssl_context: the SSL context object to use (if omitted, a default context is
+        created)
+    :param tls_standard_compatible: If ``True``, performs the TLS shutdown handshake
+        before closing the stream and requires that the server does this as well.
+        Otherwise, :exc:`~ssl.SSLEOFError` may be raised during reads from the stream.
+        Some protocols, such as HTTP, require this option to be ``False``.
+        See :meth:`~ssl.SSLContext.wrap_socket` for details.
+    :param tls_hostname: host name to check the server certificate against (defaults to
+        the value of ``remote_host``)
+    :param happy_eyeballs_delay: delay (in seconds) before starting the next connection
+        attempt
+    :return: a socket stream object if no TLS handshake was done, otherwise a TLS stream
+    :raises ConnectionFailed: if the connection fails
+
+    """
+    # Placed here due to https://github.com/python/mypy/issues/7057
+    connected_stream: SocketStream | None = None
+
+    async def try_connect(remote_host: str, event: Event) -> None:
+        nonlocal connected_stream
+        try:
+            stream = await asynclib.connect_tcp(remote_host, remote_port, local_address)
+        except OSError as exc:
+            oserrors.append(exc)
+            return
+        else:
+            if connected_stream is None:
+                connected_stream = stream
+                tg.cancel_scope.cancel()
+            else:
+                await stream.aclose()
+        finally:
+            event.set()
+
+    asynclib = get_async_backend()
+    local_address: IPSockAddrType | None = None
+    family = socket.AF_UNSPEC
+    if local_host:
+        gai_res = await getaddrinfo(str(local_host), None)
+        family, *_, local_address = gai_res[0]
+
+    target_host = str(remote_host)
+    try:
+        addr_obj = ip_address(remote_host)
+    except ValueError:
+        addr_obj = None
+
+    if addr_obj is not None:
+        if isinstance(addr_obj, IPv6Address):
+            target_addrs = [(socket.AF_INET6, addr_obj.compressed)]
+        else:
+            target_addrs = [(socket.AF_INET, addr_obj.compressed)]
+    else:
+        # getaddrinfo() will raise an exception if name resolution fails
+        gai_res = await getaddrinfo(
+            target_host, remote_port, family=family, type=socket.SOCK_STREAM
+        )
+
+        # Organize the list so that the first address is an IPv6 address (if available)
+        # and the second one is an IPv4 addresses. The rest can be in whatever order.
+        v6_found = v4_found = False
+        target_addrs = []
+        for af, *_, sa in gai_res:
+            if af == socket.AF_INET6 and not v6_found:
+                v6_found = True
+                target_addrs.insert(0, (af, sa[0]))
+            elif af == socket.AF_INET and not v4_found and v6_found:
+                v4_found = True
+                target_addrs.insert(1, (af, sa[0]))
+            else:
+                target_addrs.append((af, sa[0]))
+
+    oserrors: list[OSError] = []
+    try:
+        async with create_task_group() as tg:
+            for _af, addr in target_addrs:
+                event = Event()
+                tg.start_soon(try_connect, addr, event)
+                with move_on_after(happy_eyeballs_delay):
+                    await event.wait()
+
+        if connected_stream is None:
+            cause = (
+                oserrors[0]
+                if len(oserrors) == 1
+                else ExceptionGroup("multiple connection attempts failed", oserrors)
+            )
+            raise OSError("All connection attempts failed") from cause
+    finally:
+        oserrors.clear()
+
+    if tls or tls_hostname or ssl_context:
+        try:
+            return await TLSStream.wrap(
+                connected_stream,
+                server_side=False,
+                hostname=tls_hostname or str(remote_host),
+                ssl_context=ssl_context,
+                standard_compatible=tls_standard_compatible,
+            )
+        except BaseException:
+            await aclose_forcefully(connected_stream)
+            raise
+
+    return connected_stream
+
+
+async def connect_unix(path: str | bytes | PathLike[Any]) -> UNIXSocketStream:
+    """
+    Connect to the given UNIX socket.
+
+    Not available on Windows.
+
+    :param path: path to the socket
+    :return: a socket stream object
+    :raises ConnectionFailed: if the connection fails
+
+    """
+    path = os.fspath(path)
+    return await get_async_backend().connect_unix(path)
+
+
+async def create_tcp_listener(
+    *,
+    local_host: IPAddressType | None = None,
+    local_port: int = 0,
+    family: AnyIPAddressFamily = socket.AddressFamily.AF_UNSPEC,
+    backlog: int = 65536,
+    reuse_port: bool = False,
+) -> MultiListener[SocketStream]:
+    """
+    Create a TCP socket listener.
+
+    :param local_port: port number to listen on
+    :param local_host: IP address of the interface to listen on. If omitted, listen on
+        all IPv4 and IPv6 interfaces. To listen on all interfaces on a specific address
+        family, use ``0.0.0.0`` for IPv4 or ``::`` for IPv6.
+    :param family: address family (used if ``local_host`` was omitted)
+    :param backlog: maximum number of queued incoming connections (up to a maximum of
+        2**16, or 65536)
+    :param reuse_port: ``True`` to allow multiple sockets to bind to the same
+        address/port (not supported on Windows)
+    :return: a multi-listener object containing one or more socket listeners
+    :raises OSError: if there's an error creating a socket, or binding to one or more
+        interfaces failed
+
+    """
+    asynclib = get_async_backend()
+    backlog = min(backlog, 65536)
+    local_host = str(local_host) if local_host is not None else None
+
+    def setup_raw_socket(
+        fam: AddressFamily,
+        bind_addr: tuple[str, int] | tuple[str, int, int, int],
+        *,
+        v6only: bool = True,
+    ) -> socket.socket:
+        sock = socket.socket(fam)
+        try:
+            sock.setblocking(False)
+
+            if fam == AddressFamily.AF_INET6:
+                sock.setsockopt(IPPROTO_IPV6, socket.IPV6_V6ONLY, v6only)
+
+            # For Windows, enable exclusive address use. For others, enable address
+            # reuse.
+            if sys.platform == "win32":
+                sock.setsockopt(socket.SOL_SOCKET, socket.SO_EXCLUSIVEADDRUSE, 1)
+            else:
+                sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+
+            if reuse_port:
+                sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEPORT, 1)
+
+            # Workaround for #554
+            if fam == socket.AF_INET6 and "%" in bind_addr[0]:
+                addr, scope_id = bind_addr[0].split("%", 1)
+                bind_addr = (addr, bind_addr[1], 0, int(scope_id))
+
+            sock.bind(bind_addr)
+            sock.listen(backlog)
+        except BaseException:
+            sock.close()
+            raise
+
+        return sock
+
+    # We passing type=0 on non-Windows platforms as a workaround for a uvloop bug
+    # where we don't get the correct scope ID for IPv6 link-local addresses when passing
+    # type=socket.SOCK_STREAM to getaddrinfo():
+    # https://github.com/MagicStack/uvloop/issues/539
+    gai_res = await getaddrinfo(
+        local_host,
+        local_port,
+        family=family,
+        type=socket.SOCK_STREAM if sys.platform == "win32" else 0,
+        flags=socket.AI_PASSIVE | socket.AI_ADDRCONFIG,
+    )
+
+    # The set comprehension is here to work around a glibc bug:
+    # https://sourceware.org/bugzilla/show_bug.cgi?id=14969
+    sockaddrs = sorted({res for res in gai_res if res[1] == SocketKind.SOCK_STREAM})
+
+    # Special case for dual-stack binding on the "any" interface
+    if (
+        local_host is None
+        and family == AddressFamily.AF_UNSPEC
+        and socket.has_dualstack_ipv6()
+        and any(fam == AddressFamily.AF_INET6 for fam, *_ in gai_res)
+    ):
+        raw_socket = setup_raw_socket(
+            AddressFamily.AF_INET6, ("::", local_port), v6only=False
+        )
+        listener = asynclib.create_tcp_listener(raw_socket)
+        return MultiListener([listener])
+
+    errors: list[OSError] = []
+    try:
+        for _ in range(len(sockaddrs)):
+            listeners: list[SocketListener] = []
+            bound_ephemeral_port = local_port
+            try:
+                for fam, *_, sockaddr in sockaddrs:
+                    sockaddr = sockaddr[0], bound_ephemeral_port, *sockaddr[2:]
+                    raw_socket = setup_raw_socket(fam, sockaddr)
+
+                    # Store the assigned port if an ephemeral port was requested, so
+                    # we'll bind to the same port on all interfaces
+                    if local_port == 0 and len(gai_res) > 1:
+                        bound_ephemeral_port = raw_socket.getsockname()[1]
+
+                    listeners.append(asynclib.create_tcp_listener(raw_socket))
+            except BaseException as exc:
+                for listener in listeners:
+                    await listener.aclose()
+
+                # If an ephemeral port was requested but binding the assigned port
+                # failed for another interface, rotate the address list and try again
+                if (
+                    isinstance(exc, OSError)
+                    and exc.errno == errno.EADDRINUSE
+                    and local_port == 0
+                    and bound_ephemeral_port
+                ):
+                    errors.append(exc)
+                    sockaddrs.append(sockaddrs.pop(0))
+                    continue
+
+                raise
+
+            return MultiListener(listeners)
+
+        raise OSError(
+            f"Could not create {len(sockaddrs)} listeners with a consistent port"
+        ) from ExceptionGroup("Several bind attempts failed", errors)
+    finally:
+        del errors  # Prevent reference cycles
+
+
+async def create_unix_listener(
+    path: str | bytes | PathLike[Any],
+    *,
+    mode: int | None = None,
+    backlog: int = 65536,
+) -> SocketListener:
+    """
+    Create a UNIX socket listener.
+
+    Not available on Windows.
+
+    :param path: path of the socket
+    :param mode: permissions to set on the socket
+    :param backlog: maximum number of queued incoming connections (up to a maximum of
+        2**16, or 65536)
+    :return: a listener object
+
+    .. versionchanged:: 3.0
+        If a socket already exists on the file system in the given path, it will be
+        removed first.
+
+    """
+    backlog = min(backlog, 65536)
+    raw_socket = await setup_unix_local_socket(path, mode, socket.SOCK_STREAM)
+    try:
+        raw_socket.listen(backlog)
+        return get_async_backend().create_unix_listener(raw_socket)
+    except BaseException:
+        raw_socket.close()
+        raise
+
+
+async def create_udp_socket(
+    family: AnyIPAddressFamily = AddressFamily.AF_UNSPEC,
+    *,
+    local_host: IPAddressType | None = None,
+    local_port: int = 0,
+    reuse_port: bool = False,
+) -> UDPSocket:
+    """
+    Create a UDP socket.
+
+    If ``port`` has been given, the socket will be bound to this port on the local
+    machine, making this socket suitable for providing UDP based services.
+
+    :param family: address family (``AF_INET`` or ``AF_INET6``) – automatically
+        determined from ``local_host`` if omitted
+    :param local_host: IP address or host name of the local interface to bind to
+    :param local_port: local port to bind to
+    :param reuse_port: ``True`` to allow multiple sockets to bind to the same
+        address/port (not supported on Windows)
+    :return: a UDP socket
+
+    """
+    if family is AddressFamily.AF_UNSPEC and not local_host:
+        raise ValueError('Either "family" or "local_host" must be given')
+
+    if local_host:
+        gai_res = await getaddrinfo(
+            str(local_host),
+            local_port,
+            family=family,
+            type=socket.SOCK_DGRAM,
+            flags=socket.AI_PASSIVE | socket.AI_ADDRCONFIG,
+        )
+        family = cast(AnyIPAddressFamily, gai_res[0][0])
+        local_address = gai_res[0][-1]
+    elif family is AddressFamily.AF_INET6:
+        local_address = ("::", 0)
+    else:
+        local_address = ("0.0.0.0", 0)
+
+    sock = await get_async_backend().create_udp_socket(
+        family, local_address, None, reuse_port
+    )
+    return cast(UDPSocket, sock)
+
+
+async def create_connected_udp_socket(
+    remote_host: IPAddressType,
+    remote_port: int,
+    *,
+    family: AnyIPAddressFamily = AddressFamily.AF_UNSPEC,
+    local_host: IPAddressType | None = None,
+    local_port: int = 0,
+    reuse_port: bool = False,
+) -> ConnectedUDPSocket:
+    """
+    Create a connected UDP socket.
+
+    Connected UDP sockets can only communicate with the specified remote host/port, an
+    any packets sent from other sources are dropped.
+
+    :param remote_host: remote host to set as the default target
+    :param remote_port: port on the remote host to set as the default target
+    :param family: address family (``AF_INET`` or ``AF_INET6``) – automatically
+        determined from ``local_host`` or ``remote_host`` if omitted
+    :param local_host: IP address or host name of the local interface to bind to
+    :param local_port: local port to bind to
+    :param reuse_port: ``True`` to allow multiple sockets to bind to the same
+        address/port (not supported on Windows)
+    :return: a connected UDP socket
+
+    """
+    local_address = None
+    if local_host:
+        gai_res = await getaddrinfo(
+            str(local_host),
+            local_port,
+            family=family,
+            type=socket.SOCK_DGRAM,
+            flags=socket.AI_PASSIVE | socket.AI_ADDRCONFIG,
+        )
+        family = cast(AnyIPAddressFamily, gai_res[0][0])
+        local_address = gai_res[0][-1]
+
+    gai_res = await getaddrinfo(
+        str(remote_host), remote_port, family=family, type=socket.SOCK_DGRAM
+    )
+    family = cast(AnyIPAddressFamily, gai_res[0][0])
+    remote_address = gai_res[0][-1]
+
+    sock = await get_async_backend().create_udp_socket(
+        family, local_address, remote_address, reuse_port
+    )
+    return cast(ConnectedUDPSocket, sock)
+
+
+async def create_unix_datagram_socket(
+    *,
+    local_path: None | str | bytes | PathLike[Any] = None,
+    local_mode: int | None = None,
+) -> UNIXDatagramSocket:
+    """
+    Create a UNIX datagram socket.
+
+    Not available on Windows.
+
+    If ``local_path`` has been given, the socket will be bound to this path, making this
+    socket suitable for receiving datagrams from other processes. Other processes can
+    send datagrams to this socket only if ``local_path`` is set.
+
+    If a socket already exists on the file system in the ``local_path``, it will be
+    removed first.
+
+    :param local_path: the path on which to bind to
+    :param local_mode: permissions to set on the local socket
+    :return: a UNIX datagram socket
+
+    """
+    raw_socket = await setup_unix_local_socket(
+        local_path, local_mode, socket.SOCK_DGRAM
+    )
+    return await get_async_backend().create_unix_datagram_socket(raw_socket, None)
+
+
+async def create_connected_unix_datagram_socket(
+    remote_path: str | bytes | PathLike[Any],
+    *,
+    local_path: None | str | bytes | PathLike[Any] = None,
+    local_mode: int | None = None,
+) -> ConnectedUNIXDatagramSocket:
+    """
+    Create a connected UNIX datagram socket.
+
+    Connected datagram sockets can only communicate with the specified remote path.
+
+    If ``local_path`` has been given, the socket will be bound to this path, making
+    this socket suitable for receiving datagrams from other processes. Other processes
+    can send datagrams to this socket only if ``local_path`` is set.
+
+    If a socket already exists on the file system in the ``local_path``, it will be
+    removed first.
+
+    :param remote_path: the path to set as the default target
+    :param local_path: the path on which to bind to
+    :param local_mode: permissions to set on the local socket
+    :return: a connected UNIX datagram socket
+
+    """
+    remote_path = os.fspath(remote_path)
+    raw_socket = await setup_unix_local_socket(
+        local_path, local_mode, socket.SOCK_DGRAM
+    )
+    return await get_async_backend().create_unix_datagram_socket(
+        raw_socket, remote_path
+    )
+
+
+async def getaddrinfo(
+    host: bytes | str | None,
+    port: str | int | None,
+    *,
+    family: int | AddressFamily = 0,
+    type: int | SocketKind = 0,
+    proto: int = 0,
+    flags: int = 0,
+) -> list[tuple[AddressFamily, SocketKind, int, str, tuple[str, int]]]:
+    """
+    Look up a numeric IP address given a host name.
+
+    Internationalized domain names are translated according to the (non-transitional)
+    IDNA 2008 standard.
+
+    .. note:: 4-tuple IPv6 socket addresses are automatically converted to 2-tuples of
+        (host, port), unlike what :func:`socket.getaddrinfo` does.
+
+    :param host: host name
+    :param port: port number
+    :param family: socket family (`'AF_INET``, ...)
+    :param type: socket type (``SOCK_STREAM``, ...)
+    :param proto: protocol number
+    :param flags: flags to pass to upstream ``getaddrinfo()``
+    :return: list of tuples containing (family, type, proto, canonname, sockaddr)
+
+    .. seealso:: :func:`socket.getaddrinfo`
+
+    """
+    # Handle unicode hostnames
+    if isinstance(host, str):
+        try:
+            encoded_host: bytes | None = host.encode("ascii")
+        except UnicodeEncodeError:
+            import idna
+
+            encoded_host = idna.encode(host, uts46=True)
+    else:
+        encoded_host = host
+
+    gai_res = await get_async_backend().getaddrinfo(
+        encoded_host, port, family=family, type=type, proto=proto, flags=flags
+    )
+    return [
+        (family, type, proto, canonname, convert_ipv6_sockaddr(sockaddr))
+        for family, type, proto, canonname, sockaddr in gai_res
+        # filter out IPv6 results when IPv6 is disabled
+        if not isinstance(sockaddr[0], int)
+    ]
+
+
+def getnameinfo(sockaddr: IPSockAddrType, flags: int = 0) -> Awaitable[tuple[str, str]]:
+    """
+    Look up the host name of an IP address.
+
+    :param sockaddr: socket address (e.g. (ipaddress, port) for IPv4)
+    :param flags: flags to pass to upstream ``getnameinfo()``
+    :return: a tuple of (host name, service name)
+    :raises NoEventLoopError: if no supported asynchronous event loop is running in the
+        current thread
+
+    .. seealso:: :func:`socket.getnameinfo`
+
+    """
+    return get_async_backend().getnameinfo(sockaddr, flags)
+
+
+@deprecated("This function is deprecated; use `wait_readable` instead")
+def wait_socket_readable(sock: socket.socket) -> Awaitable[None]:
+    """
+    .. deprecated:: 4.7.0
+       Use :func:`wait_readable` instead.
+
+    Wait until the given socket has data to be read.
+
+    .. warning:: Only use this on raw sockets that have not been wrapped by any higher
+        level constructs like socket streams!
+
+    :param sock: a socket object
+    :raises ~anyio.ClosedResourceError: if the socket was closed while waiting for the
+        socket to become readable
+    :raises ~anyio.BusyResourceError: if another task is already waiting for the socket
+        to become readable
+    :raises NoEventLoopError: if no supported asynchronous event loop is running in the
+        current thread
+
+    """
+    return get_async_backend().wait_readable(sock.fileno())
+
+
+@deprecated("This function is deprecated; use `wait_writable` instead")
+def wait_socket_writable(sock: socket.socket) -> Awaitable[None]:
+    """
+    .. deprecated:: 4.7.0
+       Use :func:`wait_writable` instead.
+
+    Wait until the given socket can be written to.
+
+    This does **NOT** work on Windows when using the asyncio backend with a proactor
+    event loop (default on py3.8+).
+
+    .. warning:: Only use this on raw sockets that have not been wrapped by any higher
+        level constructs like socket streams!
+
+    :param sock: a socket object
+    :raises ~anyio.ClosedResourceError: if the socket was closed while waiting for the
+        socket to become writable
+    :raises ~anyio.BusyResourceError: if another task is already waiting for the socket
+        to become writable
+    :raises NoEventLoopError: if no supported asynchronous event loop is running in the
+        current thread
+
+    """
+    return get_async_backend().wait_writable(sock.fileno())
+
+
+def wait_readable(obj: FileDescriptorLike) -> Awaitable[None]:
+    """
+    Wait until the given object has data to be read.
+
+    On Unix systems, ``obj`` must either be an integer file descriptor, or else an
+    object with a ``.fileno()`` method which returns an integer file descriptor. Any
+    kind of file descriptor can be passed, though the exact semantics will depend on
+    your kernel. For example, this probably won't do anything useful for on-disk files.
+
+    On Windows systems, ``obj`` must either be an integer ``SOCKET`` handle, or else an
+    object with a ``.fileno()`` method which returns an integer ``SOCKET`` handle. File
+    descriptors aren't supported, and neither are handles that refer to anything besides
+    a ``SOCKET``.
+
+    On backends where this functionality is not natively provided (asyncio
+    ``ProactorEventLoop`` on Windows), it is provided using a separate selector thread
+    which is set to shut down when the interpreter shuts down.
+
+    .. warning:: Don't use this on raw sockets that have been wrapped by any higher
+        level constructs like socket streams!
+
+    :param obj: an object with a ``.fileno()`` method or an integer handle
+    :raises ~anyio.ClosedResourceError: if the object was closed while waiting for the
+        object to become readable
+    :raises ~anyio.BusyResourceError: if another task is already waiting for the object
+        to become readable
+    :raises NoEventLoopError: if no supported asynchronous event loop is running in the
+        current thread
+
+    """
+    return get_async_backend().wait_readable(obj)
+
+
+def wait_writable(obj: FileDescriptorLike) -> Awaitable[None]:
+    """
+    Wait until the given object can be written to.
+
+    :param obj: an object with a ``.fileno()`` method or an integer handle
+    :raises ~anyio.ClosedResourceError: if the object was closed while waiting for the
+        object to become writable
+    :raises ~anyio.BusyResourceError: if another task is already waiting for the object
+        to become writable
+    :raises NoEventLoopError: if no supported asynchronous event loop is running in the
+        current thread
+
+    .. seealso:: See the documentation of :func:`wait_readable` for the definition of
+       ``obj`` and notes on backend compatibility.
+
+    .. warning:: Don't use this on raw sockets that have been wrapped by any higher
+        level constructs like socket streams!
+
+    """
+    return get_async_backend().wait_writable(obj)
+
+
+def notify_closing(obj: FileDescriptorLike) -> None:
+    """
+    Call this before closing a file descriptor (on Unix) or socket (on
+    Windows). This will cause any `wait_readable` or `wait_writable`
+    calls on the given object to immediately wake up and raise
+    `~anyio.ClosedResourceError`.
+
+    This doesn't actually close the object – you still have to do that
+    yourself afterwards. Also, you want to be careful to make sure no
+    new tasks start waiting on the object in between when you call this
+    and when it's actually closed. So to close something properly, you
+    usually want to do these steps in order:
+
+    1. Explicitly mark the object as closed, so that any new attempts
+       to use it will abort before they start.
+    2. Call `notify_closing` to wake up any already-existing users.
+    3. Actually close the object.
+
+    It's also possible to do them in a different order if that's more
+    convenient, *but only if* you make sure not to have any checkpoints in
+    between the steps. This way they all happen in a single atomic
+    step, so other tasks won't be able to tell what order they happened
+    in anyway.
+
+    :param obj: an object with a ``.fileno()`` method or an integer handle
+    :raises NoEventLoopError: if no supported asynchronous event loop is running in the
+        current thread
+
+    """
+    get_async_backend().notify_closing(obj)
+
+
+#
+# Private API
+#
+
+
+def convert_ipv6_sockaddr(
+    sockaddr: tuple[str, int, int, int] | tuple[str, int],
+) -> tuple[str, int]:
+    """
+    Convert a 4-tuple IPv6 socket address to a 2-tuple (address, port) format.
+
+    If the scope ID is nonzero, it is added to the address, separated with ``%``.
+    Otherwise the flow id and scope id are simply cut off from the tuple.
+    Any other kinds of socket addresses are returned as-is.
+
+    :param sockaddr: the result of :meth:`~socket.socket.getsockname`
+    :return: the converted socket address
+
+    """
+    # This is more complicated than it should be because of MyPy
+    if isinstance(sockaddr, tuple) and len(sockaddr) == 4:
+        host, port, flowinfo, scope_id = sockaddr
+        if scope_id:
+            # PyPy (as of v7.3.11) leaves the interface name in the result, so
+            # we discard it and only get the scope ID from the end
+            # (https://foss.heptapod.net/pypy/pypy/-/issues/3938)
+            host = host.split("%")[0]
+
+            # Add scope_id to the address
+            return f"{host}%{scope_id}", port
+        else:
+            return host, port
+    else:
+        return sockaddr
+
+
+async def setup_unix_local_socket(
+    path: None | str | bytes | PathLike[Any],
+    mode: int | None,
+    socktype: int,
+) -> socket.socket:
+    """
+    Create a UNIX local socket object, deleting the socket at the given path if it
+    exists.
+
+    Not available on Windows.
+
+    :param path: path of the socket
+    :param mode: permissions to set on the socket
+    :param socktype: socket.SOCK_STREAM or socket.SOCK_DGRAM
+
+    """
+    path_str: str | None
+    if path is not None:
+        path_str = os.fsdecode(path)
+
+        # Linux abstract namespace sockets aren't backed by a concrete file so skip stat call
+        if not path_str.startswith("\0"):
+            # Copied from pathlib...
+            try:
+                stat_result = os.stat(path)
+            except OSError as e:
+                if e.errno not in (
+                    errno.ENOENT,
+                    errno.ENOTDIR,
+                    errno.EBADF,
+                    errno.ELOOP,
+                ):
+                    raise
+            else:
+                if stat.S_ISSOCK(stat_result.st_mode):
+                    os.unlink(path)
+    else:
+        path_str = None
+
+    raw_socket = socket.socket(socket.AF_UNIX, socktype)
+    raw_socket.setblocking(False)
+
+    if path_str is not None:
+        try:
+            await to_thread.run_sync(raw_socket.bind, path_str, abandon_on_cancel=True)
+            if mode is not None:
+                await to_thread.run_sync(chmod, path_str, mode, abandon_on_cancel=True)
+        except BaseException:
+            raw_socket.close()
+            raise
+
+    return raw_socket
+
+
+@dataclass
+class TCPConnectable(ByteStreamConnectable):
+    """
+    Connects to a TCP server at the given host and port.
+
+    :param host: host name or IP address of the server
+    :param port: TCP port number of the server
+    """
+
+    host: str | IPv4Address | IPv6Address
+    port: int
+
+    def __post_init__(self) -> None:
+        if self.port < 1 or self.port > 65535:
+            raise ValueError("TCP port number out of range")
+
+    @override
+    async def connect(self) -> SocketStream:
+        try:
+            return await connect_tcp(self.host, self.port)
+        except OSError as exc:
+            raise ConnectionFailed(
+                f"error connecting to {self.host}:{self.port}: {exc}"
+            ) from exc
+
+
+@dataclass
+class UNIXConnectable(ByteStreamConnectable):
+    """
+    Connects to a UNIX domain socket at the given path.
+
+    :param path: the file system path of the socket
+    """
+
+    path: str | bytes | PathLike[str] | PathLike[bytes]
+
+    @override
+    async def connect(self) -> UNIXSocketStream:
+        try:
+            return await connect_unix(self.path)
+        except OSError as exc:
+            raise ConnectionFailed(f"error connecting to {self.path!r}: {exc}") from exc
+
+
+def as_connectable(
+    remote: ByteStreamConnectable
+    | tuple[str | IPv4Address | IPv6Address, int]
+    | str
+    | bytes
+    | PathLike[str],
+    /,
+    *,
+    tls: bool = False,
+    ssl_context: ssl.SSLContext | None = None,
+    tls_hostname: str | None = None,
+    tls_standard_compatible: bool = True,
+) -> ByteStreamConnectable:
+    """
+    Return a byte stream connectable from the given object.
+
+    If a bytestream connectable is given, it is returned unchanged.
+    If a tuple of (host, port) is given, a TCP connectable is returned.
+    If a string or bytes path is given, a UNIX connectable is returned.
+
+    If ``tls=True``, the connectable will be wrapped in a
+    :class:`~.streams.tls.TLSConnectable`.
+
+    :param remote: a connectable, a tuple of (host, port) or a path to a UNIX socket
+    :param tls: if ``True``, wrap the plaintext connectable in a
+        :class:`~.streams.tls.TLSConnectable`, using the provided TLS settings)
+    :param ssl_context: if ``tls=True``, the SSLContext object to use  (if not provided,
+        a secure default will be created)
+    :param tls_hostname: if ``tls=True``, host name of the server to use for checking
+        the server certificate (defaults to the host portion of the address for TCP
+        connectables)
+    :param tls_standard_compatible: if ``False`` and ``tls=True``, makes the TLS stream
+        skip the closing handshake when closing the connection, so it won't raise an
+        exception if the server does the same
+
+    """
+    connectable: TCPConnectable | UNIXConnectable | TLSConnectable
+    if isinstance(remote, ByteStreamConnectable):
+        return remote
+    elif isinstance(remote, tuple) and len(remote) == 2:
+        connectable = TCPConnectable(*remote)
+    elif isinstance(remote, (str, bytes, PathLike)):
+        connectable = UNIXConnectable(remote)
+    else:
+        raise TypeError(f"cannot convert {remote!r} to a connectable")
+
+    if tls:
+        if not tls_hostname and isinstance(connectable, TCPConnectable):
+            tls_hostname = str(connectable.host)
+
+        connectable = TLSConnectable(
+            connectable,
+            ssl_context=ssl_context,
+            hostname=tls_hostname,
+            standard_compatible=tls_standard_compatible,
+        )
+
+    return connectable