travelkit documentation

<div align=”center”>

<img src=”https://raw.githubusercontent.com/pavelsr/travelkit/refs/heads/main/docs/logo.png” alt=”ENR Logo” width=”300”>

</div>

# 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:

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

Using Poetry:

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

## Quick Start

```python 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:

```python # 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:

```python # 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:

```python # 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:

```python 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:

```yaml # 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:

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

Run tests:

`shell poetry run pytest `

## Requirements

  • Python 3.10+

  • Core dependencies: python-dateutil, pyicu, pyyaml

  • Optional autofill: flagz, countrynames

## License

MIT

Contents: