jstdata 0.1.0__tar.gz

jstdata-0.1.0/LICENSE

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

jstdata-0.1.0/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: jstdata
+Version: 0.1.0
+Summary: A Python interface to the Jefferson Street REST API.
+License: MIT
+License-File: LICENSE
+Keywords: api,cli,data,jefferson street
+Author: Mahfuj Ahbab
+Requires-Python: >=3.10,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT 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
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: click (>=8.2.1,<9.0.0)
+Requires-Dist: pandas (>=2.3.1,<3.0.0)
+Requires-Dist: tabulate (>=0.9.0,<0.10.0)
+Project-URL: Homepage, https://github.com/mahfuj/python_api
+Project-URL: Repository, https://github.com/mahfuj/python_api
+Description-Content-Type: text/markdown
+
+# jstdata
+
+A Python interface to the Jefferson Street REST API.
+
+## Installation
+
+```bash
+pip install jstdata
+```
+
+## Usage
+
+Set your API key as an environment variable:
+
+```bash
+export JEFFERSON_STREET_API_KEY="your_api_key_here"
+```
+
+Then you can use the CLI:
+
+```bash
+jst --help
+```
+
+Or use it as a Python library:
+
+```python
+from jstdata.client import JeffersonStreetClient
+
+client = JeffersonStreetClient("your_api_key_here")
+metrics = client.get_metrics()
+print(metrics)
+```
+

jstdata-0.1.0/README.md

@@ -0,0 +1,33 @@
+# jstdata
+
+A Python interface to the Jefferson Street REST API.
+
+## Installation
+
+```bash
+pip install jstdata
+```
+
+## Usage
+
+Set your API key as an environment variable:
+
+```bash
+export JEFFERSON_STREET_API_KEY="your_api_key_here"
+```
+
+Then you can use the CLI:
+
+```bash
+jst --help
+```
+
+Or use it as a Python library:
+
+```python
+from jstdata.client import JeffersonStreetClient
+
+client = JeffersonStreetClient("your_api_key_here")
+metrics = client.get_metrics()
+print(metrics)
+```

jstdata-0.1.0/jstdata/__init__.py

@@ -0,0 +1 @@
+from .client import JeffersonStreetClient

jstdata-0.1.0/jstdata/cli.py

@@ -0,0 +1,213 @@
+import os
+import sys
+
+import click
+
+from .client import ApiKeyNotSetError, JeffersonStreetClient
+from .utils import common_params, format_and_print
+
+api_key = os.getenv("JEFFERSON_STREET_API_KEY")
+if api_key is None:
+    raise click.Abort(
+        "Please set the JEFFERSON_STREET_API_KEY environment variable to a valid API key."
+    )
+
+client = JeffersonStreetClient(api_key)
+
+
+@click.group()
+def cli():
+    """
+    Jefferson Street CLI.
+    """
+
+
+@cli.group()
+def metric():
+    """
+    Commands for interacting with metrics.
+    """
+
+
+@cli.group()
+def entity():
+    """
+    Commands for interacting with entities.
+    """
+
+
+@cli.group()
+def query():
+    """
+    Commands for querying data.
+    """
+
+
+@entity.command("groups")
+@click.option(
+    "--format",
+    default="pretty",
+    help="Output format. Valid formats are: json, csv, pretty.",
+)
+def list_entity_groups(format):
+    """
+    List all available entity groups.
+    """
+    entity_groups = client.get_entity_groups()
+    format_and_print(entity_groups, format)
+
+
+@entity.command("values")
+@click.argument("entity_group", required=True)
+@common_params
+def list_entities(entity_group, limit, format, offset):
+    """
+    List entities within a specified entity group.
+    """
+    results = client.get_entities(entity_group, offset, limit)
+    format_and_print(results, format)
+
+
+@entity.command("metrics")
+@click.argument("entity", required=True)
+@common_params
+def get_entity_links(entity, limit, format, offset):
+    """
+    Retrieve metrics associated with a specific entity.
+    """
+    results = client.get_entity_metrics(entity, limit, offset)
+    format_and_print(results, format)
+
+
+@metric.command("ls")
+@common_params
+@click.option(
+    "--sort_order", default="desc", help="Sort order (asc or desc, default: desc)"
+)
+@click.option(
+    "--order_by",
+    default="last_updated",
+    help="Column to order by (default: last_updated)",
+)
+@click.option("--expanded", is_flag=True, default=False, help="Return expanded metrics")
+def list_metrics(limit, offset, sort_order, order_by, format, expanded):
+    """
+    List all available metrics.
+    """
+    metrics = client.get_metrics(None, limit, offset, order_by, sort_order)
+    if expanded:
+        format_and_print(metrics, format)
+    else:
+        condensed_metrics = [{"slug": m["slug"]} for m in metrics]
+        format_and_print(condensed_metrics, format)
+
+
+@metric.command("show")
+@click.argument("metric", required=True)
+@click.option(
+    "--format",
+    default="pretty",
+    help="Output format. Valid formats are: json, csv, pretty.",
+)
+def show_metric(metric, format):
+    """
+    Display details for a specific metric.
+    """
+    metric = client.get_metrics(metric)
+    format_and_print(metric, format)
+
+
+@metric.command("entities")
+@click.argument("metric", required=True)
+@click.option(
+    "--format",
+    default="pretty",
+    help="Output format. Valid formats are: json, csv, pretty.",
+)
+def show_metric_dimensions(metric, format):
+    """
+    Display dimensions for a specific metric.
+    """
+    dimensions = client.get_metric_dimensions(metric)
+    format_and_print(dimensions, format)
+
+
+@query.command("metric")
+@common_params
+@click.argument("metric", required=True, nargs=1)
+@click.option(
+    "--sort_order", default="desc", help="Sort order (asc or desc, default: desc)"
+)
+@click.option("--order_by", default="id", help="Column to order by (default: id)")
+@click.option(
+    "--start_date",
+    default=None,
+    help="Start period. Valid formats: YYYY-MM-DD, YYYY-MM, YYYY, unix timestamp",
+)
+@click.option(
+    "--end_date",
+    default=None,
+    help="End period. Valid formats: YYYY-MM-DD, YYYY-MM, YYYY, unix timestamp",
+)
+def get_observations_by_metric(
+    metric, sort_order, order_by, start_date, end_date, limit, offset, format
+):
+    """
+    Retrieve observations for a specific metric.
+    """
+    observations = client.query("metric", metric, start_date, end_date, limit, offset)
+    format_and_print(observations, format)
+
+
+@query.command("entity")
+@click.argument("entity", required=True, nargs=1)
+@click.option(
+    "--sort_order", default="desc", help="Sort order (asc or desc, default: desc)"
+)
+@click.option("--order_by", default="id", help="Column to order by (default: id)")
+@click.option(
+    "--start_date",
+    default=None,
+    help="Start period. Valid formats: YYYY-MM-DD, YYYY-MM, YYYY, unix timestamp",
+)
+@click.option(
+    "--end_date",
+    default=None,
+    help="End period. Valid formats: YYYY-MM-DD, YYYY-MM, YYYY, unix timestamp",
+)
+@common_params
+def get_observations_by_entity(
+    entity, sort_order, order_by, start_date, end_date, limit, offset, format
+):
+    """
+    Retrieve observations for a specific entity.
+    """
+    observations = client.query("entity", entity, start_date, end_date, limit, offset)
+    format_and_print(observations, format)
+
+
+@entity.command("search")
+@click.option(
+    "--limit", default=3, help="Maximum number of records to return (default: 10000)"
+)
+@click.option("--offset", default=0, help="Number of records to skip (default: 0)")
+@click.option(
+    "--format",
+    default="pretty",
+    help="Output format. Valid formats are: json, csv, pretty.",
+)
+@click.argument("query", required=True, nargs=1)
+def search_for_entity(query, limit, offset, format):
+    """
+    Search for entities.
+    """
+    results = client.search_for_entity(query, limit, offset)
+    format_and_print(results, format)
+
+
+if __name__ == "__main__":
+    try:
+        cli()
+    except ApiKeyNotSetError as e:
+        click.echo(f"Error: {e}", err=True)
+        sys.exit(1)

jstdata-0.1.0/jstdata/client.py

@@ -0,0 +1,258 @@
+import os
+from typing import Any, Dict, Optional
+import requests
+from collections import namedtuple
+
+EntityType = namedtuple("EntityType", ["name", "slug", "classification"])
+
+
+class ApiKeyNotSetError(Exception):
+    pass
+
+
+class InvalidApiKeyError(Exception):
+    pass
+
+
+class InvalidInputError(Exception):
+    pass
+
+
+class JeffersonStreetClient:
+    # For testing purposes
+    base_url = os.getenv("JEFFERSON_STREET_SERVER") or "https://api.jeffersonst.io"
+
+    def __init__(self, api_key: Optional[str] = None):
+        """
+        Initializes the JeffersonStreetClient with an API key.
+
+        Args:
+            api_key: The API key for authenticating with the Jefferson Street REST API.
+        """
+        if api_key is None:
+            raise ApiKeyNotSetError("API key is not set")
+        self._api_key = api_key
+        self.session = requests.Session()
+        self.session.params = {"api-key": api_key}
+
+        self._api_key_is_valid = False
+
+    @property
+    def api_key(self):
+        """
+        Returns the API key used by the client.
+        """
+        return self._api_key
+
+    def _validate_api_key(self, api_key) -> None:
+        """
+        Validates the provided API key by making a heartbeat request to the API.
+
+        Args:
+            api_key: The API key to validate.
+
+        Raises:
+            ApiKeyNotSetError: If the API key is None.
+            InvalidApiKeyError: If the API key is invalid.
+        """
+        if api_key is None:
+            raise ApiKeyNotSetError("API key is not set")
+
+        url = f"{self.base_url}/heartbeat"
+        heartbeat = self.session.get(url).json()
+        if heartbeat["status"] != "ok":
+            raise InvalidApiKeyError("Invalid API key")
+        self._api_key_is_valid = True
+        return
+
+    def _make_request(
+        self, endpoint: str, params: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
+        """
+        Makes a GET request to the specified API endpoint.
+
+        Args:
+            endpoint: The API endpoint to call.
+            params: A dictionary of query parameters to send with the request.
+
+        Returns:
+            A dictionary containing the JSON response from the API.
+
+        Raises:
+            ApiKeyNotSetError: If the API key is not set.
+            InvalidApiKeyError: If the API key is invalid.
+            requests.exceptions.RequestException: For network-related errors or unsuccessful HTTP responses.
+        """
+        if not self._api_key_is_valid:
+            self._validate_api_key(self.api_key)
+
+        url = f"{self.base_url}/{endpoint}"
+        response = self.session.get(url, params=params)
+        response.raise_for_status()
+        return response.json()
+
+    def get_metrics(
+        self,
+        metric: Optional[str] = None,
+        limit: int = 100,
+        offset: int = 0,
+        order_by: str = "last_updated",
+        sort_order: str = "desc",
+    ) -> Dict[str, Any]:
+        """Get available metrics.
+
+        Args:
+            metric: The metric's slug. If empty, all metrics are returned
+            limit: Maximum number of records to return (default: 10000)
+            offset: Number of records to skip (default: 0)
+            order_by: Column to order by (default: "last_updated")
+            sort_order: Sort order ("asc" or "desc", default: "desc")
+
+        Returns:
+            MetricResponse containing list of available metrics
+        """
+        response = self._make_request(
+            "metric",
+            {
+                "metric": metric,
+                "limit": limit,
+                "offset": offset,
+                "order_by": order_by,
+                "sort_order": sort_order,
+            },
+        )
+        return response["records"]
+
+    def get_metric_dimensions(self, metric: str) -> Dict[str, Any]:
+        try:
+            response = self._make_request(f"metric/{metric}/entities")
+        except requests.exceptions.HTTPError as e:
+            raise InvalidInputError(f"Invalid input: {e}")
+        return response["records"]
+
+    def get_entity_groups(self) -> Dict[str, Any]:
+        """Get available entity types.
+
+        Returns:
+            Dictionary containing list of available entity types
+        """
+        try:
+            response = self._make_request("entity/groups")
+        except requests.exceptions.HTTPError as e:
+            raise InvalidInputError(f"Invalid input: {e}")
+        return response["records"]
+
+    def get_entities(
+        self,
+        entity_group: Optional[str] = None,
+        offset: int = 0,
+        limit: int = 10000,
+        sort_order: str = "asc",
+    ) -> Dict[str, Any]:
+        """Get available entities.
+        Args:
+            offset: Number of records to skip (default: 0)
+            limit: Maximum number of records to return (default: 10000)
+            sort_order: Sort order ("asc" or "desc", default: "asc")
+
+        Returns:
+            Dictionary containing list of available entities
+        """
+        response = self._make_request(
+            f"entity/{entity_group}",
+            {"offset": offset, "limit": limit, "sort_order": sort_order},
+        )
+        return response["records"]
+
+    def get_entity_metrics(
+        self,
+        entity: Optional[str] = None,
+        limit: int = 10000,
+        offset: int = 0,
+        sort_order: str = "asc",
+    ) -> Dict[str, Any]:
+        """Get metrics for a specific entity.
+
+        Args:
+            entity: The entity's slug
+            limit: Maximum number of records to return (default: 10000)
+            offset: Number of records to skip (default: 0)
+            order_by: Column to order by (default: "last_updated")
+            sort_order: Sort order ("asc" or "desc", default: "asc")
+
+        Returns:
+            MetricResponse containing list of metrics for the entity
+        """
+        response = self._make_request(
+            f"entity/{entity}/metrics",
+            {"limit": limit, "offset": offset, "sort_order": sort_order},
+        )
+        return response["records"]
+
+    def query(
+        self,
+        by: str,
+        id: str,
+        start_date: str,
+        end_date: str,
+        limit: int = 100,
+        offset: int = 0,
+        order_by: str = "release_date",
+        sort_order: str = "asc",
+        entity_filter: Optional[list[str]] = None,
+    ) -> Dict[str, Any]:
+        """Query by metric.
+
+        Args:
+            by: The type of query to perform (either "metric" or "entity")
+            id: The metric or entity's id/slug
+            start_date: Start date (YYYY-MM-DD)
+            end_date: End date (YYYY-MM-DD)
+            limit: Maximum number of records to return (default: 100)
+            offset: Number of records to skip (default: 0)
+            order_by: Column to order by (either "release_date" or "series_label", default: "release_date")
+            sort_order: Sort order ("asc" or "desc", default: "desc")
+
+        Returns:
+            QueryResponse containing list of query results
+        """
+        if by not in ["metric", "entity"]:
+            raise InvalidInputError(f"Invalid input: {by}")
+        if order_by not in ["release_date", "series_label"]:
+            raise InvalidInputError(f"Invalid input: {order_by}")
+        if sort_order not in ["asc", "desc"]:
+            raise InvalidInputError(f"Invalid input: {sort_order}")
+        params = {
+            "start_date": start_date,
+            "end_date": end_date,
+            "limit": limit,
+            "offset": offset,
+            "sort_order": sort_order,
+            "order_by": order_by,
+        }
+        if entity_filter is not None:
+            params["entities"] = entity_filter
+        response = self._make_request(f"query/{by}/{id}", params)
+        return response["records"]
+
+    def search_for_entity(
+        self,
+        query: str,
+        limit: int = 3,
+        offset: int = 0,
+    ) -> Dict[str, Any]:
+        """Search for an entity.
+
+        Args:
+            query: The query to search for
+            offset: Number of records to skip (default: 0)
+            limit: Maximum number of records to return (default: 10000)
+            sort_order: Sort order ("asc" or "desc", default: "asc")
+
+        Returns:
+            SearchResponse containing list of search results
+        """
+        response = self._make_request(
+            f"search/entity", {"query": query, "offset": offset, "limit": limit}
+        )
+        return response["records"]

jstdata-0.1.0/jstdata/utils.py

@@ -0,0 +1,58 @@
+import json
+from io import StringIO
+
+import click
+import pandas as pd
+from tabulate import tabulate
+
+
+def common_params(f):
+    """
+    Decorator to apply common CLI parameters: limit, offset, and format.
+    """
+    f = click.option(
+        "--limit",
+        default=100,
+        help="Maximum number of records to return (default: 10000)",
+    )(f)
+    f = click.option(
+        "--offset", default=0, help="Number of records to skip (default: 0)"
+    )(f)
+    f = click.option(
+        "--format",
+        default="pretty",
+        help="Output format. Valid formats are: json, csv, pretty.",
+    )(f)
+    return f
+
+
+def date_handler(date_str):
+    if len(date_str) in (10, 11):  # YYYY-MM-DD or unix timestamp
+        return date_str
+    elif len(date_str) == 4:  # year
+        return f"{date_str}-01-01"
+    elif len(date_str) == 7:  # year-month
+        return f"{date_str}-01"
+    else:
+        raise ValueError(f"Invalid date format: {date_str}")
+
+
+def df_to_csv_string(df):
+    csv_buffer = StringIO()
+    df.to_csv(csv_buffer, index=False)
+    return csv_buffer.getvalue()
+
+
+def format_and_print(response_data, format):
+    if format == "json":
+        click.echo(json.dumps(response_data))
+    elif format == "csv":
+        click.echo(df_to_csv_string(pd.DataFrame(response_data)))
+    elif format == "pretty":
+        if len(response_data) == 1:
+            response_data = [(k, v) for k, v in response_data[0].items()]
+            click.echo(
+                tabulate(response_data, headers=["key", "value"], tablefmt="pretty")
+            )
+            return
+        click.echo(tabulate(response_data, headers="keys", tablefmt="pretty"))

jstdata-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[tool.poetry]
+name = "jstdata"
+version = "0.1.0"
+description = "A Python interface to the Jefferson Street REST API."
+authors = ["Mahfuj Ahbab"]
+readme = "README.md"
+license = "MIT"
+homepage = "https://github.com/mahfuj/python_api"
+repository = "https://github.com/mahfuj/python_api"
+keywords = ["api", "cli", "data", "jefferson street"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[tool.poetry.dependencies]
+python = "^3.10"
+click = "^8.2.1"
+pandas = "^2.3.1"
+tabulate = "^0.9.0"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.3.5"
+requests-mock = "^1.12.1"
+pytest-cov = "^6.1.1"
+black = "^25.1.0"
+isort = "^6.0.1"
+flake8 = "^7.2.0"
+mypy = "^1.15.0"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry.scripts]
+jst = "jstdata.cli:cli"