docs: Update README and module docstrings for clarity and consistency

Author: dankkom

README.md

@@ -1,6 +1,6 @@
 # comexdown: Brazil's foreign trade data downloader
 
-![GitHub](https://img.shields.io/github/license/viridis-data/comexdown?style=flat-square) ![PyPI](https://img.shields.io/pypi/v/comexdown?style=flat-square)
+![GitHub](https://img.shields.io/github/license/dankkom/comexdown?style=flat-square) ![PyPI](https://img.shields.io/pypi/v/comexdown?style=flat-square)
 
 This package contains functions to download brazilian foreign trade data
 published by [Ministerio da Economia(ME)/Secretaria de Comercio Exterior (SCE)][1].
@@ -51,15 +51,16 @@ To setup a development environment clone this repository and install the require
 ```shell
 git clone https://github.com/dankkom/comexdown.git
 cd comexdown
-poetry install
+pip install -e .[dev]
 ```
 
 ### Run tests
 
 To run the tests suite, use the following command:
 
 ```shell
-poetry run pytest --cov=comexdown --cov-report term-missing --cov-report html tests/
+ pip install -e .[dev]
+ pytest tests/
 ```
 
 [1]: https://www.gov.br/produtividade-e-comercio-exterior/pt-br/assuntos/comercio-exterior/estatisticas/base-de-dados-bruta

comexdown/cli.py

@@ -1,11 +1,31 @@
 #!/usr/bin/env python3
 
-"""usage: comexdown { trade | table } <arguments>
+"""Command-line interface for downloading Brazil's foreign trade data.
 
-  comexdown trade <year> ... -o <output>
+This module provides a CLI tool for downloading trade transaction data and
+auxiliary code tables from Brazil's Ministry of Economy (SECEX/COMEX).
 
-  comexdown table <table name> -o <output>
+Usage:
+    comexdown { trade | table } <arguments>
 
+    comexdown trade <year> ... -o <output>
+    comexdown table <table name> -o <output>
+
+Examples:
+    Download exports and imports for 2020:
+        $ comexdown trade 2020
+
+    Download exports for years 2018-2020:
+        $ comexdown trade 2018:2020 -exp
+
+    Download municipality data:
+        $ comexdown trade 2020 -mun
+
+    Download all auxiliary tables:
+        $ comexdown table all
+
+    Download specific auxiliary table:
+        $ comexdown table ncm
 """
 
 
@@ -17,6 +37,34 @@
 
 
 def expand_years(args_years: str) -> list[int]:
+    """Expand year arguments into a list of individual years.
+
+    Processes command-line year arguments which may include individual years
+    or year ranges (e.g., "2018:2020") and expands them into a complete list
+    of years.
+
+    Parameters
+    ----------
+    args_years : str
+        List of year strings, which can be individual years (e.g., "2020") or
+        ranges (e.g., "2018:2020"). Ranges can be ascending or descending.
+
+    Returns
+    -------
+    list[int]
+        Expanded list of years in the order they were specified.
+
+    Examples
+    --------
+    >>> expand_years(["2020"])
+    [2020]
+    >>> expand_years(["2018:2020"])
+    [2018, 2019, 2020]
+    >>> expand_years(["2020:2018"])
+    [2020, 2019, 2018]
+    >>> expand_years(["2018", "2020:2022"])
+    [2018, 2020, 2021, 2022]
+    """
     years = []
     for arg in args_years:
         if ":" in arg:
@@ -35,6 +83,30 @@ def expand_years(args_years: str) -> list[int]:
 # ----------------------------TRANSACTION TRADE DATA---------------------------
 # =============================================================================
 def download_trade(args: argparse.Namespace):
+    """Download trade transaction data based on command-line arguments.
+
+    Handles the download of Brazil's foreign trade data for specified years.
+    Supports downloading exports, imports, and municipality-level data for both
+    modern NCM classification (1997+) and older NBM classification (1989-1996).
+
+    Parameters
+    ----------
+    args : argparse.Namespace
+        Command-line arguments containing:
+        - years: List of years or year ranges to download
+        - exp: Flag to download export data only
+        - imp: Flag to download import data only
+        - mun: Flag to download municipality-level data
+        - path: Output directory path for downloaded files
+
+    Notes
+    -----
+    - If neither exp nor imp flags are set, both are downloaded
+    - Years before 1989 are not available
+    - Years 1989-1996 use NBM classification (municipality data not available)
+    - Years 1997+ use NCM classification
+    - Special year value "complete" downloads complete historical datasets
+    """
     if not args.exp and not args.imp:
         exp = imp = True
     else:
@@ -81,6 +153,25 @@ def download_trade(args: argparse.Namespace):
 # ----------------------------AUXILIARY CODE TABLES----------------------------
 # =============================================================================
 def download_tables(args: argparse.Namespace):
+    """Download auxiliary code tables based on command-line arguments.
+
+    Handles downloading of various classification and reference tables used
+    for interpreting Brazil's foreign trade data, including NCM codes, country
+    codes, municipality codes, and various product classifications.
+
+    Parameters
+    ----------
+    args : argparse.Namespace
+        Command-line arguments containing:
+        - tables: List of table names to download (or 'all' for all tables)
+        - path: Output directory path for downloaded tables
+
+    Notes
+    -----
+    - If no table names are provided, prints available tables and exits
+    - Special value 'all' downloads all available auxiliary tables
+    - Tables are saved in an 'auxiliary-tables' subdirectory
+    """
     if args.tables == []:
         print_code_tables()
     if "all" in args.tables:
@@ -98,6 +189,17 @@ def download_tables(args: argparse.Namespace):
 
 
 def print_code_tables():
+    """Print formatted list of all available auxiliary code tables.
+
+    Displays a formatted list of all auxiliary tables available for download,
+    including their short names, full names, and descriptions. Long descriptions
+    are word-wrapped to fit within 70 characters per line.
+
+    Notes
+    -----
+    This function is called when the user runs 'comexdown table' without
+    specifying any table names, serving as a help/reference guide.
+    """
     print("\nAvailable code tables:")
     for table in TABLES:
         print(f"\n  {table: <11}{TABLES[table]['name']}")
@@ -121,6 +223,13 @@ def print_code_tables():
 
 
 def download_help(args: argparse.Namespace):
+    """Print CLI help message.
+
+    Parameters
+    ----------
+    args : argparse.Namespace
+        Unused, but required by argparse callback interface.
+    """
     print(__doc__)
 
 
@@ -131,6 +240,28 @@ def set_download_trade_subparser(
     download_subs: argparse.ArgumentParser,
     default_output: Path,
 ):
+    """Configure the 'trade' subcommand parser.
+
+    Sets up the argument parser for downloading trade transaction data,
+    including all supported flags and options.
+
+    Parameters
+    ----------
+    download_subs : argparse.ArgumentParser
+        Subparser collection to add the trade subcommand to.
+    default_output : Path
+        Default output directory path for downloaded files.
+
+    Notes
+    -----
+    Configures the following arguments:
+    - years: Required positional argument for years to download
+    - -exp: Optional flag to download only exports
+    - -imp: Optional flag to download only imports
+    - -mun: Optional flag to download municipality-level data
+    - -nbm: Optional flag for NBM classification data
+    - -o: Optional output path argument
+    """
     # !!! DOWNLOAD TRADE TRANSACTIONS DATA
     download_trade_parser = download_subs.add_parser(
         "trade", description="Download Exports & Imports data")
@@ -159,6 +290,23 @@ def set_download_table_subparser(
     download_subs: argparse.ArgumentParser,
     default_output: Path,
 ):
+    """Configure the 'table' subcommand parser.
+
+    Sets up the argument parser for downloading auxiliary code tables.
+
+    Parameters
+    ----------
+    download_subs : argparse.ArgumentParser
+        Subparser collection to add the table subcommand to.
+    default_output : Path
+        Default output directory path for downloaded tables.
+
+    Notes
+    -----
+    Configures the following arguments:
+    - tables: Optional list of table names to download
+    - -o: Optional output path argument
+    """
     # !!! DOWNLOAD CODE TABLES
     download_table_parser = download_subs.add_parser(
         "table", description="Download code tables for Brazil's foreign data")
@@ -184,6 +332,23 @@ def set_download_table_subparser(
 
 
 def set_parser() -> argparse.ArgumentParser:
+    """Create and configure the main argument parser.
+
+    Builds the complete command-line argument parser with all subcommands
+    and their respective options.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser ready to parse command-line arguments.
+
+    Notes
+    -----
+    Sets up two subcommands:
+    - trade: For downloading trade transaction data
+    - table: For downloading auxiliary code tables
+    Default output path is './data/secex-comex'
+    """
     default_output = Path(".", "data", "secex-comex")
 
     parser = argparse.ArgumentParser(
@@ -199,6 +364,16 @@ def set_parser() -> argparse.ArgumentParser:
 
 
 def main():
+    """Main entry point for the comexdown CLI tool.
+
+    Parses command-line arguments and dispatches to the appropriate
+    download function based on the subcommand provided.
+
+    Notes
+    -----
+    This function is called when the module is executed as a script or
+    when the 'comexdown' command is run from the command line.
+    """
     parser = set_parser()
     args = parser.parse_args()
 

comexdown/constants.py

@@ -1,3 +1,25 @@
+"""Constants and configuration for Brazil's foreign trade data tables.
+
+This module contains metadata for all auxiliary code tables available from
+Brazil's SECEX/COMEX system. These tables provide reference data for
+interpreting trade transaction records, including product classifications,
+geographic codes, and various categorization schemes.
+
+The TABLES dictionary contains metadata for each available auxiliary table:
+- description: Portuguese description of the table's content
+- file_ref: Filename of the table file
+- pkey: Primary key field(s) for the table
+- name: Full name of the classification/table
+- url: (optional) Alternative download URL for external tables
+
+Available table categories:
+- Product Classifications: ncm, sh, cuci, cgce, isic, siit, nbm
+- Product Groupings: fat_agreg, ppi, ppe, grupo, agronegocio
+- Geographic: pais, pais_bloco, uf, uf_mun
+- Operational: via, urf, unidade
+- Conversion: nbm_ncm, isic_cuci
+"""
+
 TABLES = {
     "ncm": {
         "description": "Códigos NCM e descrições.",
@@ -178,6 +200,7 @@
     },
 }
 
+# Dictionary mapping table names to their filenames
 AUX_TABLES = {
     name: TABLES[name]["file_ref"] for name in TABLES
 }