oda-data 2.0.0__tar.gz → 2.0.0b2__tar.gz

{oda_data-2.0.0 → oda_data-2.0.0b2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: oda_data
-Version: 2.0.0
+Version: 2.0.0b2
 Summary: A python package to work with Official Development Assistance data from the OECD DAC.
 Author: Jorge Rivera
 Author-email: jorge.rivera@one.org
@@ -13,7 +13,7 @@ Classifier: Programming Language :: Python :: 3.13
 Provides-Extra: dev
 Requires-Dist: black (>=24) ; extra == "dev"
 Requires-Dist: cachetools (>=5.5.1,<6.0.0)
-Requires-Dist: oda-reader (>=1.1.3)
+Requires-Dist: oda-reader (>=1)
 Requires-Dist: pandas (>=2)
 Requires-Dist: pyarrow (>=14,<20)
 Requires-Dist: pydeflate (>=2.0.1)
@@ -27,14 +27,13 @@ Description-Content-Type: text/markdown
 
 [![pypi](https://img.shields.io/pypi/v/oda_data.svg)](https://pypi.org/project/oda_data/)
 [![python](https://img.shields.io/pypi/pyversions/oda_data.svg)](https://pypi.org/project/oda_data/)
+[![codecov](https://codecov.io/gh/ONEcampaign/oda_data_package/branch/main/graph/badge.svg?token=G8N8BWWPL8)](https://codecov.io/gh/ONEcampaign/oda_data_package)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 
 # The ODA Data Package
 This is a Python package designed for accessing, processing, and analyzing Official Development Assistance (ODA) data from OECD DAC. With an intuitive API, it simplifies common tasks like retrieving ODA indicators, converting currencies, filtering data, and handling bulk downloads.
 
-**Note: This is the new version of the package (V2). This release includes many breaking changes and previous workflows
-will not work. The previous 1.5.x version remains available on PyPI and we will continue to support it at least until
-August 2025.**
+**Note: You are currently looking at a pre-release version of the package. We are aiming for a stable release mid-April 2025. The documentation is still incomplete, and features and APIs may change before release.**
 
 Interacting with the DAC databases can be a complex task. There are many databases, tables, and web interfaces which
 can be used to get the data you need. This means that getting the right ODA data can require expert knowledge not only
@@ -59,7 +58,7 @@ The package is compatible with Python 3.10 and above.
 
 ## Basic usage
 
-Most users can get the data they need by using the `OECDClient` class.
+Most users can get the data they need by using the `Indicators` class.
 
 An object of this class can handle:
 - getting data for specific indicators (one or more)
@@ -71,15 +70,14 @@ data for all providers, for all recipients (if applicable), as net disbursements
 using the OECD data-explorer API.
 
 In the example below, we get all data for Total ODA (net disbursements), for 2012 to 2022.
-
 ```python
-from oda_data import OECDClient, set_data_path
+from oda_data import Indicators, set_data_path
 
-# set the path to the folder where the raw data should be cached
+# set the path to the folder where the data should be stored
 set_data_path("path/to/data/folder")
 
 # create object, specifying key details of the desired output
-indicator = OECDClient(years=range(2012, 2023))
+indicator =  Indicators( years=range(2012,2023))
 
 # Get the desired indicator
 data = indicator.get_indicators("DAC1.10.1010")
@@ -88,100 +86,100 @@ data = indicator.get_indicators("DAC1.10.1010")
 Here's an example to get Bilateral ODA for France and the US, for 2020 and 2021. The data will be in grant equivalents, in constant 2019 Euros.
 
 ```python
-from oda_data import OECDClient, set_data_path
+from oda_data import Indicators, set_data_path
 
 # set the path to the folder where the data should be stored
 set_data_path("path/to/data/folder")
 
 # create object, specifying key details of the desired output
-client = OECDClient(
-    years=[2020, 2021],
-    providers=[4, 302],  # Example provider codes
-    measure="grant_equivalent",  # Options: "commitment", "grant_equivalent", etc.
-    currency="EUR",  # Default is USD; others include EUR, GBP, CAD, LCU
-    base_year=2019,  # Adjust data to constant prices of the specified year
+indicator =  Indicators(
+  years=[2020, 2021],
+  providers=[4, 302],          # Example provider codes
+  measure="grant_equivalent",   # Options: "commitment", "grant_equivalent", etc.
+  currency="EUR",               # Default is USD; others include EUR, GBP, CAD, LCU
+  base_year=2019,               # Adjust data to constant prices of the specified year
 )
 
 # Get the desired indicator
-data = client.get_indicators("DAC1.10.11015")
+data = indicator.get_indicators("DAC1.10.11015")
 ```
 
 If you intend to download many indicators, we recommend using the Bulk download file instead. The OECD data-explorer
 API has pretty low usage limits, and you could get a temporary block if you make too many repeated calls. While downloading a particular bulk file may time a few minutes, subsequently getting indicator data is much faster.
 
 ```python
-from oda_data import OECDClient, set_data_path
+from oda_data import Indicators, set_data_path
 
 # set the path to the folder where the data should be stored
 set_data_path("path/to/data/folder")
 
 # define a list of indicators to get
-research_indicators = ["DAC1.10.1100", "DAC1.10.1410", "DAC1.10.2102", "DAC1.10.1500"]
+research_indicators = ["DAC1.10.1100","DAC1.10.1410","DAC1.10.2102","DAC1.10.1500"]
 
 # create object, specifying key details of the desired output
-client = OECDClient(
-    years=[2019, 2020, 2021],
-    measure="net_disbursement",  # Options: "commitment", "grant_equivalent", etc.
-    currency="LCU",  # To get the data in providers' own currencies
-    use_bulk_download=True
+indicator =  Indicators(
+  years=[2019, 2020, 2021],
+  measure="net_disbursement",   # Options: "commitment", "grant_equivalent", etc.
+  currency="LCU", # To get the data in providers' own currencies
+  use_bulk_download=True
 )
 
 # Get the desired indicators
-data = client.get_indicators(research_indicators)
+data = indicator.get_indicators(research_indicators)
 ```
 
-### OECDClient
+### Indicators
 
 Over three thousand indicators are currently supported. They are mostly produced by filtering (and sometimes aggregating) data from the different DAC Tables and databases.
 
 You can get a dictionary with all supported indicators, with their code, name, description and source by using the `.available_indicators()` method:
 
 ```python
-from oda_data import OECDClient
+from oda_data import Indicators
 
-all_indicators = OECDClient.available_indicators()
+all_indicators = Indicators.available_indicators()
 ```
 
 Alternatively, you can export the indicators to a CSV by using the `.export_available_indicators()` method.
 
 ```python
-from oda_data import OECDClient
+from oda_data import Indicators
 
-OECDClient.export_available_indicators(export_folder="path/to/folder/")
+Indicators.export_available_indicators(export_folder="path/to/folder/")
 ```
 
 ### Providers
 You can get a dictionary with all available providers, with their code and name, by using the `.available_providers()` method:
 
 ```python
-from oda_data import OECDClient
+from oda_data import Indicators
 
-providers = OECDClient.available_providers()
+providers = Indicators.available_providers()
 ```
 
 ### Recipients
 You can get a dictionary with all available recipients, with their code and name, by using the `.available_recipients()` method:
 
 ```python
-from oda_data import OECDClient
+from oda_data import Indicators
 
-recipients = OECDClient.available_recipients()
+recipients = Indicators.available_recipients()
 ```
 
 ### Currencies
 You can get a dictionary with all available currencies, with their code and name, by using the `.available_currencies()` method:
 
 ```python
-from oda_data import OECDClient
+from oda_data import Indicators
 
-currencies = OECDClient.available_currencies()
+currencies = Indicators.available_currencies()
 ```
 
 ## Accessing the data
 For more advanced users, you can use this package to get and work with different tables and databases from the OECD DAC.
 
 ### DAC 1
-The `DAC1Data` class can retrieve and return DAC 1 data.
+The `Dac1Data` class can retrieve and return DAC 1 data.
 
 You can optionally specify:
 - years: to filter the data for specific years
@@ -195,13 +193,13 @@ After instantiating the object, you can call:
 - `read`: to read data as stored in the specified folder. If the data is not available, it will be downloaded.
 
 ```python
-from oda_data import DAC1Data, set_data_path
+from oda_data import Dac1Data, set_data_path
 
 # set the path to the folder where the data should be stored
 set_data_path("path/to/data/folder")
 
 # instantiate a DAC1Data object
-dac1 = DAC1Data()
+dac1 = Dac1Data()
 
 # Perform a bulk download
 dac1.download(bulk=True)
@@ -214,14 +212,15 @@ Use cases can be quite elaborate. For example, here we will download data for Fr
 
 When reading, we will also filter to get only current prices, and to only read a few columns.
 
+
 ```python
-from oda_data import DAC1Data, set_data_path
+from oda_data import Dac1Data, set_data_path
 
 # set the path to the folder where the data should be stored
 set_data_path("path/to/data/folder")
 
 # instantiate a DAC1Data object
-dac1 = DAC1Data(years=2022, providers=4, indicators=1010)
+dac1 = Dac1Data(years=2022, providers=4, indicators=1010)
 
 # Get the data by calling on read. It will be downloaded since it isn't already available.
 data = dac1.read(
@@ -232,7 +231,7 @@ data = dac1.read(
 
 
 ### DAC 2A
-The `DAC2AData` class can retrieve and return DAC2a data.
+The `Dac2aData` class can retrieve and return DAC2a data.
 
 You can optionally specify:
 - years: to filter the data for specific years
@@ -247,13 +246,13 @@ After instantiating the object, you can call:
 - `read`: to read data as stored in the specified folder. If the data is not available, it will be downloaded.
 
 ```python
-from oda_data import DAC2AData, set_data_path
+from oda_data import Dac2aData, set_data_path
 
 # set the path to the folder where the data should be stored
 set_data_path("path/to/data/folder")
 
 # instantiate a DAC1Data object
-dac2a = DAC2AData()
+dac2a = Dac2aData()
 
 # Perform a bulk download
 dac2a.download(bulk=True)
@@ -267,14 +266,15 @@ multilateral aid.
 
 When reading, we will also filter to get only current prices, and to only read a few columns.
 
+
 ```python
-from oda_data import DAC2AData, set_data_path
+from oda_data import Dac2aData, set_data_path
 
 # set the path to the folder where the data should be stored
 set_data_path("path/to/data/folder")
 
 # instantiate a DAC2aData object
-dac2a = DAC2AData(years=2022, providers=4, recipients=283, indicators=106)
+dac2a = Dac2aData(years=2022, providers=4, recipients=283, indicators=106)
 
 # Get the data by calling on read. It will be downloaded since it isn't already available.
 data = dac2a.read(
@@ -292,7 +292,7 @@ data = dac2a.read(
 ```
 
 ### CRS
-The `CRSData` class can retrieve and return CRS data.
+The `CrsData` class can retrieve and return CRS data.
 
 You can optionally specify:
 - years: to filter the data for specific years
@@ -305,21 +305,22 @@ You can refer to the examples above for DAC1 and DAC2a to understand the usage o
 **Note**: given the speed and rate-limiting of the dac-explorer APIs, it's recommended to always use the 
 bulk option when using the CRS class.
 
+
 ```python
-from oda_data import CRSData, set_data_path
+from oda_data import CrsData, set_data_path
 
 # set the path to the folder where the data should be stored
 set_data_path("path/to/data/folder")
 
-# instantiate a CRSData object
-crs = CRSData(years=range(2010, 2024))
+# instantiate a CrsData object
+crs = CrsData(years=range(2010,2024))
 
 # Get the data by calling on read. It will be downloaded since it isn't already available.
 data = crs.read(using_bulk_download=True)
 ```
 
 
-### MultiSystem
+### CRS
 The `MultiSystemData` class can retrieve and return Providers Total Use of the Multilateral System data.
 
 You can optionally specify:

{oda_data-2.0.0 → oda_data-2.0.0b2}/README.md

@@ -1,13 +1,12 @@
 [![pypi](https://img.shields.io/pypi/v/oda_data.svg)](https://pypi.org/project/oda_data/)
 [![python](https://img.shields.io/pypi/pyversions/oda_data.svg)](https://pypi.org/project/oda_data/)
+[![codecov](https://codecov.io/gh/ONEcampaign/oda_data_package/branch/main/graph/badge.svg?token=G8N8BWWPL8)](https://codecov.io/gh/ONEcampaign/oda_data_package)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 
 # The ODA Data Package
 This is a Python package designed for accessing, processing, and analyzing Official Development Assistance (ODA) data from OECD DAC. With an intuitive API, it simplifies common tasks like retrieving ODA indicators, converting currencies, filtering data, and handling bulk downloads.
 
-**Note: This is the new version of the package (V2). This release includes many breaking changes and previous workflows
-will not work. The previous 1.5.x version remains available on PyPI and we will continue to support it at least until
-August 2025.**
+**Note: You are currently looking at a pre-release version of the package. We are aiming for a stable release mid-April 2025. The documentation is still incomplete, and features and APIs may change before release.**
 
 Interacting with the DAC databases can be a complex task. There are many databases, tables, and web interfaces which
 can be used to get the data you need. This means that getting the right ODA data can require expert knowledge not only
@@ -32,7 +31,7 @@ The package is compatible with Python 3.10 and above.
 
 ## Basic usage
 
-Most users can get the data they need by using the `OECDClient` class.
+Most users can get the data they need by using the `Indicators` class.
 
 An object of this class can handle:
 - getting data for specific indicators (one or more)
@@ -44,15 +43,14 @@ data for all providers, for all recipients (if applicable), as net disbursements
 using the OECD data-explorer API.
 
 In the example below, we get all data for Total ODA (net disbursements), for 2012 to 2022.
-
 ```python
-from oda_data import OECDClient, set_data_path
+from oda_data import Indicators, set_data_path
 
-# set the path to the folder where the raw data should be cached
+# set the path to the folder where the data should be stored
 set_data_path("path/to/data/folder")
 
 # create object, specifying key details of the desired output
-indicator = OECDClient(years=range(2012, 2023))
+indicator =  Indicators( years=range(2012,2023))
 
 # Get the desired indicator
 data = indicator.get_indicators("DAC1.10.1010")
@@ -61,100 +59,100 @@ data = indicator.get_indicators("DAC1.10.1010")
 Here's an example to get Bilateral ODA for France and the US, for 2020 and 2021. The data will be in grant equivalents, in constant 2019 Euros.
 
 ```python
-from oda_data import OECDClient, set_data_path
+from oda_data import Indicators, set_data_path
 
 # set the path to the folder where the data should be stored
 set_data_path("path/to/data/folder")
 
 # create object, specifying key details of the desired output
-client = OECDClient(
-    years=[2020, 2021],
-    providers=[4, 302],  # Example provider codes
-    measure="grant_equivalent",  # Options: "commitment", "grant_equivalent", etc.
-    currency="EUR",  # Default is USD; others include EUR, GBP, CAD, LCU
-    base_year=2019,  # Adjust data to constant prices of the specified year
+indicator =  Indicators(
+  years=[2020, 2021],
+  providers=[4, 302],          # Example provider codes
+  measure="grant_equivalent",   # Options: "commitment", "grant_equivalent", etc.
+  currency="EUR",               # Default is USD; others include EUR, GBP, CAD, LCU
+  base_year=2019,               # Adjust data to constant prices of the specified year
 )
 
 # Get the desired indicator
-data = client.get_indicators("DAC1.10.11015")
+data = indicator.get_indicators("DAC1.10.11015")
 ```
 
 If you intend to download many indicators, we recommend using the Bulk download file instead. The OECD data-explorer
 API has pretty low usage limits, and you could get a temporary block if you make too many repeated calls. While downloading a particular bulk file may time a few minutes, subsequently getting indicator data is much faster.
 
 ```python
-from oda_data import OECDClient, set_data_path
+from oda_data import Indicators, set_data_path
 
 # set the path to the folder where the data should be stored
 set_data_path("path/to/data/folder")
 
 # define a list of indicators to get
-research_indicators = ["DAC1.10.1100", "DAC1.10.1410", "DAC1.10.2102", "DAC1.10.1500"]
+research_indicators = ["DAC1.10.1100","DAC1.10.1410","DAC1.10.2102","DAC1.10.1500"]
 
 # create object, specifying key details of the desired output
-client = OECDClient(
-    years=[2019, 2020, 2021],
-    measure="net_disbursement",  # Options: "commitment", "grant_equivalent", etc.
-    currency="LCU",  # To get the data in providers' own currencies
-    use_bulk_download=True
+indicator =  Indicators(
+  years=[2019, 2020, 2021],
+  measure="net_disbursement",   # Options: "commitment", "grant_equivalent", etc.
+  currency="LCU", # To get the data in providers' own currencies
+  use_bulk_download=True
 )
 
 # Get the desired indicators
-data = client.get_indicators(research_indicators)
+data = indicator.get_indicators(research_indicators)
 ```
 
-### OECDClient
+### Indicators
 
 Over three thousand indicators are currently supported. They are mostly produced by filtering (and sometimes aggregating) data from the different DAC Tables and databases.
 
 You can get a dictionary with all supported indicators, with their code, name, description and source by using the `.available_indicators()` method:
 
 ```python
-from oda_data import OECDClient
+from oda_data import Indicators
 
-all_indicators = OECDClient.available_indicators()
+all_indicators = Indicators.available_indicators()
 ```
 
 Alternatively, you can export the indicators to a CSV by using the `.export_available_indicators()` method.
 
 ```python
-from oda_data import OECDClient
+from oda_data import Indicators
 
-OECDClient.export_available_indicators(export_folder="path/to/folder/")
+Indicators.export_available_indicators(export_folder="path/to/folder/")
 ```
 
 ### Providers
 You can get a dictionary with all available providers, with their code and name, by using the `.available_providers()` method:
 
 ```python
-from oda_data import OECDClient
+from oda_data import Indicators
 
-providers = OECDClient.available_providers()
+providers = Indicators.available_providers()
 ```
 
 ### Recipients
 You can get a dictionary with all available recipients, with their code and name, by using the `.available_recipients()` method:
 
 ```python
-from oda_data import OECDClient
+from oda_data import Indicators
 
-recipients = OECDClient.available_recipients()
+recipients = Indicators.available_recipients()
 ```
 
 ### Currencies
 You can get a dictionary with all available currencies, with their code and name, by using the `.available_currencies()` method:
 
 ```python
-from oda_data import OECDClient
+from oda_data import Indicators
 
-currencies = OECDClient.available_currencies()
+currencies = Indicators.available_currencies()
 ```
 
 ## Accessing the data
 For more advanced users, you can use this package to get and work with different tables and databases from the OECD DAC.
 
 ### DAC 1
-The `DAC1Data` class can retrieve and return DAC 1 data.
+The `Dac1Data` class can retrieve and return DAC 1 data.
 
 You can optionally specify:
 - years: to filter the data for specific years
@@ -168,13 +166,13 @@ After instantiating the object, you can call:
 - `read`: to read data as stored in the specified folder. If the data is not available, it will be downloaded.
 
 ```python
-from oda_data import DAC1Data, set_data_path
+from oda_data import Dac1Data, set_data_path
 
 # set the path to the folder where the data should be stored
 set_data_path("path/to/data/folder")
 
 # instantiate a DAC1Data object
-dac1 = DAC1Data()
+dac1 = Dac1Data()
 
 # Perform a bulk download
 dac1.download(bulk=True)
@@ -187,14 +185,15 @@ Use cases can be quite elaborate. For example, here we will download data for Fr
 
 When reading, we will also filter to get only current prices, and to only read a few columns.
 
+
 ```python
-from oda_data import DAC1Data, set_data_path
+from oda_data import Dac1Data, set_data_path
 
 # set the path to the folder where the data should be stored
 set_data_path("path/to/data/folder")
 
 # instantiate a DAC1Data object
-dac1 = DAC1Data(years=2022, providers=4, indicators=1010)
+dac1 = Dac1Data(years=2022, providers=4, indicators=1010)
 
 # Get the data by calling on read. It will be downloaded since it isn't already available.
 data = dac1.read(
@@ -205,7 +204,7 @@ data = dac1.read(
 
 
 ### DAC 2A
-The `DAC2AData` class can retrieve and return DAC2a data.
+The `Dac2aData` class can retrieve and return DAC2a data.
 
 You can optionally specify:
 - years: to filter the data for specific years
@@ -220,13 +219,13 @@ After instantiating the object, you can call:
 - `read`: to read data as stored in the specified folder. If the data is not available, it will be downloaded.
 
 ```python
-from oda_data import DAC2AData, set_data_path
+from oda_data import Dac2aData, set_data_path
 
 # set the path to the folder where the data should be stored
 set_data_path("path/to/data/folder")
 
 # instantiate a DAC1Data object
-dac2a = DAC2AData()
+dac2a = Dac2aData()
 
 # Perform a bulk download
 dac2a.download(bulk=True)
@@ -240,14 +239,15 @@ multilateral aid.
 
 When reading, we will also filter to get only current prices, and to only read a few columns.
 
+
 ```python
-from oda_data import DAC2AData, set_data_path
+from oda_data import Dac2aData, set_data_path
 
 # set the path to the folder where the data should be stored
 set_data_path("path/to/data/folder")
 
 # instantiate a DAC2aData object
-dac2a = DAC2AData(years=2022, providers=4, recipients=283, indicators=106)
+dac2a = Dac2aData(years=2022, providers=4, recipients=283, indicators=106)
 
 # Get the data by calling on read. It will be downloaded since it isn't already available.
 data = dac2a.read(
@@ -265,7 +265,7 @@ data = dac2a.read(
 ```
 
 ### CRS
-The `CRSData` class can retrieve and return CRS data.
+The `CrsData` class can retrieve and return CRS data.
 
 You can optionally specify:
 - years: to filter the data for specific years
@@ -278,21 +278,22 @@ You can refer to the examples above for DAC1 and DAC2a to understand the usage o
 **Note**: given the speed and rate-limiting of the dac-explorer APIs, it's recommended to always use the 
 bulk option when using the CRS class.
 
+
 ```python
-from oda_data import CRSData, set_data_path
+from oda_data import CrsData, set_data_path
 
 # set the path to the folder where the data should be stored
 set_data_path("path/to/data/folder")
 
-# instantiate a CRSData object
-crs = CRSData(years=range(2010, 2024))
+# instantiate a CrsData object
+crs = CrsData(years=range(2010,2024))
 
 # Get the data by calling on read. It will be downloaded since it isn't already available.
 data = crs.read(using_bulk_download=True)
 ```
 
 
-### MultiSystem
+### CRS
 The `MultiSystemData` class can retrieve and return Providers Total Use of the Multilateral System data.
 
 You can optionally specify:

oda_data-2.0.0b2/oda_data/__init__.py

@@ -0,0 +1,37 @@
+from importlib.metadata import version
+
+__version__ = version("oda_data")
+
+from oda_data import tools
+from oda_data.api.main import Indicators
+from oda_data.api.sources import Dac1Data, Dac2aData, MultiSystemData, CrsData
+from oda_data.tools.compatibility import ODAData
+from oda_data.tools.groupings import donor_groupings, recipient_groupings
+from oda_data.tools.sector_lists import add_sectors, add_broad_sectors
+
+
+def set_data_path(path):
+    from pathlib import Path
+    from oda_data.config import OdaPATHS
+    from pydeflate import set_pydeflate_path
+
+    """Set the path to the data folder."""
+    global OdaPATHS
+
+    OdaPATHS.raw_data = Path(path).resolve()
+    set_pydeflate_path(OdaPATHS.raw_data)
+
+
+__all__ = [
+    "Indicators",
+    "Dac1Data",
+    "Dac2aData",
+    "MultiSystemData",
+    "CrsData",
+    "donor_groupings",
+    "recipient_groupings",
+    "add_sectors",
+    "add_broad_sectors",
+    "set_data_path",
+    "ODAData"
+]