quickbase-api 0.1.0__py3-none-any.whl

quickbase_api/__init__.py

@@ -0,0 +1,68 @@
+"""A simple Python wrapper for the Quickbase API.
+
+Example::
+
+    import quickbase_api
+
+    # Option 1: Using the factory function (reads from environment variables)
+    client = quickbase_api.client()
+
+    # Option 2: Passing credentials directly
+    client = quickbase_api.client(
+        realm="mycompany.quickbase.com",
+        user_token="my-token",
+    )
+
+    # Option 3: Using the class directly
+    from quickbase_api import QuickbaseClient
+    client = QuickbaseClient("mycompany.quickbase.com", "my-token")
+"""
+
+from __future__ import annotations
+
+import os
+
+from quickbase_api.api import QuickbaseClient
+from quickbase_api.exceptions import (
+    QuickbaseAPIError,
+    QuickbaseError,
+    QuickbaseNotFoundError,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "QuickbaseClient",
+    "QuickbaseAPIError",
+    "QuickbaseError",
+    "QuickbaseNotFoundError",
+    "client",
+]
+
+
+def client(realm: str = None, user_token: str = None) -> QuickbaseClient:
+    """Create a QuickbaseClient, falling back to environment variables.
+
+    Args:
+        realm: The Quickbase realm hostname. If not provided, reads from
+            the ``QUICKBASE_REALM`` environment variable.
+        user_token: The Quickbase user token. If not provided, reads from
+            the ``QUICKBASE_USER_TOKEN`` environment variable.
+
+    Returns:
+        A configured QuickbaseClient instance.
+
+    Raises:
+        KeyError: If a credential is not provided and the corresponding
+            environment variable is not set.
+
+    Example::
+
+        # Set environment variables, then:
+        import quickbase_api
+        client = quickbase_api.client()
+    """
+    return QuickbaseClient(
+        realm=realm or os.environ["QUICKBASE_REALM"],
+        user_token=user_token or os.environ["QUICKBASE_USER_TOKEN"],
+    )

quickbase_api/api.py

@@ -0,0 +1,564 @@
+# FILE: api.py
+
+"""Quickbase API client providing high-level methods for apps, tables, fields, and records."""
+
+from __future__ import annotations
+
+import logging
+from typing import Optional
+
+from quickbase_api.exceptions import QuickbaseAPIError, QuickbaseNotFoundError
+from quickbase_api.legacy_method import LegacyMethod
+from quickbase_api.rest_method import RestMethod
+
+logger = logging.getLogger(__name__)
+
+
+class QuickbaseClient:
+    """High-level client for interacting with the Quickbase API.
+
+    Args:
+        realm: The Quickbase realm hostname (e.g., 'mycompany.quickbase.com').
+        user_token: The Quickbase user token for authentication.
+
+    Example::
+
+        from quickbase_api import QuickbaseClient
+
+        client = QuickbaseClient("mycompany.quickbase.com", "my-token")
+        app = client.get_app("bqrg4xyza")
+    """
+
+    def __init__(self, realm: str, user_token: str):
+        self.realm = realm
+        self.user_token = user_token
+        self._rm = RestMethod(realm, user_token)
+        self._lm = LegacyMethod(realm, user_token)
+
+    def _require_success(self, resp_json: dict, resp_code: int, context: str) -> dict:
+        """Raise QuickbaseAPIError if the response code indicates failure.
+
+        Args:
+            resp_json: The parsed response body.
+            resp_code: The HTTP status code.
+            context: A human-readable description of the operation for error messages.
+
+        Returns:
+            The response body if successful.
+
+        Raises:
+            QuickbaseAPIError: If the status code is 400 or above.
+        """
+        if resp_code >= 400:
+            raise QuickbaseAPIError(resp_code, resp_json)
+        return resp_json
+
+    # ── Apps ──────────────────────────────────────────────────────────────
+
+    def create_app(
+        self,
+        name: str,
+        description: str = None,
+        assign_token: bool = None,
+    ) -> str:
+        """Create a new Quickbase app.
+
+        Args:
+            name: The name for the new app.
+            description: Optional description for the app.
+            assign_token: If True, assigns the user token to the new app.
+
+        Returns:
+            The app ID of the newly created app.
+
+        Raises:
+            QuickbaseAPIError: If the API request fails.
+        """
+        body = {"name": name}
+        if description is not None:
+            body["description"] = description
+        if assign_token is not None:
+            body["assignToken"] = assign_token
+
+        resp_json, resp_code = self._rm.post("apps", data=body)
+        self._require_success(resp_json, resp_code, f"create app '{name}'")
+        logger.info("Created app '%s' with ID: %s", resp_json["name"], resp_json["id"])
+        return resp_json["id"]
+
+    def delete_app(self, app_name: str, app_id: str) -> dict:
+        """Delete a Quickbase app.
+
+        Args:
+            app_name: The name of the app (required for confirmation).
+            app_id: The ID of the app to delete.
+
+        Returns:
+            The API response body.
+
+        Raises:
+            QuickbaseAPIError: If the API request fails.
+        """
+        resp_json, resp_code = self._rm.delete(
+            f"apps/{app_id}",
+            data={"name": app_name},
+        )
+        self._require_success(resp_json, resp_code, f"delete app '{app_name}'")
+        logger.info("Deleted app '%s' (%s)", app_name, app_id)
+        return resp_json
+
+    def get_app(self, app_id: str) -> dict:
+        """Get metadata for a Quickbase app.
+
+        Args:
+            app_id: The ID of the app.
+
+        Returns:
+            A dictionary of app metadata.
+
+        Raises:
+            QuickbaseAPIError: If the API request fails.
+        """
+        resp_json, resp_code = self._rm.get(f"apps/{app_id}")
+        self._require_success(resp_json, resp_code, f"get app '{app_id}'")
+        return resp_json
+
+    # ── Tables ────────────────────────────────────────────────────────────
+
+    def create_table(self, app_id: str, properties: dict) -> str:
+        """Create a new table in a Quickbase app.
+
+        Args:
+            app_id: The ID of the app to create the table in.
+            properties: A dictionary of table properties (must include 'name').
+
+        Returns:
+            The table ID of the newly created table.
+
+        Raises:
+            QuickbaseAPIError: If the API request fails.
+        """
+        resp_json, resp_code = self._rm.post(
+            "tables",
+            params={"appId": app_id},
+            data=properties,
+        )
+        self._require_success(resp_json, resp_code, f"create table in app '{app_id}'")
+        logger.info("Created table '%s' with ID: %s", resp_json["name"], resp_json["id"])
+        return resp_json["id"]
+
+    def get_tables(self, app_id: str) -> list[dict]:
+        """Get all tables for a Quickbase app.
+
+        Args:
+            app_id: The ID of the app.
+
+        Returns:
+            A list of table metadata dictionaries.
+
+        Raises:
+            QuickbaseAPIError: If the API request fails.
+        """
+        resp_json, resp_code = self._rm.get("tables", params={"appId": app_id})
+        self._require_success(resp_json, resp_code, f"get tables for app '{app_id}'")
+        return resp_json
+
+    def get_table_id(self, app_id: str, table_name: str) -> str:
+        """Find a table ID by its name.
+
+        Args:
+            app_id: The ID of the app containing the table.
+            table_name: The exact name of the table to find.
+
+        Returns:
+            The table ID.
+
+        Raises:
+            QuickbaseNotFoundError: If no table with the given name is found.
+        """
+        tables = self.get_tables(app_id)
+        for table in tables:
+            if table["name"] == table_name:
+                return table["id"]
+        raise QuickbaseNotFoundError(f"No table named '{table_name}' in app '{app_id}'")
+
+    def delete_table(self, app_id: str, table_id: str) -> dict:
+        """Delete a table from a Quickbase app.
+
+        Args:
+            app_id: The ID of the app containing the table.
+            table_id: The ID of the table to delete.
+
+        Returns:
+            The API response body.
+
+        Raises:
+            QuickbaseAPIError: If the API request fails.
+        """
+        resp_json, resp_code = self._rm.delete(
+            f"tables/{table_id}",
+            params={"appId": app_id},
+        )
+        self._require_success(resp_json, resp_code, f"delete table '{table_id}'")
+        logger.info("Deleted table %s from app %s", table_id, app_id)
+        return resp_json
+
+    # ── Reports ───────────────────────────────────────────────────────────
+
+    def get_reports(self, table_id: str) -> list[dict]:
+        """Get all reports for a table.
+
+        Args:
+            table_id: The ID of the table.
+
+        Returns:
+            A list of report metadata dictionaries.
+
+        Raises:
+            QuickbaseAPIError: If the API request fails.
+        """
+        resp_json, resp_code = self._rm.get("reports", params={"tableId": table_id})
+        self._require_success(resp_json, resp_code, f"get reports for table '{table_id}'")
+        return resp_json
+
+    def get_report(self, table_id: str, report_id: str) -> dict:
+        """Get metadata for a specific report.
+
+        Args:
+            table_id: The ID of the table containing the report.
+            report_id: The ID of the report.
+
+        Returns:
+            A dictionary of report metadata.
+
+        Raises:
+            QuickbaseAPIError: If the API request fails.
+        """
+        resp_json, resp_code = self._rm.get(
+            f"reports/{report_id}",
+            params={"tableId": table_id},
+        )
+        self._require_success(resp_json, resp_code, f"get report '{report_id}'")
+        return resp_json
+
+    def run_report(
+        self,
+        table_id: str,
+        report_id: str,
+        skip: int = None,
+        top: int = None,
+    ) -> dict:
+        """Run a report and return its results.
+
+        Args:
+            table_id: The ID of the table containing the report.
+            report_id: The ID of the report to run.
+            skip: Number of records to skip (for pagination).
+            top: Maximum number of records to return.
+
+        Returns:
+            The report results.
+
+        Raises:
+            QuickbaseAPIError: If the API request fails.
+        """
+        params = {"tableId": table_id}
+        if skip is not None:
+            params["skip"] = skip
+        if top is not None:
+            params["top"] = top
+
+        resp_json, resp_code = self._rm.post(
+            f"reports/{report_id}/run",
+            params=params,
+        )
+        self._require_success(resp_json, resp_code, f"run report '{report_id}'")
+        return resp_json
+
+    # ── Fields ────────────────────────────────────────────────────────────
+
+    def create_field(self, table_id: str, properties: dict) -> dict:
+        """Create a new field in a table.
+
+        Args:
+            table_id: The ID of the table.
+            properties: Field properties (must include 'label' and 'fieldType').
+
+        Returns:
+            The API response body with the created field's metadata.
+
+        Raises:
+            QuickbaseAPIError: If the API request fails.
+        """
+        resp_json, resp_code = self._rm.post(
+            "fields",
+            params={"tableId": table_id},
+            data=properties,
+        )
+        self._require_success(resp_json, resp_code, f"create field in table '{table_id}'")
+        logger.info(
+            "Created field '%s' (ID: %s) in table %s",
+            resp_json["label"],
+            resp_json["id"],
+            table_id,
+        )
+        return resp_json
+
+    def create_fields(self, table_id: str, fields: list[dict]) -> dict:
+        """Create multiple fields in a table.
+
+        Args:
+            table_id: The ID of the table.
+            fields: A list of field property dictionaries.
+
+        Returns:
+            A dict with 'succeeded' and 'failed' lists.
+        """
+        results = {"succeeded": [], "failed": []}
+        for field in fields:
+            try:
+                created = self.create_field(table_id, field)
+                results["succeeded"].append(created)
+            except QuickbaseAPIError as e:
+                logger.warning("Failed to create field %s: %s", field, e)
+                results["failed"].append({"field": field, "error": str(e)})
+
+        logger.info(
+            "%d of %d fields created for table %s",
+            len(results["succeeded"]),
+            len(fields),
+            table_id,
+        )
+        return results
+
+    def get_table_fields(self, table_id: str) -> list[dict]:
+        """Get all fields for a table.
+
+        Args:
+            table_id: The ID of the table.
+
+        Returns:
+            A list of field metadata dictionaries.
+
+        Raises:
+            QuickbaseAPIError: If the API request fails.
+        """
+        resp_json, resp_code = self._rm.get("fields", params={"tableId": table_id})
+        self._require_success(resp_json, resp_code, f"get fields for table '{table_id}'")
+        return resp_json
+
+    def get_field_id(self, table_id: str, field_label: str) -> str:
+        """Find a field ID by its label.
+
+        Args:
+            table_id: The ID of the table.
+            field_label: The exact label of the field to find.
+
+        Returns:
+            The field ID as a string.
+
+        Raises:
+            QuickbaseNotFoundError: If no field with the given label is found.
+        """
+        fields = self.get_table_fields(table_id)
+        for field in fields:
+            if field["label"] == field_label:
+                return str(field["id"])
+        raise QuickbaseNotFoundError(f"No field labeled '{field_label}' in table '{table_id}'")
+
+    def get_field_label_id_map(self, table_id: str) -> dict[str, str]:
+        """Build a mapping of field labels to field IDs.
+
+        Args:
+            table_id: The ID of the table.
+
+        Returns:
+            A dict mapping field label strings to field ID strings.
+        """
+        fields = self.get_table_fields(table_id)
+        return {f["label"]: str(f["id"]) for f in fields}
+
+    def get_key_field_id(self, app_id: str, table_id: str) -> str:
+        """Get the key field ID for a table.
+
+        Args:
+            app_id: The ID of the app.
+            table_id: The ID of the table.
+
+        Returns:
+            The key field ID as a string.
+
+        Raises:
+            QuickbaseAPIError: If the API request fails.
+        """
+        resp_json, resp_code = self._rm.get(
+            f"tables/{table_id}",
+            params={"appId": app_id},
+        )
+        self._require_success(resp_json, resp_code, f"get key field for table '{table_id}'")
+        return str(resp_json["keyFieldId"])
+
+    def set_key_field(self, table_id: str, field_id: str) -> bool:
+        """Set the key field for a table using the legacy API.
+
+        Args:
+            table_id: The ID of the table.
+            field_id: The ID of the field to set as the key field.
+
+        Returns:
+            True if the key field was set successfully.
+
+        Raises:
+            QuickbaseAPIError: If the API request fails.
+        """
+        url = f"https://{self.realm}/db/{table_id}"
+        params = {"a": "API_SetKeyField", "fid": field_id}
+
+        resp_json, resp_code = self._lm.post(url, params=params)
+        if resp_code != 200:
+            raise QuickbaseAPIError(resp_code, resp_json)
+
+        logger.info(
+            "Set key field to %s for table %s",
+            field_id,
+            table_id,
+        )
+        return True
+
+    def set_required_field(self, table_id: str, field_id: str) -> bool:
+        """Mark a field as required.
+
+        Args:
+            table_id: The ID of the table.
+            field_id: The ID of the field to mark as required.
+
+        Returns:
+            True if the field was successfully marked as required.
+
+        Raises:
+            QuickbaseAPIError: If the API request fails.
+        """
+        resp_json, resp_code = self._rm.post(
+            f"fields/{field_id}",
+            params={"tableId": table_id},
+            data={"required": True},
+        )
+        self._require_success(resp_json, resp_code, f"set field '{field_id}' as required")
+        return True
+
+    # ── Records ───────────────────────────────────────────────────────────
+
+    def upsert_records(self, table_id: str, data: list[dict]) -> dict:
+        """Insert or update records in a table.
+
+        Args:
+            table_id: The ID of the table.
+            data: A list of record dictionaries, keyed by field ID::
+
+                [
+                    {
+                        "6": {"value": "Some text"},
+                        "7": {"value": 42},
+                        "8": {"value": "2024-01-15T08:00:00Z"},
+                    }
+                ]
+
+        Returns:
+            A dict with keys: processed, created, updated, unchanged,
+            errored, errored_details.
+
+        Raises:
+            QuickbaseAPIError: If the API request fails entirely (4xx/5xx).
+        """
+        resp_json, resp_code = self._rm.post(
+            "records",
+            data={"to": table_id, "data": data},
+        )
+        if resp_code not in (200, 207):
+            raise QuickbaseAPIError(resp_code, resp_json)
+
+        metadata = resp_json["metadata"]
+        line_errors = metadata.get("lineErrors", {})
+
+        result = {
+            "processed": metadata["totalNumberOfRecordsProcessed"] - len(line_errors),
+            "created": len(metadata["createdRecordIds"]),
+            "updated": len(metadata["updatedRecordIds"]),
+            "unchanged": len(metadata["unchangedRecordIds"]),
+            "errored": len(line_errors),
+            "errored_details": line_errors,
+        }
+
+        if line_errors:
+            logger.warning(
+                "Upsert to table %s had %d line errors: %s",
+                table_id,
+                len(line_errors),
+                line_errors,
+            )
+
+        return result
+
+    def delete_records(self, table_id: str, where: str) -> int:
+        """Delete records from a table.
+
+        Args:
+            table_id: The ID of the table.
+            where: A Quickbase query string (e.g., "{6.EX.'123'}").
+
+        Returns:
+            The number of records deleted.
+
+        Raises:
+            QuickbaseAPIError: If the API request fails.
+        """
+        resp_json, resp_code = self._rm.delete(
+            "records",
+            data={"from": table_id, "where": where},
+        )
+        self._require_success(resp_json, resp_code, f"delete records from table '{table_id}'")
+        deleted = resp_json["numberDeleted"]
+        logger.info("Deleted %d records from table %s", deleted, table_id)
+        return deleted
+
+    def query_for_data(
+        self,
+        table_id: str,
+        select: list[int] = None,
+        where: str = None,
+        sort_by: list[dict] = None,
+        group_by: list[dict] = None,
+        options: dict = None,
+    ) -> dict:
+        """Query for record data from a table.
+
+        Args:
+            table_id: The ID of the table to query.
+            select: List of field IDs to return. If omitted, returns
+                fields from the default report.
+            where: A Quickbase query string (e.g., "{12.EX.'VPF'}").
+            sort_by: Sort order, e.g., [{"fieldId": 6, "order": "ASC"}].
+            group_by: Grouping, e.g., [{"fieldId": 6, "grouping": "equal-values"}].
+            options: Additional options, e.g.,
+                {"skip": 0, "top": 100, "compareWithAppLocalTime": False}.
+
+        Returns:
+            The query response including data and metadata.
+
+        Raises:
+            QuickbaseAPIError: If the API request fails.
+        """
+        body = {"from": table_id}
+        if select is not None:
+            body["select"] = select
+        if where is not None:
+            body["where"] = where
+        if sort_by is not None:
+            body["sortBy"] = sort_by
+        if group_by is not None:
+            body["groupBy"] = group_by
+        if options is not None:
+            body["options"] = options
+
+        resp_json, resp_code = self._rm.post("records/query", data=body)
+        self._require_success(resp_json, resp_code, f"query table '{table_id}'")
+        return resp_json

quickbase_api/exceptions.py

@@ -0,0 +1,19 @@
+"""Custom exceptions for the quickbase-api package."""
+
+
+class QuickbaseError(Exception):
+    """Base exception for all Quickbase errors."""
+
+
+class QuickbaseAPIError(QuickbaseError):
+    """Raised when the Quickbase API returns an unexpected status code."""
+
+    def __init__(self, status_code: int, response_body: dict):
+        self.status_code = status_code
+        self.response_body = response_body
+        message = response_body.get("message", response_body)
+        super().__init__(f"Quickbase API error {status_code}: {message}")
+
+
+class QuickbaseNotFoundError(QuickbaseError):
+    """Raised when a requested resource (table, field, etc.) is not found."""

quickbase_api/legacy_method.py

@@ -0,0 +1,66 @@
+"""Client for Quickbase's legacy XML/URL-based API endpoints."""
+
+from __future__ import annotations
+
+import logging
+
+from quickbase_api.session import create_session
+
+logger = logging.getLogger(__name__)
+
+
+class LegacyMethod:
+    """Low-level HTTP client for legacy Quickbase API endpoints.
+
+    Used for older API actions (e.g., API_SetKeyField) that are not
+    available through the modern REST API.
+    """
+
+    def __init__(self, realm: str, user_token: str):
+        self.realm = realm
+        self.session = create_session(realm, user_token)
+
+    def make_request(
+        self,
+        method: str,
+        url: str,
+        params: dict = None,
+    ) -> tuple[dict, int]:
+        """Execute an HTTP request against a legacy Quickbase endpoint.
+
+        Args:
+            method: HTTP method (GET, POST, DELETE).
+            url: Full URL for the legacy endpoint.
+            params: Optional query string parameters.
+
+        Returns:
+            A tuple of (response_body, status_code).
+        """
+        response = self.session.request(method=method, url=url, params=params)
+        try:
+            body = response.json()
+        except ValueError:
+            body = {"raw_response": response.text}
+
+        if response.status_code >= 400:
+            logger.error(
+                "Legacy API error %d on %s %s: %s",
+                response.status_code,
+                method,
+                url,
+                body,
+            )
+
+        return body, response.status_code
+
+    def get(self, url: str, params: dict = None) -> tuple[dict, int]:
+        """Send a GET request."""
+        return self.make_request("GET", url, params=params)
+
+    def post(self, url: str, params: dict = None) -> tuple[dict, int]:
+        """Send a POST request."""
+        return self.make_request("POST", url, params=params)
+
+    def delete(self, url: str, params: dict = None) -> tuple[dict, int]:
+        """Send a DELETE request."""
+        return self.make_request("DELETE", url, params=params)

quickbase_api/rest_method.py

@@ -0,0 +1,75 @@
+"""Client for Quickbase's RESTful JSON API."""
+
+from __future__ import annotations
+
+import logging
+
+from quickbase_api.session import create_session
+
+logger = logging.getLogger(__name__)
+
+BASE_URL = "https://api.quickbase.com/v1"
+
+
+class RestMethod:
+    """Low-level HTTP client for the Quickbase REST API.
+
+    Handles URL construction, request execution, and response parsing
+    for all REST API endpoints.
+    """
+
+    def __init__(self, realm: str, user_token: str):
+        self.session = create_session(realm, user_token)
+
+    def make_request(
+        self,
+        method: str,
+        endpoint: str,
+        params: dict = None,
+        data: dict = None,
+    ) -> tuple[dict, int]:
+        """Execute an HTTP request against the Quickbase REST API.
+
+        Args:
+            method: HTTP method (GET, POST, DELETE).
+            endpoint: API endpoint path (appended to base URL).
+            params: Optional query string parameters.
+            data: Optional JSON request body.
+
+        Returns:
+            A tuple of (response_body, status_code).
+        """
+        url = f"{BASE_URL}/{endpoint}"
+        response = self.session.request(
+            method=method,
+            url=url,
+            params=params,
+            json=data,
+        )
+        try:
+            body = response.json()
+        except ValueError:
+            body = {"raw_response": response.text}
+
+        if response.status_code >= 400:
+            logger.error(
+                "REST API error %d on %s %s: %s",
+                response.status_code,
+                method,
+                endpoint,
+                body,
+            )
+
+        return body, response.status_code
+
+    def get(self, endpoint: str, params: dict = None) -> tuple[dict, int]:
+        """Send a GET request."""
+        return self.make_request("GET", endpoint, params=params)
+
+    def post(self, endpoint: str, params: dict = None, data: dict = None) -> tuple[dict, int]:
+        """Send a POST request."""
+        return self.make_request("POST", endpoint, params=params, data=data)
+
+    def delete(self, endpoint: str, params: dict = None, data: dict = None) -> tuple[dict, int]:
+        """Send a DELETE request."""
+        return self.make_request("DELETE", endpoint, params=params, data=data)

quickbase_api/session.py

@@ -0,0 +1,32 @@
+"""Shared HTTP session factory for Quickbase API clients."""
+
+import requests
+from requests.adapters import HTTPAdapter, Retry
+
+
+def create_session(realm: str, user_token: str) -> requests.Session:
+    """Create a configured requests session with retry logic.
+
+    Args:
+        realm: The Quickbase realm hostname (e.g., 'mycompany.quickbase.com').
+        user_token: The Quickbase user token for authentication.
+
+    Returns:
+        A configured requests.Session with retries and auth headers.
+    """
+    session = requests.Session()
+    retries = Retry(
+        total=5,
+        backoff_factor=1,
+        status_forcelist=[429, 502, 503, 504],
+        respect_retry_after_header=True,
+    )
+    session.mount("https://", HTTPAdapter(max_retries=retries))
+    session.headers.update(
+        {
+            "QB-Realm-Hostname": realm,
+            "Authorization": f"QB-USER-TOKEN {user_token}",
+            "Content-Type": "application/json",
+        }
+    )
+    return session

quickbase_api-0.1.0.dist-info/METADATA

@@ -0,0 +1,265 @@
+Metadata-Version: 2.4
+Name: quickbase-api
+Version: 0.1.0
+Summary: A simple Python wrapper for the Quickbase API
+Project-URL: Homepage, https://github.com/tbrezler/quickbase-api
+Project-URL: Issues, https://github.com/tbrezler/quickbase-api/issues
+Project-URL: Documentation, https://github.com/tbrezler/quickbase-api#readme
+Author-email: Tyler Brezler <tbrezler@gmail.com>
+License: MIT
+License-File: LICENSE.txt
+Keywords: api,database,quickbase,rest,wrapper
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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: >=3.9
+Requires-Dist: requests>=2.25.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: responses>=0.20; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# quickbase-api
+
+A simple Python wrapper for the [Quickbase API](https://developer.quickbase.com/).
+
+[![PyPI version](https://badge.fury.io/py/quickbase-api.svg)](https://pypi.org/project/quickbase-api/)
+[![Python versions](https://img.shields.io/pypi/pyversions/quickbase-api.svg)](https://pypi.org/project/quickbase-api/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Installation
+
+```bash
+pip install quickbase-api
+```
+
+## Quick Start
+
+```python
+import quickbase_api
+
+# Option 1: Pass credentials directly
+client = quickbase_api.client(
+    realm="mycompany.quickbase.com",
+    user_token="your-user-token",
+)
+
+# Option 2: Use environment variables
+#   export QUICKBASE_REALM=mycompany.quickbase.com
+#   export QUICKBASE_USER_TOKEN=your-user-token
+client = quickbase_api.client()
+
+# Query records from a table
+records = client.query_for_data(
+    table_id="bqrg4xyza",
+    select=[3, 6, 7],
+    where="{6.EX.'Active'}",
+)
+```
+
+## Authentication
+
+This library uses [Quickbase user tokens](https://developer.quickbase.com/auth) for
+authentication. You can pass your credentials directly or set environment variables:
+
+| Environment Variable     | Description                                            |
+|--------------------------|--------------------------------------------------------|
+| `QUICKBASE_REALM`        | Your Quickbase realm (e.g., `mycompany.quickbase.com`) |
+| `QUICKBASE_USER_TOKEN`   | Your Quickbase user token                              |
+
+> **Security note:** Never commit tokens to source control. Use environment variables
+> or a secrets manager.
+
+## Usage
+
+### Apps
+
+```python
+# Create an app
+app_id = client.create_app(
+    name="My App",
+    description="An example app",
+    assign_token=True,
+)
+
+# Get app metadata
+app = client.get_app(app_id)
+
+# Delete an app
+client.delete_app("My App", app_id)
+```
+
+### Tables
+
+```python
+# Create a table
+table_id = client.create_table(app_id, {
+    "name": "Customers",
+    "description": "Customer records",
+})
+
+# List all tables in an app
+tables = client.get_tables(app_id)
+
+# Find a table ID by name
+table_id = client.get_table_id(app_id, "Customers")
+
+# Delete a table
+client.delete_table(app_id, table_id)
+```
+
+### Fields
+
+```python
+# Create a field
+client.create_field(table_id, {
+    "label": "Full Name",
+    "fieldType": "text",
+})
+
+# Create multiple fields at once
+results = client.create_fields(table_id, [
+    {"label": "Email", "fieldType": "email"},
+    {"label": "Age", "fieldType": "numeric"},
+    {"label": "Active", "fieldType": "checkbox"},
+])
+print(f"Created: {len(results['succeeded'])}, Failed: {len(results['failed'])}")
+
+# List all fields in a table
+fields = client.get_table_fields(table_id)
+
+# Find a field ID by label
+field_id = client.get_field_id(table_id, "Full Name")
+
+# Get a mapping of all field labels to IDs
+field_map = client.get_field_label_id_map(table_id)
+# {"Full Name": "6", "Email": "7", "Age": "8", "Active": "9"}
+
+# Set a key field (uses legacy API)
+client.set_key_field(table_id, field_id)
+
+# Mark a field as required
+client.set_required_field(table_id, field_id)
+```
+
+### Records
+
+```python
+# Upsert (insert or update) records
+result = client.upsert_records(table_id, [
+    {
+        "6": {"value": "Jane Smith"},
+        "7": {"value": "jane@example.com"},
+        "8": {"value": 32},
+    },
+    {
+        "6": {"value": "Bob Jones"},
+        "7": {"value": "bob@example.com"},
+        "8": {"value": 45},
+    },
+])
+print(f"Created: {result['created']}, Updated: {result['updated']}")
+
+# Check for partial failures
+if result["errored"] > 0:
+    print(f"Errors: {result['errored_details']}")
+
+# Query for records
+records = client.query_for_data(
+    table_id=table_id,
+    select=[6, 7, 8],
+    where="{8.GT.30}",
+    sort_by=[{"fieldId": 6, "order": "ASC"}],
+    options={"skip": 0, "top": 100},
+)
+
+# Delete records
+deleted = client.delete_records(table_id, where="{8.LT.18}")
+print(f"Deleted {deleted} records")
+```
+
+### Reports
+
+```python
+# List all reports for a table
+reports = client.get_reports(table_id)
+
+# Get a specific report
+report = client.get_report(table_id, report_id="1")
+
+# Run a report
+results = client.run_report(table_id, report_id="1", skip=0, top=100)
+```
+
+## Error Handling
+
+The library raises specific exceptions that you can catch and handle:
+
+```python
+from quickbase_api import QuickbaseAPIError, QuickbaseNotFoundError
+
+# Handle API errors
+try:
+    app = client.get_app("invalid-id")
+except QuickbaseAPIError as e:
+    print(f"API error {e.status_code}: {e.response_body}")
+
+# Handle not-found lookups
+try:
+    table_id = client.get_table_id(app_id, "Nonexistent Table")
+except QuickbaseNotFoundError as e:
+    print(f"Not found: {e}")
+```
+
+Exception hierarchy:
+
+```
+QuickbaseError              # Base exception
+├── QuickbaseAPIError       # HTTP errors from the API
+└── QuickbaseNotFoundError  # Resource not found in lookup methods
+```
+
+## Logging
+
+This library uses Python's built-in `logging` module. To see log output,
+configure logging in your application:
+
+```python
+import logging
+
+# See all quickbase-api log messages
+logging.basicConfig(level=logging.INFO)
+
+# Or configure just the quickbase_api logger
+logging.getLogger("quickbase_api").setLevel(logging.DEBUG)
+```
+
+## Configuration
+
+### Retry Behavior
+
+The library automatically retries failed requests up to 5 times with
+exponential backoff for the following HTTP status codes:
+
+- `429` — Rate limited
+- `502` — Bad gateway
+- `503` — Service unavailable
+- `504` — Gateway timeout
+
+## Requirements
+
+- Python 3.9+
+- [requests](https://requests.readthedocs.io/) >= 2.25.0
+
+## License
+
+This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.

quickbase_api-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+quickbase_api/__init__.py,sha256=zkWcjGbkVh3_MJbfTY7_hCGsA9bTObXF2ktFx0XTcY0,1790
+quickbase_api/api.py,sha256=t-1DFUpufgsGLjm62TFodLHd6_Ch8yS9Bpotq2pN2pE,18922
+quickbase_api/exceptions.py,sha256=DZcoNLoRVDadwZW_wZuqRn8lOfvGV3pIBqS3Z8bTQj8,667
+quickbase_api/legacy_method.py,sha256=4_tAD1gToTzBnbhHRc8WwgLCW8teVzXOzHekEaCdsNk,2003
+quickbase_api/rest_method.py,sha256=H4WhGG6KVxDdGFhipWvOa1sJ-E0i47cxJnX9NWf1rXg,2270
+quickbase_api/session.py,sha256=R2kaUebgYhgZDXQx_xF-vS2VNHkejE6xkK-EtNhZJh0,982
+quickbase_api-0.1.0.dist-info/METADATA,sha256=u48PTsFwYTJnwDBB8HdJRcIrAjrK-xgGiB8TKxl2hGI,7019
+quickbase_api-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+quickbase_api-0.1.0.dist-info/licenses/LICENSE.txt,sha256=gMsqXSha8Ek0_Q99VdMgsO-Vr1mmWSqSIHmM9WxJodA,1070
+quickbase_api-0.1.0.dist-info/RECORD,,

quickbase_api-0.1.0.dist-info/WHEEL

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

quickbase_api-0.1.0.dist-info/licenses/LICENSE.txt

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