mta-subway 1.0.0__tar.gz

mta_subway-1.0.0/.gitignore

@@ -0,0 +1,23 @@
+# Virtual environments
+venv/
+.venv/
+env/
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+
+# Node
+node_modules/
+dist/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+
+# OS
+.DS_Store

mta_subway-1.0.0/PKG-INFO

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: mta-subway
+Version: 1.0.0
+Summary: Real-time NYC subway arrivals CLI and MCP server
+Project-URL: Homepage, https://github.com/reichertjalex/mta-subway
+Project-URL: Repository, https://github.com/reichertjalex/mta-subway
+Author: Alex Reichert
+License-Expression: MIT
+Keywords: cli,gtfs,mcp,mta,nyc,subway,transit
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: nyct-gtfs>=1.3.0
+Requires-Dist: pydantic>=2.0
+Description-Content-Type: text/markdown
+
+# MTA API v3
+
+Real-time NYC subway arrivals API with async concurrent feed fetching.
+
+## Key Differences from v2
+
+- **Concurrent fetching**: All 8 MTA feeds fetched in parallel using `asyncio.to_thread()`
+- **Async cache**: Uses `asyncio.Lock` to prevent concurrent refresh storms
+- **Lazy refresh**: Cache updates on first request after expiry
+
+## Performance
+
+- Sequential fetch (v2): ~2-4 seconds
+- Concurrent fetch (v3): ~500ms-1s
+
+## Quick Start
+
+```bash
+python -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+uvicorn app.main:app --reload
+```
+
+## API Endpoints
+
+Same as v2 - see `/docs` for OpenAPI documentation.
+
+## Docker
+
+```bash
+docker build -t mta-api-v3 .
+docker run -p 8000:8000 mta-api-v3
+```
+
+## Deploy to Fly.io
+
+[Fly.io](https://fly.io) is recommended for v3 since it supports persistent servers with the async caching model.
+
+### First-time setup
+
+```bash
+# Install flyctl
+curl -L https://fly.io/install.sh | sh
+
+# Login
+fly auth login
+
+# Launch app (creates fly.toml)
+cd mta-api-v3
+fly launch --name mta-api-v3 --region ewr --no-deploy
+
+# Deploy
+fly deploy
+```
+
+### fly.toml
+
+If you need to create it manually:
+
+```toml
+app = "mta-api-v3"
+primary_region = "ewr"  # Newark, close to MTA servers
+
+[build]
+  dockerfile = "Dockerfile"
+
+[http_service]
+  internal_port = 8000
+  force_https = true
+
+[[http_service.checks]]
+  path = "/"
+  interval = "30s"
+  timeout = "5s"
+```
+
+### Useful commands
+
+```bash
+fly status              # Check app status
+fly logs                # View logs
+fly ssh console         # SSH into the container
+fly scale count 2       # Scale to 2 instances
+fly secrets set KEY=val # Set environment variables
+```
+
+## CLI
+
+Query subway data from the command line. Output is JSON by default.
+
+```bash
+# Setup
+source venv/bin/activate
+
+# List all stations
+python -m mta.cli stations
+
+# Search stations by name
+python -m mta.cli stations -q "Times Sq"
+
+# Get station by ID (with arrivals)
+python -m mta.cli stations 127
+
+# Get multiple stations
+python -m mta.cli stations 127,A32
+
+# Search by location
+python -m mta.cli stations --lat 40.7580 --lon -73.9855
+
+# List all routes
+python -m mta.cli routes
+
+# Get stations on a route
+python -m mta.cli routes A
+
+# Find next trains from a station
+python -m mta.cli find "Times Sq"
+
+# Find specific route from a station
+python -m mta.cli find "Times Sq" -r A
+
+# Human-readable output (--pretty goes before the command)
+python -m mta.cli --pretty stations 127
+```
+
+## MCP Server
+
+Run as a Model Context Protocol server for AI assistants:
+
+```bash
+python -m mta.mcp
+```
+
+### Available Tools
+
+| Tool           | Description                         |
+| -------------- | ----------------------------------- |
+| `get_stations` | Search stations by name or location |
+| `get_station`  | Get station(s) by ID with arrivals  |
+| `get_routes`   | List all active subway routes       |
+| `get_route`    | Get all stations on a route         |
+| `find_train`   | Find next trains from a station     |
+
+### Claude Desktop Configuration
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "mta-subway": {
+      "command": "python",
+      "args": ["-m", "mta.mcp"],
+      "cwd": "/path/to/mta-api-v3"
+    }
+  }
+}
+```

mta_subway-1.0.0/README.md

@@ -0,0 +1,159 @@
+# MTA API v3
+
+Real-time NYC subway arrivals API with async concurrent feed fetching.
+
+## Key Differences from v2
+
+- **Concurrent fetching**: All 8 MTA feeds fetched in parallel using `asyncio.to_thread()`
+- **Async cache**: Uses `asyncio.Lock` to prevent concurrent refresh storms
+- **Lazy refresh**: Cache updates on first request after expiry
+
+## Performance
+
+- Sequential fetch (v2): ~2-4 seconds
+- Concurrent fetch (v3): ~500ms-1s
+
+## Quick Start
+
+```bash
+python -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+uvicorn app.main:app --reload
+```
+
+## API Endpoints
+
+Same as v2 - see `/docs` for OpenAPI documentation.
+
+## Docker
+
+```bash
+docker build -t mta-api-v3 .
+docker run -p 8000:8000 mta-api-v3
+```
+
+## Deploy to Fly.io
+
+[Fly.io](https://fly.io) is recommended for v3 since it supports persistent servers with the async caching model.
+
+### First-time setup
+
+```bash
+# Install flyctl
+curl -L https://fly.io/install.sh | sh
+
+# Login
+fly auth login
+
+# Launch app (creates fly.toml)
+cd mta-api-v3
+fly launch --name mta-api-v3 --region ewr --no-deploy
+
+# Deploy
+fly deploy
+```
+
+### fly.toml
+
+If you need to create it manually:
+
+```toml
+app = "mta-api-v3"
+primary_region = "ewr"  # Newark, close to MTA servers
+
+[build]
+  dockerfile = "Dockerfile"
+
+[http_service]
+  internal_port = 8000
+  force_https = true
+
+[[http_service.checks]]
+  path = "/"
+  interval = "30s"
+  timeout = "5s"
+```
+
+### Useful commands
+
+```bash
+fly status              # Check app status
+fly logs                # View logs
+fly ssh console         # SSH into the container
+fly scale count 2       # Scale to 2 instances
+fly secrets set KEY=val # Set environment variables
+```
+
+## CLI
+
+Query subway data from the command line. Output is JSON by default.
+
+```bash
+# Setup
+source venv/bin/activate
+
+# List all stations
+python -m mta.cli stations
+
+# Search stations by name
+python -m mta.cli stations -q "Times Sq"
+
+# Get station by ID (with arrivals)
+python -m mta.cli stations 127
+
+# Get multiple stations
+python -m mta.cli stations 127,A32
+
+# Search by location
+python -m mta.cli stations --lat 40.7580 --lon -73.9855
+
+# List all routes
+python -m mta.cli routes
+
+# Get stations on a route
+python -m mta.cli routes A
+
+# Find next trains from a station
+python -m mta.cli find "Times Sq"
+
+# Find specific route from a station
+python -m mta.cli find "Times Sq" -r A
+
+# Human-readable output (--pretty goes before the command)
+python -m mta.cli --pretty stations 127
+```
+
+## MCP Server
+
+Run as a Model Context Protocol server for AI assistants:
+
+```bash
+python -m mta.mcp
+```
+
+### Available Tools
+
+| Tool           | Description                         |
+| -------------- | ----------------------------------- |
+| `get_stations` | Search stations by name or location |
+| `get_station`  | Get station(s) by ID with arrivals  |
+| `get_routes`   | List all active subway routes       |
+| `get_route`    | Get all stations on a route         |
+| `find_train`   | Find next trains from a station     |
+
+### Claude Desktop Configuration
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "mta-subway": {
+      "command": "python",
+      "args": ["-m", "mta.mcp"],
+      "cwd": "/path/to/mta-api-v3"
+    }
+  }
+}
+```

mta_subway-1.0.0/app/cache.py

@@ -0,0 +1,61 @@
+"""Async TTL cache with lock to prevent concurrent refreshes."""
+
+import asyncio
+from datetime import datetime, timedelta
+from typing import TypeVar, Generic, Callable, Awaitable
+from zoneinfo import ZoneInfo
+
+TZ = ZoneInfo("America/New_York")
+T = TypeVar("T")
+
+
+class AsyncTTLCache(Generic[T]):
+    """Thread-safe async cache with TTL expiration."""
+
+    def __init__(self, ttl_seconds: int = 60):
+        self.ttl_seconds = ttl_seconds
+        self._value: T | None = None
+        self._last_update: datetime | None = None
+        self._lock = asyncio.Lock()
+
+    def is_expired(self) -> bool:
+        """Check if cache has expired."""
+        if self._last_update is None:
+            return True
+        age = datetime.now(TZ) - self._last_update
+        return age.total_seconds() > self.ttl_seconds
+
+    async def get(self) -> T | None:
+        """Get cached value (may be stale)."""
+        return self._value
+
+    async def set(self, value: T) -> None:
+        """Set cached value."""
+        async with self._lock:
+            self._value = value
+            self._last_update = datetime.now(TZ)
+
+    async def get_or_refresh(
+        self, refresh_fn: Callable[[], Awaitable[T]]
+    ) -> T | None:
+        """Get cached value, refreshing if expired.
+
+        Uses lock to prevent multiple concurrent refreshes.
+        """
+        if not self.is_expired():
+            return self._value
+
+        async with self._lock:
+            # Double-check after acquiring lock
+            if not self.is_expired():
+                return self._value
+
+            # Refresh
+            self._value = await refresh_fn()
+            self._last_update = datetime.now(TZ)
+            return self._value
+
+    @property
+    def last_update(self) -> datetime | None:
+        """Get timestamp of last update."""
+        return self._last_update

mta_subway-1.0.0/app/main.py

@@ -0,0 +1,126 @@
+"""Async FastAPI application for MTA API v3."""
+
+import logging
+import os
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+from fastapi import FastAPI, Query, HTTPException
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+)
+from fastapi.middleware.cors import CORSMiddleware
+
+from app.mta_service import AsyncMTAService
+from app.models import StationsResponse, RoutesResponse
+
+# Configuration from environment
+STATIONS_FILE = Path(os.getenv("STATIONS_FILE", "data/stations.json"))
+CACHE_SECONDS = int(os.getenv("CACHE_SECONDS", "60"))
+MAX_TRAINS = int(os.getenv("MAX_TRAINS", "10"))
+MAX_MINUTES = int(os.getenv("MAX_MINUTES", "30"))
+
+# Global service instance
+mta_service: AsyncMTAService | None = None
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Initialize async MTA service on startup."""
+    global mta_service
+    mta_service = AsyncMTAService(
+        stations_file=STATIONS_FILE,
+        cache_seconds=CACHE_SECONDS,
+        max_trains=MAX_TRAINS,
+        max_minutes=MAX_MINUTES,
+    )
+    yield
+
+
+app = FastAPI(
+    title="MTA API v3",
+    description="Real-time NYC subway arrivals (async)",
+    version="3.0.0",
+    lifespan=lifespan,
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+@app.get("/")
+async def root():
+    """API info."""
+    return {
+        "title": "MTA API v3",
+        "description": "Real-time NYC subway arrivals (async with concurrent fetching)",
+        "docs": "/docs",
+    }
+
+
+@app.get("/api/stations", response_model=StationsResponse)
+async def get_stations(
+    query: str | None = Query(None, description="Search by station name"),
+    latitude: float | None = Query(None, description="Latitude for location search"),
+    longitude: float | None = Query(None, description="Longitude for location search"),
+    limit: int = Query(10, ge=1, le=100, description="Max results"),
+):
+    """Get stations by name or location."""
+    if mta_service is None:
+        raise HTTPException(status_code=503, detail="Service not initialized")
+
+    if latitude is not None and longitude is not None:
+        data = await mta_service.get_by_location(latitude, longitude, limit)
+    elif query:
+        data = await mta_service.get_stations(query, limit)
+    else:
+        data = await mta_service.get_stations(limit=limit)
+
+    return StationsResponse(data=data, updated=mta_service.last_update())
+
+
+@app.get("/api/stations/{station_id}", response_model=StationsResponse)
+async def get_stations_by_id(station_id: str):
+    """Get station(s) by ID (comma-separated)."""
+    if mta_service is None:
+        raise HTTPException(status_code=503, detail="Service not initialized")
+
+    ids = [s.strip() for s in station_id.split(",")]
+    data = await mta_service.get_by_ids(ids)
+
+    if not data:
+        raise HTTPException(status_code=404, detail="Station(s) not found")
+
+    return StationsResponse(data=data, updated=mta_service.last_update())
+
+
+@app.get("/api/routes", response_model=RoutesResponse)
+async def get_routes():
+    """Get all active subway routes."""
+    if mta_service is None:
+        raise HTTPException(status_code=503, detail="Service not initialized")
+
+    routes = await mta_service.get_routes()
+    return RoutesResponse(data=routes, updated=mta_service.last_update())
+
+
+@app.get("/api/routes/{route}", response_model=StationsResponse)
+async def get_stations_by_route(route: str):
+    """Get all stations on a route."""
+    if mta_service is None:
+        raise HTTPException(status_code=503, detail="Service not initialized")
+
+    data = await mta_service.get_by_route(route)
+
+    if not data:
+        raise HTTPException(status_code=404, detail=f"Route {route} not found")
+
+    return StationsResponse(data=data, updated=mta_service.last_update())

mta_subway-1.0.0/app/models.py

@@ -0,0 +1,38 @@
+"""Pydantic models for API responses."""
+
+from datetime import datetime
+from pydantic import BaseModel
+
+
+class Train(BaseModel):
+    """A train arrival."""
+
+    route: str
+    time: datetime
+
+
+class Station(BaseModel):
+    """A subway station with train arrivals."""
+
+    id: str
+    name: str
+    location: tuple[float, float]
+    routes: list[str]
+    N: list[Train]  # Northbound/Uptown trains
+    S: list[Train]  # Southbound/Downtown trains
+    stops: dict[str, tuple[float, float]]
+    last_update: datetime | None
+
+
+class StationsResponse(BaseModel):
+    """API response containing stations."""
+
+    data: list[Station]
+    updated: datetime | None
+
+
+class RoutesResponse(BaseModel):
+    """API response containing route list."""
+
+    data: list[str]
+    updated: datetime | None