phonelint 0.1.0__py3-none-any.whl

phonelint/__init__.py

@@ -0,0 +1,156 @@
+"""Carrier and line type for phone numbers, from published numbering plans.
+
+libphonenumber parses and formats; it does not tell you who a number belongs to.
+For a UK or US number its `carrier` is usually empty and its type is often
+FIXED_LINE_OR_MOBILE, because that is as far as range metadata goes. This fills
+exactly that gap and nothing else:
+
+    >>> import phonelint
+    >>> r = phonelint.lookup("+44 1803 930000")
+    >>> r.line_type, r.location, r.allocated
+    ('landline', 'Torquay', False)
+
+It is built ON libphonenumber rather than against it. Parsing, validation and
+formatting are delegated to `phonenumbers`, which does them well. What is added
+is the block the number sits in, taken from the regulator's own allocation
+records.
+
+The most useful field is the one nobody else returns: `allocated`. A number in
+a range no operator has been assigned **cannot ring**, whatever its shape. That
+is deterministic, and it is where most of the value in list cleaning sits.
+
+Coverage: United Kingdom, 345,274 prefixes. United States is not bundled — see
+the README; the data exists but its redistribution terms do not permit shipping
+it here yet.
+"""
+from __future__ import annotations
+
+import functools
+import pathlib
+import sqlite3
+from dataclasses import dataclass
+from typing import Optional
+
+__all__ = ["lookup", "Result", "enrich", "coverage", "__version__"]
+__version__ = "0.1.0"
+
+_DATA = pathlib.Path(__file__).parent / "_data"
+# +44 is one numbering plan across four jurisdictions. libphonenumber returns
+# the ISO region, so a Guernsey or Jersey number comes back GG or JE and would
+# miss the dataset entirely — a mobile that resolved to "Guernsey" was the bug
+# that found this.
+_SUPPORTED = {"GB": "uk.db", "GG": "uk.db", "JE": "uk.db", "IM": "uk.db"}
+
+
+@dataclass(frozen=True)
+class Result:
+    """What is known about a number. Fields are None when unknown, never guessed."""
+
+    number: str
+    country: Optional[str] = None
+    valid: Optional[bool] = None          # from libphonenumber: is it a possible number
+    allocated: Optional[bool] = None      # is its block assigned to an operator
+    line_type: Optional[str] = None       # landline | mobile | voip | freephone | ...
+    carrier: Optional[str] = None         # the operator the BLOCK was allocated to
+    location: Optional[str] = None        # the exchange area, where published
+    prefix: Optional[str] = None          # the block that matched
+
+    @property
+    def reachable(self) -> Optional[bool]:
+        """False when the number provably cannot ring. None when not known.
+
+        A number outside an allocated block is dead regardless of how well it
+        is formatted, and that is the one judgement here that is deterministic
+        rather than probabilistic.
+        """
+        if self.valid is False or self.allocated is False:
+            return False
+        if self.valid and self.allocated:
+            return True
+        return None
+
+
+@functools.lru_cache(maxsize=4)
+def _db(country: str) -> Optional[sqlite3.Connection]:
+    name = _SUPPORTED.get(country)
+    if not name:
+        return None
+    path = _DATA / name
+    if not path.exists():
+        return None
+    return sqlite3.connect(f"file:{path}?mode=ro", uri=True, check_same_thread=False)
+
+
+def coverage() -> dict[str, int]:
+    """Prefix count per bundled DATASET, so callers can check before relying on it.
+
+    Keyed by dataset, not by region: GB, GG, JE and IM share one numbering plan
+    and one file, and reporting 345,274 four times would imply four times the
+    data.
+    """
+    out = {}
+    for name in sorted(set(_SUPPORTED.values())):
+        path = _DATA / name
+        if not path.exists():
+            continue
+        regions = sorted(k for k, v in _SUPPORTED.items() if v == name)
+        db = sqlite3.connect(f"file:{path}?mode=ro", uri=True)
+        out["+44 " + "/".join(regions)] = db.execute(
+            "SELECT COUNT(*) FROM blocks").fetchone()[0]
+        db.close()
+    return out
+
+
+def _match(db: sqlite3.Connection, national: str):
+    """Longest matching block.
+
+    Allocation records are published at several depths — a six-digit range and
+    a seven-digit range can both exist, and the longer one is the more specific
+    truth. Matching shortest-first would answer with the parent block and get
+    the operator wrong whenever a range has been subdivided.
+    """
+    for end in range(len(national), 2, -1):
+        row = db.execute(
+            "SELECT prefix, line_type, carrier, location, allocated "
+            "FROM blocks WHERE prefix = ?", (national[:end],)
+        ).fetchone()
+        if row:
+            return row
+    return None
+
+
+def lookup(number: str, region: Optional[str] = None) -> Result:
+    """Look up `number`. `region` is a two-letter code for local-format input."""
+    import phonenumbers
+
+    try:
+        parsed = phonenumbers.parse(number, region)
+    except phonenumbers.NumberParseException:
+        return Result(number=number)
+
+    country = phonenumbers.region_code_for_number(parsed)
+    valid = phonenumbers.is_valid_number(parsed)
+    national = str(parsed.national_number)
+
+    db = _db(country or "")
+    if db is None:
+        # No data bundled for this country. Report what libphonenumber knows
+        # and leave the rest None rather than inventing a confident blank.
+        return Result(number=number, country=country, valid=valid)
+
+    row = _match(db, national)
+    if row is None:
+        return Result(number=number, country=country, valid=valid, allocated=False)
+
+    prefix, line_type, carrier, location, allocated = row
+    return Result(number=number, country=country, valid=valid,
+                  allocated=bool(allocated), line_type=line_type,
+                  carrier=carrier or None, location=location or None,
+                  prefix=prefix)
+
+
+def enrich(parsed) -> Result:
+    """Same as `lookup`, for a number already parsed by `phonenumbers`."""
+    import phonenumbers
+    return lookup(phonenumbers.format_number(
+        parsed, phonenumbers.PhoneNumberFormat.E164))

phonelint-0.1.0.dist-info/METADATA

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: phonelint
+Version: 0.1.0
+Summary: Carrier, line type and block allocation for phone numbers, on top of libphonenumber
+Author: Phonelint
+License: MIT
+Project-URL: Homepage, https://phonelint.com
+Project-URL: Source, https://github.com/phonelint/phonelint-py
+Keywords: phone,telephone,carrier,line-type,numbering-plan,libphonenumber,validation,ofcom,msisdn
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Communications :: Telephony
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: phonenumbers>=8.13
+Dynamic: license-file
+
+# phonelint
+
+**Is this number's range actually assigned to anyone?**
+
+`libphonenumber` tells you a number is well-formed and what type it looks like.
+It does not tell you whether the range it sits in has been allocated to an
+operator — and a number in an unallocated range **cannot ring**, however
+perfectly it is formatted.
+
+```python
+import phonelint
+
+r = phonelint.lookup("+44 1803 930000")
+r.line_type   # 'landline'
+r.location    # 'Torquay'
+r.allocated   # False  <- this range is published as Free
+r.reachable   # False
+```
+
+`libphonenumber` calls that same number `FIXED_LINE` and valid. Both are true.
+It still cannot ring.
+
+## The comparison, reproducible in ten lines
+
+```python
+import phonenumbers, phonelint
+from phonenumbers import carrier, number_type
+
+n = phonenumbers.parse("+441803930000", None)
+print(number_type(n), repr(carrier.name_for_number(n, "en")))
+#  1 ''                       <- FIXED_LINE, no carrier
+
+print(phonelint.lookup("+441803930000"))
+#  line_type='landline' location='Torquay' allocated=False reachable=False
+```
+
+| | libphonenumber | phonelint |
+|---|---|---|
+| parse, format, validate | **yes** | delegates to it |
+| line type | yes, where ranges allow | from allocation records |
+| operator the range was allocated to | often empty | yes, where published |
+| **is the range allocated at all** | **no** | **yes** |
+
+This is a companion, not a replacement. Parsing is a solved problem and
+`libphonenumber` solved it; this adds the one layer it does not carry.
+
+## Install
+
+```
+pip install phonelint
+```
+
+`phonenumbers` comes with it. No network calls, no API key, no account. Every
+lookup is local.
+
+## Coverage
+
+```python
+phonelint.coverage()
+# {'+44 GB/GG/IM/JE': 345274}
+```
+
+**United Kingdom only, 345,274 prefixes**, from Ofcom's published allocation
+records. GB, Guernsey, Jersey and the Isle of Man share one numbering plan and
+one dataset.
+
+**The United States is not bundled.** It is where the gap is widest —
+`libphonenumber` returns `FIXED_LINE_OR_MOBILE` and an empty carrier for
+essentially every US number, because NANP mobile and landline numbers come from
+the same ranges and nothing in the digits separates them. The allocation data
+that answers it is public, but NANPA publishes no terms of use, only a blanket
+copyright footer, and redistributing someone else's data inside a package is a
+different act from reading it. The code is country-agnostic; if that is settled
+the data drops in without an API change.
+
+## What this does not do
+
+**It does not know about porting.** `carrier` is the operator a *range* was
+allocated to. A subscriber who moved network keeps their number, so a ported
+number still reports the operator it started with. Resolving that needs a live
+query against the routing database, which no offline dataset can answer. If
+your use case turns on current network rather than original allocation, this is
+not the tool and nothing offline is.
+
+**It does not tell you a number is in service.** An allocated range means
+numbers in it *can* exist. Whether a particular one is connected today is a
+different question, and again a live one.
+
+**`allocated=False` is the firm half.** That one is deterministic: if the
+regulator has assigned the range to nobody, nothing in it rings. Most of the
+value in cleaning a list is there.
+
+## API
+
+```python
+phonelint.lookup(number: str, region: str | None = None) -> Result
+phonelint.enrich(parsed_phonenumber) -> Result
+phonelint.coverage() -> dict[str, int]
+```
+
+`Result` fields are `None` when unknown and are never guessed:
+
+`number` `country` `valid` `allocated` `line_type` `carrier` `location`
+`prefix` `reachable`
+
+`region` is a two-letter code, needed only for numbers written in local format
+(`"01803 930000", "GB"`).
+
+## Data licence
+
+Code is MIT. The bundled UK data is separate:
+
+> Contains information licensed under the Open Government Licence v3.0.
+
+See [DATA-LICENCE.md](DATA-LICENCE.md). Ofcom does not endorse this package.
+
+## Related
+
+Built by the people behind [phonelint.com](https://phonelint.com) — a desktop
+bulk list cleaner and a free browser tool that does the same allocation check
+on a whole file without uploading it.
+
+## Development
+
+```
+git clone https://github.com/<owner>/phonelint-py
+cd phonelint-py
+pip install -e . pytest
+pytest -q
+```
+
+`pip install -e .` matters: this is a `src/` layout, so `pytest` on a fresh
+clone fails with `ModuleNotFoundError: No module named 'phonelint'` until the
+package is installed, or `PYTHONPATH=src` is set. That is the layout working as
+intended, not a broken checkout.

phonelint-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+phonelint/__init__.py,sha256=6PATKqlUGYeGw5a5ySl8AYSG5tCRFJwZY6gwZgEgxgU,6048
+phonelint/_data/uk.db,sha256=nRSMFHaVt_PlNMVRMoT4Vi0RoHdRaxiWKp_jORSel9M,13438976
+phonelint-0.1.0.dist-info/licenses/LICENSE,sha256=yRzfu7MD0y0cpNoFj7a_GWodg0YHJH-evyeMld-mRVk,1066
+phonelint-0.1.0.dist-info/METADATA,sha256=CuP498iES_-a2zdSmu-mbiuV0ZEYUOkZwJwK_U50Pzg,5323
+phonelint-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+phonelint-0.1.0.dist-info/top_level.txt,sha256=PloyMK_pJp0EFWWGEJJrRjmRJBUh_FL4ouLZrFOpJGY,10
+phonelint-0.1.0.dist-info/RECORD,,

phonelint-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

phonelint-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Phonelint
+
+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.

phonelint-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+phonelint