buildstock-fetch

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/

Installing the CLI tool

We recommend using uv or pipx to install the buildstock-fetch CLI:

uv tool install buildstock-fetch

or

pipx install buildstock-fetch

You'll then be able to access the bsf command system-wide:

bsf --help

Installing the library

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 package via:

pip install buildstock-fetch

or

uv add buildstock-fetch

Using the CLI

To make it easy to download what you want from NREL's S3 bucket, bsf has an interactive mode. Activate it with:

bsf

Alternatively, you can tell bsf exactly what to download via CLI args:

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

For more details about the usage, see Usage

Developing the library

To simplify development, this library uses devcontainers for reproducible development environments and the just command runner for all major tasks.

Available commands are defined in Justfile. To view available them:

just --list

Setting up development environment

This library uses uv for managing python versions, virtual environments, and packages.

However, given the presence of system dependencies, the easiest way to set up the library's develop 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.

If you prefer not to use a devcontainer, you can install uv, install the pre-commit hooks, launch the virtualenv, and download the packages (pinned in uv.lock) by running:

./devcontainer/postCreateCommand.sh
just install

Using a system package manager (like brew or apt), you'll also need to manually install just and quarto.

Adding a package

To add a python package to the project:

uv add <package-name>

This replaces pip install <package-name>, and has the effect of adding the package to pyproject.toml, as well as pinning the package version in uv.lock.

To add a package that will only be used as a development tool:

uv add --dev <package-name>

This will update the dev dependency-groups in pyproject.toml, and ensure that the package isn't declared as a run-time dependency of the library itself.

Running code quality checks

We use ruff for linting and code formatting, mypy for type checking, and a series of post-commit hooks for validating YAML, JSON, whitespaces, and so on.

To run code quality checks:

just check

The checks will also be run automatically by Github Actions when opening PRs, merging to main, or creating a new release.

Running tests

Our test are written using pytest and live in tests/. They are checked against multiple python versions using tox.

To run the tests:

just test

Rendering docs

We use mkdocs and mkdocs-material for writing and rendering docs. The docs are written in markdown and live in docs/.

To dynamically render the docs as you develop them:

just docs

To statically render the docs into HTML:

just docs-test

The docs are served by Github Pages out of the gh-pages branch. We do not publish them manually: they are automatically rendered and published by the Github Actions workflow when merging to main.

Releasing the library

To release the latest version of the library, first update the version number in the pyproject.toml and __init__.py files.

Next, navigate to the library's publish new release page.

Under the Tag: Select tag dragdown menu, enter the latest version number accordingly and select Create new tag

Include relevant notes for the release inside the Write textbox. Once finished, click the Publish release button at the bottom to publish the latest release.

---

Repository initiated with fpgmaas/cookiecutter-uv.