ustrade 0.4.0__tar.gz

ustrade-0.4.0/LICENSE.txt

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

ustrade-0.4.0/PKG-INFO

@@ -0,0 +1,189 @@
+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**.  
+> Allows to fetch imports and exports between the US and commercial partners - based on Harmonized System codes (HS)
+
+<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/badge/license-MIT-green" />
+</p>
+
+---
+
+## Features
+
+- **Simple API**: `ust.get_imports()`, `ust.get_exports()`
+- Automatic normalization of country inputs:
+  - `"France"`
+  - `"FR"` (ISO2)
+  - `"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
+
+---
+
+## Installation
+
+### PyPI Install
+
+Install with pip :
+
+```bash
+pip install ustrade
+```
+
+### Github 
+Clone this repository and install via pip in editable mode:
+
+```bash
+git clone https://github.com/fantinsib/ustrade.git
+cd ustrade
+pip install -e .
+```
+## Quick Example
+
+```python
+
+import ustrade as ust
+
+# Example: Mexican imports of fruits and nuts between January 2010 and January 2025
+df = ust.get_imports_on_period("Mexico", "08", "2010-01", "2025-01")
+print(df)
+```
+
+## Full API Reference
+
+## *Fetching Data*
+
+### • `get_imports(country, product, date)`
+Fetch monthly import data for a given country and HS code.
+
+**Parameters:**
+- `country` — country name (`France`), ISO2 (`FR`), Census code (`4279`) or `Country` instance, or a list of the previous
+- `product` — HS code as string (e.g. `2701`) or list of string
+- `date` — `YYYY-MM` format (e.g. `2020-01`)
+
+**Example:**
+```python
+ust.get_imports("FR", "10", "2025-01")
+ust.get_imports(["France", "GB"], ["12", "13"], "2018-03")
+```
+
+---
+
+### • `get_exports(country, product, date)`
+Fetch monthly export data for a given country and HS code.
+
+**Example:**
+```python
+ust.get_exports("GB", "73", "2019-01")
+ust.get_exports(["France", "GB"], ["08", "09"], "2018-03")
+```
+
+---
+
+### • `get_imports_on_period(country, product, start, end)`
+Fetch a DataFrame containing monthly imports for a given country and HS code
+
+**Parameters:**
+- `country` — country name (`France`), ISO2 (`FR`), Census code (`4279`) or `Country` instance, or list of the previous
+- `product` — HS code as string (e.g. `2701`) or list of string
+- `start` and `end` — `YYYY-MM` format (e.g. `2020-01`)
+
+**Example:**
+```python
+ust.get_imports_on_period("Mexico", "27", "2010-01", "2025-01")
+ust.get_imports_on_period(["France", "DE", "GB"], ["09", "08", "07"], "2016-01", "2018-01")
+```
+
+---
+
+### • `get_exports_on_period(country, product, start, end)`
+Fetch a DataFrame containing monthly exports for a given country and HS code
+
+**Example:**
+```python
+ust.get_exports_on_period("France", "10", "2020-01", "2023-01")
+```
+
+---
+
+## *Exploring Codes*
+
+HS Codes follow a tree hierarchy. 
+
+### • `get_desc_from_code(hs)`
+Return the description associated with an HS code.
+
+**Example:**
+```python
+ust.get_desc_from_code("2701")
+```
+
+### • `get_children_codes(code, return_names)`
+Return a dictionnary of the codes and descriptions attached to the parent code if return_names is True, and a list of the code if return_names if False.
+
+**Example:**
+```python
+ust.get_children_codes("10")
+```
+
+
+### • `get_product(hs)`
+Return the HSCode instance associated with the hs code specified.
+
+**Example:**
+```python
+ust.get_product("10")
+```
+
+## *Exploring countries*
+
+### • `get_country_by_name(name)`
+Look up a country by its full name (case-insensitive).
+
+**Example:**
+```python
+ust.get_country_by_name("France")
+```
+
+### • `get_country_by_code(code)`
+Look up a country using its U.S. Census numeric code.
+
+**Example:**
+```python
+ust.get_country_by_code("4279")
+```
+
+### • `get_country_by_iso2(iso)`
+Look up a country by ISO2 code.
+
+**Example:**
+```python
+ust.get_country_by_iso2("FR")
+```
+
+---
+
+## 🧩 Notes
+
+- 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 !

ustrade-0.4.0/README.md

@@ -0,0 +1,175 @@
+# ustrade
+
+> A lightweight and intuitive Python client for the **U.S. Census Bureau International Trade API**.  
+> Allows to fetch imports and exports between the US and commercial partners - based on Harmonized System codes (HS)
+
+<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/badge/license-MIT-green" />
+</p>
+
+---
+
+## Features
+
+- **Simple API**: `ust.get_imports()`, `ust.get_exports()`
+- Automatic normalization of country inputs:
+  - `"France"`
+  - `"FR"` (ISO2)
+  - `"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
+
+---
+
+## Installation
+
+### PyPI Install
+
+Install with pip :
+
+```bash
+pip install ustrade
+```
+
+### Github 
+Clone this repository and install via pip in editable mode:
+
+```bash
+git clone https://github.com/fantinsib/ustrade.git
+cd ustrade
+pip install -e .
+```
+## Quick Example
+
+```python
+
+import ustrade as ust
+
+# Example: Mexican imports of fruits and nuts between January 2010 and January 2025
+df = ust.get_imports_on_period("Mexico", "08", "2010-01", "2025-01")
+print(df)
+```
+
+## Full API Reference
+
+## *Fetching Data*
+
+### • `get_imports(country, product, date)`
+Fetch monthly import data for a given country and HS code.
+
+**Parameters:**
+- `country` — country name (`France`), ISO2 (`FR`), Census code (`4279`) or `Country` instance, or a list of the previous
+- `product` — HS code as string (e.g. `2701`) or list of string
+- `date` — `YYYY-MM` format (e.g. `2020-01`)
+
+**Example:**
+```python
+ust.get_imports("FR", "10", "2025-01")
+ust.get_imports(["France", "GB"], ["12", "13"], "2018-03")
+```
+
+---
+
+### • `get_exports(country, product, date)`
+Fetch monthly export data for a given country and HS code.
+
+**Example:**
+```python
+ust.get_exports("GB", "73", "2019-01")
+ust.get_exports(["France", "GB"], ["08", "09"], "2018-03")
+```
+
+---
+
+### • `get_imports_on_period(country, product, start, end)`
+Fetch a DataFrame containing monthly imports for a given country and HS code
+
+**Parameters:**
+- `country` — country name (`France`), ISO2 (`FR`), Census code (`4279`) or `Country` instance, or list of the previous
+- `product` — HS code as string (e.g. `2701`) or list of string
+- `start` and `end` — `YYYY-MM` format (e.g. `2020-01`)
+
+**Example:**
+```python
+ust.get_imports_on_period("Mexico", "27", "2010-01", "2025-01")
+ust.get_imports_on_period(["France", "DE", "GB"], ["09", "08", "07"], "2016-01", "2018-01")
+```
+
+---
+
+### • `get_exports_on_period(country, product, start, end)`
+Fetch a DataFrame containing monthly exports for a given country and HS code
+
+**Example:**
+```python
+ust.get_exports_on_period("France", "10", "2020-01", "2023-01")
+```
+
+---
+
+## *Exploring Codes*
+
+HS Codes follow a tree hierarchy. 
+
+### • `get_desc_from_code(hs)`
+Return the description associated with an HS code.
+
+**Example:**
+```python
+ust.get_desc_from_code("2701")
+```
+
+### • `get_children_codes(code, return_names)`
+Return a dictionnary of the codes and descriptions attached to the parent code if return_names is True, and a list of the code if return_names if False.
+
+**Example:**
+```python
+ust.get_children_codes("10")
+```
+
+
+### • `get_product(hs)`
+Return the HSCode instance associated with the hs code specified.
+
+**Example:**
+```python
+ust.get_product("10")
+```
+
+## *Exploring countries*
+
+### • `get_country_by_name(name)`
+Look up a country by its full name (case-insensitive).
+
+**Example:**
+```python
+ust.get_country_by_name("France")
+```
+
+### • `get_country_by_code(code)`
+Look up a country using its U.S. Census numeric code.
+
+**Example:**
+```python
+ust.get_country_by_code("4279")
+```
+
+### • `get_country_by_iso2(iso)`
+Look up a country by ISO2 code.
+
+**Example:**
+```python
+ust.get_country_by_iso2("FR")
+```
+
+---
+
+## 🧩 Notes
+
+- 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 !

ustrade-0.4.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ustrade"
+version = "0.4.0"
+description = "Python client for the U.S. Census Bureau International Trade API"
+authors = [
+  { name = "Fantin Sibony" }
+]
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE.txt"]
+requires-python = ">=3.10"
+dependencies = [
+  "requests",
+  "pandas",
+]
+
+[project.urls]
+Homepage = "https://github.com/fantinsib/ustrade"
+
+[tool.setuptools]
+package-dir = {"" = "."}
+packages = ["ustrade"]
+include-package-data = true
+
+[tool.setuptools.package-data]
+"ustrade" = ["data/*.csv"]

ustrade-0.4.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ustrade-0.4.0/tests/test_api.py

@@ -0,0 +1,28 @@
+####### 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

@@ -0,0 +1,40 @@
+######## 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
+
+

ustrade-0.4.0/tests/test_hscode.py

@@ -0,0 +1,33 @@
+####### TESTS FOR codes.py ######
+
+import ustrade as ut
+from ustrade.codes import HSCode, build_tree_from_codes
+from ustrade import CensusClient
+
+
+def test_build_tree_simple():
+    codes = [
+        HSCode(section="I", hscode="10", description="Cereals", parent="", level=2, children=[]),
+        HSCode(section="I", hscode="1001", description="Wheat", parent="10", level=4, children=[]),
+        HSCode(section="I", hscode="100190", description="Other wheat", parent="1001", level=6, children=[]),
+    ]
+
+    tree = build_tree_from_codes(codes)
+
+    assert set(tree.keys()) == {"10", "1001", "100190"}
+    assert "1001" in tree["10"].children
+    assert "100190" in tree["1001"].children
+    assert tree["100190"].children == []
+
+
+def test_build_tree_roots():
+    codes = [
+        HSCode(section="I", hscode="10", description="Cereals", parent="", level=2, children=[]),
+        HSCode(section="I", hscode="1001", description="Wheat", parent="10", level=4, children=[]),
+    ]
+
+    tree = build_tree_from_codes(codes)
+    roots = [code for code, node in tree.items() if all(code not in n.children for n in tree.values())]
+    assert "10" in roots
+
+

ustrade-0.4.0/ustrade/__init__.py

@@ -0,0 +1,175 @@
+import pandas as pd
+from .countries import Country
+from .client import CensusClient
+from .codes import HSCode
+from .errors import *
+
+from importlib import metadata
+
+try:
+    __version__ = metadata.version("ustrade")
+except metadata.PackageNotFoundError:
+    __version__ = "0.0.0"  
+
+
+_default_client: CensusClient | None = None
+
+def _get_default_client() -> CensusClient:
+    global _default_client
+    if _default_client is None:
+        _default_client = CensusClient()
+    return _default_client
+
+def get_imports(country : str| Country | list[str | Country], product : str|list[str], date : str)-> pd.DataFrame:
+    """
+    Returns the import value from the US to the specified country of the product for the month
+    Args:
+        country (str | Country | list[str | Country]) : can be the ISO2 code, the full name, the Census Bureau code for this country, or a Country object
+        product (str | list[str]) : HS code
+        date (str): the month, in format 'YYYY-MM'
+
+    Examples:
+    >>> ut.get_imports(["France", "GB"], ["12", "13"], "2018-03")
+    >>> ut.get_imports("GB", "12", "2018-03")
+    """
+    return _get_default_client().get_imports(country = country, product= product, date = date)
+
+def get_exports(country : str| Country | list[str | Country], product : str|list[str], date : str)-> pd.DataFrame:
+    """
+    Returns the export value from the US to the specified country of the product for the month
+    
+    Args:
+        country (str | Country | list[str | Country]) : can be the ISO2 code, the full name, the Census Bureau code for this country, or a Country object
+        product (str | list[str]) : HS code
+        date (str): the date, in format 'YYYY-MM'
+    Examples:
+    >>> ut.get_exports(["France", "GB"], ["08", "09"], "2018-03")
+    >>> ut.get_exports("GB", "08", "2018-03")
+    """
+    return _get_default_client().get_exports(country = country, product= product, date = date)
+
+def get_imports_on_period(country : str| Country | list[str | Country], product : str|list[str], start: str, end: str)->pd.DataFrame:
+    """
+    Return the imports on the specified period
+
+    Args:
+        country (str | Country | list[str | Country]):
+            ISO2 code, full name, Census Bureau code, or a Country object.
+        product (str | list[str]):
+            HS code.
+        start (str):
+            Starting date in format "YYYY-MM".
+        end (str):
+            Ending date in format "YYYY-MM".
+
+    Examples:
+        >>> ut.get_imports_on_period(["France", "DE", "GB"], ["09", "08", "07"], "2016-01", "2018-01")
+        >>> from ustrade import CensusClient
+        >>> c = CensusClient(timeout=120)
+        >>> c.get_imports_on_period(["France", "DE", "GB"], ["08", "07"], "2016-01", "2018-01")
+
+    Notes:
+        - Queries can take time to load.
+        - Consider increasing `timeout`.
+        - Data is only available from 2010-01.
+    """
+    return _get_default_client().get_imports_on_period(country, product, start, end)
+
+
+def get_exports_on_period(country : str| Country | list[str | Country], product : str|list[str], start: str, end: str)->pd.DataFrame:
+    """
+    Return the exports on the specified period.
+
+    Args:
+        country (str | Country | list[str | Country]):
+            ISO2 code, full name, Census Bureau code, or a Country object.
+        product (str | list[str]):
+            HS code(s).
+        start (str):
+            Start date in format "YYYY-MM".
+        end (str):
+            End date in format "YYYY-MM".
+
+    Examples:
+        >>> ut.get_exports_on_period(["France", "DE", "GB"], ["09", "08", "07"], "2016-01", "2018-01")
+        >>> from ustrade import CensusClient
+        >>> c = CensusClient(timeout=120)
+        >>> c.get_exports_on_period(["France", "DE", "GB"], ["08", "07"], "2016-01", "2018-01")
+
+    Notes:
+        - Queries can take time to load.
+        - Consider increasing `timeout`.
+        - Data is only available from 2010-01.
+    """
+    return _get_default_client().get_exports_on_period(country, product, start, end)
+
+def get_country_by_name(country: str)-> Country:
+    """
+    Search a country with its name
+
+    Args:
+        country (str) : the full name of the country (ex: 'France')
+    """
+    return _get_default_client().get_country_by_name(country)
+
+def get_country_by_code(cty_code: str):
+    """
+    Search a country with its code
+    
+    Args:
+        cty_code (str) : the Census Bureau code of the country  (ex: '4120')
+    """
+    return _get_default_client().get_country_by_code(cty_code)
+
+def get_country_by_iso2(iso2: str):
+    """
+    Search a country with its ISO 2 ID
+
+    Args:
+        iso2 (str) : the ISO2 code of the country  (ex: 'IT')
+    """
+    return _get_default_client().get_country_by_iso2(iso2)
+
+def get_desc_from_code(hs: str):
+    """
+    Returns the description associated with the HS code specified
+
+    Args:
+        hs (str): the HS code (ex: '73')
+    """
+    return _get_default_client().get_desc_from_code(hs)
+
+def get_children_codes(code: str | HSCode, return_names = True)-> dict | list[str]:
+    """
+    Returns a dict of the codes and their desc directly attached to code in the hierarchy
+
+    Args:
+        code (str | HSCode): either the code as a string or the HSCode object
+        return_names (bool): returns a dict with the code and the description if true, a list of the codes if false    
+    """
+    return _get_default_client().get_children_codes(code, return_names)
+
+def get_product(hs: str) -> HSCode:
+    """
+    Returns all the informations on a specified HS code through a HSCode object
+
+    Args:
+        hs (str): the HS code (ex: '1806')
+    """
+    return _get_default_client().get_product(hs)
+
+
+__all__ = [
+    "CensusClient",
+    "Country",
+    "get_imports",
+    "get_exports",
+    "get_imports_on_period",
+    "get_exports_on_period",
+    "get_country_by_name",
+    "get_country_by_code",
+    "get_country_by_iso2",
+    "get_desc_from_code",
+    "get_children_codes", 
+    "get_product"
+]