teluri 0.2.0__tar.gz → 1.0.0__tar.gz

teluri-1.0.0/CHANGELOG.md

@@ -0,0 +1,103 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0] - 2026-11-01
+
+### Stable
+
+- The seven exported names, their signatures and defaults: `Reason`, `TelURI`,
+  `TelURIError`, `build`, `equivalent`, `parse` and `parse_link`.
+- Validated immutable URI fields, canonical serialization, RFC 3966 comparison,
+  the explicit link dialect, typed error reasons and command-line modes.
+- Python 3.10 through 3.14; no runtime dependencies; `py.typed` included.
+
+### Changed
+
+- Library errors and CLI diagnostics no longer echo input, parameter names or values.
+  CLI usage errors also omit arbitrary arguments. Error reasons remain unchanged;
+  caller-created `TelURIError(reason, message)` still preserves its message and args.
+- `parse` requires a boolean `strict`; `parse_link` rejects a non-string context with
+  `TypeError` rather than leaking `AttributeError`. `build` checks strings before
+  stripping whitespace and rejects false-valued non-mappings in `params`.
+- Wrong-type diagnostics use fixed descriptions rather than user-controlled type names.
+  `equivalent` names the offending argument (`a must be a str or TelURI`, or `b ...`)
+  instead of reporting `uri must be a str` for either one.
+- CLI output failures caused by a closed pipe return 1 without a traceback.
+- String subclasses are normalized to plain strings before validation and storage,
+  including mapping keys and values, so overridden operations cannot bypass validation.
+- CLI stdin decoding keeps its configured encoding and replaces malformed bytes with
+  characters that fail URI validation. Invalid lines receive bounded diagnostics and
+  valid neighboring lines are processed, even with strict input decoding configured.
+- A parameter value or link number that is not valid UTF-8 raises `TelURIError` without
+  the underlying `UnicodeDecodeError` as `__context__`, so the undecodable input no longer
+  stays reachable from the error. No library error is chained to another exception.
+- Duplicate parameter detection uses a set rather than scanning an ever-growing list.
+- `TelURI` and `TelURIError` identify their public module as `teluri`; old pickles still
+  load, and new pickles also load in 0.2.0. The accidental `annotations` attribute is removed.
+- The release helper checks version availability and a clean working tree, preserves
+  any existing `dist` directory and stops if a quality or build check fails.
+
+### Added
+
+- Runnable public docstrings, a guide with explicit grammar policies, strict consumer
+  typing checks, seeded properties, refreshed source checks and wheel upgrade tests.
+- Source distributions include the development requirements and check script referenced
+  by their contributor instructions.
+- Contracts for long domain contexts, multiple href hashes, reflected equality,
+  single-pass link decoding, populated CLI JSON fields and stdin whitespace handling.
+- Contracts for string subclasses that override indexing or hide invalid numbers and
+  extensions through iteration, and malformed stdin under `ignore` and
+  `surrogateescape` decoding policies while preserving valid neighboring lines.
+- Contracts preserving underlying numbers in strict parsing with overridden partitioning,
+  and constructor numbers and extensions with overridden indexing, including canonical URIs.
+- Contracts rejecting invalid false-valued extension subclasses whose iteration hides
+  their text, and preserving valid false-valued extensions, subaddresses and contexts.
+- Contracts rejecting invalid false-valued number subclasses and preserving valid ones,
+  plus bounded constructor type errors that omit private optional-field input.
+- Contracts pinning the exact constructor type-error messages for `number`, the optional
+  text fields and `params`, so no part of a private input representation can be appended.
+- Contracts requiring every syntax reason and every wrong-type error to carry no
+  `__cause__` or `__context__` and no input in its formatted traceback, plus a source
+  check that no raise chains with `from` or raises a new error inside a handler.
+- The consumer typing check runs inline with no config file or cache, so it writes
+  nothing to disk and does not depend on the pytest temporary directory.
+
+## [0.2.0]
+
+### Added
+
+- `TelURIError.reason` from the closed set `Reason`; errors survive pickling.
+- Full RFC 3966 grammar: ASCII digits only, domain names per the ABNF, `pvalue` and
+  percent-encoding checks, `isub` per erratum 203, `ext` and `isub` mutually exclusive.
+- `parse(..., strict=True)` enforces the section 3 parameter order.
+- `equivalent(a, b)`, and `==` and `hash` on `TelURI`, follow the section 4 rules.
+- `TelURI.isub`, `is_e164`, `unknown_mandatory` and `href`.
+- `parse_link` reads real-world `tel:` links (spaces, encoded numbers, missing context).
+- `build` accepts `isub`, strips spaces from printed numbers and encodes values.
+- `teluri` command line with `--json`, `--strict`, `--link` and `--context`.
+
+### Changed
+
+- `str(TelURI)` writes the canonical form: section 3 order, lower-case parameter names.
+- `TelURI(number, ext, isub, phone_context, params)`: `is_global` is now derived from the
+  number, every field is validated on construction (wrong types raise `TypeError`), and
+  `params` is read-only and hashable.
+- `params` values are percent-decoded; `isub` has its own field.
+- `build` percent-encodes `params` values, so callers that passed encoded values must now
+  pass plain text.
+- `TelURIError(reason, message)` replaces the single message argument.
+
+## [0.1.0]
+
+- First release: parse and build tel: URIs per RFC 3966.
+- `parse` reads global numbers (leading `+`) and local numbers with a
+  `phone-context`, strips visual separators, and keeps other parameters verbatim.
+- `build` composes a tel: URI from a number, optional `ext`, optional
+  `phone-context` and extra parameters, normalizing visual separators.
+- `TelURI` is a frozen, typed result whose `str()` round-trips through `build`.
+- `TelURIError` signals malformed input.

{teluri-0.2.0 → teluri-1.0.0}/CONTRIBUTING.md

@@ -1,19 +1,21 @@
-# Contributing
-
-Thanks for taking the time. This project keeps a small, predictable shape.
-
-## Setup
-
-```
-pip install -r requirements-dev.txt
-```
-
-## Before you open a pull request
-
-- Keep public API in `src/teluri/__init__.py`; internals live in `_`-prefixed modules.
-- Add a test for the behaviour you change. Tests inject time, disk and network; they
-  never touch the real thing.
-- Run `scripts/check.ps1` (format, lint, types, tests) and make sure it passes.
-- One logical change per commit, imperative subject line.
-
-Open an issue first if the change is large or shifts the public API.
+# Contributing
+
+Thanks for taking the time. This project keeps a small, predictable shape.
+Run the commands below from the repository root or an unpacked source distribution;
+both include `requirements-dev.txt` and `scripts/check.ps1`.
+
+## Setup
+
+```
+pip install -r requirements-dev.txt
+```
+
+## Before you open a pull request
+
+- Keep public API in `src/teluri/__init__.py`; internals live in `_`-prefixed modules.
+- Add a test for the behaviour you change. Tests inject time, disk and network; they
+  never touch the real thing.
+- Run `scripts/check.ps1` (format, lint, types, tests) and make sure it passes.
+- One logical change per commit, imperative subject line.
+
+Open an issue first if the change is large or shifts the public API.

teluri-1.0.0/GUIDE.md

@@ -0,0 +1,139 @@
+# teluri guide
+
+## Stable surface
+
+Import only from `teluri`. `__all__` contains `Reason`, `TelURI`, `TelURIError`,
+`build`, `equivalent`, `parse` and `parse_link`. `__version__` is the release version.
+Parameter names, positional arguments, keyword-only arguments and defaults are stable:
+
+```python
+from teluri import TelURI, build, equivalent, parse, parse_link
+
+uri = TelURI("7042", phone_context="example.com", params={"m-service": "desk"})
+print(uri.unknown_mandatory)  # ('m-service',)
+print(build("+1 201", ext="3"))  # tel:+1201;ext=3
+print(equivalent(parse("tel:+1-201"), "TEL:+1201"))  # True
+print(parse_link("tel:7042", context="example.com"))  # tel:7042;phone-context=example.com
+```
+
+`TelURI(number, ext=None, isub=None, phone_context=None, params=<empty mapping>)`
+validates on construction. It snapshots the mapping, normalizes the number, extension
+and numeric context, and stores generic parameter names in sorted lower case. Its public
+fields are frozen; changing a source mapping later does not change the URI. The mapping
+interface is read-only. Private attributes are outside the immutability contract.
+`dataclasses.replace` validates again. Copying and pickling preserve values.
+
+`parse(uri, *, strict=False)` accepts parameters in any order. `strict=True` also
+requires `ext` or `isub` first, then `phone-context`, then generic parameters sorted
+by lower-case name. Duplicate names are always invalid.
+
+`build(number, *, ext=None, isub=None, phone_context=None, params=None)` removes
+Unicode whitespace from numbers, extensions and numeric contexts. It percent-encodes
+plain-text generic parameter values as UTF-8. Pass `isub` already percent-encoded.
+Reserved names in `params` are rejected; use the corresponding fields instead.
+
+`parse_link(href, *, context=None)` strips surrounding whitespace, decodes the number
+as UTF-8 and removes its Unicode whitespace. A local number without a context uses
+the supplied context. An existing context wins; a global number ignores the default.
+Any supplied default is still validated. Encoded semicolons cannot inject parameters.
+Parameter syntax is the same as `parse`; parameter order remains permissive.
+
+`equivalent(a, b)` accepts strings or `TelURI` objects. Invalid strings raise the same
+errors as `parse`. `==` and `hash` use the same identity: separator-free numbers,
+case-insensitive ASCII octets, the same parameter names and values, and context identity.
+A domain's final root dot is ignored. Local and global numbers are never equivalent.
+A local context is an identifier, not a prefix to concatenate with a local number.
+
+## Syntax policies and limits
+
+The basis is [RFC 3966](https://www.rfc-editor.org/rfc/rfc3966.html), sections 3 to 5,
+with [verified erratum 203](https://www.rfc-editor.org/errata/eid203) for `isub`.
+The following are deliberate library policies, also present in 0.2.0:
+
+- Generic parameter values must decode as UTF-8. An `isub` can contain any encoded
+  octet and retains its encoded spelling. Empty values are invalid; `None` means a flag.
+- An extension must contain a digit, even though the RFC's ABNF also permits a string
+  of separators. Global syntax accepts any positive digit count, including a leading 0.
+- Parameter values follow the ABNF character set, including literal `+`. Comparison
+  folds decoded ASCII bytes, including reserved characters represented by percent escapes.
+- Domain contexts follow the RFC's label syntax without DNS resolution or length limits.
+- Registered parameters such as `rn`, `cic`, `tgrp` and `isub-encoding` receive generic
+  syntax validation only. Their parameter-specific semantics belong to the caller.
+- `unknown_mandatory` reports every `m-` name in sorted order. The caller decides which
+  it understands before using the URI. The parser does not dial or contact anything.
+- `is_e164` is only a shape check: global, 1 to 15 digits, nonzero first digit. It does
+  not validate assigned country codes, number lengths by country, or reachability.
+- `href` escapes `#` for URL use, but does not HTML-escape `&` or quotes. Use an HTML
+  serializer when putting it into markup. Not every device can dial every valid URI.
+
+There is no fixed input length cap. Work is linear in input length plus parameter
+sorting, O(p log p); memory is proportional to input and output size. Applications
+receiving untrusted traffic should choose limits appropriate to their own workload.
+
+## Errors
+
+Malformed text raises `TelURIError`, a `ValueError`. `.reason` is one of the twelve
+`Literal` strings in `Reason`; see the complete list in the
+[README](https://github.com/JaviLianes8/teluri/blob/main/README.md#reasons).
+`.message` provides a short description; `.args` is `(reason, message)`.
+Library-generated diagnostics never include input. The wording is not a stable parser
+interface: branch on `.reason`. Directly creating an exception preserves a caller's
+message without redacting it. `Reason` is a typing alias, not a runtime validator.
+
+```python
+from teluri import TelURIError, parse
+
+try:
+    parse("tel:7042")
+except TelURIError as error:
+    print(error.reason)  # missing-context
+```
+
+Wrong argument types raise `TypeError`: URI text, number and optional string fields,
+the boolean `strict`, the default link context, and mapping keys. Invalid generic
+parameter values, including non-strings, raise `TelURIError` with `param-value`.
+`None` is accepted only where shown in the signatures.
+String subclasses are accepted using their underlying text, without invoking overridden
+string operations. Validation and stored fields use plain strings, including parameter
+names and values.
+
+## Command line
+
+Both `teluri` and `python -m teluri` accept one URI per argument, or one URI per stdin
+line when there are no arguments. Empty lines are skipped. Each valid URI produces a
+canonical line on stdout; each invalid URI produces `invalid (reason)` on stderr.
+`--json` emits one ASCII JSON object per valid URI with `uri`, `number`, `global`,
+`e164`, `ext`, `isub`, `phone_context` and `params`. `--strict`, `--link` and
+`--context` match the API options. `--context` requires `--link`; `--link` and
+`--strict` cannot be combined. Use `--` before URIs beginning with `-`.
+
+Exit codes: 0 for success or help, 1 if any URI is invalid or an output pipe closes,
+2 for invalid command-line usage. Inputs are processed independently and in order.
+Diagnostics are ASCII, bounded per input, and omit the supplied data.
+Stdin uses its configured encoding. Malformed byte sequences become replacement
+characters, which fail URI validation on that line; valid neighboring lines still run.
+Only line endings are removed in the default and `--strict` modes. `--link` removes
+surrounding whitespace, but a whitespace-only line is invalid in every mode.
+
+## Upgrading from 0.2.0
+
+Install with `pip install --upgrade teluri`. The exported signatures, valid URI results,
+and error reasons remain unchanged. Invalid-type handling is stricter, diagnostics no
+longer echo data, and pipe failures exit quietly. Import classes from `teluri`; their
+public module identity now also controls new pickles. Existing 0.2.0 pickles remain
+readable. See every change in the
+[1.0.0 changelog](https://github.com/JaviLianes8/teluri/blob/main/CHANGELOG.md).
+
+## Reproducing checks
+
+Install `.[dev]`, then run `ruff format --check .`, `ruff check .`,
+`mypy --strict src tests` and `pytest --basetemp=<your-scratch-directory>`.
+Tests use a 300-second per-test timeout. Set `TELURI_UPSTREAM` to a local scratch
+directory and run `python scripts/fetch_upstream.py` to enable fetched-source checks.
+Sources are hash-checked against the manifest and are never distributed.
+Set `TELURI_E2E=1` for wheel builds and clean-environment tests, and `TELURI_PYPI=1`
+to include installing and upgrading the published 0.2.0 release. Set `TEMP` and `TMP`
+to your scratch directory so build and venv tools use it too. The optional reference
+checks use `phonenumbers` and `pypdf`, installed separately, and otherwise skip cleanly.
+`TELURI_OLD_PYTHON` can point to a separate environment containing PyPI 0.2.0 to run
+the seeded compatibility comparison without rebuilding the distributions.

{teluri-0.2.0 → teluri-1.0.0}/LICENSE

@@ -1,21 +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.
+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.

{teluri-0.2.0 → teluri-1.0.0}/PKG-INFO

@@ -1,9 +1,10 @@
 Metadata-Version: 2.5
 Name: teluri
-Version: 0.2.0
+Version: 1.0.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: Source, 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/
@@ -12,7 +13,7 @@ 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: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
@@ -30,12 +31,15 @@ Provides-Extra: dev
 Requires-Dist: build; extra == 'dev'
 Requires-Dist: mypy; extra == 'dev'
 Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-timeout; extra == 'dev'
 Requires-Dist: ruff; extra == 'dev'
 Requires-Dist: twine; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # teluri
 
+[![Lianes8 Certified](https://lianes8studio.com/certified/lianes8-certified-badge.svg)](https://lianes8studio.com/certified)
+
 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.
 
@@ -65,7 +69,7 @@ print(local.phone_context)  # +1914555
 print(local.is_global)  # False
 ```
 
-`parse` validates the whole RFC 3966 grammar and returns a frozen `TelURI`. Visual
+`parse` validates RFC 3966 syntax with the policies in the [guide](https://github.com/JaviLianes8/teluri/blob/main/GUIDE.md) 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
@@ -147,13 +151,14 @@ its Phone app does not dial a link containing `*` or `#`.
 ```
 $ teluri "tel:+1-201-555-0123;Ext=9" "tel:863-1234"
 tel:+12015550123;ext=9
-invalid (missing-context): tel:863-1234
+invalid (missing-context)
 ```
 
 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.
+Diagnostics contain the reason, never the input. A closed output pipe exits 1 quietly.
 
 ## API
 
@@ -167,8 +172,8 @@ console can print it. The exit status is 1 when any input is invalid, 2 for bad
 | `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
+`is_e164` checks only global syntax, at most 15 digits and a nonzero first digit;
+it does not check country allocation or dialability. `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.
 
@@ -189,12 +194,13 @@ kept in its encoded form because a subaddress may carry any octet.
 
 ## 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.
+Use teluri to preserve URI parameters, validate local contexts and compare URI identity.
+[urllib.parse](https://docs.python.org/3/library/urllib.parse.html) splits URL components;
+it does not validate telephone syntax.
+[phonenumbers](https://github.com/daviddrysdale/python-phonenumbers) parses and formats
+phone numbers, including RFC 3966 forms, and supplies numbering-plan validation.
+Choose it when you need country or number validity checks. teluri keeps arbitrary URI
+parameters and local identifiers without a numbering database or runtime dependencies.
 
 ## Sources
 
@@ -203,9 +209,13 @@ RFC 3966 and its errata, the IANA tel URI parameter registry, RFC 4694, 4715, 47
 `python scripts/fetch_upstream.py` to fetch the texts and enable the tests that compare
 against them.
 
+See the [guide and limits](https://github.com/JaviLianes8/teluri/blob/main/GUIDE.md),
+[release changes](https://github.com/JaviLianes8/teluri/blob/main/CHANGELOG.md), and
+[reference manifest](https://github.com/JaviLianes8/teluri/blob/main/tests/upstream/MANIFEST.json).
+
 ## License
 
-MIT. See [LICENSE](LICENSE).
+MIT. See [LICENSE](https://github.com/JaviLianes8/teluri/blob/main/LICENSE).
 
 ## Links
 

{teluri-0.2.0 → teluri-1.0.0}/README.md

@@ -1,5 +1,7 @@
 # teluri
 
+[![Lianes8 Certified](https://lianes8studio.com/certified/lianes8-certified-badge.svg)](https://lianes8studio.com/certified)
+
 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.
 
@@ -29,7 +31,7 @@ print(local.phone_context)  # +1914555
 print(local.is_global)  # False
 ```
 
-`parse` validates the whole RFC 3966 grammar and returns a frozen `TelURI`. Visual
+`parse` validates RFC 3966 syntax with the policies in the [guide](https://github.com/JaviLianes8/teluri/blob/main/GUIDE.md) 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
@@ -111,13 +113,14 @@ its Phone app does not dial a link containing `*` or `#`.
 ```
 $ teluri "tel:+1-201-555-0123;Ext=9" "tel:863-1234"
 tel:+12015550123;ext=9
-invalid (missing-context): tel:863-1234
+invalid (missing-context)
 ```
 
 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.
+Diagnostics contain the reason, never the input. A closed output pipe exits 1 quietly.
 
 ## API
 
@@ -131,8 +134,8 @@ console can print it. The exit status is 1 when any input is invalid, 2 for bad
 | `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
+`is_e164` checks only global syntax, at most 15 digits and a nonzero first digit;
+it does not check country allocation or dialability. `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.
 
@@ -153,12 +156,13 @@ kept in its encoded form because a subaddress may carry any octet.
 
 ## 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.
+Use teluri to preserve URI parameters, validate local contexts and compare URI identity.
+[urllib.parse](https://docs.python.org/3/library/urllib.parse.html) splits URL components;
+it does not validate telephone syntax.
+[phonenumbers](https://github.com/daviddrysdale/python-phonenumbers) parses and formats
+phone numbers, including RFC 3966 forms, and supplies numbering-plan validation.
+Choose it when you need country or number validity checks. teluri keeps arbitrary URI
+parameters and local identifiers without a numbering database or runtime dependencies.
 
 ## Sources
 
@@ -167,9 +171,13 @@ RFC 3966 and its errata, the IANA tel URI parameter registry, RFC 4694, 4715, 47
 `python scripts/fetch_upstream.py` to fetch the texts and enable the tests that compare
 against them.
 
+See the [guide and limits](https://github.com/JaviLianes8/teluri/blob/main/GUIDE.md),
+[release changes](https://github.com/JaviLianes8/teluri/blob/main/CHANGELOG.md), and
+[reference manifest](https://github.com/JaviLianes8/teluri/blob/main/tests/upstream/MANIFEST.json).
+
 ## License
 
-MIT. See [LICENSE](LICENSE).
+MIT. See [LICENSE](https://github.com/JaviLianes8/teluri/blob/main/LICENSE).
 
 ## Links
 

{teluri-0.2.0 → teluri-1.0.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "teluri"
-version = "0.2.0"
+version = "1.0.0"
 description = "Strict, typed, zero-dependency parser, builder and comparator for tel: URIs (RFC 3966), with a reader for real-world tel: links"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -13,7 +13,7 @@ license-files = ["LICENSE"]
 authors = [{ name = "Javier Lianes", email = "javier@lianes8studio.com" }]
 keywords = ["tel", "uri", "rfc3966", "telephone", "phone", "phone-number", "e164", "href", "link", "sip", "parser"]
 classifiers = [
-    "Development Status :: 4 - Beta",
+    "Development Status :: 5 - Production/Stable",
     "Intended Audience :: Developers",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
@@ -30,11 +30,12 @@ classifiers = [
 dependencies = []
 
 [project.optional-dependencies]
-dev = ["ruff", "mypy", "pytest", "build", "twine"]
+dev = ["ruff", "mypy", "pytest", "pytest-timeout", "build", "twine"]
 
 [project.urls]
 Homepage = "https://lianes8studio.com"
 Repository = "https://github.com/JaviLianes8/teluri"
+Source = "https://github.com/JaviLianes8/teluri"
 Issues = "https://github.com/JaviLianes8/teluri/issues"
 Changelog = "https://github.com/JaviLianes8/teluri/blob/main/CHANGELOG.md"
 LinkedIn = "https://www.linkedin.com/in/jlianes/"
@@ -51,9 +52,12 @@ include = [
     "tests/data/examples.json",
     "tests/upstream/MANIFEST.json",
     "scripts/fetch_upstream.py",
+    "scripts/check.ps1",
+    "requirements-dev.txt",
     "CHANGELOG.md",
     "CONTRIBUTING.md",
     "README.md",
+    "GUIDE.md",
     "LICENSE",
     "pyproject.toml",
 ]
@@ -76,3 +80,4 @@ strict = true
 testpaths = ["tests"]
 pythonpath = ["src"]
 addopts = "-q"
+timeout = 300

teluri-1.0.0/requirements-dev.txt

@@ -0,0 +1,3 @@
+# Development dependencies: the package in editable mode plus its dev extras
+# (ruff, mypy, pytest, build, twine). Install with:  pip install -r requirements-dev.txt
+-e .[dev]

teluri-1.0.0/scripts/check.ps1

@@ -0,0 +1,16 @@
+# Local quality gate. Run before every commit. No CI runs in the cloud.
+# $ErrorActionPreference does NOT stop on a native command's non-zero exit, so each tool's
+# exit code is checked explicitly: a red gate must fail, never pass silently.
+$ErrorActionPreference = "Stop"
+
+function Invoke-Step($label, [scriptblock]$cmd) {
+    Write-Host "== $label =="
+    & $cmd
+    if ($LASTEXITCODE -ne 0) { Write-Host "FAILED: $label (exit $LASTEXITCODE)"; exit $LASTEXITCODE }
+}
+
+Invoke-Step "ruff format" { ruff format --check . }
+Invoke-Step "ruff lint"   { ruff check . }
+Invoke-Step "mypy"        { mypy --strict src tests }
+Invoke-Step "pytest"      { python -m pytest }
+Write-Host "gate green"

{teluri-0.2.0 → teluri-1.0.0}/scripts/fetch_upstream.py

@@ -10,15 +10,18 @@ from __future__ import annotations
 
 import hashlib
 import json
+import os
 import sys
 import urllib.request
 from pathlib import Path
 
-FOLDER = Path(__file__).resolve().parents[1] / "tests" / "upstream"
+MANIFEST = Path(__file__).resolve().parents[1] / "tests" / "upstream" / "MANIFEST.json"
+FOLDER = Path(os.environ.get("TELURI_UPSTREAM", str(MANIFEST.parent)))
 
 
 def main() -> int:
-    manifest = json.loads((FOLDER / "MANIFEST.json").read_text(encoding="utf-8"))
+    manifest = json.loads(MANIFEST.read_text(encoding="utf-8"))
+    FOLDER.mkdir(parents=True, exist_ok=True)
     failed = 0
     for name, entry in manifest.items():
         with urllib.request.urlopen(entry["url"], timeout=60) as response:

{teluri-0.2.0 → teluri-1.0.0}/src/teluri/__init__.py

@@ -2,12 +2,20 @@
 
 from __future__ import annotations
 
+from typing import get_type_hints as _get_type_hints
+
 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"
+__version__ = "1.0.0"
+
+TelURI.__annotations__ = _get_type_hints(TelURI)
+TelURI.__module__ = __name__
+TelURIError.__module__ = __name__
+
+del annotations
 
 __all__ = ["Reason", "TelURI", "TelURIError", "build", "equivalent", "parse", "parse_link"]