postal-analytics 0.1.0

Sales report generation library for postal service applications

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

pip install postal-analytics

Quick Start

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

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

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

Generate Report for Specific Location

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

{
    '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:

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 - [e-mail]

• 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