shortcutxl 0.3.76 → 0.3.78

package/xll/python/Lib/site-packages/pip/_vendor/idna/cli.py

@@ -0,0 +1,128 @@
+"""Command-line interface for the :mod:`idna` package.
+
+Invoked via ``python -m idna``. See :func:`main` for the entry point.
+"""
+
+import argparse
+import sys
+from collections.abc import Iterable
+from itertools import chain
+from typing import IO, Optional
+
+from . import IDNAError, decode, encode
+from .core import _alabel_prefix, _unicode_dots_re
+from .package_data import __version__
+
+
+def _looks_like_alabel(s: str) -> bool:
+    """Return True if any label in ``s`` carries the ``xn--`` ACE prefix."""
+    prefix = _alabel_prefix.decode("ascii")
+    return any(label.lower().startswith(prefix) for label in _unicode_dots_re.split(s))
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="python -m idna",
+        description=(
+            "Convert a domain name between its Unicode (U-label) and "
+            "ASCII-compatible (A-label) forms. With no mode flag, the "
+            "direction is chosen from the first input — if it contains "
+            "an xn-- label the stream is decoded, otherwise it is "
+            "encoded — and the same mode is applied to every remaining "
+            "input. UTS #46 mapping is applied by default; pass "
+            "--strict to disable it. When no domains are given on the "
+            "command line and stdin is piped, one domain per line is "
+            "read from stdin."
+        ),
+    )
+    mode = parser.add_mutually_exclusive_group()
+    mode.add_argument(
+        "-e",
+        "--encode",
+        dest="mode",
+        action="store_const",
+        const="encode",
+        help="Encode the input to its ASCII A-label form.",
+    )
+    mode.add_argument(
+        "-d",
+        "--decode",
+        dest="mode",
+        action="store_const",
+        const="decode",
+        help="Decode the input from its ASCII A-label form.",
+    )
+    parser.add_argument(
+        "--strict",
+        action="store_true",
+        help="Disable the default UTS #46 mapping and apply IDNA 2008 rules verbatim.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"idna {__version__}",
+    )
+    parser.add_argument(
+        "domain",
+        nargs="*",
+        help="One or more domain names to convert. Omit to read from stdin.",
+    )
+    return parser
+
+
+def _iter_stdin(stream: IO[str]) -> Iterable[str]:
+    """Yield non-empty stripped lines from ``stream``, ignoring blanks."""
+    for line in stream:
+        stripped = line.strip()
+        if stripped:
+            yield stripped
+
+
+def _convert_one(domain: str, mode: str, uts46: bool) -> bool:
+    """Convert ``domain`` and write the result; return ``False`` on failure."""
+    try:
+        if mode == "decode":
+            print(decode(domain, uts46=uts46))
+        else:
+            print(encode(domain, uts46=uts46).decode("ascii"))
+    except IDNAError as err:
+        print(f"idna: {mode} failed for {domain!r}: {err}", file=sys.stderr)
+        return False
+    return True
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+    """Entry point for ``python -m idna``.
+
+    When more than one domain is supplied (via positional arguments or
+    piped stdin) and no mode flag is given, the first input determines
+    the direction and that mode is applied uniformly to the rest.
+
+    :param argv: Argument list excluding the program name. Defaults to
+        :data:`sys.argv` when ``None``.
+    :returns: ``0`` on success, ``1`` if any conversion fails.
+    """
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    uts46 = not args.strict
+
+    if args.domain:
+        domains: Iterable[str] = args.domain
+    elif not sys.stdin.isatty():
+        domains = _iter_stdin(sys.stdin)
+    else:
+        parser.error("a domain argument is required when stdin is a terminal")
+
+    iterator = iter(domains)
+    first = next(iterator, None)
+    if first is None:
+        return 0
+
+    mode = args.mode or ("decode" if _looks_like_alabel(first) else "encode")
+
+    results = [_convert_one(domain, mode, uts46) for domain in chain([first], iterator)]
+    return 0 if all(results) else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/xll/python/Lib/site-packages/pip/_vendor/idna/codec.py

@@ -1,25 +1,32 @@
 import codecs
-import re
-from typing import Any, Optional, Tuple
+from typing import Any, Optional
 
-from .core import IDNAError, alabel, decode, encode, ulabel
-
-_unicode_dots_re = re.compile("[\u002e\u3002\uff0e\uff61]")
+from .core import IDNAError, _unicode_dots_re, alabel, decode, encode, ulabel
 
 
 class Codec(codecs.Codec):
-    def encode(self, data: str, errors: str = "strict") -> Tuple[bytes, int]:
+    """Stateless IDNA 2008 codec.
+
+    Implements the :class:`codecs.Codec` protocol so that the whole-domain
+    encoder (:func:`idna.encode`) and decoder (:func:`idna.decode`) are
+    accessible through the standard codec machinery as ``"idna2008"``.
+
+    Only the ``"strict"`` error handler is supported; any other handler
+    raises :exc:`~idna.IDNAError`.
+    """
+
+    def encode(self, data: str, errors: str = "strict") -> tuple[bytes, int]:  # ty: ignore[invalid-method-override]
         if errors != "strict":
-            raise IDNAError('Unsupported error handling "{}"'.format(errors))
+            raise IDNAError(f'Unsupported error handling "{errors}"')
 
         if not data:
             return b"", 0
 
         return encode(data), len(data)
 
-    def decode(self, data: bytes, errors: str = "strict") -> Tuple[str, int]:
+    def decode(self, data: bytes, errors: str = "strict") -> tuple[str, int]:  # ty: ignore[invalid-method-override]
         if errors != "strict":
-            raise IDNAError('Unsupported error handling "{}"'.format(errors))
+            raise IDNAError(f'Unsupported error handling "{errors}"')
 
         if not data:
             return "", 0
@@ -28,9 +35,20 @@ class Codec(codecs.Codec):
 
 
 class IncrementalEncoder(codecs.BufferedIncrementalEncoder):
-    def _buffer_encode(self, data: str, errors: str, final: bool) -> Tuple[bytes, int]:
+    """Incremental IDNA 2008 encoder.
+
+    Buffers a partial trailing label across calls until either the next
+    label separator is seen or ``final=True``, so that streamed input is
+    encoded one whole label at a time. Any of the four Unicode label
+    separators (``U+002E``, ``U+3002``, ``U+FF0E``, ``U+FF61``) ends a
+    label; the result always uses ``U+002E`` as the separator.
+
+    Only the ``"strict"`` error handler is supported.
+    """
+
+    def _buffer_encode(self, data: str, errors: str, final: bool) -> tuple[bytes, int]:  # ty: ignore[invalid-method-override]
         if errors != "strict":
-            raise IDNAError('Unsupported error handling "{}"'.format(errors))
+            raise IDNAError(f'Unsupported error handling "{errors}"')
 
         if not data:
             return b"", 0
@@ -62,9 +80,18 @@ class IncrementalEncoder(codecs.BufferedIncrementalEncoder):
 
 
 class IncrementalDecoder(codecs.BufferedIncrementalDecoder):
-    def _buffer_decode(self, data: Any, errors: str, final: bool) -> Tuple[str, int]:
+    """Incremental IDNA 2008 decoder.
+
+    Buffers a partial trailing label across calls until either the next
+    label separator is seen or ``final=True``, so that streamed input is
+    decoded one whole label at a time.
+
+    Only the ``"strict"`` error handler is supported.
+    """
+
+    def _buffer_decode(self, data: Any, errors: str, final: bool) -> tuple[str, int]:  # ty: ignore[invalid-method-override]
         if errors != "strict":
-            raise IDNAError('Unsupported error handling "{}"'.format(errors))
+            raise IDNAError(f'Unsupported error handling "{errors}"')
 
         if not data:
             return ("", 0)
@@ -106,6 +133,16 @@ class StreamReader(Codec, codecs.StreamReader):
 
 
 def search_function(name: str) -> Optional[codecs.CodecInfo]:
+    """Codec search function registered with :mod:`codecs`.
+
+    Returns a :class:`codecs.CodecInfo` for the ``"idna2008"`` codec name
+    so that ``str.encode("idna2008")`` and ``bytes.decode("idna2008")``
+    invoke the IDNA 2008 codec defined in this module.
+
+    :param name: The codec name being looked up.
+    :returns: A :class:`codecs.CodecInfo` instance if ``name`` is
+        ``"idna2008"``, otherwise ``None``.
+    """
     if name != "idna2008":
         return None
     return codecs.CodecInfo(

package/xll/python/Lib/site-packages/pip/_vendor/idna/compat.py

@@ -4,12 +4,38 @@ from .core import decode, encode
 
 
 def ToASCII(label: str) -> bytes:
+    """Compatibility shim for :rfc:`3490` ``ToASCII``.
+
+    Delegates to :func:`idna.encode` (IDNA 2008). Provided to ease porting
+    of code written against the legacy :mod:`encodings.idna` API; new code
+    should call :func:`idna.encode` directly.
+
+    :param label: The label or domain to encode.
+    :returns: The encoded form as ASCII :class:`bytes`.
+    """
     return encode(label)
 
 
 def ToUnicode(label: Union[bytes, bytearray]) -> str:
+    """Compatibility shim for :rfc:`3490` ``ToUnicode``.
+
+    Delegates to :func:`idna.decode` (IDNA 2008). Provided to ease porting
+    of code written against the legacy :mod:`encodings.idna` API; new code
+    should call :func:`idna.decode` directly.
+
+    :param label: The label or domain to decode.
+    :returns: The decoded Unicode form.
+    """
     return decode(label)
 
 
 def nameprep(s: Any) -> None:
+    """Stub for :rfc:`3491` Nameprep, which is not used by IDNA 2008.
+
+    IDNA 2008 (:rfc:`5891`) replaces Nameprep with the per-codepoint
+    validity classes from :rfc:`5892`; this function exists only to
+    return a clear error if legacy code attempts to call it.
+
+    :raises NotImplementedError: Always.
+    """
     raise NotImplementedError("IDNA 2008 does not utilise nameprep protocol")