"""
Atlas Common Data - Shared data and utilities for Growth Lab projects.

This package provides:
1. Static classification data (countries, products, etc.)
2. Data fetching classes for external sources (IMF, WDI, FRED, UN)
3. Common utilities used across multiple Growth Lab projects

Quick Start:
    # Load static data
    from atlas_common_data import load_countries, load_products

    countries = load_countries()
    products = load_products('hs92')

    # Fetch external data
    from atlas_common_data import IMFData, WDIData, FREDData, UNPopulationData

    imf = IMFData()
    df = imf.get_indicators(['NGDPD', 'LP'])

For more details, see the module documentation:
- atlas_common_data.loaders: Static data loading functions
- atlas_common_data.sources: Data fetching classes (IMF, WDI, FRED, UN)
"""

__version__ = "0.3.0"


def describe() -> None:
    """Print a quick-reference of every public function and class in this package.

    Example:
        >>> import atlas_common_data
        >>> atlas_common_data.describe()
    """
    text = f"""\
atlas_common_data v{__version__} — Quick Reference
{'=' * 50}

STATIC LOADERS  (no network required)
--------------------------------------
load_countries()                              → DataFrame  Country classification (iso3, names, ids)
load_groups()                                 → DataFrame  Geographic groups (regions, income tiers)
load_group_members()                          → DataFrame  Country-to-group membership
load_products(classification='hs92')          → DataFrame  Products: 'hs92' | 'hs12' | 'hs22' | 'sitc'
list_available_product_classifications()      → list       e.g. ['hs12', 'hs22', 'hs92', 'sitc']
load_product_space_edges(classification)      → DataFrame  Product space network edges (weights)
load_product_space_clusters(classification)   → DataFrame  Product space cluster definitions
load_services(service_type='bilateral')       → DataFrame  Services: 'bilateral' | 'unilateral'
load_comparator_countries()                   → DataFrame  Comparator country mappings per country
load_sitc_natural_resource_products()         → DataFrame  SITC product codes with natural resource flag
load_geo_distances()                          → DataFrame  Pairwise geographic distances (~4 MB)
load_column_metadata()                        → DataFrame  Column definitions / data dictionary
load_growth_projections()                     → DataFrame  Growth projections (iso3, growth_proj, year)
load_classifications()                        → dict       Trade classification metadata (H0, H1…)
list_available_conversion_weights()           → list       Available classification conversion pairs
load_conversion_weights(source, target)       → DataFrame  Conversion weights (e.g. 'H0' → 'H1')

CONVENIENCE LOOKUPS
--------------------
get_country_by_iso3(iso3_code)                → Series     Single country row by ISO3 code
get_country_id_mapping()                      → dict       ISO3 → country_id
get_iso3_to_name_mapping()                    → dict       ISO3 → English name

DATA SOURCE CLASSES  (require network)
--------------------------------------
IMFData(latest_year=None)
  .get_imf_data(end_year)                     → DataFrame  Full IMF dataset; matches imf_data.csv
                                                            Applies FRED PPIIDC deflator for _const cols
  .get_indicators(indicators, country_codes,  → DataFrame  Raw indicators (no deflator)
                  start_year, end_year,
                  include_country_id)
  .get_country_metadata(reference_year)       → DataFrame  Income level & region per country
  .get_average_growth_rates(lookback_periods, → DataFrame  Avg GDP/pc growth: 3/5/10/15-yr windows
                             reference_year,
                             country_codes)
  .get_inflation_index(base_year,             → DataFrame  Cumulative inflation index (IMF PCPIPCH)
                       country_code='USA')
  .list_available_indicators()   [classmethod]→ dict       IMF codes → friendly column names

  IMF codes: NGDP_R, NGDP_RPCH, NGDPD, PPPGDP, NGDPDPC, PPPPC, LP, BCA, PCPIPCH

WDIData(latest_year=None)
  .get_wdi_data(end_year)                     → DataFrame  Full WDI dataset; matches wdi_data.csv
  .get_indicators(indicators, start_year,     → DataFrame  Custom indicators (dict: code → name)
                  end_year, include_country_id)            Note: batches requests (WB limit = 8)
  .get_country_metadata()                     → DataFrame  Income level & region per country
  .get_gdp_data(start_year, end_year)         → DataFrame  GDP indicators only
  .get_services_data(start_year, end_year)    → DataFrame  Services trade indicators
  .get_bop_data(start_year, end_year)         → DataFrame  Balance of payments indicators
  .list_available_indicators() [classmethod]  → dict       Preset indicator groups by category
  .get_indicator_description(code) [classmethod] → str     Friendly name for a WDI code

FREDData(api_key, base_year)   ← requires FRED API key
  .get_fred_data()                            → DataFrame  PPIIDC deflator; matches fred_ppiidc.csv
  .get_inflation_index(month=12)              → DataFrame  PPI index with deflator column
  .list_available_series()   [classmethod]    → dict       Supported FRED series IDs

UNPopulationData(latest_year=None)
  .get_population_forecast(start_year,        → DataFrame  Population forecast, Medium variant
                            end_year)                       Columns: iso3_code, year, population

MISSING-DATA WARNINGS
----------------------
get_imf_data() and get_wdi_data() emit a UserWarning when countries appear in
historical data but have no row for end_year (e.g. ERI, SYR in IMF data).

USAGE EXAMPLES
--------------
  from atlas_common_data import (
      load_countries, load_products,
      IMFData, WDIData, FREDData, UNPopulationData,
  )
  import datetime

  # Static data — instant, no network
  countries = load_countries()
  products  = load_products('hs92')
  weights   = load_conversion_weights('H0', 'H1')

  # Live data — requires network
  latest = datetime.date.today().year - 1

  imf = IMFData(latest_year=latest)
  imf_df  = imf.get_imf_data(end_year=latest)       # → imf_data.csv schema
  meta_df = imf.get_country_metadata()               # → imf_country_data.csv schema
  grow_df = imf.get_average_growth_rates()           # → imf_avg_growth.csv schema

  wdi = WDIData(latest_year=latest)
  wdi_df  = wdi.get_wdi_data(end_year=latest)        # → wdi_data.csv schema
  svc_df  = wdi.get_services_data()                  # → wdi_service_data.csv schema

  fred = FREDData(api_key='YOUR_KEY', base_year=latest)
  fred_df = fred.get_fred_data()                     # → fred_ppiidc.csv schema

  un = UNPopulationData(latest_year=latest)
  un_df   = un.get_population_forecast()             # → un_population_forecast_medium.csv schema

For per-function docs: help(atlas_common_data.loaders) or help(IMFData)
"""
    print(text)

# Static data loaders
from atlas_common_data.loaders import (
    load_countries,
    load_groups,
    load_group_members,
    load_products,
    list_available_product_classifications,
    load_product_space_edges,
    load_product_space_clusters,
    load_services,
    load_comparator_countries,
    load_sitc_natural_resource_products,
    load_geo_distances,
    load_column_metadata,
    get_country_by_iso3,
    get_country_id_mapping,
    get_iso3_to_name_mapping,
    load_growth_projections,
    list_available_growth_projection_years,
    list_available_product_space_classifications,
    load_classifications,
    list_available_conversion_weights,
    load_conversion_weights,
)

# Data source classes
from atlas_common_data.sources.imf import IMFData
from atlas_common_data.sources.wdi import WDIData
from atlas_common_data.sources.fred import FREDData
from atlas_common_data.sources.un import UNPopulationData

__all__ = [
    # Version
    "__version__",
    # Help
    "describe",
    # Static data loaders
    "load_countries",
    "load_groups",
    "load_group_members",
    "load_products",
    "list_available_product_classifications",
    "load_product_space_edges",
    "load_product_space_clusters",
    "load_services",
    "load_comparator_countries",
    "load_geo_distances",
    "load_column_metadata",
    "get_country_by_iso3",
    "get_country_id_mapping",
    "get_iso3_to_name_mapping",
    # Growth projections
    "load_growth_projections",
    "list_available_growth_projection_years",
    "list_available_product_space_classifications",
    # Classifications and conversion weights
    "load_classifications",
    "list_available_conversion_weights",
    "load_conversion_weights",
    # Data source classes
    "IMFData",
    "WDIData",
    "FREDData",
    "UNPopulationData",
]
