Update package to 1.0.0

.gitignore

@@ -23,5 +23,11 @@ htmlcov/
 .DS_Store
 Thumbs.db
 
-# Keep egg-info for package metadata
-!global_macro_data.egg-info/
+# Remove egg-info
+global_macro_data.egg-info/
+
+# Test file
+test.py
+
+# Testing: .tox
+.tox/

README.md

@@ -17,7 +17,7 @@ This repository complements paper, **Müller, Xu, Lehbib, and Chen (2025)**, whi
 - **Scheduled Updates**: Regular releases ensure data reliability.
 - **Full Transparency**: All code is open source and available in this repository.
 - **Accessible Formats**: Provided in `.dta`, `.csv` and as **<a href="https://github.com/KMueller-Lab/Global-Macro-Database" target="_blank" rel="noopener noreferrer">Stata</a>
-/<a href="https://github.com/KMueller-Lab/Global-Macro-Database-Python" target="_blank" rel="noopener noreferrer">Python</a>/<a href="https://github.com/KMueller-Lab/Global-Macro-Database-R" target="_blank" rel="noopener noreferrer">R</a> package**.
+/<a href="https://github.com/KMueller-Lab/Global-Macro-Database-Python" target="_blank" rel="noopener noreferrer">Python</a>/<a href="https://github.com/KMueller-Lab/Global-Macro-Database-R" target="_blank" rel="noopener noreferrer">R</a> packages**.
 
 ## Data access
 
@@ -30,47 +30,52 @@ pip install global_macro_data
 
 **How to use (examples)**
 ```python
-from global_macro_data import gmd
+import global_macro_data as gmd
 
 # Get data from latest available version
-df = gmd()
+df = gmd.get_data()
 
 # Get data from a specific version
-df = gmd(version="2025_01")
+df = gmd.get_data(version="2025_01")
 
 # Get data for a specific country
-df = gmd(country="USA")
+df = gmd.get_data(country="USA")
 
 # Get data for multiple countries
-df = gmd(country=["USA", "CHN", "DEU"])
+df = gmd.get_data(country=["USA", "CHN", "Germany"])
 
 # Get specific variables
-df = gmd(variables=["rGDP", "infl", "unemp"])
+df = gmd.get_data(variables=["rGDP", "infl", "unemp"])
 
 # Get raw data for a single variable
-df = gmd(variables="rGDP", raw=True)
+df = gmd.get_data(variables="rGDP", raw=True)
 
 # List available variables and their descriptions
-gmd(vars=True)
+gmd.list_variables()
 
 # List available countries and their ISO codes
-gmd(iso=True)
+gmd.list_countries()
+
+# List available versions
+gmd.list_versions()
 
 # Combine parameters
-df = gmd(
+df = gmd.get_data(
     version="2025_01",
     country=["USA", "CHN"],
     variables=["rGDP", "unemp", "CPI"]
 )
+
+# Enable verbose logging (INFO-level and above)
+gmd.enable_verbose_logging()
 ```
 
-## Parameters
+## Parameters for `gmd.get_data()`
 - **variables (str or list)**: Variable code(s) to include (e.g., "rGDP" or ["rGDP", "unemp"])
-- **country (str or list)**: ISO3 country code(s) (e.g., "SGP" or ["MRT", "SGP"])
+- **country (str or list)**: Country name or ISO3 country code(s) (e.g., "SGP" or ["MRT", "SGP"])
 - **version (str)**: Dataset version in format 'YYYY_MM' (e.g., '2025_01'). If None or "current", uses the latest version
 - **raw (bool)**: If True, download raw data for a single variable
-- **iso (bool)**: If True, display list of available countries
-- **vars (bool)**: If True, display list of available variables
+
 
 ## Release schedule 
 | Release Date | Details         |

global_macro_data/__init__.py

@@ -1,17 +1,19 @@
-from .gmd import (
-    gmd,
-    get_available_versions,
+from global_macro_data.gmd import (
+    get_data,
+    list_versions,
     get_current_version,
     list_variables,
     list_countries,
     VALID_VARIABLES
 )
+from global_macro_data.logging import enable_verbose_logging
 
 __all__ = [
-    "gmd",
-    "get_available_versions",
+    "get_data",
+    "list_versions",
     "get_current_version",
     "list_variables",
     "list_countries",
+    "enable_verbose_logging",
     "VALID_VARIABLES"
-]
+]

global_macro_data/exceptions.py

@@ -0,0 +1,90 @@
+from typing import List
+
+
+INTRO = (
+    "\nGlobal Macro Database by Müller et al. (2025)\n"
+    "Website: https://www.globalmacrodata.com\n\n"
+)
+
+
+class InvalidVariableError(ValueError):
+    """Raised when one or more variable codes are invalid."""
+
+    def __init__(self, invalid_vars: List[str]):
+        self.invalid_vars = invalid_vars
+
+        # Format variable list nicely
+        if len(invalid_vars) == 1:
+            var_list = invalid_vars[0]
+            var_intro = "Invalid variable code"
+        else:
+            var_list = ', '.join(invalid_vars)
+            var_intro = "Invalid variable codes"
+
+        message = (
+            INTRO +
+            f"{var_intro}: {var_list}\n\n"
+            "To see the list of valid variable codes, "
+            "use: gmd.list_variables()"
+        )
+
+        super().__init__(message)
+
+
+class InvalidVersionError(ValueError):
+    """Raised when a requested dataset version does not exist."""
+
+    def __init__(self, requested_version: str):
+
+        self.requested_version = requested_version
+        message = (
+            INTRO +
+            f"Error: '{requested_version}' is not a valid dataset version.\n"
+            "To see the list of valid versions, use: gmd.list_versions()"
+        )
+        super().__init__(message)
+
+
+class RawModeError(ValueError):
+    """Raised when raw=True is used incorrectly."""
+
+    def __init__(self):
+        message = (
+            INTRO +
+            "'raw=True' requires specifying exactly one variable.\n"
+            "Raw data is only accessed variable-wise using: "
+            "gmd.get_data(variable, raw=True)\n"
+            "For full documentation: https://www.globalmacrodata.com/GMD.xlsx"
+        )
+        super().__init__(message)
+
+
+class DataDownloadError(ConnectionError):
+    """Raised when data cannot be downloaded from the remote source."""
+
+    def __init__(self, original_exception: Exception):
+        message = (
+            INTRO +
+            f"Error downloading data:\n{original_exception}"
+        )
+        super().__init__(message)
+        self.original_exception = original_exception
+
+
+class InvalidCountryError(ValueError):
+    """Raised when one or more country codes are invalid."""
+
+    def __init__(self, invalid_codes: List[str]):
+        self.invalid_codes = invalid_codes
+
+        if len(invalid_codes) == 1:
+            msg = f"Invalid country code: '{invalid_codes[0]}'"
+        else:
+            msg = f"Invalid country codes: {', '.join(invalid_codes)}"
+
+        message = (
+            INTRO +
+            f"{msg}\n\n"
+            "To see the list of valid country codes, use: gmd.list_countries()"
+        )
+        super().__init__(message)