buildstock-fetch 0.1.0__py3-none-any.whl

buildstock_fetch/main.py

@@ -0,0 +1,85 @@
+import json
+import os
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+import requests
+
+
+@dataclass
+class BuildingID:
+    bldg_id: int
+    release_number: str = "1"
+    release_year: str = "2022"
+    res_com: str = "resstock"
+    weather: str = "tmy3"
+    upgrade_id: str = "0"
+
+    def get_download_url(self) -> str:
+        """Generate the S3 download URL for this building."""
+        return (
+            "https://oedi-data-lake.s3.amazonaws.com/nrel-pds-building-stock/"
+            f"end-use-load-profiles-for-us-building-stock/{self.release_year}/"
+            f"{self.res_com}_{self.weather}_release_{self.release_number}/"
+            f"building_energy_models/upgrade={self.upgrade_id}/"
+            f"bldg{self.bldg_id:07}-up0{self.upgrade_id}.zip"
+        )
+
+    def to_json(self) -> str:
+        """Convert the building ID object to a JSON string."""
+        return json.dumps(asdict(self))
+
+
+def fetch_bldg_ids(state: str) -> list[BuildingID]:
+    """Fetch a list of Building ID's
+
+    Provided a state, returns a list of building ID's for that state.
+
+    Args:
+        state: The state to fetch building ID's for.
+
+    Returns:
+        A list of building ID's for the given state.
+    """
+    if state == "MA":
+        return [
+            BuildingID(bldg_id=7),
+            BuildingID(bldg_id=8),
+            BuildingID(bldg_id=9),
+        ]
+
+    else:
+        raise NotImplementedError(f"State {state} not supported")
+
+
+def fetch_bldg_data(bldg_ids: list[BuildingID]) -> list[Path]:
+    """Download building data for a given list of building ids
+
+    Downloads the data for the given building ids and returns list of paths to the downloaded files.
+
+    Args:
+        bldg_ids: A list of BuildingID objects to download data for.
+
+    Returns:
+        A list of paths to the downloaded files.
+    """
+    data_dir = Path(__file__).parent.parent / "data"
+    downloaded_paths = []
+    os.makedirs(data_dir, exist_ok=True)
+
+    for bldg_id in bldg_ids:
+        response = requests.get(bldg_id.get_download_url(), timeout=30)
+        response.raise_for_status()
+
+        output_path = data_dir / f"{bldg_id.bldg_id:07}_upgrade{bldg_id.upgrade_id}.zip"
+        with open(output_path, "wb") as file:
+            file.write(response.content)
+
+        downloaded_paths.append(output_path)
+    return downloaded_paths
+
+
+if __name__ == "__main__":  # pragma: no cover
+    tmp_ids = fetch_bldg_ids("MA")
+    tmp_data = fetch_bldg_data(tmp_ids)
+    print(f"Downloaded files: {[str(path) for path in tmp_data]}")

buildstock_fetch-0.1.0.dist-info/METADATA

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: buildstock-fetch
+Version: 0.1.0
+Summary: This library simplifies downloading building characteristics and load curve data from NREL's ResStock and ComStock projects.
+Project-URL: Homepage, https://switchbox-data.github.io/buildstock-fetch/
+Project-URL: Repository, https://github.com/switchbox-data/buildstock-fetch
+Project-URL: Documentation, https://switchbox-data.github.io/buildstock-fetch/
+Author-email: Switchbox <bryan@switch.box>
+License-File: LICENSE
+Keywords: python
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: <4.0,>=3.9
+Requires-Dist: requests>=2.32.3
+Description-Content-Type: text/markdown
+
+# buildstock-fetch
+
+[![Release](https://img.shields.io/github/v/release/switchbox-data/buildstock-fetch)](https://img.shields.io/github/v/release/switchbox-data/buildstock-fetch)
+[![Build status](https://img.shields.io/github/actions/workflow/status/switchbox-data/buildstock-fetch/main.yml?branch=main)](https://github.com/switchbox-data/buildstock-fetch/actions/workflows/main.yml?query=branch%3Amain)
+[![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.
+
+- **Github repository**: <https://github.com/switchbox-data/buildstock-fetch/>
+- **Documentation** <https://switchbox-data.github.io/buildstock-fetch/>
+
+## Getting start with the project
+
+### 1. Set Up Your Development Environment
+
+The easiest way to set up the library's dev environment is to use devcontainers. To do so, open up the repo in VSCode or a VSCode fork like Cursor or Positron. The editor will auto-detect the presence of the repo's devcontainer (configured in `.devcontainer/devcontainer.json`). Click "Reopen in Container" to launch the devcontainer.
+
+Alternatively, you can install the environment and the pre-commit hooks on your laptop with
+
+```bash
+make install
+```
+
+You are now ready to start development on the library!
+The github action CI/CD pipeline will be triggered when you open a pull request, merge to main, or when you create a new release.
+
+### 2. Set up PyPI publishing
+
+To finalize the set-up for publishing to PyPI, see [here](https://fpgmaas.github.io/cookiecutter-uv/features/publishing/#set-up-for-pypi).
+
+### 3. Activate automatic documentation
+For activating the automatic documentation with MkDocs, see [here](https://fpgmaas.github.io/cookiecutter-uv/features/mkdocs/#enabling-the-documentation-on-github).
+
+## Releasing a new version
+
+- Create an API Token on [PyPI](https://pypi.org/).
+- Add the API Token to your projects secrets with the name `PYPI_TOKEN` by visiting [this page](https://github.com/switchbox-data/buildstock-fetch/settings/secrets/actions/new).
+- Create a [new release](https://github.com/switchbox-data/buildstock-fetch/releases/new) on Github.
+- Create a new tag in the form `*.*.*`.
+
+For more details, see [here](https://fpgmaas.github.io/cookiecutter-uv/features/cicd/#how-to-trigger-a-release).
+
+---
+
+Repository initiated with [fpgmaas/cookiecutter-uv](https://github.com/fpgmaas/cookiecutter-uv).

buildstock_fetch-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+buildstock_fetch/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+buildstock_fetch/main.py,sha256=Jl-sQ0n8bnelK5RfZSIX5VkcxwPye0VHWV5U-GvfkII,2535
+buildstock_fetch-0.1.0.dist-info/METADATA,sha256=SXBeRuWWJ8mnMagcMy7TLDPbu4ZtG1tFHcKwrT4Hp_0,3803
+buildstock_fetch-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+buildstock_fetch-0.1.0.dist-info/licenses/LICENSE,sha256=TJeh2yvO8__8Rbamd8r48-zvlFCINAsu9nOo5QdMRX8,1066
+buildstock_fetch-0.1.0.dist-info/RECORD,,

buildstock_fetch-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

buildstock_fetch-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Switchbox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.