agritechtz-pycli 1.0.5

A client library for fetching and processing crop price data in Tanzania.

Crop Price Client

This module implements a client for fetching and processing crop price data from a REST API. It allows filtering by crop types, regions, districts, dates, and ordering. The data is fetched as a CSV, converted into a pandas DataFrame, and preprocessed for analysis.

Table of Contents

1. Features
2. Requirements
3. Installation
4. Usage
5. Classes
6. Error Handling
7. Logging
8. Testing
9. License
10. Contributing

Features

• Flexible Filtering: Filter crop price data by crops, regions, districts, date range, and ordering.
• Chained Configuration: Use a chainable builder pattern for constructing DataFrames with specific parameters.
• Progress Tracking: Displays a download progress bar.
• Data Cleanup: Preprocesses and formats data for consistency.

Requirements

• Python 3.11+
• Required Packages:
  • pandas
  • requests
  • tqdm

Installation

To install this library, use pip:

pip install agritechtz-pycli

Or, if you’re installing from source:

git https://github.com/cloudnuttz/agritechtz-pycli.git
cd agritechtz-pycli
pip install .

Usage

Initialize the Builder:

The CropPriceDataFrameBuilder class allows you to configure and retrieve crop price data as a pandas DataFrame. Here’s an example of how to use it:

from agritechtz_cli import CropPriceDataFrameBuilder

df = CropPriceDataFrameBuilder.of("Maize", "Rice") \
    .in_regions("Dar es saalam/Kinondoni", "Mbeya/Sido") \
    .from_date("2023-01-01") \
    .to_date("2023-12-31") \
    .order_by("-ts") # Order data by date in descending order\
    .build()

print(df.head())

Classes and Methods

CropPriceFilterParams

A data class for setting up filter parameters.

Parameters include:

Attribute	Type	Description
crops	List[str]	A list of crop names
regions	List[str]	A list of regions
districts	List[str]	A list of districts
start_date	Union[date,str]	Specify start date (ISO8601 format) of our time series data
end_date	Union[date,str]	Specify end date (ISO8601 format) of our time series data
ordering	List[str]	Specify sort priority. + or - before the parameter name where +=ascending -=descending

CropPriceDataFrameBuilder

A builder class for constructing crop price DataFrames with chainable configuration methods.

Methods:

Method	Parameters	Return Type	Description
of	Comma separated list of crops e.g., "Maize","Rice"	An instance CropPriceDataFrameBuilder	Crops to retrieve from the API
in_regions	Comma separated list of regions	The current instance created by the of method	Specify regions to include in your API query
from_date	Date object or String representation of the date in ISO8601 format	The current instance created by the of method	Specify the starting date to include in your API query
end_date	Date object or String representation of the date in ISO8601 format	The current instance create by the of method	Specify the end date to include in your API query. If specified togehter with the start_date, they will create time horizon for your time series data.
ordering	Comma separated list of sort specifications. e.g., "+ts"	The current instance created by the of method.	Specify the order parameter to use in sorting. The sign before parameter indicates sorting direction +/asc, -/desc
build	N/A	DataFrame	Builds the dataframe using the data from the API you've specified in the parameters above.

Error Handling

The library raises informative errors in specific cases:

• Date Format Errors: Raises ValueError for invalid date formats.
• API Errors: Raises RuntimeError if network or request errors occur during data fetching.

Note: Since this is a public API, we employed rate limit techniques in order to safeguard against Denial of service (DoD) attacks. Therefore, once you exceeds 5 req/minute you'll be locked.

Logging

Logs messages at the CRITICAL level by default and outputs errors and warnings in case of invalid data or network issues.

Testing

Run tests by typing python -m unittest tests/test_crop_price_data_frame_builder.py

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Contributing

Contributions are welcome! To contribute:

• Fork the repository.
• Create a new branch (git checkout -b feature-branch).
• Make your changes.
• Commit your changes (git commit -m 'Add new feature').
• Push to the branch (git push origin feature-branch).
• Open a pull request.