comexpy 0.1.0__tar.gz

comexpy-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,25 @@
+name: docs
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  build-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Install package and docs dependencies
+        run: pip install -e ".[docs]"
+
+      - name: Build and deploy to gh-pages
+        run: mkdocs gh-deploy --force --no-history

comexpy-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,52 @@
+name: publish
+
+# Publishes to PyPI on a GitHub Release (or manual dispatch) using PyPI
+# Trusted Publishing (OIDC) — no API token stored in the repository.
+# One-time setup on PyPI: add a "pending publisher" for project `comexpy`
+# pointing at owner `StrategicProjects`, repo `comexpy`, workflow `publish.yml`.
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+
+      - name: Check artifacts
+        run: |
+          python -m pip install --upgrade twine
+          twine check dist/*
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/comexpy/
+    permissions:
+      id-token: write  # required for Trusted Publishing (OIDC)
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

comexpy-0.1.0/.gitignore

@@ -0,0 +1,36 @@
+# Byte-compiled / optimized
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+.eggs/
+wheels/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# MkDocs build output
+site/
+
+# Test / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+.ruff_cache/
+.mypy_cache/
+
+# Editors / OS
+.DS_Store
+.idea/
+.vscode/
+
+# Claude Code: local guidance and memory (not for the repo)
+CLAUDE.md
+CLAUDE.local.md
+.claude/

comexpy-0.1.0/LICENSE

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

comexpy-0.1.0/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.4
+Name: comexpy
+Version: 0.1.0
+Summary: Access the Brazilian Foreign Trade Statistics API (ComexStat) from Python
+Project-URL: Homepage, https://github.com/StrategicProjects/comexpy
+Project-URL: Repository, https://github.com/StrategicProjects/comexpy
+Project-URL: Issues, https://github.com/StrategicProjects/comexpy/issues
+Project-URL: R package (comexr), https://github.com/StrategicProjects/comexr
+Author-email: Andre Leite <leite@castlab.org>, Marcos Wasilew <marcos.wasilew@gmail.com>, Hugo Vasconcelos <hugo.vasconcelos@ufpe.br>, Carlos Amorin <carlos.agaf@ufpe.br>, Diogo Bezerra <diogo.bezerra@ufpe.br>
+License: MIT License
+        
+        Copyright (c) 2026 comexpy authors
+        
+        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.
+License-File: LICENSE
+Keywords: Brazil,ComexStat,MDIC,exports,foreign-trade,imports,open-data,pandas
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.9
+Requires-Dist: pandas>=1.3
+Requires-Dist: requests>=2.25
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: responses>=0.23; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# comexpy
+
+[![PyPI](https://img.shields.io/pypi/v/comexpy.svg)](https://pypi.org/project/comexpy/)
+[![Python versions](https://img.shields.io/pypi/pyversions/comexpy.svg)](https://pypi.org/project/comexpy/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**Access the Brazilian Foreign Trade Statistics API (ComexStat) from Python.**
+
+`comexpy` is a pandas-friendly interface to the
+[ComexStat API](https://api-comexstat.mdic.gov.br/docs#/) of the Brazilian
+Ministry of Development, Industry, Trade and Services (MDIC). It provides
+programmatic access to detailed Brazilian export and import data — every
+query returns a `pandas.DataFrame`.
+
+This is the Python port of the R package
+[`comexr`](https://github.com/StrategicProjects/comexr); the public function
+names mirror the R API so knowledge transfers directly between the two.
+
+## Features
+
+- **General trade data** (1997–present), **city-level** data, and
+  **historical** records (1989–1996)
+- **Auxiliary tables**: countries, economic blocs, NCM/NBM/HS product codes,
+  CGCE/SITC/ISIC classifications, states, cities, transport modes, customs units
+- **Friendly aliases** — pass `"hs4"`, `"transport_mode"`, `"cgce_n1"` and the
+  package translates them to the API's internal names
+- **Multilingual** responses: Portuguese, English, Spanish
+- **SSL auto-fallback** — handles ICP-Brasil certificate issues transparently
+- **Configurable retry/timeout** for the API's aggressive rate limiting
+
+## Installation
+
+```bash
+pip install comexpy
+```
+
+Requires Python 3.9+, `requests` and `pandas`.
+
+## Quick start
+
+```python
+import comexpy
+
+# Exports by country in January 2024
+exports = comexpy.comex_export(
+    start_period="2024-01",
+    end_period="2024-01",
+    details="country",
+)
+
+# Imports with CIF value, by country, for all of 2024
+imports = comexpy.comex_import(
+    start_period="2024-01",
+    end_period="2024-12",
+    details="country",
+    metric_cif=True,
+)
+
+# Exports to China (160), grouped by HS4
+# (the package translates "hs4" to the API's `heading`)
+soy = comexpy.comex_export(
+    start_period="2024-01",
+    end_period="2024-12",
+    details=["country", "hs4"],
+    filters={"country": 160},
+)
+```
+
+## Discover available options
+
+```python
+comexpy.comex_details("general")     # grouping fields available
+comexpy.comex_filters("general")     # filters available
+comexpy.comex_metrics("general")     # metrics available
+
+# Look up country codes
+countries = comexpy.comex_countries()
+countries[countries["text"].str.contains("China", case=False)]
+
+# Economic blocs in Portuguese
+comexpy.comex_blocs(language="pt")
+```
+
+## City-level and historical data
+
+```python
+# Exports declared in Pernambuco (state 26) in 2023
+comexpy.comex_query_city(
+    flow="export",
+    start_period="2023-01",
+    end_period="2023-12",
+    details=["country", "state"],
+    filters={"state": 26},
+)
+
+# Historical exports 1995–1996 by country (NBM classification)
+comexpy.comex_historical(
+    flow="export",
+    start_period="1995-01",
+    end_period="1996-12",
+    details="country",
+)
+```
+
+## Rate limiting and timeouts
+
+The ComexStat API frequently returns rate-limit errors (HTTP 429,
+*"Você excedeu o limite de solicitações..."*) or times out. Adjust the
+behaviour with `set_options`:
+
+```python
+comexpy.set_options(retry_time=30)   # wait 30s between retries
+comexpy.set_options(max_tries=5, timeout_post=180)
+```
+
+Silence progress/success messages with `comexpy.set_verbose(False)`.
+
+## Public API
+
+| Function | Purpose |
+|----------|---------|
+| `comex_query` / `comex_export` / `comex_import` | General trade data (1997–present) |
+| `comex_query_city` | City-level data |
+| `comex_historical` | Historical data (1989–1996) |
+| `comex_last_update` / `comex_available_years` | API metadata |
+| `comex_filters` / `comex_filter_values` / `comex_details` / `comex_metrics` | Query option discovery |
+| `comex_countries` / `comex_blocs` / `comex_states` / `comex_cities` / `comex_transport_modes` / `comex_customs_units` (+ `_detail`) | Geography tables |
+| `comex_ncm` / `comex_nbm` / `comex_hs` (+ `_detail`) | Product nomenclatures |
+| `comex_cgce` / `comex_sitc` / `comex_isic` | Economic classifications |
+| `set_options` / `set_verbose` | Configuration |
+
+## License
+
+MIT — see [LICENSE](LICENSE). Developed by the comexpy authors.

comexpy-0.1.0/README.md

@@ -0,0 +1,134 @@
+# comexpy
+
+[![PyPI](https://img.shields.io/pypi/v/comexpy.svg)](https://pypi.org/project/comexpy/)
+[![Python versions](https://img.shields.io/pypi/pyversions/comexpy.svg)](https://pypi.org/project/comexpy/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**Access the Brazilian Foreign Trade Statistics API (ComexStat) from Python.**
+
+`comexpy` is a pandas-friendly interface to the
+[ComexStat API](https://api-comexstat.mdic.gov.br/docs#/) of the Brazilian
+Ministry of Development, Industry, Trade and Services (MDIC). It provides
+programmatic access to detailed Brazilian export and import data — every
+query returns a `pandas.DataFrame`.
+
+This is the Python port of the R package
+[`comexr`](https://github.com/StrategicProjects/comexr); the public function
+names mirror the R API so knowledge transfers directly between the two.
+
+## Features
+
+- **General trade data** (1997–present), **city-level** data, and
+  **historical** records (1989–1996)
+- **Auxiliary tables**: countries, economic blocs, NCM/NBM/HS product codes,
+  CGCE/SITC/ISIC classifications, states, cities, transport modes, customs units
+- **Friendly aliases** — pass `"hs4"`, `"transport_mode"`, `"cgce_n1"` and the
+  package translates them to the API's internal names
+- **Multilingual** responses: Portuguese, English, Spanish
+- **SSL auto-fallback** — handles ICP-Brasil certificate issues transparently
+- **Configurable retry/timeout** for the API's aggressive rate limiting
+
+## Installation
+
+```bash
+pip install comexpy
+```
+
+Requires Python 3.9+, `requests` and `pandas`.
+
+## Quick start
+
+```python
+import comexpy
+
+# Exports by country in January 2024
+exports = comexpy.comex_export(
+    start_period="2024-01",
+    end_period="2024-01",
+    details="country",
+)
+
+# Imports with CIF value, by country, for all of 2024
+imports = comexpy.comex_import(
+    start_period="2024-01",
+    end_period="2024-12",
+    details="country",
+    metric_cif=True,
+)
+
+# Exports to China (160), grouped by HS4
+# (the package translates "hs4" to the API's `heading`)
+soy = comexpy.comex_export(
+    start_period="2024-01",
+    end_period="2024-12",
+    details=["country", "hs4"],
+    filters={"country": 160},
+)
+```
+
+## Discover available options
+
+```python
+comexpy.comex_details("general")     # grouping fields available
+comexpy.comex_filters("general")     # filters available
+comexpy.comex_metrics("general")     # metrics available
+
+# Look up country codes
+countries = comexpy.comex_countries()
+countries[countries["text"].str.contains("China", case=False)]
+
+# Economic blocs in Portuguese
+comexpy.comex_blocs(language="pt")
+```
+
+## City-level and historical data
+
+```python
+# Exports declared in Pernambuco (state 26) in 2023
+comexpy.comex_query_city(
+    flow="export",
+    start_period="2023-01",
+    end_period="2023-12",
+    details=["country", "state"],
+    filters={"state": 26},
+)
+
+# Historical exports 1995–1996 by country (NBM classification)
+comexpy.comex_historical(
+    flow="export",
+    start_period="1995-01",
+    end_period="1996-12",
+    details="country",
+)
+```
+
+## Rate limiting and timeouts
+
+The ComexStat API frequently returns rate-limit errors (HTTP 429,
+*"Você excedeu o limite de solicitações..."*) or times out. Adjust the
+behaviour with `set_options`:
+
+```python
+comexpy.set_options(retry_time=30)   # wait 30s between retries
+comexpy.set_options(max_tries=5, timeout_post=180)
+```
+
+Silence progress/success messages with `comexpy.set_verbose(False)`.
+
+## Public API
+
+| Function | Purpose |
+|----------|---------|
+| `comex_query` / `comex_export` / `comex_import` | General trade data (1997–present) |
+| `comex_query_city` | City-level data |
+| `comex_historical` | Historical data (1989–1996) |
+| `comex_last_update` / `comex_available_years` | API metadata |
+| `comex_filters` / `comex_filter_values` / `comex_details` / `comex_metrics` | Query option discovery |
+| `comex_countries` / `comex_blocs` / `comex_states` / `comex_cities` / `comex_transport_modes` / `comex_customs_units` (+ `_detail`) | Geography tables |
+| `comex_ncm` / `comex_nbm` / `comex_hs` (+ `_detail`) | Product nomenclatures |
+| `comex_cgce` / `comex_sitc` / `comex_isic` | Economic classifications |
+| `set_options` / `set_verbose` | Configuration |
+
+## License
+
+MIT — see [LICENSE](LICENSE). Developed by the comexpy authors.

comexpy-0.1.0/docs/getting-started.md

@@ -0,0 +1,69 @@
+# Getting started
+
+## Install
+
+```bash
+pip install comexpy
+```
+
+Requires Python 3.9+, `requests` and `pandas`.
+
+## Your first queries
+
+```python
+import comexpy
+
+# Exports by country in January 2024 (monthly detail off → one row per country)
+exports = comexpy.comex_export(
+    start_period="2024-01",
+    end_period="2024-01",
+    details="country",
+    month_detail=False,
+)
+
+# Imports for all of 2024, by country, including the CIF value
+imports = comexpy.comex_import(
+    start_period="2024-01",
+    end_period="2024-12",
+    details="country",
+    metric_cif=True,
+)
+```
+
+## Filtering and grouping
+
+`details` controls the grouping; `filters` restricts the rows. Both accept
+friendly aliases that the package translates to the API's internal names
+(e.g. `"hs4"` → `heading`, `"transport_mode"` → `via`).
+
+```python
+# Exports to China (160), grouped by HS4 product heading
+soy = comexpy.comex_export(
+    start_period="2024-01",
+    end_period="2024-12",
+    details=["country", "hs4"],
+    filters={"country": 160},
+)
+```
+
+## Discover what you can query
+
+```python
+comexpy.comex_details("general")   # available grouping fields
+comexpy.comex_filters("general")   # available filters
+comexpy.comex_metrics("general")   # available metrics
+
+# Look up codes
+comexpy.comex_countries(search="china")
+comexpy.comex_ncm(search="soja", per_page=10)
+```
+
+## Messages and rate limiting
+
+The ComexStat API rate-limits aggressively. Tune the HTTP behaviour and
+silence progress messages as needed:
+
+```python
+comexpy.set_options(retry_time=30, max_tries=5)
+comexpy.set_verbose(False)
+```

comexpy-0.1.0/docs/guide.md

@@ -0,0 +1,110 @@
+# User guide
+
+## The three datasets
+
+| Function | Period | Product detail | Metrics |
+|----------|--------|----------------|---------|
+| `comex_query` / `comex_export` / `comex_import` | 1997–present | NCM, HS2/4/6, CGCE, SITC, ISIC | FOB, KG, statistic, freight, insurance, CIF |
+| `comex_query_city` | 1997–present | HS2/HS4 only | FOB, KG |
+| `comex_historical` | 1989–1996 | NBM | FOB, KG |
+
+### General trade
+
+```python
+comexpy.comex_query(
+    flow="export",
+    start_period="2023-01",
+    end_period="2023-12",
+    details=["ncm", "country"],
+    filters={"country": [160, 249]},
+    month_detail=True,
+    metric_cif=True,
+)
+```
+
+### City-level
+
+City information is based on the **declarant** of exports/imports, not the
+producer or buyer. Only FOB and KG metrics are available, and product detail
+goes only down to HS4.
+
+```python
+comexpy.comex_query_city(
+    flow="export",
+    start_period="2023-01",
+    end_period="2023-12",
+    details=["country", "state"],
+    filters={"state": 26},
+)
+```
+
+### Historical (1989–1996)
+
+Uses the NBM nomenclature. Details are limited to `country`, `state` and
+`nbm`.
+
+```python
+comexpy.comex_historical(
+    flow="export",
+    start_period="1995-01",
+    end_period="1996-12",
+    details="country",
+)
+```
+
+## Detail and filter aliases
+
+The package maps user-friendly names to the API's internal names. You can
+always pass the API name verbatim instead.
+
+| Alias | API name |
+|-------|----------|
+| `bloc` / `economic_block` | `economicBlock` |
+| `transport_mode` | `via` |
+| `customs_unit` | `urf` |
+| `hs6` / `sh6` | `subHeading` |
+| `hs4` / `sh4` | `heading` |
+| `hs2` / `sh2` | `chapter` |
+| `cgce_n1/2/3` | `BECLevel1/2/3` |
+| `sitc_section` … | `SITCSection` … |
+| `isic_section` … | `ISICSection` … |
+
+The full table is exposed as `comexpy.DETAILS_MAP`.
+
+## Auxiliary tables
+
+```python
+# Geography
+comexpy.comex_countries()
+comexpy.comex_blocs(language="pt")
+comexpy.comex_states()
+comexpy.comex_cities()
+comexpy.comex_transport_modes()
+comexpy.comex_customs_units()
+
+# Products
+comexpy.comex_ncm(search="animal")
+comexpy.comex_nbm()
+comexpy.comex_hs(add="ncm")
+
+# Classifications
+comexpy.comex_cgce()
+comexpy.comex_sitc(search="carne")
+comexpy.comex_isic("division")
+```
+
+Every `*_detail` function (e.g. `comex_country_detail(105)`) returns a single
+record as a `dict`.
+
+## Configuration
+
+```python
+comexpy.set_options(
+    timeout_get=60,    # seconds, GET requests
+    timeout_post=120,  # seconds, POST requests
+    max_tries=3,       # attempts per request
+    retry_time=10,     # seconds between retries (API recommends 10)
+    ssl_verify=True,   # set False to skip ICP-Brasil verification
+)
+comexpy.set_verbose(False)   # silence progress/success messages
+```

comexpy-0.1.0/docs/index.md

@@ -0,0 +1,45 @@
+# comexpy
+
+**Access the Brazilian Foreign Trade Statistics API (ComexStat) from Python.**
+
+`comexpy` is a [pandas](https://pandas.pydata.org/)-friendly interface to the
+[ComexStat API](https://api-comexstat.mdic.gov.br/docs#/) of the Brazilian
+Ministry of Development, Industry, Trade and Services (MDIC). Query detailed
+Brazilian export and import data — every fetch returns a `pandas.DataFrame`.
+
+It is the Python port of the R package
+[`comexr`](https://github.com/StrategicProjects/comexr); the public function
+names mirror the R API so knowledge transfers directly between the two.
+
+## Install
+
+```bash
+pip install comexpy
+```
+
+## A first query
+
+```python
+import comexpy
+
+# Exports by country in January 2024
+df = comexpy.comex_export(
+    start_period="2024-01",
+    end_period="2024-01",
+    details="country",
+)
+```
+
+Continue with the [Getting started](getting-started.md) guide, the
+[User guide](guide.md), or jump to the full [API reference](reference.md).
+
+## Highlights
+
+- **Tidy output** — every query and table function returns a
+  `pandas.DataFrame`.
+- **Three datasets** — general trade (1997–present), city-level, and
+  historical (1989–1996).
+- **Friendly aliases** — pass `"hs4"`, `"transport_mode"`, `"cgce_n1"`; the
+  package translates them to the API's internal names.
+- **Resilient HTTP** — configurable retry/timeout for the API's aggressive
+  rate limiting, plus SSL auto-fallback for ICP-Brasil certificates.