pytrials-v2 0.1.0__py3-none-any.whl

pytrials/__init__.py

@@ -0,0 +1,63 @@
+"""pytrials-v2: a modern, fully-typed Python SDK for the ClinicalTrials.gov API v2."""
+
+from __future__ import annotations
+
+from .client import CTGClient
+from .errors import CTGError, NotFoundError, RateLimitError
+from .models import OverallStatus, Phase, Study, StudySearchResult, StudyType
+from .modules.studies import StudiesModule
+
+__version__ = "0.1.0"
+
+
+class ClinicalTrials:
+    """The main entry point for the SDK.
+
+    Exposes module namespaces (currently :attr:`studies`) over a shared HTTP
+    client. Async support, the QueryBuilder, pagination, and stats endpoints are
+    planned for later releases.
+
+    Example:
+        >>> ctg = ClinicalTrials()
+        >>> results = ctg.studies.search(condition="breast cancer")
+        >>> study = ctg.studies.get("NCT04852770")
+    """
+
+    def __init__(
+        self,
+        base_url: str = "https://clinicaltrials.gov/api/v2",
+        timeout: float = 30.0,
+        page_size: int = 100,
+    ) -> None:
+        self._client = CTGClient(
+            base_url=base_url,
+            timeout=timeout,
+            default_page_size=page_size,
+        )
+        self.studies = StudiesModule(self._client)
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._client.close()
+
+    def __enter__(self) -> ClinicalTrials:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+
+__all__ = [
+    "CTGClient",
+    "CTGError",
+    "ClinicalTrials",
+    "NotFoundError",
+    "OverallStatus",
+    "Phase",
+    "RateLimitError",
+    "StudiesModule",
+    "Study",
+    "StudySearchResult",
+    "StudyType",
+    "__version__",
+]

pytrials/client.py

@@ -0,0 +1,87 @@
+"""Low level HTTP client wrapping httpx for the ClinicalTrials.gov API v2."""
+
+from __future__ import annotations
+
+from typing import Any, NoReturn
+
+import httpx
+
+from .errors import CTGError, NotFoundError, RateLimitError
+
+DEFAULT_BASE_URL = "https://clinicaltrials.gov/api/v2"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_PAGE_SIZE = 100
+
+
+class CTGClient:
+    """Synchronous HTTP client for the ClinicalTrials.gov API v2.
+
+    This is an internal building block. Most users should go through the
+    :class:`pytrials.ClinicalTrials` facade and its module namespaces.
+    """
+
+    def __init__(
+        self,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        default_page_size: int = DEFAULT_PAGE_SIZE,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.default_page_size = default_page_size
+        self._client = httpx.Client(
+            base_url=self.base_url,
+            timeout=timeout,
+            headers={"Accept": "application/json"},
+        )
+
+    def get(self, path: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
+        """Issue a GET request and return the parsed JSON body.
+
+        Raises :class:`NotFoundError` on 404, :class:`RateLimitError` on 429,
+        and :class:`CTGError` on any other 4xx or 5xx response.
+        """
+        cleaned = _clean_params(params or {})
+        response = self._client.get(path, params=cleaned)
+        if response.is_success:
+            data: dict[str, Any] = response.json()
+            return data
+        self._raise_for_status(response)
+
+    @staticmethod
+    def _raise_for_status(response: httpx.Response) -> NoReturn:
+        status = response.status_code
+        message = _extract_message(response)
+        if status == 404:
+            raise NotFoundError(status, message)
+        if status == 429:
+            raise RateLimitError(status, message)
+        raise CTGError(status, message)
+
+    def close(self) -> None:
+        """Close the underlying httpx client and its connection pool."""
+        self._client.close()
+
+    def __enter__(self) -> CTGClient:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+
+def _clean_params(params: dict[str, Any]) -> dict[str, Any]:
+    """Drop None values so they are not serialized into the query string."""
+    return {key: value for key, value in params.items() if value is not None}
+
+
+def _extract_message(response: httpx.Response) -> str:
+    """Pull a useful error message out of an error response body."""
+    try:
+        body = response.json()
+    except ValueError:
+        return response.text or response.reason_phrase
+    if isinstance(body, dict):
+        for key in ("message", "detail", "error"):
+            value = body.get(key)
+            if isinstance(value, str):
+                return value
+    return response.reason_phrase

pytrials/errors.py

@@ -0,0 +1,28 @@
+"""Exception types raised by the SDK."""
+
+from __future__ import annotations
+
+
+class CTGError(Exception):
+    """Base error for all ClinicalTrials.gov API failures.
+
+    Carries the HTTP status code (when available) and a human readable message.
+    """
+
+    def __init__(self, status_code: int | None, message: str) -> None:
+        self.status_code = status_code
+        self.message = message
+        super().__init__(message)
+
+    def __str__(self) -> str:
+        if self.status_code is None:
+            return self.message
+        return f"[{self.status_code}] {self.message}"
+
+
+class NotFoundError(CTGError):
+    """Raised on HTTP 404, for example when an NCT ID does not exist."""
+
+
+class RateLimitError(CTGError):
+    """Raised on HTTP 429 when the API rate limit (around 50 req/min) is hit."""

pytrials/models/__init__.py

@@ -0,0 +1,33 @@
+"""Pydantic models for ClinicalTrials.gov API v2 responses."""
+
+from __future__ import annotations
+
+from .enums import OverallStatus, Phase, StudyType
+from .search import StudySearchResult
+from .study import (
+    ConditionsModule,
+    DesignModule,
+    IdentificationModule,
+    Organization,
+    ProtocolSection,
+    Sponsor,
+    SponsorCollaboratorsModule,
+    StatusModule,
+    Study,
+)
+
+__all__ = [
+    "ConditionsModule",
+    "DesignModule",
+    "IdentificationModule",
+    "Organization",
+    "OverallStatus",
+    "Phase",
+    "ProtocolSection",
+    "Sponsor",
+    "SponsorCollaboratorsModule",
+    "StatusModule",
+    "Study",
+    "StudySearchResult",
+    "StudyType",
+]

pytrials/models/enums.py

@@ -0,0 +1,46 @@
+"""Enumerated values from the ClinicalTrials.gov API v2 data model.
+
+These mirror the real, case sensitive values the API accepts and returns.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class OverallStatus(str, Enum):
+    """Recruitment status of a study (statusModule.overallStatus)."""
+
+    ACTIVE_NOT_RECRUITING = "ACTIVE_NOT_RECRUITING"
+    COMPLETED = "COMPLETED"
+    ENROLLING_BY_INVITATION = "ENROLLING_BY_INVITATION"
+    NOT_YET_RECRUITING = "NOT_YET_RECRUITING"
+    RECRUITING = "RECRUITING"
+    SUSPENDED = "SUSPENDED"
+    TERMINATED = "TERMINATED"
+    WITHDRAWN = "WITHDRAWN"
+    AVAILABLE = "AVAILABLE"
+    NO_LONGER_AVAILABLE = "NO_LONGER_AVAILABLE"
+    TEMPORARILY_NOT_AVAILABLE = "TEMPORARILY_NOT_AVAILABLE"
+    APPROVED_FOR_MARKETING = "APPROVED_FOR_MARKETING"
+    WITHHELD = "WITHHELD"
+    UNKNOWN = "UNKNOWN"
+
+
+class Phase(str, Enum):
+    """Clinical trial phase (designModule.phases)."""
+
+    NA = "NA"
+    EARLY_PHASE1 = "EARLY_PHASE1"
+    PHASE1 = "PHASE1"
+    PHASE2 = "PHASE2"
+    PHASE3 = "PHASE3"
+    PHASE4 = "PHASE4"
+
+
+class StudyType(str, Enum):
+    """Type of study (designModule.studyType)."""
+
+    INTERVENTIONAL = "INTERVENTIONAL"
+    OBSERVATIONAL = "OBSERVATIONAL"
+    EXPANDED_ACCESS = "EXPANDED_ACCESS"

pytrials/models/search.py

@@ -0,0 +1,17 @@
+"""Models for the /studies search response."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from .study import Study
+
+
+class StudySearchResult(BaseModel):
+    """The parsed response from a GET /studies search request."""
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+    studies: list[Study] = Field(default_factory=list)
+    next_page_token: str | None = Field(default=None, alias="nextPageToken")
+    total_count: int | None = Field(default=None, alias="totalCount")

pytrials/models/study.py

@@ -0,0 +1,133 @@
+"""Pydantic v2 models mirroring the ClinicalTrials.gov API v2 study record.
+
+The models are intentionally minimal for v0.1 but use the real API field names
+(camelCase) via aliases. Every model allows extra fields so that new API fields
+do not break deserialization, and every field is optional because the API has
+many nullable values.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from .enums import OverallStatus, Phase, StudyType
+
+_CONFIG = ConfigDict(populate_by_name=True, extra="allow")
+
+
+class Organization(BaseModel):
+    """Sponsoring or submitting organization (identificationModule.organization)."""
+
+    model_config = _CONFIG
+
+    full_name: str | None = Field(default=None, alias="fullName")
+    org_class: str | None = Field(default=None, alias="class")
+
+
+class IdentificationModule(BaseModel):
+    """Identifiers and titles (protocolSection.identificationModule)."""
+
+    model_config = _CONFIG
+
+    nct_id: str | None = Field(default=None, alias="nctId")
+    brief_title: str | None = Field(default=None, alias="briefTitle")
+    official_title: str | None = Field(default=None, alias="officialTitle")
+    organization: Organization | None = None
+
+
+class StatusModule(BaseModel):
+    """Recruitment status and key dates (protocolSection.statusModule)."""
+
+    model_config = _CONFIG
+
+    overall_status: OverallStatus | None = Field(default=None, alias="overallStatus")
+    status_verified_date: str | None = Field(default=None, alias="statusVerifiedDate")
+
+
+class Sponsor(BaseModel):
+    """A lead sponsor or collaborator."""
+
+    model_config = _CONFIG
+
+    name: str | None = None
+    org_class: str | None = Field(default=None, alias="class")
+
+
+class SponsorCollaboratorsModule(BaseModel):
+    """Lead sponsor and collaborators (protocolSection.sponsorCollaboratorsModule)."""
+
+    model_config = _CONFIG
+
+    lead_sponsor: Sponsor | None = Field(default=None, alias="leadSponsor")
+    collaborators: list[Sponsor] = Field(default_factory=list)
+
+
+class ConditionsModule(BaseModel):
+    """Conditions and keywords (protocolSection.conditionsModule)."""
+
+    model_config = _CONFIG
+
+    conditions: list[str] = Field(default_factory=list)
+    keywords: list[str] = Field(default_factory=list)
+
+
+class DesignModule(BaseModel):
+    """Study design (protocolSection.designModule)."""
+
+    model_config = _CONFIG
+
+    study_type: StudyType | None = Field(default=None, alias="studyType")
+    phases: list[Phase] = Field(default_factory=list)
+
+
+class ProtocolSection(BaseModel):
+    """The protocol section of a study record."""
+
+    model_config = _CONFIG
+
+    identification_module: IdentificationModule | None = Field(
+        default=None, alias="identificationModule"
+    )
+    status_module: StatusModule | None = Field(default=None, alias="statusModule")
+    sponsor_collaborators_module: SponsorCollaboratorsModule | None = Field(
+        default=None, alias="sponsorCollaboratorsModule"
+    )
+    conditions_module: ConditionsModule | None = Field(
+        default=None, alias="conditionsModule"
+    )
+    design_module: DesignModule | None = Field(default=None, alias="designModule")
+
+
+class Study(BaseModel):
+    """A single ClinicalTrials.gov study record."""
+
+    model_config = _CONFIG
+
+    protocol_section: ProtocolSection | None = Field(
+        default=None, alias="protocolSection"
+    )
+    has_results: bool = Field(default=False, alias="hasResults")
+
+    @property
+    def nct_id(self) -> str | None:
+        """Convenience accessor for the NCT identifier."""
+        protocol = self.protocol_section
+        if protocol is None or protocol.identification_module is None:
+            return None
+        return protocol.identification_module.nct_id
+
+    @property
+    def brief_title(self) -> str | None:
+        """Convenience accessor for the brief title."""
+        protocol = self.protocol_section
+        if protocol is None or protocol.identification_module is None:
+            return None
+        return protocol.identification_module.brief_title
+
+    @property
+    def overall_status(self) -> OverallStatus | None:
+        """Convenience accessor for the recruitment status."""
+        protocol = self.protocol_section
+        if protocol is None or protocol.status_module is None:
+            return None
+        return protocol.status_module.overall_status

pytrials/modules/__init__.py

@@ -0,0 +1,7 @@
+"""Module namespaces exposed on the ClinicalTrials client."""
+
+from __future__ import annotations
+
+from .studies import StudiesModule
+
+__all__ = ["StudiesModule"]

pytrials/modules/studies.py

@@ -0,0 +1,81 @@
+"""The studies module: search and fetch study records."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..client import CTGClient
+from ..models.enums import OverallStatus, Phase
+from ..models.search import StudySearchResult
+from ..models.study import Study
+
+
+def _as_value_list(value: Any) -> list[str]:
+    """Coerce a scalar, enum, or sequence into a list of string values."""
+    if value is None:
+        return []
+    if isinstance(value, (str, OverallStatus, Phase)):
+        return [_to_str(value)]
+    if isinstance(value, (list, tuple, set)):
+        return [_to_str(item) for item in value]
+    return [_to_str(value)]
+
+
+def _to_str(value: Any) -> str:
+    if isinstance(value, OverallStatus):
+        return value.value
+    if isinstance(value, Phase):
+        return value.value
+    return str(value)
+
+
+class StudiesModule:
+    """Operations against the /studies endpoints."""
+
+    def __init__(self, client: CTGClient) -> None:
+        self._client = client
+
+    def search(
+        self,
+        condition: str | None = None,
+        status: str | OverallStatus | list[str | OverallStatus] | None = None,
+        phase: str | Phase | list[str | Phase] | None = None,
+        page_size: int | None = None,
+        sort: str | None = None,
+        **extra: Any,
+    ) -> StudySearchResult:
+        """Search studies and return a validated :class:`StudySearchResult`.
+
+        Maps the friendly keyword arguments onto the real API query parameters:
+        ``query.cond``, ``filter.overallStatus``, ``aggFilters`` (for phase),
+        ``pageSize``, ``sort``, and ``countTotal=true``.
+        """
+        params: dict[str, Any] = {
+            "countTotal": "true",
+            "pageSize": page_size if page_size is not None else self._client.default_page_size,
+        }
+
+        if condition is not None:
+            params["query.cond"] = condition
+
+        statuses = _as_value_list(status)
+        if statuses:
+            params["filter.overallStatus"] = ",".join(statuses)
+
+        phases = _as_value_list(phase)
+        if phases:
+            agg = ",".join(f"phase:{value}" for value in phases)
+            params["aggFilters"] = agg
+
+        if sort is not None:
+            params["sort"] = sort
+
+        params.update(extra)
+
+        data = self._client.get("/studies", params=params)
+        return StudySearchResult.model_validate(data)
+
+    def get(self, nct_id: str) -> Study:
+        """Fetch a single study by NCT ID via /studies/{nctId}."""
+        data = self._client.get(f"/studies/{nct_id}")
+        return Study.model_validate(data)

pytrials_v2-0.1.0.dist-info/METADATA

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: pytrials-v2
+Version: 0.1.0
+Summary: A modern, fully-typed Python SDK for the ClinicalTrials.gov API v2.
+Project-URL: Homepage, https://github.com/raami/pytrials-v2
+Project-URL: Repository, https://github.com/raami/pytrials-v2
+Author: Prahlaad Ram
+License: MIT License
+        
+        Copyright (c) 2026 Prahlaad R.
+        
+        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.
+License-File: LICENSE
+Keywords: api,clinical-trials,clinicaltrials,healthcare,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2
+Description-Content-Type: text/markdown
+
+# pytrials-v2
+
+A modern, fully-typed Python SDK for the [ClinicalTrials.gov API v2](https://clinicaltrials.gov/data-api/api).
+
+> Status: early development. See [PROJECT_PLAN.md](./PROJECT_PLAN.md) for the full design and roadmap.
+
+## Why
+
+The ClinicalTrials.gov API v2 (JSON, token pagination, OpenAPI 3.0) launched in 2024, and the old XML v1 API was retired. There is still no well-designed Python SDK for v2. pytrials-v2 aims to be the default: Pydantic-modeled, async-capable, with the ergonomic helpers clinical-trial data consumers actually need.
+
+## What it offers
+
+- Full Pydantic v2 models for every API response (real autocomplete, no dict-digging)
+- A validating QueryBuilder that catches bad status, phase, and sort values before the request
+- Async auto-pagination over `pageToken`
+- DataFrame integration that flattens the nested study structure for analysis
+- Date normalization across the API's inconsistent formats
+- Built-in rate limiting (50 req/min) and retry with backoff
+
+## Quickstart (planned API)
+
+```python
+from pytrials import ClinicalTrials
+
+ctg = ClinicalTrials()
+
+results = ctg.studies.search(condition="breast cancer", status=["RECRUITING"], phase=["PHASE3"])
+study = ctg.studies.get("NCT04852770")
+df = ctg.studies.search(condition="diabetes", status=["RECRUITING"]).to_dataframe()
+```
+
+## Roadmap
+
+- **v0.1.0 Core**: client, search/get, core models, error handling, PyPI publish
+- **v0.2.0 Ergonomics**: QueryBuilder, async paginator, stats endpoints, rate limiting
+- **v0.3.0 Data science**: DataFrame integration, docs site, 90%+ coverage
+- **v1.0.0 Stable**: full results-section models, CLI, notebook examples
+
+## License
+
+MIT

pytrials_v2-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+pytrials/__init__.py,sha256=EJkJJIj10OHXoT2ivbd-Z4B1qTTVrkYM30h_MVD85A8,1638
+pytrials/client.py,sha256=9NU_y-kNtJS6r9FOnwDGYd1LPKLdd_BRYaCne3SJVTQ,2863
+pytrials/errors.py,sha256=57VSlvSXxT81i2oeZgOGM6Q8AjDNjClF_3jYbt_J1wg,805
+pytrials/models/__init__.py,sha256=mOqbyJsCs0zf65GgvT8JJPLGSByMvi3JvUMzzDM-qMM,679
+pytrials/models/enums.py,sha256=p7KBtGtUhaPQvxJd5IWmg55LRtj4tsiB2rFqARubix0,1261
+pytrials/models/search.py,sha256=PLZDBJ6k97hAgl4iVcra9Tp6keYMAUhbDy4WNRK-HXE,536
+pytrials/models/study.py,sha256=zQqW10fjGECmx207SNg2AFtGDSUnnCGvItjnUfdPY1Q,4349
+pytrials/modules/__init__.py,sha256=q_M0t-AmLE4anwWnUErlSTzFj9zzXrn8w7_ap3QHlo4,163
+pytrials/modules/studies.py,sha256=rezDYpz9q7HnHhCv33-oWTPdtk1xncieF4bbm4QTC6I,2586
+pytrials_v2-0.1.0.dist-info/METADATA,sha256=8oJMzqsCL251rzpzAOuZz4jBFIneQnV7Q-w-WgL51SM,3657
+pytrials_v2-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+pytrials_v2-0.1.0.dist-info/licenses/LICENSE,sha256=0c59Jt9ArzNKAPGxgNSIHwZBph_TAQOcu-9XHSEHc-s,1068
+pytrials_v2-0.1.0.dist-info/RECORD,,

pytrials_v2-0.1.0.dist-info/WHEEL

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

pytrials_v2-0.1.0.dist-info/licenses/LICENSE

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