pacer-client 1.1.0rc1__tar.gz

pacer_client-1.1.0rc1/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2018-2026, Alliance for Energy Innovation, LLC, and other contributors. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
+following conditions are met:
+
+(1) Redistributions of source code must retain the above copyright notice, this list of conditions and the following
+disclaimer.
+
+(2) Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
+disclaimer in the documentation and/or other materials provided with the distribution.
+
+(3) Neither the name of the copyright holder nor the names of any contributors may be used to endorse or promote products
+derived from this software without specific prior written permission from the respective party.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) AND ANY CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
+INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S), ANY CONTRIBUTORS, THE UNITED STATES GOVERNMENT, OR THE UNITED
+STATES DEPARTMENT OF ENERGY, NOR ANY OF THEIR EMPLOYEES, BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
+USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

pacer_client-1.1.0rc1/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: pacer-client
+Version: 1.1.0rc1
+Summary: A standalone client for the NLR's Alfalfa application
+License: LICENSE.txt
+License-File: LICENSE.txt
+Author: Kyle Benne
+Author-email: kyle.benne@nlr.gov
+Requires-Python: >=3.10
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: 3.14
+Requires-Dist: requests-toolbelt (>=1.0,<1.1)
+Description-Content-Type: text/markdown
+
+# Pacer Client
+
+The purpose of this repository is to provide a standalone client for use with the Alfalfa application. It additionally includes a Historian to quickly/easily enable saving of results from Alfalfa simulations.
+
+## Usage
+
+This repo is packaged and hosted on [PyPI here](https://pypi.org/project/pacer-client/).
+
+```bash
+pip install pacer-client
+```
+
+```python
+from pacer_client.pacer_client import PacerClient
+
+client = PacerClient("http://localhost")
+```
+
+> **Renaming from `alfalfa-client`:** this project was renamed from `alfalfa-client`/`AlfalfaClient` to
+> `pacer-client`/`PacerClient`. During the transition, both names keep working: `AlfalfaClient` is an alias of
+> `PacerClient`, and the `alfalfa_client` package/`pip install alfalfa-client` continue to be published with
+> identical functionality (see `alfalfa_client/__init__.py`). `import alfalfa_client` (in any form) emits a
+> `DeprecationWarning` pointing you to `pacer_client`; the `alfalfa-client` name and imports will eventually be
+> removed, so new code should prefer `pacer_client`/`PacerClient`.
+
+Additional documentation for the functions of `pacer-client` can be found [here](https://natlabrockies.github.io/alfalfa-client/).
+
+## Development
+
+Prerequisites:
+
+- [poetry](https://python-poetry.org/docs/#installation) for managing environment
+
+Cloning and Installing:
+
+```bash
+git clone https://github.com/NatLabRockies/alfalfa-client.git
+cd alfalfa-client
+poetry install
+```
+
+Running Tests:
+All `pacer-client` tests currently require a running instance of [Alfalfa](https://github.com/NatLabRockies/alfalfa) with at least 2 workers.
+
+```bash
+poetry run pytest -m integration
+```
+
+## Releasing
+
+Every PR must carry at least one categorization label (`breaking`, `enhancement`, `bug`, `dependencies`,
+`github_actions`, `python`, `documentation`, `add test`, or `do not publish` to exclude it) — this is enforced by
+the `Verify Pull Request Labeling` CI check and is what allows GitHub to group the auto-generated release notes
+correctly, per `.github/release.yml`.
+
+1. Confirm all PRs intended for the release are merged into `develop`, are labeled correctly, and CI is passing.
+1. Bump the version on `develop` (assume version is 0.1.2): `poetry version 0.1.2`, open a PR, and merge it once tests pass.
+1. Fast-forward `main` to `develop` so both branches point at the same commit (do **not** create a merge commit):
+   ```bash
+   git checkout main
+   git merge --ff-only develop
+   git push origin main
+   ```
+   If `--ff-only` fails, `main` and `develop` have diverged (e.g. a hotfix landed only on `main`) — reconcile that first so the release doesn't leave the branches out of sync.
+1. Draft a release on the GitHub repository targeting `main` (tag `v0.1.2`) and click **"Generate release notes"**
+   (UI), or run `gh release create v0.1.2 --target main --generate-notes --draft` — do not publish yet.
+1. Copy the generated "## What's Changed" notes into `CHANGELOG.md` under the `# Unreleased` section, then (as part of the release) rename that header to `# pacer-client Version 0.1.2` and add the `**Full Changelog**` line.
+1. Commit this alongside the version bump PR, or as a quick follow-up commit on `main`.
+1. Publish the drafted release. This triggers the `PyPIRelease` workflow (`.github/workflows/pypi_release.yml`),
+   which builds the package **twice** (once as `pacer-client`, once with the name swapped to `alfalfa-client`) and
+   publishes both to PyPI via trusted publishing — no manual `poetry build`/`poetry publish` needed. Both
+   distributions have identical contents; this keeps `pip install alfalfa-client` working during the rename
+   transition (see the note in the README's Usage section). Publishing to `alfalfa-client` requires a Trusted
+   Publisher to be configured on that PyPI project pointing at the `pypi_release_alfalfa` environment — set this
+   up once on [pypi.org](https://pypi.org/manage/project/alfalfa-client/settings/publishing/) before the first
+   release after this change.
+1. Confirm the new version appears on both [pacer-client](https://pypi.org/project/pacer-client/) and
+   [alfalfa-client](https://pypi.org/project/alfalfa-client/) on PyPI, and that the release notes and
+   `CHANGELOG.md` match.
+

pacer_client-1.1.0rc1/README.md

@@ -0,0 +1,79 @@
+# Pacer Client
+
+The purpose of this repository is to provide a standalone client for use with the Alfalfa application. It additionally includes a Historian to quickly/easily enable saving of results from Alfalfa simulations.
+
+## Usage
+
+This repo is packaged and hosted on [PyPI here](https://pypi.org/project/pacer-client/).
+
+```bash
+pip install pacer-client
+```
+
+```python
+from pacer_client.pacer_client import PacerClient
+
+client = PacerClient("http://localhost")
+```
+
+> **Renaming from `alfalfa-client`:** this project was renamed from `alfalfa-client`/`AlfalfaClient` to
+> `pacer-client`/`PacerClient`. During the transition, both names keep working: `AlfalfaClient` is an alias of
+> `PacerClient`, and the `alfalfa_client` package/`pip install alfalfa-client` continue to be published with
+> identical functionality (see `alfalfa_client/__init__.py`). `import alfalfa_client` (in any form) emits a
+> `DeprecationWarning` pointing you to `pacer_client`; the `alfalfa-client` name and imports will eventually be
+> removed, so new code should prefer `pacer_client`/`PacerClient`.
+
+Additional documentation for the functions of `pacer-client` can be found [here](https://natlabrockies.github.io/alfalfa-client/).
+
+## Development
+
+Prerequisites:
+
+- [poetry](https://python-poetry.org/docs/#installation) for managing environment
+
+Cloning and Installing:
+
+```bash
+git clone https://github.com/NatLabRockies/alfalfa-client.git
+cd alfalfa-client
+poetry install
+```
+
+Running Tests:
+All `pacer-client` tests currently require a running instance of [Alfalfa](https://github.com/NatLabRockies/alfalfa) with at least 2 workers.
+
+```bash
+poetry run pytest -m integration
+```
+
+## Releasing
+
+Every PR must carry at least one categorization label (`breaking`, `enhancement`, `bug`, `dependencies`,
+`github_actions`, `python`, `documentation`, `add test`, or `do not publish` to exclude it) — this is enforced by
+the `Verify Pull Request Labeling` CI check and is what allows GitHub to group the auto-generated release notes
+correctly, per `.github/release.yml`.
+
+1. Confirm all PRs intended for the release are merged into `develop`, are labeled correctly, and CI is passing.
+1. Bump the version on `develop` (assume version is 0.1.2): `poetry version 0.1.2`, open a PR, and merge it once tests pass.
+1. Fast-forward `main` to `develop` so both branches point at the same commit (do **not** create a merge commit):
+   ```bash
+   git checkout main
+   git merge --ff-only develop
+   git push origin main
+   ```
+   If `--ff-only` fails, `main` and `develop` have diverged (e.g. a hotfix landed only on `main`) — reconcile that first so the release doesn't leave the branches out of sync.
+1. Draft a release on the GitHub repository targeting `main` (tag `v0.1.2`) and click **"Generate release notes"**
+   (UI), or run `gh release create v0.1.2 --target main --generate-notes --draft` — do not publish yet.
+1. Copy the generated "## What's Changed" notes into `CHANGELOG.md` under the `# Unreleased` section, then (as part of the release) rename that header to `# pacer-client Version 0.1.2` and add the `**Full Changelog**` line.
+1. Commit this alongside the version bump PR, or as a quick follow-up commit on `main`.
+1. Publish the drafted release. This triggers the `PyPIRelease` workflow (`.github/workflows/pypi_release.yml`),
+   which builds the package **twice** (once as `pacer-client`, once with the name swapped to `alfalfa-client`) and
+   publishes both to PyPI via trusted publishing — no manual `poetry build`/`poetry publish` needed. Both
+   distributions have identical contents; this keeps `pip install alfalfa-client` working during the rename
+   transition (see the note in the README's Usage section). Publishing to `alfalfa-client` requires a Trusted
+   Publisher to be configured on that PyPI project pointing at the `pypi_release_alfalfa` environment — set this
+   up once on [pypi.org](https://pypi.org/manage/project/alfalfa-client/settings/publishing/) before the first
+   release after this change.
+1. Confirm the new version appears on both [pacer-client](https://pypi.org/project/pacer-client/) and
+   [alfalfa-client](https://pypi.org/project/alfalfa-client/) on PyPI, and that the release notes and
+   `CHANGELOG.md` match.

pacer_client-1.1.0rc1/alfalfa_client/__init__.py

@@ -0,0 +1,22 @@
+# :copyright (c) Alliance for Energy Innovation, LLC, and other contributors.
+# See also https://github.com/NatLabRockies/alfalfa-client/blob/develop/LICENSE.txt
+
+# `alfalfa_client` is a compatibility package: `alfalfa-client` is being renamed to
+# `pacer-client`. This package re-exports the `pacer_client` API under the original
+# `alfalfa_client` names/import paths so existing code keeps working unchanged while
+# both names are supported. New code should prefer `import pacer_client`.
+
+import warnings
+
+from alfalfa_client.alfalfa_client import AlfalfaClient
+
+warnings.warn(
+    "The 'alfalfa-client' package is being renamed to 'pacer-client'. `alfalfa_client` / "
+    "`AlfalfaClient` still work today, but this compatibility package will be removed in a "
+    "future release. Please migrate to `import pacer_client` / `from pacer_client import "
+    "PacerClient` (`pip install pacer-client`).",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+__all__ = ["AlfalfaClient"]

pacer_client-1.1.0rc1/alfalfa_client/alfalfa_client.py

@@ -0,0 +1,10 @@
+# :copyright (c) Alliance for Energy Innovation, LLC, and other contributors.
+# See also https://github.com/NatLabRockies/alfalfa-client/blob/develop/LICENSE.txt
+
+# Compatibility shim for the pre-rename `alfalfa_client.alfalfa_client` module.
+# `AlfalfaClient` and `PacerClient` are the same class; see `pacer_client.pacer_client`.
+
+from pacer_client.pacer_client import ModelID, PacerClient, RunID
+from pacer_client.pacer_client import PacerClient as AlfalfaClient
+
+__all__ = ["AlfalfaClient", "ModelID", "PacerClient", "RunID"]

pacer_client-1.1.0rc1/alfalfa_client/lib.py

@@ -0,0 +1,28 @@
+# :copyright (c) Alliance for Energy Innovation, LLC, and other contributors.
+# See also https://github.com/NatLabRockies/alfalfa-client/blob/develop/LICENSE.txt
+
+# Compatibility shim for the pre-rename `alfalfa_client.lib` module. These helpers were
+# never renamed (they describe the Alfalfa server, not the client package), so this is
+# a straight re-export of `pacer_client.lib`.
+
+from pacer_client.lib import (
+    AlfalfaAPIException,
+    AlfalfaClientException,
+    AlfalfaException,
+    AlfalfaWorkerException,
+    common_root,
+    create_zip,
+    parallelize,
+    prepare_model,
+)
+
+__all__ = [
+    "AlfalfaAPIException",
+    "AlfalfaClientException",
+    "AlfalfaException",
+    "AlfalfaWorkerException",
+    "common_root",
+    "create_zip",
+    "parallelize",
+    "prepare_model",
+]

pacer_client-1.1.0rc1/pacer_client/__init__.py

@@ -0,0 +1,6 @@
+# :copyright (c) Alliance for Energy Innovation, LLC, and other contributors.
+# See also https://github.com/NatLabRockies/alfalfa-client/blob/develop/LICENSE.txt
+
+from pacer_client.pacer_client import AlfalfaClient, PacerClient
+
+__all__ = ["AlfalfaClient", "PacerClient"]

pacer_client-1.1.0rc1/pacer_client/lib.py

@@ -0,0 +1,148 @@
+# :copyright (c) Alliance for Energy Innovation, LLC, and other contributors.
+# See also https://github.com/NatLabRockies/alfalfa-client/blob/develop/LICENSE.txt
+
+import concurrent.futures
+import functools
+import json
+import tempfile
+from functools import partial
+from os import PathLike
+from pathlib import Path
+from zipfile import ZipFile
+
+from requests import Response
+
+
+def parallelize(func):
+    """Parallelize a function
+    Decorator which, when applied to a function, will parallelize the function
+    on the first non-self parameter. If a list is passed n instances of the
+    original function will be called inside Threads. The results will be returned
+    as a list with the same order as the original. If a list is not passed, the
+    original function will be called.
+
+    """
+
+    def parallel_call(func, iter_vals: list, args: list = [], kwargs: dict = {}):
+        responses = [None] * len(iter_vals)
+        with concurrent.futures.ThreadPoolExecutor() as executor:
+            future_to_index = {executor.submit(func, iter_vals[i], *args, **kwargs): i for i in range(len(iter_vals))}
+            for future in concurrent.futures.as_completed(future_to_index):
+                arg = future_to_index[future]
+
+                responses[arg] = future.result()
+        return responses
+
+    @functools.wraps(func)
+    def parallel_wrapper(self, *args, **kwargs):
+        # Find the first parameter as either an arg or kwarg
+        if len(args) > 0:
+            val = args[0]
+            args = args[1:]
+        else:
+            first_varname = func.__code__.co_varnames[1]
+            if first_varname in kwargs:
+                val = kwargs[first_varname]
+                del kwargs[first_varname]
+            else:
+                raise TypeError(f"{func.__name__}() missing 1 required positional argument: '{first_varname}'")
+
+        if isinstance(val, list):
+            return parallel_call(partial(func, self), val, args, kwargs)
+        else:
+            return func(self, val, *args, **kwargs)
+
+    return parallel_wrapper
+
+
+def common_root(*paths: PathLike) -> Path:
+    path_parts = []
+    min_len = 0
+    for path in paths:
+        parts = list(Path(path).parts)
+        if len(parts) < min_len or min_len == 0:
+            min_len = len(parts)
+        path_parts.append(parts)
+
+    root_parts = path_parts[0][0:min_len]
+    path_parts.pop(0)
+    while len(root_parts) > 0:
+        current_min_len = min_len
+        part = root_parts[-1]
+        for parts in path_parts:
+            if part != parts[min_len - 1]:
+                root_parts.pop()
+                min_len -= 1
+                break
+        if current_min_len == min_len:
+            break
+
+    return Path(*root_parts)
+
+
+def create_zip(*paths: PathLike) -> str:
+    """Create Zip
+    Takes a directory and creates a temporary zip file of it.
+
+    :param dir: directory to create zip of
+
+    :returns: path of zip file
+    """
+    paths = [Path(path) for path in paths]
+    root_dir = common_root(*paths)
+    _zip_file_fd, zip_file_path = tempfile.mkstemp(prefix=root_dir.stem, suffix=".zip")
+    zip_file = ZipFile(zip_file_path, "w")
+    for path in paths:
+        if path.is_file():
+            zip_file.write(path, path.relative_to(root_dir))
+        for file_path in path.glob("**/*"):
+            zip_file.write(file_path, file_path.relative_to(root_dir))
+
+    zip_file.close()
+
+    return zip_file_path
+
+
+def prepare_model(model_path: PathLike) -> str:
+    """Prepares model for upload
+    Takes a file or directory. If the input is a file it returns the file.
+    If the input is a directory it zips the directory and returns the path to that zip.
+
+    :param model_path: path to model
+
+    :returns: path of prepared model
+    """
+    model_path = Path(model_path)
+    if model_path.is_dir():
+        return str(create_zip(str(model_path.absolute())))
+    else:
+        return str(model_path.absolute())
+
+
+class AlfalfaException(Exception):
+    """Wrapper for exceptions which come from alfalfa"""
+
+
+class AlfalfaWorkerException(AlfalfaException):
+    """Wrapper for exceptions from the alfalfa worker"""
+
+
+class AlfalfaAPIException(AlfalfaException):
+    """Wrapper for API errors"""
+
+    def __init__(self, response: Response, *args: object) -> None:
+        self.response = response
+        body = response.json()
+        super().__init__(body["message"], *args)
+
+        if "payload" in body:
+            self.payload = json.dumps(body["payload"])
+
+    def __str__(self) -> str:
+        if hasattr(self, "payload"):
+            return super().__str__() + "\nAPI Payload: \n" + json.dumps(self.payload)
+        return super().__str__()
+
+
+class AlfalfaClientException(AlfalfaException):
+    """Wrapper for exceptions in client operation"""

pacer_client-1.1.0rc1/pacer_client/pacer_client.py

@@ -0,0 +1,319 @@
+# :copyright (c) Alliance for Energy Innovation, LLC, and other contributors.
+# See also https://github.com/NatLabRockies/alfalfa-client/blob/develop/LICENSE.txt
+
+import errno
+import json
+import os
+from collections import OrderedDict
+from datetime import datetime
+from time import sleep, time
+from urllib.parse import urljoin
+
+import requests
+from requests_toolbelt import MultipartEncoder
+
+from pacer_client.lib import AlfalfaAPIException, AlfalfaClientException, AlfalfaException, parallelize, prepare_model
+
+ModelID = str
+RunID = str
+
+
+class PacerClient:
+    """PacerClient is a wrapper for the Alfalfa REST API"""
+
+    def __init__(self, host: str = "http://localhost", api_version: str = "v2"):
+        """Create a new alfalfa client instance
+
+        :param host: url for host of alfalfa web server
+        :param api_version: version of alfalfa api to use (probably don't change this)
+        """
+        self.host = host.rstrip("/")
+        self.haystack_filter = self.host + "/haystack/read?filter="
+        self.haystack_json_header = {"Content-Type": "application/json", "Accept": "application/json"}
+
+        self.host = host
+        self.api_version = api_version
+        self.point_translation_map = {}
+
+    @property
+    def url(self):
+        return urljoin(self.host, f"api/{self.api_version}/")
+
+    def _request(self, endpoint: str, method="POST", parameters=None) -> requests.Response:
+        if parameters:
+            response = requests.request(
+                method=method, url=self.url + endpoint, json=parameters, headers={"Content-Type": "application/json"}
+            )
+        else:
+            response = requests.request(method=method, url=self.url + endpoint)
+
+        if response.status_code >= 400:
+            try:
+                raise AlfalfaAPIException(response)
+            except json.JSONDecodeError:
+                pass
+        response.raise_for_status()
+
+        return response
+
+    @parallelize
+    def status(self, run_id: RunID | list[RunID]) -> str:
+        """Get status of run
+
+        :param run_id: id of run or list of ids
+        :returns: status of run
+        """
+        response = self._request(f"runs/{run_id}", method="GET").json()
+        return response["payload"]["status"]
+
+    @parallelize
+    def get_error_log(self, run_id: RunID | list[RunID]) -> str:
+        """Get error log from run
+
+        :param run_id: id of run or list of ids
+        :returns: error log from run
+        """
+        response = self._request(f"runs/{run_id}", method="GET").json()
+        return response["payload"]["errorLog"]
+
+    @parallelize
+    def wait(self, run_id: RunID | list[RunID], desired_status: str, timeout: float = 600) -> None:
+        """Wait for a run to have a certain status or timeout with error
+
+        :param run_id: id of run or list of ids
+        :param desired_status: status to wait for
+        :param timeout: timeout length in seconds
+        """
+
+        start_time = time()
+        previous_status = None
+        current_status = None
+        while time() - timeout < start_time:
+            try:
+                current_status = self.status(run_id)
+            except AlfalfaAPIException as e:
+                if e.response.status_code != 404:
+                    raise e
+
+            if current_status == "ERROR":
+                error_log = self.get_error_log(run_id)
+                raise AlfalfaException(error_log)
+
+            if current_status != previous_status:
+                print(f"Desired status: {desired_status}\t\tCurrent status: {current_status}")
+                previous_status = current_status
+            if current_status == desired_status.upper():
+                return
+            sleep(2)
+        raise AlfalfaClientException(f"'wait' timed out waiting for status: '{desired_status}', current status: '{current_status}'")
+
+    def upload_model(self, model_path: os.PathLike) -> ModelID:
+        """Upload a model to alfalfa
+
+        :param model_path: path to model file or folder or list of paths
+
+        :returns: id of model"""
+        if not os.path.exists(model_path):
+            raise FileNotFoundError(errno.ENOENT, os.strerror(errno.ENOENT), model_path)
+        model_path = prepare_model(model_path)
+        filename = os.path.basename(model_path)
+
+        payload = {"modelName": filename}
+
+        response = self._request("models/upload", parameters=payload)
+        response_body = response.json()["payload"]
+        post_url = response_body["url"]
+
+        model_id = response_body["modelId"]
+        form_data = OrderedDict(response_body["fields"])
+        form_data["file"] = ("filename", open(model_path, "rb"))
+
+        encoder = MultipartEncoder(fields=form_data)
+        response = requests.post(post_url, data=encoder, headers={"Content-Type": encoder.content_type})
+        response.raise_for_status()
+        assert response.status_code == 204, "Model upload failed"
+
+        return model_id
+
+    def create_run_from_model(self, model_id: ModelID | list[ModelID], wait_for_status: bool = True) -> RunID:
+        """Create a run from a model
+
+        :param model_id: id of model to create a run from or list of ids
+        :param wait_for_status: wait for model to be "READY" before returning
+
+        :returns: id of run created"""
+        response = self._request(f"models/{model_id}/createRun")
+        run_id = response.json()["payload"]["runId"]
+
+        if wait_for_status:
+            self.wait(run_id, "ready")
+
+        return run_id
+
+    @parallelize
+    def submit(self, model_path: str | list[str], wait_for_status: bool = True) -> RunID:
+        """Submit a model to alfalfa
+
+        :param model_path: path to the model to upload or list of paths
+        :param wait_for_status: wait for model to be "READY" before returning
+
+        :returns: id of created run
+        :rtype: str"""
+
+        model_id = self.upload_model(model_path)
+
+        # After the file has been uploaded, then tell BOPTEST to process the run
+        # This is done not via the haystack api, but through a REST api
+        run_id = self.create_run_from_model(model_id, wait_for_status=wait_for_status)
+
+        return run_id
+
+    @parallelize
+    def start(
+        self,
+        run_id: RunID | list[RunID],
+        start_datetime: datetime,
+        end_datetime: datetime,
+        timescale: int = 5,
+        external_clock: bool = False,
+        realtime: bool = False,
+        wait_for_status: bool = True,
+    ):
+        """Start one run from a model.
+
+        :param run_id: id of run or list of ids
+        :param start_datetime: time to start the model from
+        :param end_datetime: time to stop the model at (may not be honored for external_clock=True)
+        :param timescale: multiple of real time to run model at (for external_clock=False)
+        :param external_clock: run model with an external advancer
+        :param realtime: run model with timescale=1
+        :param wait_for_status: wait for model to be "RUNNING" before returning
+        """
+        parameters = {
+            "startDatetime": str(start_datetime),
+            "endDatetime": str(end_datetime),
+            "timescale": timescale,
+            "externalClock": external_clock,
+            "realtime": realtime,
+        }
+
+        response = self._request(f"runs/{run_id}/start", parameters=parameters)
+
+        assert response.status_code == 204, "Got wrong status_code from alfalfa"
+
+        if wait_for_status:
+            self.wait(run_id, "running")
+
+    @parallelize
+    def stop(self, run_id: RunID | list[RunID], wait_for_status: bool = True):
+        """Stop a run
+
+        :param run_id: id of the run or list of ids
+        :param wait_for_status: wait for the run to be "complete" before returning
+        """
+
+        response = self._request(f"runs/{run_id}/stop")
+
+        assert response.status_code == 204, "Got wrong status_code from alfalfa"
+
+        if wait_for_status:
+            self.wait(run_id, "complete")
+
+    @parallelize
+    def advance(self, run_id: RunID | list[RunID]) -> None:
+        """Advance a run 1 timestep
+
+        :param run_id: id of run or list of ids"""
+        self._request(f"runs/{run_id}/advance")
+
+    def get_inputs(self, run_id: str) -> list[str]:
+        """Get inputs of run
+
+        :param run_id: id of run
+        :returns: list of input names"""
+
+        response = self._request(f"runs/{run_id}/points", method="POST", parameters={"pointTypes": ["INPUT", "BIDIRECTIONAL"]})
+        response_body = response.json()["payload"]
+        inputs = []
+        for point in response_body:
+            if point["name"] != "":
+                inputs.append(point["name"])
+        return inputs
+
+    def set_inputs(self, run_id: str, inputs: dict) -> None:
+        """Set inputs of run
+
+        :param run_id: id of run
+        :param inputs: dictionary of point names and input values"""
+        point_writes = {}
+        for name, value in inputs.items():
+            id = self._get_point_translation(run_id, name)
+            if id:
+                point_writes[id] = value
+            else:
+                raise AlfalfaClientException(f"No Point exists with name {name}")
+        self._request(f"runs/{run_id}/points/values", method="PUT", parameters={"points": point_writes})
+
+    def get_outputs(self, run_id: str) -> dict:
+        """Get outputs of run
+
+        :param run_id: id of run
+        :returns: dictionary of output names and values"""
+        response = self._request(f"runs/{run_id}/points/values", method="POST", parameters={"pointTypes": ["OUTPUT", "BIDIRECTIONAL"]})
+        response_body = response.json()["payload"]
+        outputs = {}
+        for point, value in response_body.items():
+            name = self._get_point_translation(run_id, point)
+            outputs[name] = value
+
+        return outputs
+
+    @parallelize
+    def get_sim_time(self, run_id: RunID | list[RunID]) -> datetime:
+        """Get sim_time of run
+
+        :param run_id: id of site or list of ids
+        :returns: datetime of site
+        """
+        response = self._request(f"runs/{run_id}/time", method="GET")
+        response_body = response.json()["payload"]
+        return datetime.strptime(response_body["time"], "%Y-%m-%d %H:%M:%S")
+
+    def set_alias(self, alias: str, run_id: RunID) -> None:
+        """Set alias to point to a run_id
+
+        :param run_id: id of run to point alias to
+        :param alias: alias to use"""
+
+        self._request(f"aliases/{alias}", method="PUT", parameters={"runId": run_id})
+
+    def get_alias(self, alias: str) -> RunID:
+        """Get run_id from alias
+
+        :param alias: alias
+        :returns: Id of run associated with alias"""
+
+        response = self._request(f"aliases/{alias}", method="GET")
+        response_body = response.json()["payload"]
+        return response_body
+
+    def _get_point_translation(self, *args):
+        if args in self.point_translation_map:
+            return self.point_translation_map[args]
+        if args not in self.point_translation_map:
+            self._fetch_points(args[0])
+        if args in self.point_translation_map:
+            return self.point_translation_map[args]
+        return None
+
+    def _fetch_points(self, run_id):
+        response = self._request(f"runs/{run_id}/points", method="GET")
+        for point in response.json()["payload"]:
+            self.point_translation_map[(run_id, point["name"])] = point["id"]
+            self.point_translation_map[(run_id, point["id"])] = point["name"]
+
+
+# `alfalfa-client` is being renamed to `pacer-client`. `AlfalfaClient` is kept as an
+# alias of `PacerClient` for backwards compatibility while both names are supported;
+# new code should prefer `PacerClient`.
+AlfalfaClient = PacerClient

pacer_client-1.1.0rc1/pyproject.toml

@@ -0,0 +1,40 @@
+[tool.poetry]
+name = "pacer-client"
+version = "1.1.0rc1"
+description = "A standalone client for the NLR's Alfalfa application"
+authors = [
+    'Kyle Benne <kyle.benne@nlr.gov>',
+    'Brian Ball <brian.ball@nlr.gov>',
+    'Cory Mosiman <cory.mosiman@nlr.gov>',
+    'Nicholas Long <nicholas.long@nlr.gov>',
+    'Willy Bernal <willy.bernalheredia@nlr.gov>',
+    'Yanfei Li <yanfei.li@nlr.gov>',
+    'Tobias Shapinsky <tobias.shapinsky@nlr.gov>'
+]
+readme = 'README.md'
+license = 'LICENSE.txt'
+# `alfalfa_client` is a backwards-compatibility shim re-exporting `pacer_client`
+# (see alfalfa_client/__init__.py). Both packages ship in every distribution so
+# `pacer-client` and `alfalfa-client` installs stay import-compatible during the
+# rename transition.
+packages = [
+    { include = "pacer_client" },
+    { include = "alfalfa_client" },
+]
+
+[tool.poetry.dependencies]
+python = ">=3.10"
+
+requests-toolbelt = "~1.0"
+
+[tool.poetry.group.dev.dependencies]
+ipykernel = ">=6.21.2,<8.0.0"
+sphinx = ">=6.1.3,<9.0.0"
+pre-commit = ">=2.21,<4.7"
+pytest = ">=7.2,<9.2"
+ruff = "^0.15.22"
+
+
+[build-system]
+requires = ["poetry_core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"