buildstock-fetch 1.3.1__py3-none-any.whl → 1.4.3__py3-none-any.whl

buildstock_fetch/main_cli.py

@@ -6,6 +6,7 @@ from pathlib import Path
 from typing import Union, cast
 
 import questionary
+import tomli
 import typer
 from rich.console import Console
 from rich.panel import Panel
@@ -29,7 +30,10 @@ app = typer.Typer(
 BUILDSTOCK_RELEASES_FILE = str(files("buildstock_fetch").joinpath("data").joinpath("buildstock_releases.json"))
 
 # File types that haven't been implemented yet
-UNAVAILABLE_FILE_TYPES = ["load_curve_daily"]
+UNAVAILABLE_FILE_TYPES: list[str] = []
+
+# Upgrade scenario description lookup file
+UPGRADES_LOOKUP_FILE = str(files("buildstock_fetch").joinpath("data").joinpath("buildstock_upgrades_lookup.json"))
 
 
 class InvalidProductError(Exception):
@@ -75,7 +79,7 @@ def _get_release_years_options(available_releases: list[str], product_type: str)
     parsed_releases = _parse_buildstock_releases(available_releases)
     available_releases = _filter_available_releases(list(parsed_releases.keys()), product_type=product_type)
     available_release_years = list({parsed_releases[release]["release_year"] for release in available_releases})
-    available_release_years.sort()
+    available_release_years.sort(reverse=True)  # Sort in descending order (latest first)
 
     return available_releases, available_release_years
 
@@ -152,6 +156,14 @@ def _get_upgrade_ids_options(release_name: str) -> list[str]:
     available_upgrade_ids.sort()
     available_upgrade_ids = [str(upgrade_id) for upgrade_id in available_upgrade_ids]
 
+    if release_name in json.loads(Path(UPGRADES_LOOKUP_FILE).read_text(encoding="utf-8")):
+        upgrade_descriptions = json.loads(Path(UPGRADES_LOOKUP_FILE).read_text(encoding="utf-8"))[release_name][
+            "upgrade_descriptions"
+        ]
+        available_upgrade_ids = [
+            f"{upgrade_id}: {upgrade_descriptions[upgrade_id]}" for upgrade_id in available_upgrade_ids
+        ]
+
     return cast(list[str], available_upgrade_ids)
 
 
@@ -218,10 +230,26 @@ def _get_file_type_options(release_name: str) -> list[str]:
     return cast(list[str], available_releases[release_name]["available_data"])
 
 
-def _get_file_type_options_grouped(release_name: str) -> list[dict]:
+def _get_file_type_options_grouped(release_name: str, selected_states: list[str]) -> list[dict]:
     """Get file type options grouped by category for questionary checkbox."""
     file_types = _get_file_type_options(release_name)
 
+    # TODO: If a trip_schedule table was built for any of the states in this release, "trip_schedules" will be included
+    # in the file_types list above. However, the state that the user wants to download files for may not have the trip_schedule tables built for it yet.
+    # So, we need to check if the release_name + state combo is in the available trip_schedules_states list.
+    # If not, we need to remove "trip_schedules" from the file_types list, so it doesn't show up in the questionary checkbox.
+    # Remember that users can select multiple states, so as long as one release_name + state combo is in the available trip_schedules_states list,
+    # we should include "trip_schedules" in the file_types list. and then later on, we need to handle different states differently.
+
+    trip_schedule_availabile = False
+    available_releases = _get_all_available_releases()
+    for state in selected_states:
+        if (
+            "trip_schedules" in available_releases[release_name]["available_data"]
+            and state in available_releases[release_name]["trip_schedule_states"]
+        ):
+            trip_schedule_availabile = True
+
     # Define categories
     categories = {
         "Simulation Files": ["hpxml", "schedule"],
@@ -233,21 +261,39 @@ def _get_file_type_options_grouped(release_name: str) -> list[dict]:
             "load_curve_annual",
         ],
         "Metadata": ["metadata"],
+        "EV": ["trip_schedules"],
         "Weather": ["weather"],
     }
 
-    choices = []
+    choices: list[dict] = []
     for category, types in categories.items():
-        # Filter available types but maintain the defined order
-        available_in_category = [ft for ft in types if ft in file_types]
-        if available_in_category:
-            choices.append({"name": f"--- {category} ---", "value": None, "disabled": True})
-            for file_type in available_in_category:
-                choices.append({"name": f"  {file_type}", "value": file_type, "style": "bold"})
+        if category == "EV":
+            _add_ev_category_choices(choices, category, types, trip_schedule_availabile)
+        else:
+            _add_standard_category_choices(choices, category, types, file_types)
 
     return choices
 
 
+def _add_ev_category_choices(
+    choices: list[dict], category: str, types: list[str], trip_schedule_available: bool
+) -> None:
+    """Add EV category choices to the choices list."""
+    for file_type in types:
+        if file_type == "trip_schedules" and trip_schedule_available:
+            choices.append({"name": f"--- {category} ---", "value": None, "disabled": True})
+            choices.append({"name": f"  {file_type}", "value": file_type, "style": "bold"})
+
+
+def _add_standard_category_choices(choices: list[dict], category: str, types: list[str], file_types: list[str]) -> None:
+    """Add standard category choices to the choices list."""
+    available_in_category = [ft for ft in types if ft in file_types]
+    if available_in_category:
+        choices.append({"name": f"--- {category} ---", "value": None, "disabled": True})
+        for file_type in available_in_category:
+            choices.append({"name": f"  {file_type}", "value": file_type, "style": "bold"})
+
+
 def _get_available_releases_names() -> list[str]:
     # Read the buildstock releases JSON file
     buildstock_releases = json.loads(Path(BUILDSTOCK_RELEASES_FILE).read_text(encoding="utf-8"))
@@ -363,20 +409,23 @@ def _run_interactive_mode() -> dict[str, Union[str, list[str]]]:
     )
 
     # Retrieve state
-    selected_states = _handle_cancellation(
-        questionary.checkbox(
-            "Select states:",
-            choices=_get_state_options(),
-            instruction="Use spacebar to select/deselect options, enter to confirm",
-            validate=lambda answer: "You must select at least one state" if len(answer) == 0 else True,
-        ).ask()
+    selected_states: list[str] = cast(
+        list[str],
+        _handle_cancellation(
+            questionary.checkbox(
+                "Select states:",
+                choices=_get_state_options(),
+                instruction="Use spacebar to select/deselect options, enter to confirm",
+                validate=lambda answer: "You must select at least one state" if len(answer) == 0 else True,
+            ).ask()
+        ),
     )
 
     # Retrieve requested file type
     requested_file_types = _handle_cancellation(
         questionary.checkbox(
             "Select file type:",
-            choices=_get_file_type_options_grouped(selected_release_name),
+            choices=_get_file_type_options_grouped(selected_release_name, selected_states),
             instruction="Use spacebar to select/deselect options, enter to confirm",
             validate=lambda answer: "You must select at least one file type" if len(answer) == 0 else True,
         ).ask()
@@ -512,6 +561,18 @@ def _check_unavailable_file_types(inputs: Mapping[str, Union[str, list[str]]]) -
     if "weather" in selected_file_types:
         _check_weather_file_availability(inputs, available_file_types, selected_unavailable_file_types)
 
+    if "trip_schedules" in selected_file_types:
+        product_short_name = "res" if inputs["product"] == "resstock" else "com"
+        input_release_name = (
+            f"{product_short_name}_{inputs['release_year']}_{inputs['weather_file']}_{inputs['release_version']}"
+        )
+        available_releases = _get_all_available_releases()
+        availble_trip_schedule_states = available_releases[input_release_name]["trip_schedule_states"]
+        for state in inputs["states"]:
+            if state not in availble_trip_schedule_states:
+                console.print(f"[yellow]The following state is not available for trip schedules: {state}[/yellow]")
+                selected_unavailable_file_types.append(f"trip_schedules_{state}")
+
     _print_unavailable_file_types_warning(selected_unavailable_file_types)
 
     return available_file_types, selected_unavailable_file_types
@@ -645,6 +706,7 @@ def _validate_file_types(inputs: dict[str, Union[str, list[str]]], release_name:
     """Validate file types."""
     available_releases = _get_all_available_releases()
     for file_type in inputs["file_type"]:
+        # TODO: Validate EV related files
         if file_type not in available_releases[release_name]["available_data"]:
             return f"Invalid file type: {file_type}"
     return True
@@ -715,6 +777,29 @@ UPGRADE_ID_OPTION = typer.Option(
     None, "--upgrade_id", "-u", help="Upgrade IDs (multiple can be provided, inside quotes and separated by spaces)"
 )
 OUTPUT_DIRECTORY_OPTION = typer.Option(None, "--output_directory", "-o", help='e.g., "data" or "../output"')
+VERSION_OPTION = typer.Option(False, "--version", "-v", help="Show version information and exit")
+
+
+def _get_version() -> str:
+    """Get the version from pyproject.toml."""
+    try:
+        # Get the path to pyproject.toml (assuming it's in the project root)
+        project_root = Path(__file__).parent.parent
+        pyproject_path = project_root / "pyproject.toml"
+
+        with open(pyproject_path, "rb") as f:
+            data = tomli.load(f)
+            version = data["project"]["version"]
+            return str(version)
+    except (FileNotFoundError, KeyError, Exception):
+        return "unknown"
+
+
+def _show_version() -> None:
+    """Display version information and exit."""
+    version = _get_version()
+    console.print(f"buildstock-fetch version {version}")
+    raise typer.Exit(0) from None
 
 
 def _run_interactive_mode_wrapper() -> dict[str, Union[str, list[str]]]:
@@ -792,7 +877,6 @@ def _process_data_download(inputs: dict[str, Union[str, list[str]]]) -> None:
             output_dir = inputs["output_directory"]
             if isinstance(output_dir, list):
                 output_dir = output_dir[0] if output_dir else "."
-
             fetch_bldg_data(
                 selected_bldg_ids, file_type_tuple, Path(output_dir), weather_states=available_weather_states
             )
@@ -811,11 +895,16 @@ def main_callback(
     file_type: str = FILE_TYPE_OPTION,
     upgrade_id: str = UPGRADE_ID_OPTION,
     output_directory: str = OUTPUT_DIRECTORY_OPTION,
+    version: bool = VERSION_OPTION,
 ) -> None:
     """
     Buildstock Fetch CLI tool. Run without arguments for interactive mode.
     """
 
+    # Handle version option first
+    if version:
+        _show_version()
+
     # If no arguments provided, run interactive mode
     if not any([product, release_year, weather_file, release_version, states, file_type]):
         inputs = _run_interactive_mode_wrapper()

{buildstock_fetch-1.3.1.dist-info → buildstock_fetch-1.4.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: buildstock-fetch
-Version: 1.3.1
+Version: 1.4.3
 Summary: This library simplifies downloading building characteristics and load curve data from NREL's ResStock and ComStock projects.
 Author-email: Switchbox <hello@switch.box>
 Project-URL: Homepage, https://switchbox-data.github.io/buildstock-fetch/
@@ -24,6 +24,9 @@ Requires-Dist: typer>=0.9.0
 Requires-Dist: rich>=13.9.5
 Requires-Dist: questionary>=1.11.0
 Requires-Dist: polars>=0.20.0
+Requires-Dist: tomli>=2.0.0
+Requires-Dist: boto3>=1.33.0
+Requires-Dist: botocore>=1.33.0
 Provides-Extra: test
 Requires-Dist: pytest>=7.2.0; extra == "test"
 Provides-Extra: docs
@@ -44,6 +47,7 @@ Requires-Dist: botocore>=1.33.0; extra == "dev-utils"
 Requires-Dist: pyarrow>=14.0.1; extra == "dev-utils"
 Requires-Dist: numpy>=1.26.4; extra == "dev-utils"
 Requires-Dist: scikit-learn>=1.6.1; extra == "dev-utils"
+Requires-Dist: awscli>=1.32.0; extra == "dev-utils"
 Requires-Dist: xmltodict>=0.14.2; extra == "dev-utils"
 Provides-Extra: dev
 Requires-Dist: buildstock-fetch[dev-utils,docs,lint,test]; extra == "dev"
@@ -57,15 +61,36 @@ Dynamic: license-file
 [![Commit activity](https://img.shields.io/github/commit-activity/m/switchbox-data/buildstock-fetch)](https://img.shields.io/github/commit-activity/m/switchbox-data/buildstock-fetch)
 [![License](https://img.shields.io/github/license/switchbox-data/buildstock-fetch)](https://img.shields.io/github/license/switchbox-data/buildstock-fetch)
 
-This library simplifies downloading building characteristics and load curve data from NREL's ResStock and ComStock projects.
+A CLI tool, and python library, to simplify downloading building characteristics and load curve data from NREL's ResStock and ComStock projects.
 
 - **Github repository**: <https://github.com/switchbox-data/buildstock-fetch/>
 - **Documentation**: <https://switchbox-data.github.io/buildstock-fetch/>
-- **PyPI page***: <https://pypi.org/project/buildstock-fetch/>
+- **PyPI page**: <https://pypi.org/project/buildstock-fetch/>
+
+## Installing the CLI tool
+
+We recommend using [uv](https://docs.astral.sh/uv/getting-started/installation/) or [pipx](https://pipx.pypa.io/stable/installation/) to install the buildstock-fetch CLI:
+
+```bash
+uv install buildstock-fetch
+```
+or
+
+```bash
+pipx install buildstock-fetch
+```
+
+You'll then be able to access the `bsf` command system-wide:
+
+```bash
+bsf --help
+```
 
 ## Installing the library
 
-`buildstock-fetch` is available on [PyPI](https://pypi.org/project/buildstock-fetch/) and can be installed via:
+buildstock-fetch is implemented in Python, and we expose our internal functions via a library.
+
+If you're using Python, and you want to install the CLI only for a particular project (rather than system-wide), or you want to user the underlying library, install our [PyPI](https://pypi.org/project/buildstock-fetch/) package via:
 
 ```bash
 pip install buildstock-fetch
@@ -77,26 +102,20 @@ or
 uv add buildstock-fetch
 ```
 
-## Using the library
+## Using the CLI
 
-To use the CLI tool in `buildstock-fetch` run:
+To make it easy to download what you want from NREL's S3 bucket, `bsf` has an interactive mode. Activate it with:
 
 ```bash
 bsf
 ```
 
-to activate the interactive mode. Alternatively, provide the inputs directly. For example,
+Alternatively, you can tell `bsf` exactly what to download via CLI args:
 
 ```bash
 bsf --product resstock --release_year 2022 --weather_file tmy3 --release_version 1 --states CA --file_type "hpxml metadata" --upgrade_id "0 1 2" --output_directory ./CA_data
 ```
 
-If the above options don't work, try:
-
-```bash
-python -m buildstock_fetch
-```
-
 For more details about the usage, see [Usage](https://switchbox-data.github.io/buildstock-fetch/usage/)
 
 ## Developing the library

{buildstock_fetch-1.3.1.dist-info → buildstock_fetch-1.4.3.dist-info}/RECORD

@@ -1,8 +1,9 @@
 buildstock_fetch/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 buildstock_fetch/__main__.py,sha256=wEPNJ-s7F6KcRQ_4B5Xh08uqvYZHno5F2R8DU0BMBtk,80
-buildstock_fetch/main.py,sha256=6NAYxs_5yW0PpNgPdCgmaJJUqgSF-InrMO8xZJe4npQ,73839
-buildstock_fetch/main_cli.py,sha256=3zKJ5sXG2QGmAs--kZPQy1qhLEnaw5gvi4RoH_q65dI,31891
-buildstock_fetch/data/buildstock_releases.json,sha256=rHbNkWtTi6VXFim7xtvhwFWQUvtqvcbCfjtvRjkWV-4,10853
+buildstock_fetch/main.py,sha256=yZ8xoYWnoyeTIDMXzVnbQt57a2NAZS7bEPRDtj_SuiU,90887
+buildstock_fetch/main_cli.py,sha256=ZZ6Yn7rBfXguCiUSszKlB0L-FY88ZJM_HXLC8o1EGNc,36311
+buildstock_fetch/data/buildstock_releases.json,sha256=XL-D1Xdix59sFGbS6vKFiGhQakhhPrwn14N-Tgt9iuk,11620
+buildstock_fetch/data/buildstock_upgrades_lookup.json,sha256=CCc2dV6voD8r6WpBBq9zoxhVQGAPcUGmAoFyKoUcUpo,1486
 buildstock_fetch/data/building_data/combined_metadata.parquet/product=comstock/release_year=2021/weather_file=amy2018/release_version=1/state=AK/d1454abff0d94c8090af7b3e923c473b-0.parquet,sha256=nG6H3oGyDzPk1B15YmFd_U81PsA14uABqqwK7P30nKE,7059
 buildstock_fetch/data/building_data/combined_metadata.parquet/product=comstock/release_year=2021/weather_file=amy2018/release_version=1/state=AK/dcd864cc169b4695be2b9775b1a054ae-0.parquet,sha256=fsREWV9g4fsA3cIWqyPnXVwd7FsJxED2btYpmyOvnbQ,7163
 buildstock_fetch/data/building_data/combined_metadata.parquet/product=comstock/release_year=2021/weather_file=amy2018/release_version=1/state=AL/d1454abff0d94c8090af7b3e923c473b-0.parquet,sha256=jiTG48ly-LZwfwAL3THdfRzHDG1qEogoxO7P78U4WOU,41201
@@ -1602,9 +1603,9 @@ buildstock_fetch/data/building_data/combined_metadata.parquet/product=resstock/r
 buildstock_fetch/data/load_curve_column_map/2022_resstock_load_curve_columns.csv,sha256=9UoTPlvxR3RqsxH8i4tI75lLtdSAT-HbAFxwlzvAYNY,7339
 buildstock_fetch/data/load_curve_column_map/2024_resstock_load_curve_columns.csv,sha256=TIxqsE-iVHE5tYq9oPSgBxIVbd5qfyDcJG_eTqds9aY,7471
 buildstock_fetch/data/weather_station_map/weather_station_map.parquet,sha256=igNrx-UGH20CqPcjANTDrrMyj6Z4_JcXIg2aaCNhFRg,346990
-buildstock_fetch-1.3.1.dist-info/licenses/LICENSE,sha256=TJeh2yvO8__8Rbamd8r48-zvlFCINAsu9nOo5QdMRX8,1066
-buildstock_fetch-1.3.1.dist-info/METADATA,sha256=hdj6JpUKIqsyAS_2CIQL-CHruvKiau28by_d6MIrebY,7607
-buildstock_fetch-1.3.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-buildstock_fetch-1.3.1.dist-info/entry_points.txt,sha256=C7zPk3BSLcI47ymvYKI05nvfRJMEXz4BPIIDKsjePn8,54
-buildstock_fetch-1.3.1.dist-info/top_level.txt,sha256=-PGb2C-Tb3O-wPqUHSOBrvJqRzNHgY_KTbTsXaHIo5M,17
-buildstock_fetch-1.3.1.dist-info/RECORD,,
+buildstock_fetch-1.4.3.dist-info/licenses/LICENSE,sha256=TJeh2yvO8__8Rbamd8r48-zvlFCINAsu9nOo5QdMRX8,1066
+buildstock_fetch-1.4.3.dist-info/METADATA,sha256=7TaxdMpRmwemxFqaneiJ09sXgPzlcuc_xBUIPGdzTn4,8323
+buildstock_fetch-1.4.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+buildstock_fetch-1.4.3.dist-info/entry_points.txt,sha256=C7zPk3BSLcI47ymvYKI05nvfRJMEXz4BPIIDKsjePn8,54
+buildstock_fetch-1.4.3.dist-info/top_level.txt,sha256=-PGb2C-Tb3O-wPqUHSOBrvJqRzNHgY_KTbTsXaHIo5M,17
+buildstock_fetch-1.4.3.dist-info/RECORD,,