### Public README for `location_checker` Package

---

# `location_checker`

A Python extension module for geographic operations, including country lookups, Haversine distance calculations, and travel time verification. This module is implemented in Rust using the `pyo3` library for Python bindings, offering high performance and reliability.

## Features

- **Country Lookup**: Identify the country (or countries) corresponding to a given latitude and longitude.
- **Distance Calculation**: Calculate the Haversine distance between two locations.
- **Travel Time Verification**: Verify if travel between two locations is feasible within a specified time based on a realistic speed limit.

## Installation

To build and install the package, you need Rust and Python installed on your system. Install the package using:

```bash
pip install maturin
maturin develop
```

Alternatively, for a production build:

```bash
maturin build
pip install ./target/wheels/location_checker-*.whl
```

---

## Usage

Here’s an example demonstrating how to use the `location_checker` module:

### Example

```python
from location_checker import Location, LocationChecker

# Initialize the LocationChecker
checker = LocationChecker()

# Load the country boundaries
checker.load_boundaries()

# Define locations
loc1 = Location(latitude=37.7749, longitude=-122.4194, timestamp="2024-12-01T10:00:00Z")  # San Francisco
loc2 = Location(latitude=34.0522, longitude=-118.2437, timestamp="2024-12-01T14:00:00Z")  # Los Angeles

# Get the country of a location
countries = checker.get_country(loc1)
print(f"San Francisco is in: {countries}")

# Calculate the distance between two locations
distance = checker.calculate_distance(loc1, loc2)
print(f"Distance between San Francisco and Los Angeles: {distance:.2f} meters")

# Verify travel feasibility
feasible = checker.verify_travel_time(loc1, loc2)
print(f"Is it feasible to travel between San Francisco and Los Angeles in the given time? {feasible}")
```

---

## API Documentation

### `Location`
Represents a geographic location.

- `Location(latitude: float, longitude: float, timestamp: Optional[str] = None)`
  - `latitude`: Latitude in degrees (-90 to 90).
  - `longitude`: Longitude in degrees (-180 to 180).
  - `timestamp`: Optional RFC3339 formatted datetime string.

### `LocationChecker`
Performs operations related to locations.

- `load_boundaries() -> None`
  - Loads country boundaries into memory.

- `get_country(location: Location) -> List[str]`
  - Identifies the country (or countries) for a given location.

- `calculate_distance(location1: Location, location2: Location) -> float`
  - Calculates the Haversine distance between two locations (in meters).

- `verify_travel_time(start_location: Location, end_location: Location) -> bool`
  - Verifies if travel between two locations within the given timestamps is feasible.

---

## Tests

Here’s an example of a test case for the package:

### `test_location_checker.py`

```python
from location_checker import Location, LocationChecker


def test_location_checker():
    checker = LocationChecker()

    # Load boundaries
    checker.load_boundaries()

    # Test location creation
    loc1 = Location(latitude=37.7749, longitude=-122.4194, timestamp="2024-12-01T10:00:00Z")
    loc2 = Location(latitude=34.0522, longitude=-118.2437, timestamp="2024-12-01T14:00:00Z")

    # Test country lookup
    countries = checker.get_country(loc1)
    assert len(countries) > 0, "Country lookup failed"

    # Test distance calculation
    distance = checker.calculate_distance(loc1, loc2)
    assert distance > 0, "Distance calculation failed"

    # Test travel feasibility
    feasible = checker.verify_travel_time(loc1, loc2)
    assert feasible, "Travel time verification failed"

    print("All tests passed!")


if __name__ == "__main__":
    test_location_checker()
```

---

## License

This project is licensed under the MIT License. See the `LICENSE` file for details.
