Metadata-Version: 2.4
Name: postal-analytics
Version: 0.1.0
Summary: Sales report generation library for postal service applications
Home-page: https://github.com/mswamych2/CPP_PostalService/tree/main/postal-service/postal_analytics
Author: Mahadeva Chandra
Author-email: x24272507@student.ncirl.ie
Project-URL: Bug Reports, https://github.com/mswamych2/CPP_PostalService/tree/main/postal-service/postal_analytics/issues
Project-URL: Source, https://github.com/mswamych2/CPP_PostalService/tree/main/postal-service/postal_analytics
Keywords: postal,analytics,sales,reports,dynamodb
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: boto3>=1.29.0
Requires-Dist: reportlab>=4.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Postal Analytics Library

Sales report generation library.
# postal-analytics

Sales report generation library for postal service applications with geo-location based analytics.

## Features

- Generate comprehensive sales reports from DynamoDB booking data
- Location-based revenue analysis
- Shipping type and parcel size analytics
- Order status distribution
- PDF report generation
- Easy integration with AWS services

## Installation

```bash
pip install postal-analytics
```

## Quick Start

```python
from postal_analytics import SalesReportGenerator, DataFetcher

# Fetch data from DynamoDB
fetcher = DataFetcher(
    region_name='us-east-1',
    table_name='PostalServiceBookings'
)
bookings = fetcher.fetch_all_bookings()

# Generate report
generator = SalesReportGenerator()
report_data = generator.generate_report_data(bookings)

# Print summary
print(generator.generate_summary())

# Generate PDF
pdf_content = generator.generate_pdf_report()

# Save PDF
with open('sales_report.pdf', 'wb') as f:
    f.write(pdf_content)
```

## Usage Examples

### Get Top Locations by Revenue

```python
generator = SalesReportGenerator()
report_data = generator.generate_report_data(bookings)

top_locations = generator.get_top_locations(n=10)
for location, data in top_locations:
    print(f"{location}: {data['count']} orders, ${data['revenue']:.2f}")
```

### Fetch Recent Bookings

```python
fetcher = DataFetcher()
recent_bookings = fetcher.fetch_recent_bookings(days=30)
```

### Generate Report for Specific Location

```python
fetcher = DataFetcher()
location_bookings = fetcher.fetch_bookings_by_location('90001')

generator = SalesReportGenerator()
report_data = generator.generate_report_data(location_bookings)
```

## API Reference

### SalesReportGenerator

Main class for generating sales reports.

**Methods:**

- `generate_report_data(bookings)` - Generate report data from booking list
- `get_top_locations(n=10)` - Get top N locations by revenue
- `get_revenue_by_shipping_type()` - Get shipping type revenue breakdown
- `get_status_distribution()` - Get order status distribution
- `generate_summary()` - Generate text summary of report
- `generate_pdf_report(report_data)` - Generate PDF report

### DataFetcher

Class for fetching data from DynamoDB.

**Methods:**

- `fetch_all_bookings()` - Fetch all booking records
- `fetch_bookings_by_date_range(start_date, end_date)` - Fetch bookings in date range
- `fetch_bookings_by_location(pincode)` - Fetch bookings for specific location
- `fetch_bookings_by_status(status)` - Fetch bookings with specific status
- `fetch_recent_bookings(days=30)` - Fetch bookings from last N days

## Report Data Structure

```python
{
    'report_date': '2025-01-01T00:00:00',
    'report_timestamp': '2025-01-01 00:00:00 UTC',
    'total_bookings': 150,
    'total_revenue': 5000.00,
    'average_order_value': 33.33,
    'by_location': {
        '90001': {'count': 20, 'revenue': 800.00, 'bookings': [...]},
        ...
    },
    'by_status': {
        'delivered': {'count': 100, 'revenue': 3500.00},
        ...
    },
    'by_shipping_type': {
        'local': {'count': 50, 'revenue': 500.00},
        'domestic': {'count': 80, 'revenue': 3200.00},
        'international': {'count': 20, 'revenue': 1300.00}
    },
    'by_parcel_size': {
        'envelope': {'count': 60, 'revenue': 1200.00},
        ...
    }
}
```

## Requirements

- Python >= 3.8
- boto3 >= 1.29.0
- reportlab >= 4.0.0

## AWS Configuration

Ensure your AWS credentials are configured:

```bash
export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key
export AWS_REGION=us-east-1
```

Or use AWS credentials file (`~/.aws/credentials`).

## License

MIT License

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Support

For issues and questions, please open an issue on GitHub.

## Author

**Mahadeva Chandra** - x24272507@student.ncirl.ie
- Student ID: x24272507
- Programme: MSc in Cloud Computing
- Institution: National College of Ireland

## Changelog

### 0.1.0 (2025-01-01)
- Initial release
- Basic sales report generation
- PDF export functionality
- DynamoDB integration
