curious-pyapi 0.1.0__py3-none-any.whl

curious_pyapi/__init__.py

@@ -0,0 +1,5 @@
+"""Python API for Curious."""
+
+from .api.curious import get_curious_token
+
+__all__ = ["get_curious_token"]

curious_pyapi/api/__init__.py

@@ -0,0 +1,5 @@
+"""API for Curious."""
+
+from .curious import get_curious_token
+
+__all__ = ["get_curious_token"]

curious_pyapi/api/curious.py

@@ -0,0 +1,81 @@
+"""Curious API functionality."""
+
+import json
+from typing import Optional
+import httpx
+
+from pydantic import AnyHttpUrl
+
+from ..schema.pyapi import Tokens
+from ..utils.defaults import CURIOUS_BASE_URL, headers
+from ..utils.data import api_data
+from ..utils.logging import get_logger
+
+LOGGER = get_logger(__name__)
+
+
+def get_curious_token(
+    curious_data: dict,
+    curious_headers: Optional[dict] = None,
+    curious_url: httpx.URL | AnyHttpUrl = CURIOUS_BASE_URL,
+) -> Optional[Tokens]:
+    """Process the response to a POST request to the specified URL.
+
+    Parameters
+    ----------
+    curious_data
+        The data to include in the POST request.
+    curious_headers
+        The headers to include in the POST request.
+    curious_url
+        The URL to send the POST request to.
+
+    Returns
+    -------
+    Tokens or None
+        An object containing (access, refresh) token strings, or None if unsuccessful.
+
+    Raises
+    ------
+    RuntimeError
+        If there is an error with the request or response.
+
+    """
+    curious_headers = headers(headers=curious_headers)
+    if isinstance(curious_url, str):
+        curious_url = httpx.URL(curious_url)
+    assert isinstance(curious_url, httpx.URL)
+    try:
+        # Sending the POST request
+        response = httpx.post(
+            curious_url.join("/auth/login"),
+            json=api_data(curious_data),
+            headers=curious_headers,
+        )
+        if response.status_code == httpx.codes.OK:
+            response_data = response.json()  # Convert response to JSON
+            access_token = (
+                response_data.get("result", {})
+                .get("token", {})
+                .get("accessToken", None)
+            )  # Get access token
+            refresh_token = (
+                response_data.get("result", {})
+                .get("token", {})
+                .get("refreshToken", None)
+            )  # Get refresh token
+        else:
+            LOGGER.exception(
+                "Failed to fetch data: %d - %s", response.status_code, response.text
+            )
+            response.raise_for_status()
+            return None
+
+        return Tokens(access=access_token, refresh=refresh_token)
+
+    except httpx.HTTPError as e:
+        msg = f"Error sending request: {e}"
+        raise RuntimeError(msg) from e
+    except json.JSONDecodeError as e:
+        msg = f"Error: Response is not valid JSON! {e}"
+        raise RuntimeError(msg) from e

curious_pyapi/schema/__init__.py

@@ -0,0 +1 @@
+"""Schemas for Curious and Curious-PyAPI."""

curious_pyapi/schema/curious.py

@@ -0,0 +1,68 @@
+"""Curious schemas."""
+
+from typing import Annotated
+
+import polars as pl
+from pydantic.types import StringConstraints
+
+from .regex import EMAIL_REGEX
+from ..utils.logging import get_logger
+
+LOGGER = get_logger(__name__)
+
+
+@pl.api.register_dataframe_namespace("curious_pyapi")
+class CuriousAccount:
+    SCHEMA = pl.Schema(
+        {
+            "email": pl.String,
+            "firstName": pl.String,
+            "lastName": pl.String,
+            "language": pl.String,
+            "secretUserId": pl.String,
+            "nickname": pl.String,
+            "tag": pl.String,
+        }
+    )
+
+    def __init__(self, df: pl.DataFrame):
+        self._df = df
+
+
+def enforce_schema(self) -> pl.DataFrame:
+    """Enforces schema, adds missing columns with nulls, and casts types."""
+    exprs = [
+        pl.col(col).cast(dtype)
+        if col in self._df.columns
+        else pl.lit(None, dtype=dtype).alias(col)
+        for col, dtype in self.SCHEMA.items()
+    ]
+
+    out_df = self._df.select(exprs)
+
+    # Evaluate against out_df where 'email' is guaranteed to exist
+    is_valid_email = pl.col("email").str.contains(EMAIL_REGEX).fill_null(False)
+
+    failures_df = out_df.filter(~is_valid_email)
+    out_df = out_df.filter(is_valid_email)
+
+    if not failures_df.is_empty():
+        log_cols = [
+            col
+            for col in ["email", "secretUserId", "nickname"]
+            if col in failures_df.columns
+        ]
+        LOGGER.error(
+            "Dropped %d records due to invalid email addresses:\n%s",
+            failures_df.height,
+            failures_df.select(log_cols),
+        )
+
+    return out_df
+
+
+CuriousId = Annotated[
+    str,
+    StringConstraints(pattern=r"^[a-zA-Z0-9]{8}(-[a-zA-Z0-9]{4}){3}-[a-zA-Z0-9]{12}$"),
+]
+"""ID string for a Curious entity."""

curious_pyapi/schema/pyapi.py

@@ -0,0 +1,29 @@
+"""Curious-PyAPI schemas."""
+
+from pydantic import BaseModel, EmailStr, SecretStr
+
+from .curious import CuriousId
+from ..utils.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class CuriousAuth(BaseModel):
+    """Required data for authentication and decryption."""
+
+    curious_email: EmailStr
+    curious_password: SecretStr
+    applet_id: CuriousId
+    applet_password: SecretStr
+
+    @property
+    def login_credentials(self) -> dict[str, str | SecretStr]:
+        """Return email and password as dictionary for API request."""
+        return {"email": self.curious_email, "password": self.curious_password}
+
+
+class Tokens(BaseModel):
+    """Curious tokens."""
+
+    access: SecretStr
+    refresh: SecretStr

curious_pyapi/schema/regex.py

@@ -0,0 +1,3 @@
+"""Global schema."""
+
+EMAIL_REGEX = r"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$"

curious_pyapi/utils/__init__.py

@@ -0,0 +1 @@
+"""Curious-PyAPI utilities."""

curious_pyapi/utils/data.py

@@ -0,0 +1,11 @@
+"""Data utilities."""
+
+from pydantic import SecretStr
+
+
+def api_data(data: dict) -> dict:
+    """Prep data for API calls."""
+    return {
+        k: v.get_secret_value() if isinstance(v, SecretStr) else v
+        for k, v in data.items()
+    }

curious_pyapi/utils/defaults.py

@@ -0,0 +1,16 @@
+"""Default values."""
+
+from typing import Optional
+
+from httpx import URL
+
+CURIOUS_BASE_URL = URL("https://api-v2.gettingcurious.com")
+"""Canonical URL for Curious API."""
+
+
+def headers(
+    token: Optional[str] = None, headers: Optional[dict] = None
+) -> dict[str, str]:
+    """Return Curious headers."""
+    auth = {"Authorization": f"Bearer {token}"} if token else {}
+    return {"Content-Type": "application/json"} | auth | (headers or {})

curious_pyapi/utils/logging.py

@@ -0,0 +1,8 @@
+"""Logging utilities."""
+
+import logging
+
+
+def get_logger(name: str) -> logging.Logger:
+    """Get Logger object."""
+    return logging.getLogger(name)

curious_pyapi-0.1.0.dist-info/METADATA

@@ -0,0 +1,18 @@
+Metadata-Version: 2.5
+Name: curious-pyapi
+Version: 0.1.0
+Summary: Python interface for Curious API.
+Author-email: Jon Cluce <jon.clucas@childmind.org>
+License-File: LICENSE
+Requires-Python: >=3.14
+Requires-Dist: fastexcel>=0.21.0
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: polars>=1.44.0
+Requires-Dist: pydantic[email]>=2.13.4
+Description-Content-Type: text/markdown
+
+# Curious-PyAPI
+
+Python interfaces for Curious API.
+
+Work-in-progress, with calls added as we use them.

curious_pyapi-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+curious_pyapi/__init__.py,sha256=sgS_xN-0tTip9sdcqCE5zbdj4K-tUbE68Ndto4goDV8,107
+curious_pyapi/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+curious_pyapi/api/__init__.py,sha256=YNUqXzLA4i2Bm43zB57-BrZc-eP02jWZ7e7BioqOxGE,96
+curious_pyapi/api/curious.py,sha256=DPfza1VCIm0WE-BU5PTWQh4-1si3pynMtWoEHwM_LfY,2442
+curious_pyapi/schema/__init__.py,sha256=8bWZXWv0Rvbm5UinVBlOjc7QILSSXyfLAtd1OntbHS8,45
+curious_pyapi/schema/curious.py,sha256=tLynmstA8rXOrayEjR0FuIFxAouW3UqWszErO10alUI,1781
+curious_pyapi/schema/pyapi.py,sha256=bbephKjYs9jr7EmTNMA-fXJnDQOL58ifPPwWej_VpGg,720
+curious_pyapi/schema/regex.py,sha256=qvVvb57PsZ6euS_WlJUef9jBY8T7Da6TQxiedHgGPTo,88
+curious_pyapi/utils/__init__.py,sha256=PqZNsxLVBIVEEx_vIp5xtnM0K3HPtFLgWTFKQxOwdOU,31
+curious_pyapi/utils/data.py,sha256=_iHD2vluH7gyBCG3JQY4RwDzwLJQkusbAfcqpPxGrUc,244
+curious_pyapi/utils/defaults.py,sha256=jlTJnqbMu8Y5I6Wq_SfrSW3tKUf2b6w5_9UhG_ZWdQI,444
+curious_pyapi/utils/logging.py,sha256=dj1OWUQLRRHiit2PNwW1t6wh-KxJB4dOJaKlP6k9TNE,152
+curious_pyapi-0.1.0.dist-info/METADATA,sha256=ZwFjmbAhS-_WL7ZQTnyF0AQWU-YXr1_x9SzHIU994kU,473
+curious_pyapi-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+curious_pyapi-0.1.0.dist-info/licenses/LICENSE,sha256=Sf2NH6l_RwtdmPtvewFiAg3o3gV5mogv4iE3O118PuY,1096
+curious_pyapi-0.1.0.dist-info/RECORD,,

curious_pyapi-0.1.0.dist-info/WHEEL

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

curious_pyapi-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Child Mind Institute — Research Teams
+
+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.