hts-lookup 0.1.0__py3-none-any.whl

hts_lookup/__init__.py

@@ -0,0 +1,145 @@
+"""Offline lookup and validation of US Harmonized Tariff Schedule (HTS) codes.
+
+    >>> import hts_lookup as hts
+    >>> hts.lookup("6201.40.70").general
+    '7.1%'
+    >>> hts.is_valid("6201.40.99.99")
+    False
+"""
+import gzip
+import json
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import List, Optional, Tuple
+
+__version__ = "0.1.0"
+__all__ = ["Line", "lookup", "is_valid", "closest", "children", "search", "format_code", "RELEASE", "TITLE", "EFFECTIVE"]
+
+
+def _load():
+    with gzip.open(Path(__file__).with_name("data") / "hts.json.gz", "rt", encoding="utf-8") as f:
+        return json.load(f)
+
+
+_DATA = _load()
+RELEASE: str = _DATA["release"]      # e.g. "2026HTSRev21"
+TITLE: str = _DATA["title"]          # e.g. "Revision 21 (2026)"
+EFFECTIVE: str = _DATA["effective"]  # MM/DD/YYYY, as published by USITC
+_ROWS = _DATA["rows"]                # [digits, indent, description, general, special, column 2, units]
+_INDEX = {r[0]: i for i, r in enumerate(_ROWS) if r[0]}
+
+
+@dataclass
+class Line:
+    code: str                       # dotted, e.g. "6201.40.70.00"
+    description: str
+    path: List[Tuple[str, str]]     # (code or "", description) from the heading down, including unnumbered levels
+    general: str                    # general (MFN) rate that applies, inherited from the 8-digit line if needed
+    special: str = ""
+    column2: str = ""
+    units: List[str] = field(default_factory=list)
+    declarable: bool = True         # False for headings and subheadings that have more detailed lines under them
+
+    def __str__(self):
+        return f"{self.code} {self.description} | general {self.general or '-'}"
+
+
+def _digits(code) -> str:
+    return re.sub(r"\D", "", str(code))
+
+
+def format_code(code) -> str:
+    """'6201407000' -> '6201.40.70.00'."""
+    d = _digits(code)
+    parts = [d[:4], d[4:6], d[6:8], d[8:10]]
+    return ".".join(p for p in parts if p)
+
+
+def _path(i: int) -> List[list]:
+    stack: List[list] = []
+    start = i
+    while start > 0 and not (_ROWS[start][0] and len(_ROWS[start][0]) == 4):
+        start -= 1
+    for r in _ROWS[start:i + 1]:
+        while stack and stack[-1][1] >= r[1]:
+            stack.pop()
+        stack.append(r)
+    return stack
+
+
+def _has_children(d: str) -> bool:
+    return any(k.startswith(d) and len(k) > len(d) for k in _INDEX)
+
+
+def lookup(code) -> Optional[Line]:
+    """Return the line for a 4- to 10-digit code, or None if it is not in the schedule.
+
+    A six- or eight-digit code that has no row of its own but has lines under it (common in the US
+    schedule) is returned as a non-declarable subheading with the description of its first line's parent.
+    """
+    d = _digits(code)
+    i = _INDEX.get(d)
+    if i is None:
+        sub = sorted(k for k in _INDEX if k.startswith(d) and len(k) > len(d))
+        if len(d) < 4 or not sub:
+            return None
+        first = _INDEX[sub[0]]
+        path = _path(first)[:-1]
+        top = [k for k in sub if len(k) == min(len(x) for x in sub)]
+        if len(top) == 1 and len(top[0]) == 10:
+            # e.g. 6201.40.70 has only the line 6201.40.70.00: that line is the answer.
+            return lookup(top[0])
+        # A subheading with a single line under it carries its text on that line (e.g. 8471.30 -> 8471.30.01.00).
+        desc = _ROWS[first][2] if len(top) == 1 else (path[-1][2] if path else "")
+        return Line(format_code(d), desc, [(format_code(p[0]) if p[0] else "", p[2]) for p in path], "", declarable=False)
+    stack = _path(i)
+    r = _ROWS[i]
+    general = r[3] or next((s[3] for s in reversed(stack) if s[3]), "")
+    special = r[4] or next((s[4] for s in reversed(stack) if s[3]), "")
+    column2 = r[5] or next((s[5] for s in reversed(stack) if s[3]), "")
+    return Line(format_code(d), r[2], [(format_code(s[0]) if s[0] else "", s[2]) for s in stack], general, special, column2,
+                list(r[6]), declarable=not _has_children(d))
+
+
+def is_valid(code) -> bool:
+    """True if the code exists in the current US schedule (as a line or as a subheading with lines under it)."""
+    return lookup(code) is not None
+
+
+def closest(code) -> Optional[Line]:
+    """The longest valid code that the given code starts with, e.g. for a made-up 10-digit code."""
+    d = _digits(code)
+    for n in (10, 8, 6, 4):
+        if len(d) >= n:
+            hit = lookup(d[:n])
+            if hit:
+                return hit
+    return None
+
+
+def children(code) -> List[Line]:
+    """The next level of numbered lines under a heading or subheading."""
+    d = _digits(code)
+    kids = sorted(k for k in _INDEX if k.startswith(d) and len(k) > len(d))
+    if not kids:
+        return []
+    step = min(len(k) for k in kids)
+    return [lookup(k) for k in kids if len(k) == step]
+
+
+def search(text: str, limit: int = 20, declarable_only: bool = True) -> List[Line]:
+    """Lines whose full official path contains every word of `text` (case-insensitive)."""
+    words = [w for w in re.findall(r"[a-z0-9]+", text.lower()) if w]
+    out = []
+    for k, i in _INDEX.items():
+        if declarable_only and len(k) < 8:
+            continue
+        hay = " ".join(p[2] for p in _path(i)).lower()
+        if all(w in hay for w in words):
+            line = lookup(k)
+            if not declarable_only or line.declarable:
+                out.append(line)
+                if len(out) >= limit:
+                    break
+    return out

hts_lookup/__main__.py

@@ -0,0 +1,46 @@
+"""Command line: hts-lookup 6201.40.70 | hts-lookup --search "lithium ion" | hts-lookup --children 8507"""
+import argparse
+import sys
+
+from . import TITLE, children, closest, lookup, search
+
+
+def show(line):
+    rows = list(line.path) if line.declarable else list(line.path) + [(line.code, line.description)]
+    for i, (code, desc) in enumerate(rows):
+        print(f"{'  ' * i}{code or '·'} {desc}")
+    if line.general:
+        print(f"General rate: {line.general}" + (f" | Special: {line.special}" if line.special else ""))
+    if not line.declarable:
+        print("Not a declarable line: more detailed codes exist under it (use --children).")
+
+
+def main(argv=None):
+    p = argparse.ArgumentParser(prog="hts-lookup", description=f"US Harmonized Tariff Schedule lookup ({TITLE}).")
+    p.add_argument("code", nargs="?", help="HTS code, 4 to 10 digits, dots optional")
+    p.add_argument("--search", help="find lines whose official text contains all these words")
+    p.add_argument("--children", metavar="CODE", help="list the next level of lines under a code")
+    a = p.parse_args(argv)
+    if a.search:
+        for line in search(a.search):
+            print(line)
+    elif a.children:
+        for line in children(a.children):
+            print(line)
+    elif a.code:
+        line = lookup(a.code)
+        if line:
+            show(line)
+        else:
+            near = closest(a.code)
+            print(f"{a.code} is not in the US tariff schedule ({TITLE}).")
+            if near:
+                print(f"Closest valid code: {near.code} {near.description}")
+            return 1
+    else:
+        p.print_help()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

hts_lookup-0.1.0.dist-info/LICENSE

@@ -0,0 +1,18 @@
+MIT License (code)
+
+Copyright (c) 2026 Anders Lee
+
+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.
+
+The data files in steel_sections/data/ are not covered by this licence; see DATA-LICENSE.md.

hts_lookup-0.1.0.dist-info/METADATA

@@ -0,0 +1,68 @@
+Metadata-Version: 2.1
+Name: hts-lookup
+Version: 0.1.0
+Summary: Offline lookup and validation of US Harmonized Tariff Schedule (HTS) codes: official descriptions, duty rates, closest valid code. No dependencies.
+Author: Anders Lee
+License: MIT (code); public domain US government data (see DATA-LICENSE.md)
+Project-URL: Homepage, https://hs-code.net/
+Keywords: hts,hs code,harmonized tariff schedule,tariff,customs,duty rate,import,trade,classification,usitc
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+
+# hts-lookup
+
+Offline lookup and validation of US Harmonized Tariff Schedule (HTS) codes. The current schedule is bundled
+(about 0.5 MB compressed), so it works without network access or API keys. Pure Python, no dependencies.
+
+```
+pip install hts-lookup
+```
+
+```python
+import hts_lookup as hts
+
+hts.TITLE                               # 'Revision 21 (2026)'
+line = hts.lookup("6201.40.70")
+line.description                        # 'Water resistant (634)'
+line.general                            # '7.1%'
+[c for c, _ in line.path]               # ['6201', '6201.40', '', '', '', '', '', '6201.40.70.00']
+
+hts.lookup("6109.10.00.12").general     # '16.5%'  (10-digit lines inherit the 8-digit rate)
+hts.lookup("6201.40").declarable        # False   (a subheading with lines under it)
+hts.lookup("8471.30").code              # '8471.30.01.00' (only one line under it, so that line)
+
+hts.is_valid("6201.40.99.99")           # False
+hts.closest("6201409999").code          # '6201.40'
+
+[l.code for l in hts.children("8507.60")]
+hts.search("lithium ion", limit=5)
+```
+
+Command line:
+
+```
+$ hts-lookup 6201.40.70
+$ hts-lookup --search "vinyl stickers"
+$ hts-lookup --children 4202.92
+```
+
+## Why validate codes
+
+HS and HTS codes copied from supplier invoices, old spreadsheets or AI chat answers are often out of date or do not exist.
+`is_valid()` and `closest()` catch those before a shipment does.
+
+## Notes
+
+- `general` is the column 1 general (MFN) rate. Extra duties under Chapter 99 depend on the country of origin and are not applied.
+- The first six digits are the international HS code; digits 7 to 10 are US-specific.
+- The bundled schedule is updated with new USITC revisions; check `hts_lookup.TITLE` for the edition you have.
+
+Step-by-step product guides, UK and EU rates, and the customs rulings behind each code: [hs-code.net](https://hs-code.net/)
+
+Code: MIT. Data: public domain US government work, see DATA-LICENSE.md. Not affiliated with USITC or CBP.

hts_lookup-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+hts_lookup/__init__.py,sha256=WSzknsn05X0Z6i8Qu7iXmM7-X_-0vI_BL9auzg6oLag,5420
+hts_lookup/__main__.py,sha256=CGiCpBVNBTkRyCOM4cykT5g3NKY-KiC1lHbHjnD_AA0,1687
+hts_lookup/data/hts.json.gz,sha256=AR9V1oZ6wmhCVwSbA_EmUuIECp1F-6pbDzQRxReP8zA,519394
+hts_lookup-0.1.0.dist-info/LICENSE,sha256=G2hYZ60E0bF6gxfQzDNC9BkuecEF1EVHviTvp6ilaFw,1168
+hts_lookup-0.1.0.dist-info/METADATA,sha256=PpmIGIwXrvyutcPM2lA3_b3qWi9sp5jGua_T6xzpdME,2741
+hts_lookup-0.1.0.dist-info/WHEEL,sha256=BNRMDyzLkkcmlv0J8ppDQkk2VED33SesJDynr9ED1gc,91
+hts_lookup-0.1.0.dist-info/entry_points.txt,sha256=0RkQqETthGFwPcFiZ0BMMeBw447AeDofTFiv-6bGp5Y,56
+hts_lookup-0.1.0.dist-info/top_level.txt,sha256=o8Vh-CdEpS_kQUOj5F5ITWFuAopDjo5Qcu3-TmSH5yo,11
+hts_lookup-0.1.0.dist-info/RECORD,,

hts_lookup-0.1.0.dist-info/WHEEL

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

hts_lookup-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+hts-lookup = hts_lookup.__main__:main

hts_lookup-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+hts_lookup