flowfabricpy 0.1.0__tar.gz

flowfabricpy-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lynker
+
+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.

flowfabricpy-0.1.0/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: flowfabricpy
+Version: 0.1.0
+Summary: Python client for Flowfabric
+Author-email: Paul Linza <plinza@lynker.com>, Mike Johnson <mjohnson@lynker.com>
+License-Expression: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests
+Dynamic: license-file
+
+# flowfabricpy: Effortless Python Access to FlowFabric API
+
+`flowfabricpy` is a powerful Python client for the FlowFabric API, providing seamless access to hydrologic forecasts, reanalysis, rating curves, and datasets. With robust authentication and automatic token caching, you can focus on data science, not on data munging plumbing.
+
+## Key Features
+- **Evolving catalog** of harmonized data from multiple models
+- **Single method access** to all models - both retrospective and forecast
+- **One-time authentication**: Log in once, and your token is cached for future use.
+- **Arrow IPC support**: Fast, memory-efficient data transfer
+
+## Installation
+```py
+#  Install from GitHub:
+pip install git+https://github.com/lynker-spatial/flowfabric-py#egg=flowfabricpy
+```
+
+## Quick Start
+```py
+# 1. List available datasets
+datasets = flowfabric_list_datasets()
+print(datasets)
+
+# 2. Query streamflow forecast (first call prompts login, then caches token)
+# More on atuhentication below ...
+tbl = flowfabric_streamflow_query(
+	dataset_id = "nws_owp_nwm_analysis",
+	feature_ids = ["101", "1001"],
+	issue_time = "latest"
+)
+print(tbl)
+
+# 3. Query streamflow reanalysis data
+tbl_re = flowfabric_streamflow_query(
+  "nws_owp_nwm_reanalysis_3_0",
+  feature_ids = ["101", "1001"],
+  start_time = "2018-01-01",
+  end_time = "2018-01-31"
+)
+print(tbl_re)
+
+# 4. Query ratings
+ratings = flowfabric_ratings_query(
+    feature_ids = ["101", "1001"], 
+    type = "rem"
+)
+print(ratings)
+```
+
+## Authentication & Token Caching
+
+Using this platform requires authentication via the Lynker Spatial Portal. Accounts are free to set up and use. If use exceeds costs we can burden we will reach out to power users to better understand how we can help.
+
+To get access, users can create an account here: https://proxy.lynker-spatial.com/
+
+The first API call will prompt you to log in via browser. Your token is then cached and reused for all future calls—no repeated browser prompts!
+
+**Manual token refresh:**
+```py
+flowfabric_refresh_token() # Forces re-authentication and updates cached token
+```
+
+**Advanced:**
+You can always pass a token explicitly:
+```py
+token = flowfabric_get_token()['id_token']
+healthz = flowfabric_healthz(token = token)
+```
+## Troubleshooting
+- If you see repeated browser prompts, call `flowfabric_refresh_token()` once, then retry your queries.
+- If you switch users, manually refresh the token.
+- Use `verbose = TRUE` in any endpoint for detailed debug output.
+
+## Learn More
+- See the vignettes for advanced usage, authentication, and custom queries.
+- All API responses are Arrow tables for high-performance analytics.

flowfabricpy-0.1.0/README.md

@@ -0,0 +1,75 @@
+# flowfabricpy: Effortless Python Access to FlowFabric API
+
+`flowfabricpy` is a powerful Python client for the FlowFabric API, providing seamless access to hydrologic forecasts, reanalysis, rating curves, and datasets. With robust authentication and automatic token caching, you can focus on data science, not on data munging plumbing.
+
+## Key Features
+- **Evolving catalog** of harmonized data from multiple models
+- **Single method access** to all models - both retrospective and forecast
+- **One-time authentication**: Log in once, and your token is cached for future use.
+- **Arrow IPC support**: Fast, memory-efficient data transfer
+
+## Installation
+```py
+#  Install from GitHub:
+pip install git+https://github.com/lynker-spatial/flowfabric-py#egg=flowfabricpy
+```
+
+## Quick Start
+```py
+# 1. List available datasets
+datasets = flowfabric_list_datasets()
+print(datasets)
+
+# 2. Query streamflow forecast (first call prompts login, then caches token)
+# More on atuhentication below ...
+tbl = flowfabric_streamflow_query(
+	dataset_id = "nws_owp_nwm_analysis",
+	feature_ids = ["101", "1001"],
+	issue_time = "latest"
+)
+print(tbl)
+
+# 3. Query streamflow reanalysis data
+tbl_re = flowfabric_streamflow_query(
+  "nws_owp_nwm_reanalysis_3_0",
+  feature_ids = ["101", "1001"],
+  start_time = "2018-01-01",
+  end_time = "2018-01-31"
+)
+print(tbl_re)
+
+# 4. Query ratings
+ratings = flowfabric_ratings_query(
+    feature_ids = ["101", "1001"], 
+    type = "rem"
+)
+print(ratings)
+```
+
+## Authentication & Token Caching
+
+Using this platform requires authentication via the Lynker Spatial Portal. Accounts are free to set up and use. If use exceeds costs we can burden we will reach out to power users to better understand how we can help.
+
+To get access, users can create an account here: https://proxy.lynker-spatial.com/
+
+The first API call will prompt you to log in via browser. Your token is then cached and reused for all future calls—no repeated browser prompts!
+
+**Manual token refresh:**
+```py
+flowfabric_refresh_token() # Forces re-authentication and updates cached token
+```
+
+**Advanced:**
+You can always pass a token explicitly:
+```py
+token = flowfabric_get_token()['id_token']
+healthz = flowfabric_healthz(token = token)
+```
+## Troubleshooting
+- If you see repeated browser prompts, call `flowfabric_refresh_token()` once, then retry your queries.
+- If you switch users, manually refresh the token.
+- Use `verbose = TRUE` in any endpoint for detailed debug output.
+
+## Learn More
+- See the vignettes for advanced usage, authentication, and custom queries.
+- All API responses are Arrow tables for high-performance analytics.

flowfabricpy-0.1.0/README.rst

@@ -0,0 +1,104 @@
+.. flowfabricpy documentation master file, created by
+   sphinx-quickstart on Wed Feb 11 13:17:49 2026.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+flowfabricpy: Effortless Python Access to FlowFabric API
+========================================================
+
+**flowfabricpy** is a powerful Python client for the FlowFabric API, providing seamless access to hydrologic forecasts, reanalysis, rating curves, and datasets. With robust authentication and automatic token caching, you can focus on data science, not on data munging plumbing.
+
+Key Features
+------------
+- **Evolving catalog** of harmonized data from multiple models
+- **Single method access** to all models - both retrospective and forecast
+- **One-time authentication**: Log in once, and your token is cached for future use.
+- **Arrow IPC support**: Fast, memory-efficient data transfer
+
+Installation
+------------
+.. code-block:: python
+
+   # Install from GitHub:
+   pip install git+https://github.com/lynker-spatial/flowfabric-py#egg=flowfabricpy
+
+Quick Start
+-----------
+.. code-block:: python
+
+   # 1. List available datasets
+   datasets = flowfabric_list_datasets()
+   print(datasets)
+
+   # 2. Query streamflow forecast (first call prompts login, then caches token)
+   # More on atuhentication below ...
+   tbl = flowfabric_streamflow_query(
+      dataset_id = "nws_owp_nwm_analysis",
+      feature_ids = ["101", "1001"],
+      issue_time = "latest"
+   )
+   print(tbl)
+
+   # 3. Query streamflow reanalysis data
+   tbl_re = flowfabric_streamflow_query(
+      "nws_owp_nwm_reanalysis_3_0",
+      feature_ids = ["101", "1001"],
+      start_time = "2018-01-01",
+      end_time = "2018-01-31"
+   )
+   print(tbl_re)
+
+   # 4. Query ratings
+   ratings = flowfabric_ratings_query(
+      feature_ids = ["101", "1001"],
+      type = "rem"
+   )
+   print(ratings)
+
+Authentication & Token Caching
+------------------------------
+
+Using this platform requires authentication via the Lynker Spatial Portal. Accounts are free to set up and use. If use exceeds costs we can burden we will reach out to power users to better understand how we can help.
+
+To get access, users can create an account here: https://proxy.lynker-spatial.com/
+
+The first API call will prompt you to log in via browser. Your token is then cached and reused for all future calls—no repeated browser prompts!
+
+
+**Manual token refresh:**
+
+.. code-block:: python
+
+   flowfabric_refresh_token() # Forces re-authentication and updates cached token
+
+
+**Advanced:**
+You can always pass a token explicitly:
+
+.. code-block:: python
+
+   token = flowfabric_get_token()['id_token']
+   healthz = flowfabric_healthz(token = token)
+
+Troubleshooting
+---------------
+- If you see repeated browser prompts, call `flowfabric_refresh_token()` once, then retry your queries.
+- If you switch users, manually refresh the token.
+- Use `verbose = TRUE` in any endpoint for detailed debug output.
+
+Learn More
+----------
+- See the vignettes for advanced usage, authentication, and custom queries.
+- All API responses are Arrow tables for high-performance analytics.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+Contents
+--------
+.. toctree::
+   getting-started
+   authentication
+   advanced
+

flowfabricpy-0.1.0/pyproject.toml

@@ -0,0 +1,13 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "flowfabricpy"
+version = "0.1.0"
+requires-python = ">=3.8"
+dependencies = ["requests"]
+description = "Python client for Flowfabric"
+readme = "README.md"
+license = "MIT"
+authors = [{name = "Paul Linza", email = "plinza@lynker.com"}, {name = "Mike Johnson", email = "mjohnson@lynker.com"}]

flowfabricpy-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

flowfabricpy-0.1.0/src/flowfabricpy/__init__.py

@@ -0,0 +1,34 @@
+# __init__.py
+from .auth import flowfabric_get_token, flowfabric_refresh_token
+from .catalog_utils import auto_streamflow_params
+from .flowfabric_http import flowfabric_get, flowfabric_post
+from .client import (
+    flowfabric_list_datasets,
+    flowfabric_get_dataset,
+    flowfabric_get_latest_run,
+    flowfabric_streamflow_query,
+    flowfabric_streamflow_estimate,
+    flowfabric_ratings_query,
+    flowfabric_ratings_estimate,
+    flowfabric_stage_query,
+    flowfabric_healthz,
+    flowfabric_inundation_ids,
+    get_bearer_token
+)
+
+__all__ = ['flowfabric_get_token',
+           'flowfabric_refresh_token',
+           'auto_streamflow_params',
+           'flowfabric_list_datasets',
+           'flowfabric_get',
+           'flowfabric_post',
+           'flowfabric_get_dataset',
+           'flowfabric_get_latest_run',
+           'flowfabric_streamflow_query',
+           'flowfabric_streamflow_estimate',
+           'flowfabric_ratings_query',
+           'flowfabric_ratings_estimate',
+           'flowfabric_stage_query',
+           'flowfabric_healthz',
+           'flowfabric_inundation_ids',
+           'get_bearer_token']

flowfabricpy-0.1.0/src/flowfabricpy/auth.py

@@ -0,0 +1,176 @@
+# auth.py
+"""
+Functions for getting an authentication token
+"""
+import json
+import os
+import threading
+import webbrowser
+import time
+from threading import Lock
+from pathlib import Path
+
+os.environ["OAUTHLIB_INSECURE_TRANSPORT"] = "1"
+token_file = Path.home() / ".flowfabric_token.json"
+
+import base64
+import hashlib
+import secrets
+import requests
+from requests_oauthlib import OAuth2Session
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from urllib.parse import urlparse, parse_qs
+
+# token lock
+token_lock = Lock()
+
+# helper function to load token
+def load_token():
+    """
+    Helper function to load a token. Do not call directly.
+    :return:
+    """
+    if not token_file.exists():
+        return None
+    try:
+        with token_file.open("r") as f:
+            return json.load(f)
+    except Exception:
+        return None
+
+# helper function to save the token
+def save_token(token):
+    """
+    Helper function to save a token. Do not call directly.
+    :param token: Token
+    :type token: dict
+    :return:
+    """
+    token_file.parent.mkdir(parents=True, exist_ok=True)
+    with token_file.open("w") as f:
+        json.dump(token, f)
+
+# helper function
+# only returns True if both the expiration time & token exist & are not expired
+def token_is_valid(token):
+    """
+    Helper function to determine the validity of a token. Do not call directly.
+    :return: Bool representing validity
+    """
+    if not token:
+        return False
+
+    expires_at = token.get("expires_at")
+    if not expires_at:
+        return False
+
+    return expires_at - 60 > time.time() # extra time as a buffer
+
+# handle the OAuth callback
+class OAuthCallbackHandler(BaseHTTPRequestHandler):
+    """
+    Class to handle the OAuth callback
+    """
+    auth_code = None
+    auth_state = None
+
+    def do_GET(self):
+        query = parse_qs(urlparse(self.path).query)
+        OAuthCallbackHandler.auth_code = query.get("code", [None])[0]
+        OAuthCallbackHandler.auth_state = query.get("state", [None])[0]
+
+        self.send_response(200)
+        self.end_headers()
+        self.wfile.write(b"Authentication complete. You may close this window.")
+
+        threading.Thread(target=self.server.shutdown).start()
+
+# login and get a token
+def flowfabric_get_token(force_refresh=False):
+    """
+    Get and cache an authentication token
+
+    :param force_refresh: (Optional) force refresh token
+    :type force_refresh: bool or None
+
+    :return: The cached authentication token
+    """
+    # dumps the cached token
+    if force_refresh:
+        token_file.unlink(missing_ok=True)
+
+    # return current token if it is still valid
+    token = load_token()
+    if token_is_valid(token):
+        return token
+
+    # otherwise generate a new token
+    with token_lock:
+        provider = requests.get(
+            "https://cognito-idp.us-west-2.amazonaws.com/us-west-2_em0hAPqnS/.well-known/openid-configuration"
+        )
+        json_prov = provider.json()
+
+        client_id = "1he6ti5109b9t6r1ifd4brecpl"
+        redirect_uri = "http://localhost:57777"
+        scope = ["openid", "profile", "email", "phone"]
+
+        # PKCE
+        code_verifier = secrets.token_urlsafe(64)
+        code_challenge = base64.urlsafe_b64encode(
+            hashlib.sha256(code_verifier.encode()).digest()
+        ).decode().rstrip("=")
+
+        oauth = OAuth2Session(
+            client_id=client_id,
+            redirect_uri=redirect_uri,
+            scope=scope,
+        )
+
+        authorization_url, state = oauth.authorization_url(
+            json_prov["authorization_endpoint"],
+            code_challenge=code_challenge,
+            code_challenge_method="S256",
+        )
+
+        # Start callback server
+        server = HTTPServer(("localhost", 57777), OAuthCallbackHandler)
+        thread = threading.Thread(target=server.serve_forever)
+        thread.daemon = True
+        thread.start()
+
+        webbrowser.open(authorization_url)
+
+        timeout = time.time() + 60
+        # Wait for redirect
+        while OAuthCallbackHandler.auth_code is None:
+            if time.time() > timeout:
+                server.shutdown()
+                thread.join()
+                server.server_close()
+            time.sleep(0.1)
+
+        server.shutdown()
+        thread.join()
+        server.server_close()
+
+        token = oauth.fetch_token(
+            json_prov["token_endpoint"],
+            code=OAuthCallbackHandler.auth_code,
+            code_verifier=code_verifier,
+            include_client_id=True,
+        )
+
+        provider.close()
+        save_token(token)
+        return token
+
+# refresh token
+def flowfabric_refresh_token():
+    """
+    Force refresh the cached token
+
+    :return: The new token
+    """
+    token = flowfabric_get_token(force_refresh=True)
+    return token

flowfabricpy-0.1.0/src/flowfabricpy/catalog_utils.py

@@ -0,0 +1,70 @@
+# catalog_utils.py
+"""
+Contains a function to get recommended streamflow parameters.
+"""
+import requests
+import pandas as pd
+
+# autofill streamflow parameters
+def auto_streamflow_params(dataset_id):
+    """
+    Auto-generate streamflow parameters for a given dataset
+
+    :param dataset_id: The id of the dataset
+    :type dataset_id: str
+
+    :return: Dictionary containing the recommended streamflow parameters
+    """
+    catalog = requests.get("https://flowfabric.lynker-spatial.com/catalog")
+    json_data = catalog.json()['provider_groups']
+    df = pd.json_normalize(json_data, record_path="datasets")
+    datasets = df.to_dict(orient='records')
+    data = next((dataset for dataset in datasets if dataset.get("id") == dataset_id), None)
+
+    if data is None:
+        print("[auto_streamflow_params] Error: dataset not found")
+        return None
+
+    # determine if it is a reanalysis or not
+    is_reanalysis = False
+    if 'query_mode' in data and data['query_mode'] == 'absolute':
+        is_reanalysis = True
+    if 'configuration' in data and 'reanalysis' in data['configuration']:
+        is_reanalysis = True
+
+    if is_reanalysis:
+        if 'default_start_time' in data:
+            start_time = data['default_start_time']
+        elif 'min_time' in data:
+            start_time = data['min_time']
+        else:
+            start_time = "2018-01-01T00:00:00Z"
+
+        if 'default_end_time' in data:
+            end_time = data['default_end_time']
+        elif 'max_time' in data:
+            end_time = data['max_time']
+        else:
+            end_time = "2018-01-31T23:59:59Z"
+
+        params = {
+            'query_mode': 'absolute',
+            'start_time': start_time,
+            'end_time': end_time,
+            'scope': data['default_scope'] if 'default_scope' in data else 'all',
+            'format': data['default_format'] if 'default_format' in data else 'json',
+            'mode': data['default_mode'] if 'default_mode' in data else 'sync',
+        }
+    else:
+        params = {
+            'query_mode': 'run',
+            'issue_time': data['issue_time'] if 'issue_time' in data else 'latest',
+            'scope': data['default_scope'] if 'default_scope' in data else 'all',
+            'lead_start': data['lead_start'] if 'lead_start' in data else 0,
+            'lead_end': data['lead_end'] if 'lead_end' in data else 0,
+            'format': data['default_format'] if 'default_format' in data else 'json',
+            'mode': data['default_mode'] if 'default_mode' in data else 'sync',
+        }
+
+    catalog.close()
+    return params