ustrade 0.4.0__tar.gz → 0.5.0__tar.gz

{ustrade-0.4.0 → ustrade-0.5.0}/PKG-INFO

@@ -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.4.0/ustrade.egg-info/PKG-INFO → ustrade-0.5.0/README.md

@@ -1,17 +1,3 @@
-Metadata-Version: 2.4
-Name: ustrade
-Version: 0.4.0
-Summary: Python client for the U.S. Census Bureau International Trade API
-Author: Fantin Sibony
-License-Expression: MIT
-Project-URL: Homepage, https://github.com/fantinsib/ustrade
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE.txt
-Requires-Dist: requests
-Requires-Dist: pandas
-Dynamic: license-file
-
 # ustrade
 
 > A lightweight and intuitive Python client for the **U.S. Census Bureau International Trade API**.  
@@ -20,7 +6,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 +22,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.4.0 → ustrade-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ustrade"
-version = "0.4.0"
+version = "0.5.0"
 description = "Python client for the U.S. Census Bureau International Trade API"
 authors = [
   { name = "Fantin Sibony" }
@@ -28,3 +28,8 @@ include-package-data = true
 
 [tool.setuptools.package-data]
 "ustrade" = ["data/*.csv"]
+
+[project.optional-dependencies]
+dev = [
+    "pytest"
+]

ustrade-0.5.0/tests/test_api.py

@@ -0,0 +1,148 @@
+import datetime as dt
+
+import pandas as pd
+import pytest
+import requests
+
+import ustrade as ut
+from ustrade.client import CensusClient
+from ustrade.errors import EmptyResult
+
+
+class FakeResponse:
+    def __init__(self, url: str, payload):
+        self.url = url
+        self._payload = payload
+
+    def raise_for_status(self):
+        return None
+
+    def json(self):
+        if isinstance(self._payload, Exception):
+            raise self._payload
+        return self._payload
+
+
+@pytest.fixture(autouse=True)
+def _reset_default_client():
+    ut._default_client = None
+    yield
+    ut._default_client = None
+
+
+def test_build_client():
+    CensusClient()
+
+
+def test_get_exports_mocks_api_call(monkeypatch):
+    called = {}
+
+    def fake_get(url, timeout):
+        called["url"] = url
+        payload = [
+            [
+                "CTY_CODE",
+                "CTY_NAME",
+                "E_COMMODITY",
+                "E_COMMODITY_SDESC",
+                "ALL_VAL_MO",
+                "YEAR",
+                "MONTH",
+            ],
+            [
+                "2010",
+                "MEXICO",
+                "27",
+                "Mineral fuels, oils, distillation products, etc.",
+                "773377170",
+                "2010",
+                "01",
+            ],
+        ]
+        return FakeResponse(url, payload)
+
+    monkeypatch.setattr(requests, "get", fake_get)
+
+    df = ut.get_exports("Mexico", "27", "2010-01")
+
+    assert isinstance(df, pd.DataFrame)
+    assert len(df) == 1
+    assert df.loc[0, "country_name"] == "MEXICO"
+    assert df.loc[0, "product_code"] == "27"
+    assert df.loc[0, "export_value"] == 773377170.0
+    assert df.loc[0, "date"].to_pydatetime() == dt.datetime(2010, 1, 1)
+
+    url = called["url"]
+    assert url.startswith("https://api.census.gov/data/timeseries/intltrade/exports/hs?")
+    assert "CTY_CODE=2010" in url
+    assert "E_COMMODITY=27" in url
+    assert "YEAR=2010" in url and "MONTH=01" in url
+
+
+def test_get_imports_mocks_api_call(monkeypatch):
+    def fake_get(url, timeout):
+        payload = [
+            [
+                "CTY_CODE",
+                "CTY_NAME",
+                "I_COMMODITY",
+                "I_COMMODITY_SDESC",
+                "GEN_VAL_MO",
+                "CON_VAL_MO",
+                "YEAR",
+                "MONTH",
+            ],
+            [
+                "1220",
+                "FRANCE",
+                "08",
+                "Edible fruit and nuts; peel of citrus fruit or melons",
+                "123.45",
+                "100.0",
+                "2018",
+                "03",
+            ],
+        ]
+        return FakeResponse(url, payload)
+
+    monkeypatch.setattr(requests, "get", fake_get)
+
+    df = ut.get_imports("France", "08", "2018-03")
+    assert len(df) == 1
+    assert df.loc[0, "country_name"] == "FRANCE"
+    assert df.loc[0, "product_code"] == "08"
+    assert df.loc[0, "import_value"] == 123.45
+    assert df.loc[0, "consumption_import_value"] == 100.0
+    assert df.loc[0, "date"].to_pydatetime() == dt.datetime(2018, 3, 1)
+
+
+def test_get_exports_returns_empty_df_on_json_decode_error(monkeypatch):
+    def fake_get(url, timeout):
+        err = requests.exceptions.JSONDecodeError("boom", "", 0)
+        return FakeResponse(url, err)
+
+    monkeypatch.setattr(requests, "get", fake_get)
+
+    c = CensusClient()
+    df = c.get_exports("Mexico", "27", "2010-01")
+    assert df.empty
+
+
+def test_get_exports_on_period_raises_on_json_decode_error(monkeypatch):
+    def fake_get(url, timeout):
+        err = requests.exceptions.JSONDecodeError("boom", "", 0)
+        return FakeResponse(url, err)
+
+    monkeypatch.setattr(requests, "get", fake_get)
+
+    c = CensusClient()
+    with pytest.raises(EmptyResult):
+        c.get_exports_on_period("Mexico", "27", "2010-01", "2010-03")
+
+
+def test_get_children_codes():
+    children = ut.get_children_codes("1001")
+
+    expected_keys = {"100111", "100119", "100191", "100199"}
+    assert set(children.keys()) == expected_keys
+    assert "durum wheat" in children["100111"].lower()

ustrade-0.5.0/tests/test_client.py

@@ -0,0 +1,54 @@
+from urllib.parse import parse_qs, urlparse
+
+import pytest
+
+from ustrade.client import CensusClient
+
+
+def _parse(url: str):
+    parsed = urlparse(url)
+    return parsed, parse_qs(parsed.query)
+
+
+def test_build_params_imports_date_month_year():
+    c = CensusClient()
+    url = c._build_params(["Mexico", "Canada"], ["08", "09"], "imports", date="2013-01")
+
+    parsed, qs = _parse(url)
+    assert parsed.scheme == "https"
+    assert parsed.netloc == "api.census.gov"
+    assert parsed.path.endswith("/data/timeseries/intltrade/imports/hs")
+
+    assert "get" in qs
+    assert "CTY_CODE" in qs and len(qs["CTY_CODE"]) == 2
+    assert "I_COMMODITY" in qs and len(qs["I_COMMODITY"]) == 2
+    assert qs["YEAR"] == ["2013"]
+    assert qs["MONTH"] == ["01"]
+    assert "time" not in qs
+
+
+def test_build_params_imports_date_range_uses_time():
+    c = CensusClient()
+    url = c._build_params(["Mexico", "Canada"], ["08", "09"], "imports", start="2013-01", end="2014-01")
+    _, qs = _parse(url)
+
+    assert "time" in qs
+    assert qs["time"] == ["from 2013-01 to 2014-01"]
+    assert "YEAR" not in qs and "MONTH" not in qs
+
+
+def test_normalize_country_accepts_name_iso_code_and_object():
+    c = CensusClient()
+    mexico = c.get_country_by_name("Mexico")
+
+    assert c._normalize_country("Mexico") == mexico.code
+    assert c._normalize_country("mx") == mexico.code
+    assert c._normalize_country(mexico.code) == mexico.code
+    assert c._normalize_country(mexico, output="iso2") == "MX"
+
+
+def test_normalize_country_rejects_unknown_country():
+    c = CensusClient()
+    with pytest.raises(ValueError):
+        c._normalize_country("Neverland")
+

{ustrade-0.4.0 → ustrade-0.5.0}/tests/test_hscode.py

@@ -2,7 +2,10 @@
 
 import ustrade as ut
 from ustrade.codes import HSCode, build_tree_from_codes
+import pytest
+
 from ustrade import CensusClient
+from ustrade.errors import CodeNotFoundError
 
 
 def test_build_tree_simple():
@@ -31,3 +34,34 @@ def test_build_tree_roots():
     assert "10" in roots
 
 
+def test_get_desc_from_code_and_product_roundtrip():
+    c = CensusClient()
+    desc = c.get_desc_from_code("1001")
+    assert isinstance(desc, str)
+    assert "wheat" in desc.lower()
+
+    product = c.get_product("1001")
+    assert product.hscode == "1001"
+    assert product.description == desc
+
+
+def test_get_desc_from_code_suggests_leading_zero_for_one_digit_code():
+    c = CensusClient()
+    with pytest.raises(CodeNotFoundError, match="Did you mean '09'\\?"):
+        c.get_desc_from_code("9")
+
+
+def test_get_children_codes_as_list_and_as_object():
+    c = CensusClient()
+    children_list = c.get_children_codes("1001", return_names=False)
+    assert set(children_list) == {"100111", "100119", "100191", "100199"}
+
+    product = c.get_product("1001")
+    assert set(c.get_children_codes(product, return_names=False)) == set(children_list)
+
+
+def test_search_for_code_scoped_and_and_mode():
+    c = CensusClient()
+    res = c.search_for_code(["durum", "wheat"], mode="AND", in_codes="1001")
+    assert "100111" in set(res["Code"])
+

{ustrade-0.4.0 → ustrade-0.5.0}/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-0.4.0 → ustrade-0.5.0}/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-0.4.0 → ustrade-0.5.0}/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/README.md → ustrade-0.5.0/ustrade.egg-info/PKG-INFO

@@ -1,3 +1,19 @@
+Metadata-Version: 2.4
+Name: ustrade
+Version: 0.5.0
+Summary: Python client for the U.S. Census Bureau International Trade API
+Author: Fantin Sibony
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/fantinsib/ustrade
+Requires-Python: >=3.10
+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
 
 > A lightweight and intuitive Python client for the **U.S. Census Bureau International Trade API**.  
@@ -6,7 +22,9 @@
 <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>
 
 ---
@@ -20,8 +38,10 @@
   - `"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)
 
 ---
 
@@ -172,4 +192,4 @@ ust.get_country_by_iso2("FR")
 
 - All data retrieval functions return a **pandas DataFrame** unless otherwise noted.
 - Column names are automatically standardized (see schema section).
-- This library is still in <1.0.0 version and can change. Contributions are always welcome !
+- This library is still in <1.0.0 version and can change. Contributions are always welcome !

{ustrade-0.4.0 → ustrade-0.5.0}/ustrade.egg-info/requires.txt

@@ -1,2 +1,5 @@
 requests
 pandas
+
+[dev]
+pytest

ustrade-0.4.0/tests/test_api.py

@@ -1,28 +0,0 @@
-####### Test for API calls ######
-
-
-import ustrade as ut
-from ustrade.client import CensusClient
-
-
-
-
-def test_build_client():
-    c= CensusClient()
-
-
-def test_basic_request():
-    df = ut.get_exports("Mexico", "27", "2010-01")
-
-    assert len(df) == 1
-    assert df.loc[0, "country_name"] == "MEXICO"
-    assert df.loc[0, "product_code"] == "27"
-    assert df.loc[0, "export_value"] == 773377170.0
-
-
-def test_get_children_codes():
-    children = ut.get_children_codes("1001")
-
-    expected_keys = {"100111", "100119", "100191", "100199"}
-    assert set(children.keys()) == expected_keys
-    assert "durum wheat" in children["100111"]

ustrade-0.4.0/tests/test_client.py

@@ -1,40 +0,0 @@
-######## Tests for clients core methods ########
-
-from urllib.parse import urlparse, parse_qs
-from ustrade import CensusClient
-
-
-import inspect
-from ustrade.client import CensusClient  
-
-def test_debug():
-    print("module:", CensusClient.__module__)
-    print("file:", inspect.getfile(CensusClient))
-    print("_build_params in dir?", "_build_params" in dir(CensusClient))
-
-
-
-def test_build_param():
-
-    c = CensusClient()
-    print(type(c))
-    print(hasattr(c, "_build_params"))
-    print(c.__class__)
-
-    url = c._build_params(["Mexico", "Canada"], ["08", "09"], "imports", start="2013-01", end= "2014-01")
-    
-    parsed = urlparse(url)
-    qs = parse_qs(parsed.query)
-
-    # URL de base
-    assert parsed.scheme == "https"
-    assert parsed.netloc == "api.census.gov"
-    assert "/intltrade/imports/hs" in parsed.path
-
-    # Paramètres critiques
-    assert "get" in qs
-    assert "CTY_CODE" in qs
-    assert "I_COMMODITY" in qs
-    assert "time" in qs
-
-