itinerizer 0.5.5

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

Using the Development Script (Recommended)

If you're working within the travel itinerary management system repository, use the provided development script:

# From the repository root
./itinerizer-dev  # Sets up venv and starts interactive shell
./itinerizer-dev itinerizer --version  # Run specific commands

Manual Setup

git clone https://github.com/bobmatnyc/itinerizer.git
cd itinerizer
python3 -m venv venv
source venv/bin/activate
pip install -e .[dev]

Quick Start

Local Configuration

Itinerizer automatically creates a .itinerizer directory in your current working directory for configuration and data storage, keeping client data separate from your codebase:

# Initialize local configuration
itinerizer config init

# View current configuration
itinerizer config show

# List itineraries (stored in .itinerizer/itineraries/)
itinerizer list

For detailed configuration options, see the Local Configuration Guide.

Basic Usage

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

# Create manager (uses local .itinerizer config by default)
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