teluri 0.2.0__py3-none-any.whl

teluri/__init__.py

@@ -0,0 +1,13 @@
+"""Parse, build and compare tel: URIs per RFC 3966, zero dependencies and fully typed."""
+
+from __future__ import annotations
+
+from ._build import build
+from ._errors import Reason, TelURIError
+from ._link import parse_link
+from ._model import TelURI
+from ._parse import equivalent, parse
+
+__version__ = "0.2.0"
+
+__all__ = ["Reason", "TelURI", "TelURIError", "build", "equivalent", "parse", "parse_link"]

teluri/__main__.py

@@ -0,0 +1,9 @@
+"""Run the command line with ``python -m teluri``."""
+
+from __future__ import annotations
+
+import sys
+
+from ._cli import main
+
+sys.exit(main())

teluri/_build.py

@@ -0,0 +1,39 @@
+"""Build a canonical tel: URI from human-written parts."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from ._model import TelURI
+
+
+def build(
+    number: str,
+    *,
+    ext: str | None = None,
+    isub: str | None = None,
+    phone_context: str | None = None,
+    params: Mapping[str, str | None] | None = None,
+) -> str:
+    """Build a canonical tel: URI, raising :class:`TelURIError` for invalid parts.
+
+    Spaces and visual separators are removed from the number, the extension and a numeric
+    phone-context, so printed forms such as ``+1 (201) 555-0123`` are accepted. A number
+    with a leading ``+`` is global; any other needs ``phone_context``. ``isub`` is taken
+    in its encoded form. ``params`` values are plain text and are percent-encoded.
+    """
+    context = phone_context
+    if context is not None and _unspaced(context).startswith("+"):
+        context = _unspaced(context)
+    uri = TelURI(
+        _unspaced(number),
+        ext=None if ext is None else _unspaced(ext),
+        isub=isub,
+        phone_context=context,
+        params=params or {},
+    )
+    return str(uri)
+
+
+def _unspaced(text: str) -> str:
+    return "".join(char for char in text if not char.isspace())

teluri/_chars.py

@@ -0,0 +1,55 @@
+"""Character classes and percent-encoding from the RFC 3966 grammar."""
+
+from __future__ import annotations
+
+from urllib.parse import quote
+
+VISUAL_SEPARATORS = "-.()"
+_SEPARATOR_TABLE = {ord(char): None for char in VISUAL_SEPARATORS}
+
+ALPHA = frozenset("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ")
+DIGITS = frozenset("0123456789")
+ALPHANUM = ALPHA | DIGITS
+HEXDIG = DIGITS | frozenset("ABCDEFabcdef")
+LOCAL_DIGITS = HEXDIG | frozenset("*#")
+PNAME_CHARS = ALPHANUM | frozenset("-")
+MARK = frozenset("-_.!~*'()")
+UNRESERVED = ALPHANUM | MARK
+# paramchar minus pct-encoded: the characters a value may carry unencoded.
+PARAMCHAR = UNRESERVED | frozenset("[]/:&+$")
+_SAFE = "".join(sorted(PARAMCHAR - ALPHANUM))
+
+# Names with their own field on TelURI; they never appear in `params`.
+RESERVED_PARAMETERS = frozenset({"ext", "isub", "phone-context"})
+
+
+def strip_separators(value: str) -> str:
+    """Drop the visual separators (-, ., (, )) that only aid readability."""
+    return value.translate(_SEPARATOR_TABLE)
+
+
+def only(value: str, allowed: frozenset[str]) -> bool:
+    """True when every character of `value` is in `allowed` (ASCII sets only)."""
+    return all(char in allowed for char in value)
+
+
+def encode_value(text: str) -> str:
+    """Percent-encode `text` (UTF-8) so that it is a valid `pvalue`."""
+    return quote(text, safe=_SAFE)
+
+
+def valid_pct(value: str, allowed: frozenset[str]) -> bool:
+    """True when `value` is made of `allowed` characters and well-formed %HH escapes."""
+    index = 0
+    while index < len(value):
+        char = value[index]
+        if char == "%":
+            escape = value[index + 1 : index + 3]
+            if len(escape) != 2 or not only(escape, HEXDIG):
+                return False
+            index += 3
+            continue
+        if char not in allowed:
+            return False
+        index += 1
+    return True

teluri/_cli.py

@@ -0,0 +1,96 @@
+"""Command line: print the canonical form of each tel: URI, exit 1 if any is invalid."""
+
+from __future__ import annotations
+
+import argparse
+import contextlib
+import json
+import sys
+from collections.abc import Iterable, Sequence
+from typing import TextIO
+
+from ._errors import TelURIError
+from ._link import parse_link
+from ._model import TelURI
+from ._parse import parse
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="teluri",
+        description="Validate tel: URIs (RFC 3966) and print their canonical form. "
+        "Reads one URI per line from standard input when none are given.",
+    )
+    parser.add_argument("uris", nargs="*", metavar="URI")
+    parser.add_argument("--json", action="store_true", help="print one JSON object per URI")
+    parser.add_argument("--strict", action="store_true", help="enforce the parameter order")
+    parser.add_argument(
+        "--link", action="store_true", help="read links as browsers do (spaces, %%23)"
+    )
+    parser.add_argument(
+        "--context", metavar="DESCRIPTOR", help="phone-context for local links without one"
+    )
+    return parser
+
+
+def main(
+    argv: Sequence[str] | None = None,
+    stdin: TextIO | None = None,
+    stdout: TextIO | None = None,
+    stderr: TextIO | None = None,
+) -> int:
+    """Run the command line and return its exit status (0 ok, 1 invalid, 2 usage)."""
+    out = stdout or sys.stdout
+    err = stderr or sys.stderr
+    try:
+        with contextlib.redirect_stdout(out), contextlib.redirect_stderr(err):
+            args = _parser().parse_args(argv)
+            if args.context is not None and not args.link:
+                _parser().error("--context needs --link")
+            if args.strict and args.link:
+                _parser().error("--strict reads RFC 3966 only and cannot be used with --link")
+    except SystemExit as stop:
+        return int(stop.code or 0)
+    uris: Iterable[str] = args.uris or _lines(stdin or sys.stdin)
+    status = 0
+    for uri in uris:
+        try:
+            if args.link:
+                parsed = parse_link(uri, context=args.context)
+            else:
+                parsed = parse(uri, strict=args.strict)
+        except TelURIError as error:
+            err.write(f"invalid ({error.reason}): {_shown(uri)}\n")
+            status = 1
+            continue
+        out.write(json.dumps(_fields(parsed)) if args.json else str(parsed))
+        out.write("\n")
+    return status
+
+
+def _fields(uri: TelURI) -> dict[str, object]:
+    return {
+        "uri": str(uri),
+        "number": uri.number,
+        "global": uri.is_global,
+        "e164": uri.is_e164,
+        "ext": uri.ext,
+        "isub": uri.isub,
+        "phone_context": uri.phone_context,
+        "params": dict(uri.params),
+    }
+
+
+def _lines(stream: TextIO) -> Iterable[str]:
+    for line in stream:
+        text = line.rstrip("\r\n")
+        if text:
+            yield text
+
+
+def _shown(uri: str) -> str:
+    """The input as safe to print on any console: non-ASCII and control characters escaped."""
+    escape = "unicode_escape"
+    return "".join(
+        c if c.isascii() and c.isprintable() else c.encode(escape).decode("ascii") for c in uri
+    )

teluri/_errors.py

@@ -0,0 +1,37 @@
+"""The error raised for a malformed tel: URI, with a machine-readable reason."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+Reason = Literal[
+    "scheme",
+    "number",
+    "ext",
+    "isub",
+    "ext-and-isub",
+    "phone-context",
+    "missing-context",
+    "global-context",
+    "param-name",
+    "param-value",
+    "duplicate-param",
+    "param-order",
+]
+
+
+class TelURIError(ValueError):
+    """Raised when a tel: URI is malformed or cannot be built.
+
+    `reason` names the rule that failed, from the closed set `Reason`.
+    """
+
+    reason: Reason
+
+    def __init__(self, reason: Reason, message: str = "") -> None:
+        super().__init__(reason, message)
+        self.reason = reason
+        self.message = message
+
+    def __str__(self) -> str:
+        return f"{self.reason}: {self.message}" if self.message else self.reason

teluri/_grammar.py

@@ -0,0 +1,92 @@
+"""Validators for the pieces of the RFC 3966 grammar, each raising a precise reason."""
+
+from __future__ import annotations
+
+from urllib.parse import unquote
+
+from ._chars import (
+    ALPHA,
+    ALPHANUM,
+    DIGITS,
+    LOCAL_DIGITS,
+    PARAMCHAR,
+    PNAME_CHARS,
+    VISUAL_SEPARATORS,
+    only,
+    strip_separators,
+    valid_pct,
+)
+from ._errors import Reason, TelURIError
+
+_GLOBAL = DIGITS | frozenset(VISUAL_SEPARATORS)
+_LOCAL = LOCAL_DIGITS | frozenset(VISUAL_SEPARATORS)
+
+
+def global_digits(raw: str, reason: Reason = "number") -> str:
+    """`global-number-digits`: digits and separators after the `+` the caller has seen."""
+    body = raw[1:]
+    if not only(body, _GLOBAL) or not strip_separators(body):
+        raise TelURIError(reason, f"not a global number: {raw!r}")
+    return "+" + strip_separators(body)
+
+
+def local_digits(raw: str) -> str:
+    """`local-number-digits`: hex digits, `*` and `#` with separators, at least one of them."""
+    if not only(raw, _LOCAL) or not strip_separators(raw):
+        raise TelURIError("number", f"not a local number: {raw!r}")
+    return strip_separators(raw)
+
+
+def is_domainname(value: str) -> bool:
+    """`domainname`: dot-separated labels, a top label starting with a letter, optional root dot."""
+    labels = value[:-1].split(".") if value.endswith(".") else value.split(".")
+    if not all(_is_label(label) for label in labels):
+        return False
+    return labels[-1][0] in ALPHA
+
+
+def descriptor(value: str, reason: Reason = "phone-context") -> str:
+    """A context `descriptor`: a global number prefix (separators dropped) or a domain name."""
+    if value.startswith("+"):
+        return global_digits(value, reason)
+    if not is_domainname(value):
+        raise TelURIError(reason, f"not a domain name or global number: {value!r}")
+    return value
+
+
+def extension(value: str) -> str:
+    """`ext`: digits and separators; at least one digit, since an empty extension names nothing."""
+    digits = strip_separators(value)
+    if not only(value, _GLOBAL) or not digits:
+        raise TelURIError("ext", f"not an extension: {value!r}")
+    return digits
+
+
+def subaddress(value: str) -> str:
+    """`isub` per erratum 203: `1*paramchar`, kept in its encoded form (any octet may occur)."""
+    if not value or not valid_pct(value, PARAMCHAR):
+        raise TelURIError("isub", f"not an ISDN subaddress: {value!r}")
+    return value
+
+
+def pname(name: str) -> str:
+    """`pname`, lower-cased: names compare case-insensitively and SHOULD be lower case."""
+    if not name or not only(name, PNAME_CHARS):
+        raise TelURIError("param-name", f"not a parameter name: {name!r}")
+    return name.lower()
+
+
+def pvalue(value: str) -> str:
+    """`pvalue`, percent-decoded as UTF-8 (an empty one is refused by the model)."""
+    if not valid_pct(value, PARAMCHAR):
+        raise TelURIError("param-value", f"not a parameter value: {value!r}")
+    try:
+        return unquote(value, errors="strict")
+    except UnicodeDecodeError:
+        raise TelURIError("param-value", f"not UTF-8 once decoded: {value!r}") from None
+
+
+def _is_label(label: str) -> bool:
+    if not label or not only(label, ALPHANUM | frozenset("-")):
+        return False
+    return label[0] != "-" and label[-1] != "-"

teluri/_link.py

@@ -0,0 +1,41 @@
+"""Read tel: links as browsers and phones accept them, which RFC 3966 does not."""
+
+from __future__ import annotations
+
+from urllib.parse import unquote
+
+from ._errors import TelURIError
+from ._grammar import descriptor
+from ._model import TelURI
+from ._parse import parse
+
+
+def parse_link(href: str, *, context: str | None = None) -> TelURI:
+    """Parse a tel: link from a web page or an app, then validate it as RFC 3966.
+
+    Links in the wild write spaces (``tel:+1 201 555 0123``), percent-encode the number
+    (``%20``, ``%2B``, ``%23``) and leave local numbers without a phone-context. This
+    reader decodes the number, drops whitespace, and gives a local number ``context``
+    when the link has none. Everything after the number is read as strict RFC 3966.
+    """
+    if not isinstance(href, str):
+        raise TypeError(f"href must be a str, not {type(href).__name__}")
+    if context is not None:
+        descriptor(context)  # one descriptor, so it cannot smuggle in other parameters
+    text = href.strip()
+    scheme, colon, rest = text.partition(":")
+    if not colon or scheme.lower() != "tel":
+        raise TelURIError("scheme", f"not a tel: link: {href!r}")
+    number, semicolon, tail = rest.partition(";")
+    try:
+        decoded = unquote(number, errors="strict")
+    except UnicodeDecodeError:
+        raise TelURIError("number", f"not UTF-8 once decoded: {number!r}") from None
+    cleaned = "".join(char for char in decoded if not char.isspace())
+    if ";" in cleaned:  # an encoded separator must not start a parameter
+        raise TelURIError("number", f"not a telephone number: {number!r}")
+    names = [segment.partition("=")[0].lower() for segment in tail.split(";")]
+    if context is not None and not cleaned.startswith("+") and "phone-context" not in names:
+        tail = f"{tail};phone-context={context}" if semicolon else f"phone-context={context}"
+        semicolon = ";"
+    return parse(f"tel:{cleaned}{semicolon}{tail}")

teluri/_model.py

@@ -0,0 +1,144 @@
+"""The parsed, validated representation of a tel: URI."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from urllib.parse import unquote_to_bytes
+
+from ._chars import RESERVED_PARAMETERS, encode_value
+from ._errors import TelURIError
+from ._grammar import descriptor, extension, global_digits, local_digits, pname, subaddress
+from ._params import Params
+
+_E164_MAX_DIGITS = 15
+
+
+@dataclass(frozen=True, eq=False)
+class TelURI:
+    """A valid tel: URI (RFC 3966) with visual separators removed from its numbers.
+
+    Constructing one validates every field: a number with a leading ``+`` is global and
+    takes no ``phone_context``; any other number is local and requires one. ``params``
+    holds the remaining parameters by lower-case name, with decoded values and ``None``
+    for a parameter without a value. ``==`` and ``hash`` follow RFC 3966 section 4 and
+    ``str()`` gives the canonical form.
+    """
+
+    number: str
+    ext: str | None = None
+    isub: str | None = None
+    phone_context: str | None = None
+    params: Mapping[str, str | None] = field(default_factory=lambda: Params({}))
+
+    def __post_init__(self) -> None:
+        _check_types(self)
+        number = self.number
+        is_global = number.startswith("+")
+        set_ = object.__setattr__
+        set_(self, "number", global_digits(number) if is_global else local_digits(number))
+        if self.ext is not None and self.isub is not None:
+            raise TelURIError("ext-and-isub", "ext and isub cannot both be present")
+        if self.ext is not None:
+            set_(self, "ext", extension(self.ext))
+        if self.isub is not None:
+            set_(self, "isub", subaddress(self.isub))
+        if self.phone_context is not None:
+            if is_global:
+                raise TelURIError("global-context", "a global number takes no phone-context")
+            set_(self, "phone_context", descriptor(self.phone_context))
+        elif not is_global:
+            raise TelURIError("missing-context", f"local number {number!r} needs phone-context")
+        set_(self, "params", _checked(self.params))
+
+    @property
+    def is_global(self) -> bool:
+        """True for a global (E.164) number, written with a leading ``+``."""
+        return self.number.startswith("+")
+
+    @property
+    def is_e164(self) -> bool:
+        """True for a global number of 1 to 15 digits not starting with 0 (E.164 limits)."""
+        digits = self.number[1:]
+        return self.is_global and len(digits) <= _E164_MAX_DIGITS and digits[0] != "0"
+
+    @property
+    def unknown_mandatory(self) -> tuple[str, ...]:
+        """Names of ``m-`` parameters: section 5.4 says not to use a URI it cannot honour."""
+        return tuple(name for name in self.params if name.startswith("m-"))
+
+    @property
+    def href(self) -> str:
+        """The canonical form for an HTML ``href``: ``#`` escaped so it is not a fragment."""
+        return str(self).replace("#", "%23")
+
+    def __str__(self) -> str:
+        out = ["tel:", self.number]
+        if self.ext is not None:
+            out.append(";ext=" + self.ext)
+        if self.isub is not None:
+            out.append(";isub=" + self.isub)
+        if self.phone_context is not None:
+            out.append(";phone-context=" + self.phone_context)
+        for name, value in self.params.items():
+            out.append(f";{name}" if value is None else f";{name}={encode_value(value)}")
+        return "".join(out)
+
+    def __repr__(self) -> str:
+        return f"TelURI({str(self)!r})"
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, TelURI):
+            return NotImplemented
+        return self._key() == other._key()
+
+    def __hash__(self) -> int:
+        return hash(self._key())
+
+    def _key(self) -> tuple[object, ...]:
+        context = self.phone_context
+        if context is not None and not context.startswith("+"):
+            context = context.lower().removesuffix(".")
+        return (
+            self.number.lower(),
+            self.ext,
+            None if self.isub is None else unquote_to_bytes(self.isub).lower(),
+            context,
+            frozenset(
+                (name, None if value is None else value.encode("utf-8").lower())
+                for name, value in self.params.items()
+            ),
+        )
+
+
+def _check_types(uri: TelURI) -> None:
+    if not isinstance(uri.number, str):
+        raise TypeError(f"number must be a str, not {type(uri.number).__name__}")
+    for name in ("ext", "isub", "phone_context"):
+        value = getattr(uri, name)
+        if value is not None and not isinstance(value, str):
+            raise TypeError(f"{name} must be a str or None, not {type(value).__name__}")
+    if not isinstance(uri.params, Mapping) or not all(isinstance(k, str) for k in uri.params):
+        raise TypeError("params must be a mapping with str keys")
+
+
+def _checked(params: Mapping[str, str | None]) -> Params:
+    items: dict[str, str | None] = {}
+    for raw, value in params.items():
+        name = pname(raw)
+        if name in RESERVED_PARAMETERS:
+            raise TelURIError("param-name", f"{name!r} has its own field")
+        if name in items:
+            raise TelURIError("duplicate-param", f"{name!r} appears twice")
+        if value is not None and (not isinstance(value, str) or not value or _unencodable(value)):
+            raise TelURIError("param-value", f"{name!r} needs a non-empty text value or None")
+        items[name] = value
+    return Params(dict(sorted(items.items())))
+
+
+def _unencodable(text: str) -> bool:
+    try:
+        text.encode("utf-8")
+    except UnicodeEncodeError:  # a lone surrogate cannot be written in a URI
+        return True
+    return False

teluri/_params.py

@@ -0,0 +1,37 @@
+"""A read-only, hashable, picklable mapping for the extra parameters of a tel: URI."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator, Mapping
+
+
+class Params(Mapping[str, "str | None"]):
+    """Parameters other than ext, isub and phone-context, keyed by lower-case name."""
+
+    __slots__ = ("_items",)
+
+    def __init__(self, items: Mapping[str, str | None]) -> None:
+        self._items = dict(items)
+
+    def __getitem__(self, name: str) -> str | None:
+        return self._items[name]
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self._items)
+
+    def __len__(self) -> int:
+        return len(self._items)
+
+    def __hash__(self) -> int:
+        return hash(frozenset(self._items.items()))
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, Mapping):
+            return dict(self._items) == dict(other)
+        return NotImplemented
+
+    def __repr__(self) -> str:
+        return f"Params({self._items!r})"
+
+    def __reduce__(self) -> tuple[type[Params], tuple[dict[str, str | None]]]:
+        return (Params, (self._items,))

teluri/_parse.py

@@ -0,0 +1,68 @@
+"""Parse a tel: URI (RFC 3966) into a validated :class:`TelURI`."""
+
+from __future__ import annotations
+
+from ._errors import TelURIError
+from ._grammar import pname, pvalue
+from ._model import TelURI
+
+_FIELDS = frozenset({"ext", "isub", "phone-context"})
+
+
+def parse(uri: str, *, strict: bool = False) -> TelURI:
+    """Parse a tel: URI, raising :class:`TelURIError` with a reason if it is malformed.
+
+    Parameters may come in any order, as the ABNF allows. With ``strict=True`` the order
+    rule of section 3 is enforced too: ext or isub first, then phone-context, then the
+    other parameters in lexicographic order.
+    """
+    if not isinstance(uri, str):
+        raise TypeError(f"uri must be a str, not {type(uri).__name__}")
+    scheme, colon, rest = uri.partition(":")
+    if not colon or scheme.lower() != "tel":
+        raise TelURIError("scheme", f"not a tel: URI: {uri!r}")
+    number, *segments = rest.split(";")
+    if not number:
+        raise TelURIError("number", "the telephone number is empty")
+
+    fields: dict[str, str] = {}
+    params: dict[str, str | None] = {}
+    order: list[str] = []
+    for segment in segments:
+        raw_name, equals, raw_value = segment.partition("=")
+        name = pname(raw_name)
+        if name in order:
+            raise TelURIError("duplicate-param", f"{name!r} appears twice")
+        order.append(name)
+        if name in _FIELDS:
+            fields[name] = raw_value  # the model refuses an empty or missing value
+        elif equals:
+            params[name] = pvalue(raw_value)
+        else:
+            params[name] = None
+
+    result = TelURI(
+        number,
+        ext=fields.get("ext"),
+        isub=fields.get("isub"),
+        phone_context=fields.get("phone-context"),
+        params=params,
+    )
+    if strict and order != _canonical_order(order):
+        raise TelURIError("param-order", f"parameters out of order: {';'.join(order)}")
+    return result
+
+
+def _canonical_order(names: list[str]) -> list[str]:
+    first = [name for name in ("ext", "isub", "phone-context") if name in names]
+    return first + sorted(name for name in names if name not in _FIELDS)
+
+
+def equivalent(a: str | TelURI, b: str | TelURI) -> bool:
+    """True when two tel: URIs are equivalent under RFC 3966 section 4.
+
+    Strings are parsed first, so a malformed one raises :class:`TelURIError`.
+    """
+    left = a if isinstance(a, TelURI) else parse(a)
+    right = b if isinstance(b, TelURI) else parse(b)
+    return left == right

teluri-0.2.0.dist-info/METADATA

@@ -0,0 +1,214 @@
+Metadata-Version: 2.5
+Name: teluri
+Version: 0.2.0
+Summary: Strict, typed, zero-dependency parser, builder and comparator for tel: URIs (RFC 3966), with a reader for real-world tel: links
+Project-URL: Homepage, https://lianes8studio.com
+Project-URL: Repository, https://github.com/JaviLianes8/teluri
+Project-URL: Issues, https://github.com/JaviLianes8/teluri/issues
+Project-URL: Changelog, https://github.com/JaviLianes8/teluri/blob/main/CHANGELOG.md
+Project-URL: LinkedIn, https://www.linkedin.com/in/jlianes/
+Project-URL: Funding, https://buymeacoffee.com/jlianesglrs
+Author-email: Javier Lianes <javier@lianes8studio.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: e164,href,link,parser,phone,phone-number,rfc3966,sip,tel,telephone,uri
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Communications :: Telephony
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# teluri
+
+Strict, typed, zero-dependency parser, builder and comparator for `tel:` URIs
+(RFC 3966), with a reader for the `tel:` links found in real web pages and apps.
+
+## Install
+
+```
+pip install teluri
+```
+
+## Usage
+
+### Parse
+
+```python
+from teluri import parse
+
+uri = parse("tel:+1-201-555-0123;ext=1234")
+print(uri.number)  # +12015550123
+print(uri.is_global)  # True
+print(uri.ext)  # 1234
+print(uri.is_e164)  # True
+print(uri)  # tel:+12015550123;ext=1234
+
+local = parse("tel:863-1234;phone-context=+1-914-555")
+print(local.number)  # 8631234
+print(local.phone_context)  # +1914555
+print(local.is_global)  # False
+```
+
+`parse` validates the whole RFC 3966 grammar and returns a frozen `TelURI`. Visual
+separators (`-`, `.`, `(`, `)`) are removed from the number, the extension and a numeric
+`phone-context`. Other parameters land in `params`, keyed by lower-case name, with
+percent-decoded values and `None` for a parameter without a value. `str()` gives a
+normalised form: separators removed, names in lower case, values re-encoded, and `ext` or
+`isub` first, then `phone-context`, then the rest sorted by name, as section 3 asks. The
+letter case of numbers, contexts and values is kept, so two equivalent URIs may still
+print differently. Wrong types (`parse(None)`, `TelURI(123)`) raise `TypeError`.
+
+### Errors
+
+```python
+from teluri import TelURIError, parse
+
+reasons = []
+for bad in ["tel:863-1234", "tel:+1;ext=1;isub=2", "tel:+1;b;a"]:
+    try:
+        parse(bad, strict=True)
+    except TelURIError as error:
+        reasons.append(error.reason)
+print(reasons)  # ['missing-context', 'ext-and-isub', 'param-order']
+```
+
+The ABNF accepts parameters in any order, so `parse` does too; `strict=True` also
+enforces the order rule of section 3, comparing names in lower case.
+
+### Compare
+
+```python
+from teluri import equivalent, parse
+
+print(equivalent("tel:+1-201-555-0123;EXT=1;a=X", "tel:+12015550123;a=x;ext=1"))  # True
+domain = "tel:7042;phone-context=Example.COM."
+print(equivalent(domain, "tel:7042;phone-context=example.com"))  # True
+print(equivalent("tel:+1234", "tel:1234;phone-context=+1"))  # False
+print(len({parse("tel:+1;b;a"), parse("tel:+1;A;B")}))  # 1
+```
+
+`==`, `hash` and `equivalent` follow section 4: global and local numbers never match,
+separators are ignored, a numeric context is compared digit by digit and a domain context
+as a host name (a final root dot is ignored), parameters are compared by name in any
+order, and the comparison is case-insensitive. Values, including `isub`, are compared as
+their percent-decoded octets with ASCII letters folded, so `%2F` equals `/` and `%41`
+equals `a`, while `%C3%A9` and `%C3%89` stay different.
+
+### Build
+
+```python
+from teluri import build
+
+print(build("+1 (201) 555-0123", ext="1234"))  # tel:+12015550123;ext=1234
+print(build("7042", phone_context="example.com"))  # tel:7042;phone-context=example.com
+print(build("+1 201 555 0123", params={"note": "a;b c"}))  # tel:+12015550123;note=a%3Bb%20c
+```
+
+`build` takes human input: it removes spaces and separators from the numbers, encodes
+parameter values, refuses `ext`, `isub` and `phone-context` inside `params`, and always
+writes the canonical order. The result always parses back with `strict=True`.
+
+### Links in the wild
+
+```python
+from teluri import parse_link
+
+print(parse_link("tel:+1 201 555 0123"))  # tel:+12015550123
+print(parse_link("tel:1-408-555-5555", context="+1"))  # tel:14085555555;phone-context=+1
+print(parse_link("tel:*31%23", context="example.com").href)  # tel:*31%23;phone-context=example.com
+```
+
+Web pages and apps often write `tel:` links that RFC 3966 does not allow: spaces as in
+printed numbers, percent-encoded numbers, and local numbers without a `phone-context`
+(Apple's Phone Links reference shows `tel:1-408-555-5555`). `parse_link` decodes and
+cleans the number, adds `context` (checked as a single phone-context descriptor) to a
+local number that has none, then validates the result as RFC 3966. In the other direction, `TelURI.href` writes `#` as `%23`: an HTML
+URL parser would otherwise read it as the start of a fragment. Apple also documents that
+its Phone app does not dial a link containing `*` or `#`.
+
+### Command line
+
+```
+$ teluri "tel:+1-201-555-0123;Ext=9" "tel:863-1234"
+tel:+12015550123;ext=9
+invalid (missing-context): tel:863-1234
+```
+
+One URI per argument, or one per line on standard input. `--json` prints every field,
+`--strict` enforces the parameter order, `--link` reads links as above (not with
+`--strict`) and `--context` gives local links their context. Output is ASCII, so any
+console can print it. The exit status is 1 when any input is invalid, 2 for bad usage.
+
+## API
+
+| Name | What it does |
+| --- | --- |
+| `parse(uri, *, strict=False)` | Parse and validate a `tel:` URI, return a `TelURI` |
+| `parse_link(href, *, context=None)` | Read a real-world `tel:` link, return a `TelURI` |
+| `build(number, *, ext, isub, phone_context, params)` | Canonical `tel:` URI from human input |
+| `equivalent(a, b)` | Section 4 comparison of two URIs (strings or `TelURI`) |
+| `TelURI` | Frozen, hashable result: `number`, `ext`, `isub`, `phone_context`, `params`, `is_global`, `is_e164`, `unknown_mandatory`, `href` |
+| `TelURIError` | `ValueError` with a `reason` from `Reason` |
+| `Reason` | The closed set of reasons, listed below |
+
+`is_e164` checks the E.164 limits only: a global number of at most 15 digits whose
+country code does not start with 0. `unknown_mandatory` lists `m-` parameters; section
+5.4 says not to use a URI whose mandatory parameters you do not understand. `isub` is
+kept in its encoded form because a subaddress may carry any octet.
+
+### Reasons
+
+- `scheme`: not a `tel:` URI
+- `number`: the number is empty or has a character the grammar does not allow
+- `ext`: the extension has no digit, or a character other than digits and separators
+- `isub`: the subaddress is empty or not `1*paramchar` (erratum 203)
+- `ext-and-isub`: both are present, which section 5.3 forbids
+- `phone-context`: the context is neither a global number prefix nor a domain name
+- `missing-context`: a local number without `phone-context`
+- `global-context`: a global number with `phone-context`
+- `param-name`: a parameter name is empty, malformed, or reserved for a field
+- `param-value`: a value is empty, malformed, badly percent-encoded or not UTF-8
+- `duplicate-param`: a parameter appears twice (names compare case-insensitively)
+- `param-order`: with `strict=True`, parameters are not in the section 3 order
+
+## Why
+
+RFC 3966 `tel:` URIs are their own grammar: global numbers with a leading `+`, local
+numbers that must carry a `phone-context`, visual separators, `ext` and `isub`, and a
+comparison rule that ignores separators, case and parameter order. The standard library
+does not model any of it, general URI libraries stop at RFC 3986, and `phonenumbers` is a
+number-validation database rather than a URI codec. teluri is a small, strict, typed one,
+with the browser and phone dialect handled explicitly instead of by accident.
+
+## Sources
+
+RFC 3966 and its errata, the IANA tel URI parameter registry, RFC 4694, 4715, 4759 and
+4904 for the registered parameters. Their examples are checked by the test suite; run
+`python scripts/fetch_upstream.py` to fetch the texts and enable the tests that compare
+against them.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Links
+
+- Website: https://lianes8studio.com
+- GitHub: https://github.com/JaviLianes8
+- LinkedIn: https://www.linkedin.com/in/jlianes/

teluri-0.2.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+teluri/__init__.py,sha256=O7nB3irzTJlyxWlQ63F6-B737eHvXFYrOdKAocUQj_o,405
+teluri/__main__.py,sha256=nvn5Kw4d2dN1-qGGSakvjVKeRQeYtOuL4tp2F7UDgbE,144
+teluri/_build.py,sha256=Je8nHgy-m_o6-xLTF1Lwa399Us6WI6Va3IfT3Fd_8i4,1231
+teluri/_chars.py,sha256=aOibDNjBmcHhPexbDkKozo1BlN65H0EDkENCrfgrT0A,1879
+teluri/_cli.py,sha256=ko8pNEL2FQvXDCx-T4d_hUe2gdi-S6MGNAFPjvmyOgc,3196
+teluri/_errors.py,sha256=x3hb-_Ci3myOIMOPeSf6XqC7Sy8PHGW6v-PCul7fJvQ,860
+teluri/_grammar.py,sha256=UuS2v0-eBuZg5V6vmLpvy8bTMOlYKKvVc7wQ9oCh8Vw,3256
+teluri/_link.py,sha256=jBsUWUNlhApNKbbo-8lLN1ovaxvSw-WSrS8HItsHFVY,1970
+teluri/_model.py,sha256=XPqFFuD2rm0-VdMX4EHGGzccNMFGeG1LBlGbvBjgCz4,5756
+teluri/_params.py,sha256=jHgva-Pn5DIswNDbrDaDKmCsaYOfT8vglifH5pjuum0,1099
+teluri/_parse.py,sha256=6PSAE86BLw88wsgBisX8juh12N23OPWbklvVOrQ2LtY,2489
+teluri/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+teluri-0.2.0.dist-info/METADATA,sha256=WmAdqmrynZTolVtpHYxZpvo9XQVIhplzF8-Z2r4vP0I,9157
+teluri-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+teluri-0.2.0.dist-info/entry_points.txt,sha256=Aizu9XLmP4ErZyChijfTnDMkTJhD4a3nWWCy68N80M0,44
+teluri-0.2.0.dist-info/licenses/LICENSE,sha256=wirD5nCA2aQa5UusK_1YHLBogI3CGcw23xAnulp3L_U,1091
+teluri-0.2.0.dist-info/RECORD,,

teluri-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

teluri-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+teluri = teluri._cli:main

teluri-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Javier Lianes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.