postal-analytics 0.1.0
Sales report generation library for postal service applications
Requires Python: >=3.8
Keywords: postal, analytics, sales, reports, dynamodb

# 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