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:

CropPriceDataFrameBuilder

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

Methods:

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.