Feed Operations

def read_feed(path_or_url, dist_units='km'):
    """
    Read a GTFS feed from a file path or URL.
    
    Parameters:
    - path_or_url (str or Path): Path to GTFS zip file, directory, or URL
    - dist_units (str): Distance units for the feed ('ft', 'mi', 'm', 'km')
    
    Returns:
    - Feed: GTFS Feed object
    """

import gtfs_kit as gk

# Read from local file
feed = gk.read_feed('gtfs.zip', dist_units='km')

# Read from URL
feed = gk.read_feed('https://example.com/gtfs.zip', dist_units='mi')

# Read from directory
feed = gk.read_feed('/path/to/gtfs/directory', dist_units='m')

def list_feed(path):
    """
    List the contents of a GTFS feed file or directory.
    
    Parameters:
    - path (str or Path): Path to GTFS zip file or directory
    
    Returns:
    - DataFrame: DataFrame with columns 'file_name' and 'file_size'
    """

# Check what files are in a GTFS feed before loading
file_info = gk.list_feed('gtfs.zip')
print(file_info)  # DataFrame with file_name and file_size columns

class Feed:
    """
    Main GTFS feed class for loading and manipulating transit data.
    
    Attributes (all pandas.DataFrame):
    - agency: Transit agency information
    - stops: Stop/station information  
    - routes: Route information
    - trips: Individual trip information
    - stop_times: Stop time schedules for trips
    - calendar: Service calendar information
    - calendar_dates: Service calendar date exceptions
    - fare_attributes: Fare information (optional)
    - fare_rules: Fare rules (optional)
    - shapes: Shape/path information (optional)
    - frequencies: Trip frequency information (optional)
    - transfers: Transfer information (optional)
    - feed_info: Feed metadata (optional)
    - attributions: Data attributions (optional)
    - dist_units (str): Distance units for the feed
    """
    
    def __init__(self, dist_units, agency=None, stops=None, routes=None, 
                 trips=None, stop_times=None, calendar=None, calendar_dates=None, 
                 fare_attributes=None, fare_rules=None, shapes=None, frequencies=None, 
                 transfers=None, feed_info=None, attributions=None):
        """
        Initialize a GTFS Feed object.
        
        Parameters:
        - dist_units (str): Distance units for the feed ('ft', 'mi', 'm', 'km')
        - agency (DataFrame, optional): Transit agency information
        - stops (DataFrame, optional): Stop/station information
        - routes (DataFrame, optional): Route information
        - trips (DataFrame, optional): Individual trip information
        - stop_times (DataFrame, optional): Stop time schedules
        - calendar (DataFrame, optional): Service calendar information
        - calendar_dates (DataFrame, optional): Calendar date exceptions
        - fare_attributes (DataFrame, optional): Fare information
        - fare_rules (DataFrame, optional): Fare rules
        - shapes (DataFrame, optional): Shape/path information
        - frequencies (DataFrame, optional): Trip frequency information
        - transfers (DataFrame, optional): Transfer information
        - feed_info (DataFrame, optional): Feed metadata
        - attributions (DataFrame, optional): Data attributions
        """
    
    @property
    def dist_units(self):
        """Distance units property getter."""
    
    @dist_units.setter
    def dist_units(self, value):
        """Distance units property setter."""
        
    def __str__(self):
        """String representation of the Feed object."""
        
    def __eq__(self, other):
        """Equality comparison between Feed objects."""

def copy(self):
    """
    Create a deep copy of the feed.
    
    Returns:
    - Feed: Deep copy of the feed object
    """

def to_file(self, path, ndigits=None):
    """
    Write the feed to a file or ZIP archive.
    
    Parameters:
    - path (str or Path): Output file path (zip extension creates ZIP archive)
    - ndigits (int, optional): Number of decimal places for coordinate precision
    """

import gtfs_kit as gk

# Load a feed
feed = gk.read_feed('gtfs.zip', dist_units='km')

# Access GTFS tables as DataFrames
print(feed.agency)
print(feed.routes.head())
print(feed.stops.head())

# Check feed attributes
print(f"Distance units: {feed.dist_units}")
print(f"Number of routes: {len(feed.routes)}")
print(f"Number of stops: {len(feed.stops)}")

# Copy the feed
feed_copy = feed.copy()

# Save feed to file
feed.to_file('output.zip')  # Save as ZIP
feed.to_file('output_dir')  # Save as directory
feed.to_file('output.zip', ndigits=6)  # Control coordinate precision

# As standalone functions
routes = gk.get_routes(feed, date='20230101')
stops = gk.get_stops(feed, as_gdf=True)

# As feed methods  
routes = feed.get_routes(date='20230101')
stops = feed.get_stops(as_gdf=True)