# Itinerizer
[](https://pypi.org/project/itinerizer/)
[](https://pypi.org/project/itinerizer/)
[](https://github.com/yourusername/itinerizer/blob/main/LICENSE)
[](https://itinerizer.readthedocs.io/en/latest/?badge=latest)
[](https://github.com/yourusername/itinerizer/actions)
[](https://codecov.io/gh/yourusername/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
### Basic Installation
Install the core library:
```bash
pip install itinerizer
```
### With Optional Components
Install with the REST API server:
```bash
pip install itinerizer[server]
```
Install with the web interface:
```bash
pip install itinerizer[web]
```
Install with everything:
```bash
pip install itinerizer[all]
```
## Quick Start
### Basic Usage
```python
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="alice@example.com"
)
# 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
```python
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
```python
# 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:
```python
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:
```bash
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:
```bash
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:
```python
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:
```python
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
```python
manager = ItineraryManager(storage_path="/path/to/storage")
```
### Thread Safety
The storage system uses file locking for safe concurrent access:
```python
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:
```python
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:
```python
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
```bash
# Clone the repository
git clone https://github.com/yourusername/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
```bash
# Unit tests
pytest tests/unit/
# Integration tests
pytest tests/integration/
# All tests with coverage
pytest --cov=itinerizer --cov-report=html
```
### Code Quality
```bash
# Format code
black src/ tests/
# Lint
flake8 src/ tests/
# Type checking
mypy src/
```
## Docker Support
Run with Docker:
```bash
# 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](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](https://itinerizer.readthedocs.io)
- [API Reference](https://itinerizer.readthedocs.io/api)
- [Examples](https://github.com/yourusername/itinerizer/tree/main/examples)
- [Changelog](CHANGELOG.md)
## Support
- [Issue Tracker](https://github.com/yourusername/itinerizer/issues)
- [Discussions](https://github.com/yourusername/itinerizer/discussions)
- Email: contact@itinerizer.io
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Acknowledgments
- Built with [Pydantic](https://pydantic-docs.helpmanual.io/) for data validation
- REST API powered by [FastAPI](https://fastapi.tiangolo.com/)
- Web interface built with [Flask](https://flask.palletsprojects.com/)
- JSON operations optimized with [orjson](https://github.com/ijl/orjson) (optional)
## Citation
If you use Itinerizer in your research or project, please cite:
```bibtex
@software{itinerizer,
title = {Itinerizer: A Comprehensive Travel Itinerary Management System},
author = {Itinerizer Contributors},
year = {2025},
url = {https://github.com/yourusername/itinerizer}
}
```
---
Made with ❤️ by the Itinerizer Contributors
Raw data
{
"_id": null,
"home_page": null,
"name": "itinerizer",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Itinerizer Contributors <contact@itinerizer.io>",
"keywords": "travel, itinerary, trip, planning, booking, tourism, vacation, business-travel, json-storage",
"author": null,
"author_email": "Itinerizer Contributors <contact@itinerizer.io>",
"download_url": "https://files.pythonhosted.org/packages/66/f0/205933fdf51c61f315620365c231bc960d0537003a822b10ec97ee8d5d9a/itinerizer-0.5.2.tar.gz",
"platform": null,
"description": "# Itinerizer\n\n[](https://pypi.org/project/itinerizer/)\n[](https://pypi.org/project/itinerizer/)\n[](https://github.com/yourusername/itinerizer/blob/main/LICENSE)\n[](https://itinerizer.readthedocs.io/en/latest/?badge=latest)\n[](https://github.com/yourusername/itinerizer/actions)\n[](https://codecov.io/gh/yourusername/itinerizer)\n\nA comprehensive travel itinerary management system with JSON storage, REST API, and web interface.\n\n## Features\n\n- **Complete Itinerary Management**: Create, update, and manage complex travel itineraries\n- **Multiple Segment Types**: Flights, hotels, meetings, activities, transfers, and custom segments\n- **JSON Storage**: Simple, file-based storage with automatic backups\n- **REST API**: Optional FastAPI server for building web applications\n- **Web Interface**: Optional Flask-based web UI with responsive design\n- **Type Safety**: Full type hints with Pydantic validation\n- **Thread-Safe**: Concurrent access with file locking\n- **Extensible**: Easy to extend with custom segment types and storage backends\n\n## Installation\n\n### Basic Installation\n\nInstall the core library:\n\n```bash\npip install itinerizer\n```\n\n### With Optional Components\n\nInstall with the REST API server:\n\n```bash\npip install itinerizer[server]\n```\n\nInstall with the web interface:\n\n```bash\npip install itinerizer[web]\n```\n\nInstall with everything:\n\n```bash\npip install itinerizer[all]\n```\n\n## Quick Start\n\n### Basic Usage\n\n```python\nfrom datetime import date, datetime\nfrom itinerizer import ItineraryManager, Traveler, TravelerType\n\n# Create manager\nmanager = ItineraryManager()\n\n# Create a traveler\ntraveler = Traveler(\n type=TravelerType.ADULT,\n first_name=\"Alice\",\n last_name=\"Smith\",\n email=\"alice@example.com\"\n)\n\n# Create an itinerary\nitinerary = manager.create_itinerary(\n title=\"Tokyo Business Trip\",\n start_date=date(2025, 3, 15),\n end_date=date(2025, 3, 22),\n travelers=[traveler],\n trip_type=\"BUSINESS\"\n)\n\nprint(f\"Created itinerary: {itinerary.id}\")\n```\n\n### Adding Segments\n\n```python\nfrom itinerizer import FlightSegment, HotelSegment, Location, Company, Money\nfrom decimal import Decimal\n\n# Add a flight\nflight = FlightSegment(\n flight_number=\"UA837\",\n airline=Company(name=\"United Airlines\", code=\"UA\"),\n origin=Location(name=\"San Francisco\", code=\"SFO\"),\n destination=Location(name=\"Tokyo Narita\", code=\"NRT\"),\n departure_datetime=datetime(2025, 3, 15, 11, 30),\n arrival_datetime=datetime(2025, 3, 16, 15, 20),\n traveler_ids=[traveler.id],\n cabin=\"BUSINESS\",\n total_price=Money(amount=Decimal(\"4500.00\"), currency=\"USD\")\n)\n\n# Add to itinerary\nmanager.add_segment(itinerary.id, flight)\n\n# Add a hotel\nhotel = HotelSegment(\n property=Company(name=\"Conrad Tokyo\"),\n location=Location(name=\"Conrad Tokyo\", city=\"Tokyo\"),\n check_in_date=date(2025, 3, 16),\n check_out_date=date(2025, 3, 21),\n traveler_ids=[traveler.id],\n room_type=\"King Executive Room\",\n total_price=Money(amount=Decimal(\"2500.00\"), currency=\"USD\")\n)\n\nmanager.add_segment(itinerary.id, hotel)\n```\n\n### Retrieving and Searching\n\n```python\n# Get a specific itinerary\nitinerary = manager.get_itinerary(itinerary_id)\n\n# Search itineraries\nbusiness_trips = manager.search_itineraries(\n trip_type=\"BUSINESS\",\n status=\"CONFIRMED\"\n)\n\n# List all itineraries\nall_ids = manager.list_itineraries()\n```\n\n## REST API Server\n\nRun the FastAPI server:\n\n```python\nfrom itinerizer.server import create_app\nimport uvicorn\n\napp = create_app()\nuvicorn.run(app, host=\"0.0.0.0\", port=8000)\n```\n\nOr from the command line:\n\n```bash\nuvicorn itinerizer.server.app:app --reload\n```\n\n### API Endpoints\n\n- `GET /health` - Health check\n- `GET /api/itineraries` - List all itineraries\n- `GET /api/itineraries/{id}` - Get specific itinerary\n- `POST /api/itineraries` - Create new itinerary\n- `PUT /api/itineraries/{id}` - Update itinerary\n- `DELETE /api/itineraries/{id}` - Delete itinerary\n- `POST /api/itineraries/{id}/segments` - Add segment\n- `DELETE /api/itineraries/{id}/segments/{segment_id}` - Remove segment\n\nAPI documentation available at `http://localhost:8000/api/docs`\n\n## Web Interface\n\nThe web interface provides a user-friendly way to manage itineraries:\n\n```bash\ncd web_ui\npython app.py\n```\n\nAccess at `http://localhost:5000`\n\nFeatures:\n- Dashboard with itinerary overview\n- Create and edit itineraries\n- Manage travelers and segments\n- Natural language itinerary creation (with NLP addon)\n- Analytics and reporting\n\n## Data Models\n\n### Itinerary\n\nThe main container for a trip:\n\n```python\nfrom itinerizer import Itinerary, ItineraryStatus\n\nitinerary = Itinerary(\n title=\"European Vacation\",\n status=ItineraryStatus.PLANNED,\n start_date=date(2025, 6, 1),\n end_date=date(2025, 6, 15),\n travelers=[...],\n segments=[...],\n trip_type=\"LEISURE\"\n)\n```\n\n### Segments\n\nDifferent types of travel segments:\n\n- **FlightSegment**: Air travel with airline, flight number, airports\n- **HotelSegment**: Accommodation with check-in/out dates\n- **MeetingSegment**: Business meetings with agenda and attendees\n- **ActivitySegment**: Tours, events, and activities\n- **TransferSegment**: Ground transportation\n- **CustomSegment**: Flexible segment for other needs\n\n### Validation\n\nBuilt-in validation ensures data integrity:\n\n```python\nfrom itinerizer import ItineraryValidator\n\nvalidator = ItineraryValidator()\nresult = validator.validate(itinerary)\n\nif not result.is_valid:\n for error in result.errors:\n print(f\"Error: {error.message}\")\n```\n\n## Storage\n\n### JSON Storage (Default)\n\nItineraries are stored as JSON files:\n\n```\ndata/\n itineraries/\n {uuid}.json\n backups/\n {uuid}_{timestamp}.json\n```\n\n### Custom Storage Path\n\n```python\nmanager = ItineraryManager(storage_path=\"/path/to/storage\")\n```\n\n### Thread Safety\n\nThe storage system uses file locking for safe concurrent access:\n\n```python\nfrom itinerizer.storage import JSONItineraryStore\n\nstore = JSONItineraryStore()\nwith store.singleton.edit_lock(itinerary_id):\n # Exclusive write access\n store.save(itinerary)\n```\n\n## Advanced Features\n\n### Custom Segment Types\n\nExtend the base segment for specialized needs:\n\n```python\nfrom itinerizer import BaseSegment\nfrom typing import Literal\n\nclass CruiseSegment(BaseSegment):\n type: Literal[\"CRUISE\"] = \"CRUISE\"\n ship_name: str\n cabin_number: str\n departure_port: Location\n arrival_port: Location\n # ... additional fields\n```\n\n### Preferences and Metadata\n\nStore additional information:\n\n```python\nfrom itinerizer import TravelPreferences\n\npreferences = TravelPreferences(\n seat_preference=\"AISLE\",\n meal_preference=\"Vegetarian\",\n hotel_chain_preference=[\"Hilton\", \"Marriott\"]\n)\n\nitinerary.preferences = preferences\nitinerary.metadata = {\n \"booking_source\": \"Corporate Portal\",\n \"approval_code\": \"MGR-2025-001\"\n}\n```\n\n## Development\n\n### Setting Up Development Environment\n\n```bash\n# Clone the repository\ngit clone https://github.com/yourusername/itinerizer.git\ncd itinerizer\n\n# Create virtual environment\npython -m venv venv\nsource venv/bin/activate # On Windows: venv\\Scripts\\activate\n\n# Install in development mode\npip install -e \".[dev]\"\n\n# Run tests\npytest\n\n# Run with coverage\npytest --cov=itinerizer\n```\n\n### Running Tests\n\n```bash\n# Unit tests\npytest tests/unit/\n\n# Integration tests\npytest tests/integration/\n\n# All tests with coverage\npytest --cov=itinerizer --cov-report=html\n```\n\n### Code Quality\n\n```bash\n# Format code\nblack src/ tests/\n\n# Lint\nflake8 src/ tests/\n\n# Type checking\nmypy src/\n```\n\n## Docker Support\n\nRun with Docker:\n\n```bash\n# Build image\ndocker build -t itinerizer .\n\n# Run container\ndocker run -p 8000:8000 itinerizer\n\n# With docker-compose\ndocker-compose up\n```\n\n## Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n### Development Workflow\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests\n5. Submit a pull request\n\n## Documentation\n\n- [Full Documentation](https://itinerizer.readthedocs.io)\n- [API Reference](https://itinerizer.readthedocs.io/api)\n- [Examples](https://github.com/yourusername/itinerizer/tree/main/examples)\n- [Changelog](CHANGELOG.md)\n\n## Support\n\n- [Issue Tracker](https://github.com/yourusername/itinerizer/issues)\n- [Discussions](https://github.com/yourusername/itinerizer/discussions)\n- Email: contact@itinerizer.io\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- Built with [Pydantic](https://pydantic-docs.helpmanual.io/) for data validation\n- REST API powered by [FastAPI](https://fastapi.tiangolo.com/)\n- Web interface built with [Flask](https://flask.palletsprojects.com/)\n- JSON operations optimized with [orjson](https://github.com/ijl/orjson) (optional)\n\n## Citation\n\nIf you use Itinerizer in your research or project, please cite:\n\n```bibtex\n@software{itinerizer,\n title = {Itinerizer: A Comprehensive Travel Itinerary Management System},\n author = {Itinerizer Contributors},\n year = {2025},\n url = {https://github.com/yourusername/itinerizer}\n}\n```\n\n---\n\nMade with \u2764\ufe0f by the Itinerizer Contributors\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A comprehensive travel itinerary management system with JSON storage",
"version": "0.5.2",
"project_urls": {
"Bug Tracker": "https://github.com/yourusername/itinerizer/issues",
"Changelog": "https://github.com/yourusername/itinerizer/blob/main/CHANGELOG.md",
"Documentation": "https://itinerizer.readthedocs.io",
"Homepage": "https://github.com/yourusername/itinerizer",
"Repository": "https://github.com/yourusername/itinerizer.git"
},
"split_keywords": [
"travel",
" itinerary",
" trip",
" planning",
" booking",
" tourism",
" vacation",
" business-travel",
" json-storage"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "427efd2d01fec465dbe9cf856313eb87523fbd6c16b61706e948e6e289cf7f17",
"md5": "819faddff13897e6c5b4e04521005067",
"sha256": "dca68eef8cc955ca9433251e09fe1d54f7a063dfa37a637ec5dff445c9d15a51"
},
"downloads": -1,
"filename": "itinerizer-0.5.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "819faddff13897e6c5b4e04521005067",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 23956,
"upload_time": "2025-08-12T01:41:44",
"upload_time_iso_8601": "2025-08-12T01:41:44.705187Z",
"url": "https://files.pythonhosted.org/packages/42/7e/fd2d01fec465dbe9cf856313eb87523fbd6c16b61706e948e6e289cf7f17/itinerizer-0.5.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "66f0205933fdf51c61f315620365c231bc960d0537003a822b10ec97ee8d5d9a",
"md5": "1f5b34ca9f9bf4fe2a929b49abf26656",
"sha256": "3ce7f8e7bee95033a65f1cc5d21bd7659bc2b1cbd4c736945c813d75c33a2851"
},
"downloads": -1,
"filename": "itinerizer-0.5.2.tar.gz",
"has_sig": false,
"md5_digest": "1f5b34ca9f9bf4fe2a929b49abf26656",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 30716,
"upload_time": "2025-08-12T01:41:46",
"upload_time_iso_8601": "2025-08-12T01:41:46.130280Z",
"url": "https://files.pythonhosted.org/packages/66/f0/205933fdf51c61f315620365c231bc960d0537003a822b10ec97ee8d5d9a/itinerizer-0.5.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-12 01:41:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yourusername",
"github_project": "itinerizer",
"github_not_found": true,
"lcname": "itinerizer"
}
JSON
