from geobr.utils import select_metadata, download_gpkg


def read_metro_area(year=2018, simplified=True, verbose=False):
    """ Download shape files of official metropolitan areas in Brazil as an sf object.
    
     The function returns the shapes of municipalities grouped by their respective metro areas.
 Metropolitan areas are created by each state in Brazil. The data set includes the municipalities that belong to
 all metropolitan areas in the country according to state legislation in each year. Orignal data were generated
 by Institute of Geography. Data at scale 1:250,000, using Geodetic reference system "SIRGAS2000" and CRS(4674).

    Parameters
    ----------
    year : int, optional
        Year of the data, by default 2018
    simplified: boolean, by default True
        Data 'type', indicating whether the function returns the 'original' dataset 
        with high resolution or a dataset with 'simplified' borders (Default)
    verbose : bool, optional
        by default False
    
    Returns
    -------
    gpd.GeoDataFrame
        Metadata and geopackage of selected states
    
    Raises
    ------
    Exception
        If parameters are not found or not well defined

    Example
    -------
    >>> from geobr import read_metro_area

    # Read specific state at a given year
    >>> df = read_metro_area(year=2018)
    """

    metadata = select_metadata("metropolitan_area", year=year, simplified=simplified)

    gdf = download_gpkg(metadata)

    return gdf
