itinerizer 0.5.4

A comprehensive travel itinerary management system with JSON storage

Itinerizer

A comprehensive travel itinerary management system with JSON storage, REST API, and web interface.

Features

• Complete Itinerary Management: Create, update, and manage complex travel itineraries
• Multiple Segment Types: Flights, hotels, meetings, activities, transfers, and custom segments
• JSON Storage: Simple, file-based storage with automatic backups
• REST API: Optional FastAPI server for building web applications
• Web Interface: Optional Flask-based web UI with responsive design
• Type Safety: Full type hints with Pydantic validation
• Thread-Safe: Concurrent access with file locking
• Extensible: Easy to extend with custom segment types and storage backends

Installation

Quick Start

pip install itinerizer

For detailed installation instructions, see the Installation Guide.

Development Setup

git clone https://github.com/bobmatnyc/itinerizer.git
cd itinerizer
pip install -e .[dev]

Quick Start

Basic Usage

from datetime import date, datetime
from itinerizer import ItineraryManager, Traveler, TravelerType

# Create manager
manager = ItineraryManager()

# Create a traveler
traveler = Traveler(
    type=TravelerType.ADULT,
    first_name="Alice",
    last_name="Smith",
    email="[e-mail]"
)

# Create an itinerary
itinerary = manager.create_itinerary(
    title="Tokyo Business Trip",
    start_date=date(2025, 3, 15),
    end_date=date(2025, 3, 22),
    travelers=[traveler],
    trip_type="BUSINESS"
)

print(f"Created itinerary: {itinerary.id}")

Adding Segments

from itinerizer import FlightSegment, HotelSegment, Location, Company, Money
from decimal import Decimal

# Add a flight
flight = FlightSegment(
    flight_number="UA837",
    airline=Company(name="United Airlines", code="UA"),
    origin=Location(name="San Francisco", code="SFO"),
    destination=Location(name="Tokyo Narita", code="NRT"),
    departure_datetime=datetime(2025, 3, 15, 11, 30),
    arrival_datetime=datetime(2025, 3, 16, 15, 20),
    traveler_ids=[traveler.id],
    cabin="BUSINESS",
    total_price=Money(amount=Decimal("4500.00"), currency="USD")
)

# Add to itinerary
manager.add_segment(itinerary.id, flight)

# Add a hotel
hotel = HotelSegment(
    property=Company(name="Conrad Tokyo"),
    location=Location(name="Conrad Tokyo", city="Tokyo"),
    check_in_date=date(2025, 3, 16),
    check_out_date=date(2025, 3, 21),
    traveler_ids=[traveler.id],
    room_type="King Executive Room",
    total_price=Money(amount=Decimal("2500.00"), currency="USD")
)

manager.add_segment(itinerary.id, hotel)

Retrieving and Searching

# Get a specific itinerary
itinerary = manager.get_itinerary(itinerary_id)

# Search itineraries
business_trips = manager.search_itineraries(
    trip_type="BUSINESS",
    status="CONFIRMED"
)

# List all itineraries
all_ids = manager.list_itineraries()

REST API Server

Run the FastAPI server:

from itinerizer.server import create_app
import uvicorn

app = create_app()
uvicorn.run(app, host="0.0.0.0", port=8000)

Or from the command line:

uvicorn itinerizer.server.app:app --reload

API Endpoints

• GET /health - Health check
• GET /api/itineraries - List all itineraries
• GET /api/itineraries/{id} - Get specific itinerary
• POST /api/itineraries - Create new itinerary
• PUT /api/itineraries/{id} - Update itinerary
• DELETE /api/itineraries/{id} - Delete itinerary
• POST /api/itineraries/{id}/segments - Add segment
• DELETE /api/itineraries/{id}/segments/{segment_id} - Remove segment

API documentation available at http://localhost:8000/api/docs

Web Interface

The web interface provides a user-friendly way to manage itineraries:

cd web_ui
python app.py

Access at http://localhost:5000

Features:

• Dashboard with itinerary overview
• Create and edit itineraries
• Manage travelers and segments
• Natural language itinerary creation (with NLP addon)
• Analytics and reporting

Data Models

Itinerary

The main container for a trip:

from itinerizer import Itinerary, ItineraryStatus

itinerary = Itinerary(
    title="European Vacation",
    status=ItineraryStatus.PLANNED,
    start_date=date(2025, 6, 1),
    end_date=date(2025, 6, 15),
    travelers=[...],
    segments=[...],
    trip_type="LEISURE"
)

Segments

Different types of travel segments:

• FlightSegment: Air travel with airline, flight number, airports
• HotelSegment: Accommodation with check-in/out dates
• MeetingSegment: Business meetings with agenda and attendees
• ActivitySegment: Tours, events, and activities
• TransferSegment: Ground transportation
• CustomSegment: Flexible segment for other needs

Validation

Built-in validation ensures data integrity:

from itinerizer import ItineraryValidator

validator = ItineraryValidator()
result = validator.validate(itinerary)

if not result.is_valid:
    for error in result.errors:
        print(f"Error: {error.message}")

Storage

JSON Storage (Default)

Itineraries are stored as JSON files:

data/
  itineraries/
    {uuid}.json
  backups/
    {uuid}_{timestamp}.json

Custom Storage Path

manager = ItineraryManager(storage_path="/path/to/storage")

Thread Safety

The storage system uses file locking for safe concurrent access:

from itinerizer.storage import JSONItineraryStore

store = JSONItineraryStore()
with store.singleton.edit_lock(itinerary_id):
    # Exclusive write access
    store.save(itinerary)

Advanced Features

Custom Segment Types

Extend the base segment for specialized needs:

from itinerizer import BaseSegment
from typing import Literal

class CruiseSegment(BaseSegment):
    type: Literal["CRUISE"] = "CRUISE"
    ship_name: str
    cabin_number: str
    departure_port: Location
    arrival_port: Location
    # ... additional fields

Preferences and Metadata

Store additional information:

from itinerizer import TravelPreferences

preferences = TravelPreferences(
    seat_preference="AISLE",
    meal_preference="Vegetarian",
    hotel_chain_preference=["Hilton", "Marriott"]
)

itinerary.preferences = preferences
itinerary.metadata = {
    "booking_source": "Corporate Portal",
    "approval_code": "MGR-2025-001"
}

Development

Setting Up Development Environment

# Clone the repository
git clone https://github.com/bobmatnyc/itinerizer.git
cd itinerizer

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=itinerizer

Running Tests

# Unit tests
pytest tests/unit/

# Integration tests
pytest tests/integration/

# All tests with coverage
pytest --cov=itinerizer --cov-report=html

Code Quality

# Format code
black src/ tests/

# Lint
flake8 src/ tests/

# Type checking
mypy src/

Docker Support

Run with Docker:

# Build image
docker build -t itinerizer .

# Run container
docker run -p 8000:8000 itinerizer

# With docker-compose
docker-compose up

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Workflow

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

Documentation

• Full Documentation
• API Reference
• Examples
• Changelog

Support

• Issue Tracker
• Discussions
• Email: [e-mail]

License

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

Acknowledgments

• Built with Pydantic for data validation
• REST API powered by FastAPI
• Web interface built with Flask
• JSON operations optimized with orjson (optional)

Citation

If you use Itinerizer in your research or project, please cite:

@software{itinerizer,
  title = {Itinerizer: A Comprehensive Travel Itinerary Management System},
  author = {Itinerizer Contributors},
  year = {2025},
  url = {https://github.com/bobmatnyc/itinerizer}
}

📚 Documentation

Comprehensive documentation is available in the docs/ directory:

• Installation Guide - Detailed setup instructions
• API Documentation - Web UI and API reference
• Development Guide - Contributing and development setup
• Testing Documentation - Testing strategy and reports
• Deployment Guide - Publishing and deployment

🛠️ Project Structure

itinerizer/
├── src/itinerizer/          # Core library code
├── tests/                   # Test suite
├── scripts/                 # Utility scripts
├── docs/                    # Documentation
├── examples/                # Usage examples
├── web_ui/                  # Web interface
└── docker/                  # Docker configuration

---

Made with ❤️ by the Itinerizer Contributors