ustrade 0.4.0__py3-none-any.whl

ustrade/errors.py

@@ -0,0 +1,47 @@
+
+
+
+class USTradeError(Exception):
+    """
+    Base error for the library
+    """
+
+class APITimeOutError(USTradeError):
+    pass
+
+
+##### Data search error ##################################################
+
+class EmptyResult(USTradeError):
+    """
+    Could not find any data for the specified query
+    """
+    pass
+
+
+
+
+
+####### countries error ##################################################
+
+class InvalidCountryError(USTradeError):
+    """
+    Country is not referenced
+    """
+    pass
+
+####### codes error ##################################################
+
+class InvalidCodeError(USTradeError):
+    """
+    Argument of function is not of a valid type
+    """
+    pass
+
+class CodeNotFoundError(USTradeError):
+    """
+    Could not find the reference to this code in the base
+    """
+    pass
+
+

ustrade-0.4.0.dist-info/METADATA

@@ -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.dist-info/RECORD

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

ustrade-0.4.0.dist-info/WHEEL

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

ustrade-0.4.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+ustrade