ustrade 0.4.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

ustrade/__init__.py

@@ -5,6 +5,7 @@ from .codes import HSCode
 from .errors import *
 
 from importlib import metadata
+from typing import Literal
 
 try:
     __version__ = metadata.version("ustrade")
@@ -158,6 +159,31 @@ def get_product(hs: str) -> HSCode:
     """
     return _get_default_client().get_product(hs)
 
+def search_for_code(keyword : str | list[str], 
+                    mode : Literal["OR", "AND"] = "OR",
+                    in_codes : str = None) -> pd.DataFrame:
+    """
+    Research keywords in the HS Code description base.
+
+    Args:
+        keyword (str | list[str]):
+            A single keyword or a list of keywords.
+        mode (Literal["OR", "AND"]):
+            Exclusive or inclusive search if `keyword` is a list. Default uses "OR".
+            "OR" mode will return every code associated with at least one keyword.
+            "AND" mode will return only the codes associated with all the keywords.
+        in_codes (str):
+            The code chapter or heading to look in. Default None will search across all chapters.
+
+    Returns:
+        pd.DataFrame:
+            A dataframe containing the list of associated codes.
+
+    Examples:
+        >>> ut.search_for_code(keyword="oil", in_codes="27")
+    """
+    return _get_default_client().search_for_code(keyword, mode, in_codes)
+
 
 __all__ = [
     "CensusClient",
@@ -171,5 +197,6 @@ __all__ = [
     "get_country_by_iso2",
     "get_desc_from_code",
     "get_children_codes", 
-    "get_product"
-]
+    "get_product",
+    "search_for_code",
+]

ustrade/client.py

@@ -2,7 +2,11 @@ import requests
 import socket
 from datetime import datetime
 import pandas as pd
+import re
 from urllib.parse import urlencode
+from typing import Literal
+import unicodedata
+
 from . import countries
 from .countries import Country
 from . import codes
@@ -23,7 +27,7 @@ class CensusClient:
         self.BASE_URL = "api.census.gov"
         self.BASE_PORT = 443
 
-        self._hs_codes, self._codes_by_hs_codes = codes._load_codes()
+        self._hs_codes, self._codes_by_hs_codes, self._desc_by_hs_codes = codes._load_codes()
         self._code_tree = codes.build_tree_from_codes(self._hs_codes)
 
         self.col_mapping = {
@@ -397,8 +401,9 @@ class CensusClient:
         """
         Returns the description of the specified HS code
 
-        ## Args:
-            hs (str): the HS code (ex: '1806')
+        Args:
+            hs (str): 
+                the HS code (ex: '1806')
         """
         if isinstance(hs, str):
             if hs in self._codes_by_hs_codes:
@@ -477,6 +482,81 @@ class CensusClient:
             raise InvalidCodeError(
                 f"Code must be a str or a HSCode instance - received a {type(code).__name__!r}"
             )
+
+
+    def _normalize_kw(self, s: str) -> str:
+        s = s.lower()
+        s = unicodedata.normalize("NFKD", s)
+        s = "".join(c for c in s if not unicodedata.combining(c))
+        s = re.sub(r"[^a-z0-9\s]+", " ", s)
+        return re.sub(r"\s+", " ", s).strip()
+
+    def _tokenize(self, s: str) -> list[str]:
+        return self._normalize_kw(s).split()     
+    
+
+    def search_for_code(self, keyword : str | list[str], 
+                        mode : Literal["OR", "AND"] = "OR",
+                        in_codes : str = None) -> pd.DataFrame:
+        """
+        Research keywords in the HS Code description base.
+
+        Args:
+            keyword (str | list[str]): 
+                a single keyword or a list of keywords.
+            mode (Literal["OR", "AND"]): 
+                exclusive or inclusive search if keyword is a list. Default uses "OR".
+                "OR" mode will return every code associated with at least one word of the list.
+                "AND" mode will return only the codes associated with all the words of the list.
+            in_codes (str):
+                the code chapter or heading to look in. Default None will search across all chapters. 
+        
+        Returns:
+            pd.Dataframe:
+                A dataframe containing the list of associated codes.
+
+        Examples:
+            >>> ut.search_for_code(keyword = "oil", in_codes = "27")
+
+        """
+        if in_codes is not None:
+            if in_codes not in self._codes_by_hs_codes:
+                raise CodeNotFoundError(f"Error : {in_codes} was not found as a valid code.")
+            
+        keywords = self._tokenize(keyword) if isinstance(keyword, str) else list(keyword)
+        keywords = [self._normalize_kw(k) for k in keywords]
+
+        results_code = []
+        results_desc = []
+
+        for desc, code in self._desc_by_hs_codes.items():
+            if in_codes is not None and not code.hscode.startswith(in_codes):
+                continue
+
+            tokens = self._tokenize(desc)
+
+            def keyword_matches(k: str) -> bool:
+                return any(tok.startswith(k) for tok in tokens)
+
+            if mode == "OR":
+                ok = any(keyword_matches(k) for k in keywords)
+            else:
+                ok = all(keyword_matches(k) for k in keywords)
+
+            if ok:
+                results_code.append(code.hscode)
+                results_desc.append(code.description)
+
+        return pd.DataFrame({
+            "Description": results_desc,
+            "Code": results_code
+        })
+
+
+
+
+
+        
         
     
 

ustrade/codes.py

@@ -19,7 +19,7 @@ class HSCode:
         return self.parent
 
 
-def _load_codes() -> tuple[list[HSCode], dict[str, HSCode]]:
+def _load_codes() -> tuple[list[HSCode], dict[str, HSCode], dict[str, HSCode]]:
     csv_path = files(__package__) / "data" / "harmonized-system.csv"
     codes: list[HSCode] = []
     with csv_path.open(encoding="utf-8") as f:
@@ -37,7 +37,7 @@ def _load_codes() -> tuple[list[HSCode], dict[str, HSCode]]:
                 )
             )
 
-    return codes, {c.hscode: c for c in codes}
+    return codes, {c.hscode: c for c in codes}, {c.description: c for c in codes}
 
 
 def _get_parent(code: str) -> str | None:
@@ -70,4 +70,3 @@ def build_tree_from_codes(codes: list[HSCode]) -> dict[str, HSCode]:
         parent_node.children.append(node.hscode)
 
     return code_dict
-

{ustrade-0.4.0.dist-info → ustrade-0.5.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ustrade
-Version: 0.4.0
+Version: 0.5.0
 Summary: Python client for the U.S. Census Bureau International Trade API
 Author: Fantin Sibony
 License-Expression: MIT
@@ -10,6 +10,8 @@ Description-Content-Type: text/markdown
 License-File: LICENSE.txt
 Requires-Dist: requests
 Requires-Dist: pandas
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
 Dynamic: license-file
 
 # ustrade
@@ -20,7 +22,9 @@ Dynamic: license-file
 <p align="left">
   <img src="https://img.shields.io/badge/python-3.10%2B-blue" />
   <img src="https://img.shields.io/badge/status-active-success" />
+  <img src= "https://img.shields.io/pypi/v/ustrade" />
   <img src="https://img.shields.io/badge/license-MIT-green" />
+  <img src="https://static.pepy.tech/personalized-badge/ustrade?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads" />
 </p>
 
 ---
@@ -34,8 +38,10 @@ Dynamic: license-file
   - `"4279"` (Census code)
 - HS codes lookup + product descriptions
 - Standardized DataFrame output with clean column names
-- Uses a cached internal client for efficiency
-- Zero configuration required
+
+For interactive exploration and non-Python usage, a Streamlit dashboard is available for this library at [https://ustrade.streamlit.app](https://ustrade.streamlit.app). 
+
+Source code : [https://github.com/fantinsib/ustrade_dashboard](https://github.com/fantinsib/ustrade_dashboard)
 
 ---
 

ustrade-0.5.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+ustrade/__init__.py,sha256=NBsxO-lvNGvQ-iK3Qfmvg-6YsuGrdqq1QuhGoSYdHEQ,7016
+ustrade/client.py,sha256=k_NyEN_IrZcIG7SfbfEqbAA6pKz3Er8ufjhFEVCm48k,19263
+ustrade/codes.py,sha256=OA8thItlx0vczrzwmdPO3Skf3COwfGYE4K4hAW69oB8,1953
+ustrade/countries.py,sha256=8CagTTccgs_Obr3dSpTffPKcikVe7eUdObcer-azIbU,783
+ustrade/errors.py,sha256=AIKPwwb1fUmtvZkwqNpVAXevwD5jSz2NN8_iYzpM1Dk,802
+ustrade/data/country_codes.csv,sha256=xwpr9MmBsIB78lIiKGDCaWDbGaO1kyDz0Vxwcxu1TTU,5794
+ustrade/data/harmonized-system.csv,sha256=537p4c_RWkLR-t6ywGGNEPa57ZrsDl1mgm3H750xJqU,850576
+ustrade-0.5.0.dist-info/licenses/LICENSE.txt,sha256=dwk5PMNyALOsBcKsVyrMjtoD0LvXr-Lu61cMjFJJn7I,1066
+ustrade-0.5.0.dist-info/METADATA,sha256=HBXw6S5RRworsbL-8VeluS2q9ZIMw7d2mwCpY4bU5co,5084
+ustrade-0.5.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+ustrade-0.5.0.dist-info/top_level.txt,sha256=sGFKm5WBJQE8rpKswtEFbRvBNzrON1Dr5UCdQptW2GE,8
+ustrade-0.5.0.dist-info/RECORD,,

{ustrade-0.4.0.dist-info → ustrade-0.5.0.dist-info}/WHEEL

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

ustrade-0.4.0.dist-info/RECORD

@@ -1,12 +0,0 @@
-ustrade/__init__.py,sha256=uOIWAm1QLJKPm0ajouB4t_NNh822k3g3xc8M6AITma0,5968
-ustrade/client.py,sha256=txGvXKFSC88T74HmBd5Q9b9L-7Bvh_eu1sEX3SWB16k,16611
-ustrade/codes.py,sha256=-4f54TUF9Dq93PYuzJli6d5HyGlWWmYlHqngb1GJe40,1900
-ustrade/countries.py,sha256=8CagTTccgs_Obr3dSpTffPKcikVe7eUdObcer-azIbU,783
-ustrade/errors.py,sha256=AIKPwwb1fUmtvZkwqNpVAXevwD5jSz2NN8_iYzpM1Dk,802
-ustrade/data/country_codes.csv,sha256=xwpr9MmBsIB78lIiKGDCaWDbGaO1kyDz0Vxwcxu1TTU,5794
-ustrade/data/harmonized-system.csv,sha256=537p4c_RWkLR-t6ywGGNEPa57ZrsDl1mgm3H750xJqU,850576
-ustrade-0.4.0.dist-info/licenses/LICENSE.txt,sha256=dwk5PMNyALOsBcKsVyrMjtoD0LvXr-Lu61cMjFJJn7I,1066
-ustrade-0.4.0.dist-info/METADATA,sha256=IhiWRMtf6vFlsmD88cITFl1F0f5HE_OmlZ4vGalWbsA,4602
-ustrade-0.4.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-ustrade-0.4.0.dist-info/top_level.txt,sha256=sGFKm5WBJQE8rpKswtEFbRvBNzrON1Dr5UCdQptW2GE,8
-ustrade-0.4.0.dist-info/RECORD,,