travelkit

travelkit is a Python library with core data structures for TravelTech projects.
It provides Point, Segment and Query classes for representing locations, travel segments, and search queries.

Installation

Using pip:

pip install travelkit
# or with optional autofill and emoji support:
pip install travelkit[autofill]

Using Poetry:

poetry add travelkit
# or with optional features:
poetry add travelkit --extras "autofill"

Quick Start

from travelkit import Point, Segment, Query

# Create a point (location)
moscow = Point(settlement="Moscow", country="RU", iata="SVO")
berlin = Point("Berlin")  # Short form for settlement

# Create a travel segment
segment = Segment(moscow, berlin, "2025-07-31", transport_type="plane")

# Create a search query
query = Query(
    origins=[moscow],
    destinations=[berlin],
    dates=["2025-07-31", "2025-08-01"],
    transport_types=["plane", "train"]
)

# Load query from YAML file
query_from_file = Query("path/to/query.yaml")
segments = query_from_file.as_segments()

Core Classes

Point

Represents a geographical or transport location with flexible identification:

# Multiple ways to create a Point
point1 = Point(settlement="Paris", country="FR", iata="CDG")
point2 = Point(lat=48.8566, lon=2.3522)  # Coordinates
point3 = Point(yandex="12345")  # Yandex code
point4 = Point(express="EXP123")  # Express code
point5 = Point("London")  # Just settlement name

# Auto-fill data (requires autofill extra)
point6 = Point(settlement="Tokyo", auto_fill=True)

Features:

• Multiple identification methods (IATA, coordinates, Yandex code, Express code)
• Country flag emoji support (with autofill extra)
• Smart comparison and sorting
• Automatic data filling from external sources

Segment

Represents a travel segment between two points:

# Create segment with different transport types
plane_segment = Segment("Moscow", "Berlin", "2025-07-31", transport_type="plane")
train_segment = Segment("Paris", "London", "2025-08-15", transport_type="train")

# Create from dictionary
segment_data = {
    "origin": "Moscow",
    "destination": "Berlin", 
    "date": "2025-07-31",
    "transport_type": "plane",
    "prices": {"low": 150, "high": 300}
}
segment = Segment(segment_data)

# Access segment properties
print(segment.origin.settlement)  # Moscow
print(segment.date)  # 2025-07-31
print(segment.transport_type)  # plane

Features:

• Flexible initialization (positional args, keywords, or dict)
• ISO 8601 date validation
• Automatic Point conversion from strings
• Price information support
• Custom transport types

Query

Represents a search request for multiple travel segments:

# Create query with multiple origins, destinations, and dates
query = Query(
    origins=["Moscow", "Saint Petersburg"],
    destinations=["Berlin", "Paris"],
    dates=["2025-07-31", "2025-08-01", "2025-08-02"],
    transport_types=["plane", "train"],
    name="Summer Europe Trip",
    comment="Flexible dates and routes"
)

# Load from YAML file
query = Query("queries/europe_trip.yaml")

# Convert to segments
segments = query.as_segments()
for segment in segments:
    print(f"{segment.origin} -> {segment.destination} on {segment.date}")

# Save query
query.save("my_query.yaml")

Features:

• Multiple origins, destinations, and dates
• Date range expansion (e.g., "2025-07" expands to all July dates)
• Transport type expansion
• YAML import/export
• Flexible initialization from parameters or files

Advanced Features

Autofill Module (Optional)

Install with pip install travelkit[autofill] for additional features:

from travelkit import Point

# Auto-fill country and other data
point = Point(settlement="Tokyo", auto_fill=True)
print(point.country)  # JP
print(point)  # Tokyo 🇯🇵

# Get country emoji
from travelkit.autofill import get_country_emoji
emoji = get_country_emoji("RU")  # 🇷🇺

Query File Format

Queries can be saved/loaded in YAML format:

# query.yaml
origins:
  - Moscow
  - Saint Petersburg
destinations:
  - Berlin
  - Paris
dates:
  - 2025-07-31
  - 2025-08-01
transport_types:
  - plane
  - train
name: "Summer Europe Trip"
comment: "Flexible dates and routes"

Development

Clear installation:

poetry env remove python
poetry install --only main,dev

Run tests:

poetry run pytest

Requirements

• Python 3.10+
• Core dependencies: python-dateutil, pyicu, pyyaml
• Optional autofill: flagz, countrynames

License

MIT