athena-client 1.0.4__tar.gz

athena_client-1.0.4/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: athena-client
+Version: 1.0.4
+Summary: Production-ready Python SDK for the OHDSI Athena Concepts API
+Author: Athena-Client Core Engineering Team
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/username/athena-client
+Project-URL: Documentation, https://athena-client.readthedocs.io
+Project-URL: Issues, https://github.com/username/athena-client/issues
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: orjson>=3.9.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pydantic-settings
+Provides-Extra: async
+Requires-Dist: httpx>=0.18.0; extra == "async"
+Provides-Extra: pandas
+Requires-Dist: pandas>=1.3.0; extra == "pandas"
+Provides-Extra: cli
+Requires-Dist: click>=8.0.0; extra == "cli"
+Requires-Dist: rich>=10.0.0; extra == "cli"
+Provides-Extra: yaml
+Requires-Dist: pyyaml>=6.0; extra == "yaml"
+Provides-Extra: crypto
+Requires-Dist: cryptography>=36.0.0; extra == "crypto"
+Provides-Extra: all
+Requires-Dist: httpx>=0.18.0; extra == "all"
+Requires-Dist: pandas>=1.3.0; extra == "all"
+Requires-Dist: click>=8.0.0; extra == "all"
+Requires-Dist: rich>=10.0.0; extra == "all"
+Requires-Dist: pyyaml>=6.0; extra == "all"
+Requires-Dist: cryptography>=36.0.0; extra == "all"
+Provides-Extra: dev
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+Requires-Dist: cyclonedx-bom>=3.15.0; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: pip-audit>=2.6; extra == "dev"
+Requires-Dist: pytest>=8.2; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: pytest-asyncio[mode-auto]>=0.23; extra == "dev"
+Requires-Dist: hypothesis>=6.103; extra == "dev"
+Requires-Dist: vcrpy>=6.0; extra == "dev"
+Requires-Dist: rich>=13.7; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.1; extra == "dev"
+Requires-Dist: pytest-benchmark>=4.0; extra == "dev"
+Requires-Dist: bandit>=1.7.5; extra == "dev"
+Requires-Dist: cyclonedx-python-lib>=5.2.0; extra == "dev"
+Requires-Dist: types-requests; extra == "dev"
+Requires-Dist: types-PyYAML; extra == "dev"
+Requires-Dist: pandas-stubs; extra == "dev"
+
+# athena-client
+[![SBOM](https://img.shields.io/badge/SBOM-available-blue)](sbom.json)
+
+A production-ready Python SDK for the OHDSI Athena Concepts API.
+
+## Installation
+
+```bash
+pip install athena-client
+```
+
+With optional dependencies:
+```bash
+pip install athena-client[cli]      # Command-line interface
+pip install athena-client[async]    # Async client
+pip install athena-client[pandas]   # DataFrame output support
+pip install athena-client[yaml]     # YAML output format
+pip install athena-client[crypto]   # HMAC authentication
+pip install athena-client[all]      # All optional dependencies
+```
+
+## Quick Start
+
+```python
+from athena_client import Athena
+
+# Create a client with default settings (public Athena server)
+athena = Athena()
+
+# Search for concepts
+results = athena.search("aspirin")
+
+# Various output formats
+concepts = results.all()         # List of Pydantic models
+top_three = results.top(3)       # First three results
+as_dict = results.to_list()      # List of dictionaries
+as_json = results.to_json()      # JSON string
+as_df = results.to_df()          # pandas DataFrame
+
+# Get details for a specific concept
+details = athena.details(concept_id=1127433)
+
+# Get relationships
+rels = athena.relationships(concept_id=1127433)
+
+# Get graph
+graph = athena.graph(concept_id=1127433, depth=5)
+
+# Get comprehensive summary
+summary = athena.summary(concept_id=1127433)
+```
+
+## CLI Usage
+
+```bash
+# Install CLI dependencies
+pip install "athena-client[cli]"
+
+# Search for concepts
+athena search "aspirin"
+
+# Get details for a specific concept
+athena details 1127433
+
+# Get a summary with various output formats
+athena summary 1127433 --output yaml
+```
+
+## Configuration
+
+The client can be configured through:
+1. Constructor arguments
+2. Environment variables
+3. A `.env` file
+4. Default values
+
+```python
+# Explicit configuration
+athena = Athena(
+    base_url="https://custom.athena.server/api/v1",
+    token="your-bearer-token",
+    timeout=15,
+    max_retries=5
+)
+```
+
+Or use environment variables:
+```
+ATHENA_BASE_URL=https://custom.athena.server/api/v1
+ATHENA_TOKEN=your-bearer-token
+ATHENA_TIMEOUT_SECONDS=15
+ATHENA_MAX_RETRIES=5
+```
+
+## Advanced Query DSL
+
+For complex queries, use the Query DSL:
+
+```python
+from athena_client.query import Q
+
+# Build complex queries
+q = (Q.term("diabetes") & Q.term("type 2")) | Q.exact('"diabetic nephropathy"')
+
+# Use with search
+results = athena.search(q)
+```
+
+### Property-Based Tests
+
+We use **Hypothesis** for edge-case discovery. New core utilities or parsers **must** include at least one Hypothesis scenario.
+
+## Modern Installation & Packaging
+
+This project uses the modern Python packaging standard with `pyproject.toml` for build and dependency management. You do not need to use `setup.py` for installation or development. Instead, use the following commands:
+
+### Install with pip (recommended)
+
+```bash
+pip install .
+```
+
+Or, for development (editable install with dev dependencies):
+
+> **Note:** For editable installs with extras, make sure you have recent versions of pip and setuptools:
+> ```bash
+> pip install --upgrade pip setuptools
+> ```
+```bash
+pip install -e '.[dev]'
+```
+
+### Why `pyproject.toml`?
+- All build, dependency, and metadata configuration is in `pyproject.toml`.
+- Compatible with modern Python tooling (pip, build, poetry, etc).
+- `setup.py` is only needed for legacy or advanced customizations.
+
+For more details, see [Packaging Python Projects](https://packaging.python.org/en/latest/tutorials/packaging-projects/).
+
+## Documentation
+
+For complete documentation, visit: [https://athena-client.readthedocs.io](https://athena-client.readthedocs.io)
+
+## License
+
+MIT

athena_client-1.0.4/README.md

@@ -0,0 +1,146 @@
+# athena-client
+[![SBOM](https://img.shields.io/badge/SBOM-available-blue)](sbom.json)
+
+A production-ready Python SDK for the OHDSI Athena Concepts API.
+
+## Installation
+
+```bash
+pip install athena-client
+```
+
+With optional dependencies:
+```bash
+pip install athena-client[cli]      # Command-line interface
+pip install athena-client[async]    # Async client
+pip install athena-client[pandas]   # DataFrame output support
+pip install athena-client[yaml]     # YAML output format
+pip install athena-client[crypto]   # HMAC authentication
+pip install athena-client[all]      # All optional dependencies
+```
+
+## Quick Start
+
+```python
+from athena_client import Athena
+
+# Create a client with default settings (public Athena server)
+athena = Athena()
+
+# Search for concepts
+results = athena.search("aspirin")
+
+# Various output formats
+concepts = results.all()         # List of Pydantic models
+top_three = results.top(3)       # First three results
+as_dict = results.to_list()      # List of dictionaries
+as_json = results.to_json()      # JSON string
+as_df = results.to_df()          # pandas DataFrame
+
+# Get details for a specific concept
+details = athena.details(concept_id=1127433)
+
+# Get relationships
+rels = athena.relationships(concept_id=1127433)
+
+# Get graph
+graph = athena.graph(concept_id=1127433, depth=5)
+
+# Get comprehensive summary
+summary = athena.summary(concept_id=1127433)
+```
+
+## CLI Usage
+
+```bash
+# Install CLI dependencies
+pip install "athena-client[cli]"
+
+# Search for concepts
+athena search "aspirin"
+
+# Get details for a specific concept
+athena details 1127433
+
+# Get a summary with various output formats
+athena summary 1127433 --output yaml
+```
+
+## Configuration
+
+The client can be configured through:
+1. Constructor arguments
+2. Environment variables
+3. A `.env` file
+4. Default values
+
+```python
+# Explicit configuration
+athena = Athena(
+    base_url="https://custom.athena.server/api/v1",
+    token="your-bearer-token",
+    timeout=15,
+    max_retries=5
+)
+```
+
+Or use environment variables:
+```
+ATHENA_BASE_URL=https://custom.athena.server/api/v1
+ATHENA_TOKEN=your-bearer-token
+ATHENA_TIMEOUT_SECONDS=15
+ATHENA_MAX_RETRIES=5
+```
+
+## Advanced Query DSL
+
+For complex queries, use the Query DSL:
+
+```python
+from athena_client.query import Q
+
+# Build complex queries
+q = (Q.term("diabetes") & Q.term("type 2")) | Q.exact('"diabetic nephropathy"')
+
+# Use with search
+results = athena.search(q)
+```
+
+### Property-Based Tests
+
+We use **Hypothesis** for edge-case discovery. New core utilities or parsers **must** include at least one Hypothesis scenario.
+
+## Modern Installation & Packaging
+
+This project uses the modern Python packaging standard with `pyproject.toml` for build and dependency management. You do not need to use `setup.py` for installation or development. Instead, use the following commands:
+
+### Install with pip (recommended)
+
+```bash
+pip install .
+```
+
+Or, for development (editable install with dev dependencies):
+
+> **Note:** For editable installs with extras, make sure you have recent versions of pip and setuptools:
+> ```bash
+> pip install --upgrade pip setuptools
+> ```
+```bash
+pip install -e '.[dev]'
+```
+
+### Why `pyproject.toml`?
+- All build, dependency, and metadata configuration is in `pyproject.toml`.
+- Compatible with modern Python tooling (pip, build, poetry, etc).
+- `setup.py` is only needed for legacy or advanced customizations.
+
+For more details, see [Packaging Python Projects](https://packaging.python.org/en/latest/tutorials/packaging-projects/).
+
+## Documentation
+
+For complete documentation, visit: [https://athena-client.readthedocs.io](https://athena-client.readthedocs.io)
+
+## License
+
+MIT

athena_client-1.0.4/athena_client/__init__.py

@@ -0,0 +1,233 @@
+"""
+athena-client: Production-ready Python SDK for the OHDSI Athena Concepts API
+"""
+
+from typing import Any, Dict, Optional
+
+from .models import ConceptDetails, ConceptRelationsGraph, ConceptRelationship
+
+__version__ = "1.0.4"
+
+
+class Athena:
+    """
+    Main facade for the Athena API client.
+
+    This class provides a simplified interface to the Athena API with six
+    intuitive verbs that cover 95% of day-to-day use cases.
+    """
+
+    def __init__(
+        self,
+        base_url: Optional[str] = None,
+        token: Optional[str] = None,
+        client_id: Optional[str] = None,
+        private_key: Optional[str] = None,
+        timeout: Optional[int] = None,
+        max_retries: Optional[int] = None,
+        backoff_factor: Optional[float] = None,
+    ) -> None:
+        """
+        Initialize the Athena facade with optional configuration.
+
+        Args:
+            base_url: The base URL for the Athena API.
+            token: Bearer token for authentication.
+            client_id: Client ID for HMAC authentication.
+            private_key: Private key for HMAC signing.
+            timeout: HTTP timeout in seconds.
+            max_retries: Maximum number of retry attempts.
+            backoff_factor: Exponential backoff factor for retries.
+        """
+        # Import here to avoid circular imports
+        from .client import AthenaClient  # pylint: disable=import-outside-toplevel
+
+        self._client = AthenaClient(
+            base_url=base_url,
+            token=token,
+            client_id=client_id,
+            private_key=private_key,
+            timeout=timeout,
+            max_retries=max_retries,
+            backoff_factor=backoff_factor,
+        )
+
+    def search(
+        self,
+        query: Any,  # Can be str or Q object
+        *,
+        exact: Optional[str] = None,
+        fuzzy: bool = False,
+        wildcard: Optional[str] = None,
+        boosts: Optional[Dict[str, Any]] = None,
+        debug: bool = False,
+        page_size: int = 20,
+        page: int = 0,
+        domain: Optional[str] = None,
+        vocabulary: Optional[str] = None,
+        standard_concept: Optional[str] = None,
+    ) -> "SearchResult":
+        """
+        Search for concepts in the Athena vocabulary.
+
+        Args:
+            query: The search query string
+            exact: Exact match phrase
+            fuzzy: Whether to enable fuzzy matching
+            wildcard: Wildcard pattern
+            boosts: Dictionary of field boosts
+            debug: Enable debug mode
+            page_size: Number of results per page
+            page: Page number (0-indexed)
+            domain: Filter by domain
+            vocabulary: Filter by vocabulary
+            standard_concept: Filter by standard concept status
+
+        Returns:
+            SearchResult object containing the search results
+        """
+        from .search_result import SearchResult
+
+        # Handle Q object if provided
+        query_str = query
+        if hasattr(query, "to_boosts") and callable(query.to_boosts):
+            boosts = query.to_boosts()
+            query_str = ""
+
+        data = self._client.search_concepts(
+            query=query_str,
+            exact=exact,
+            fuzzy=fuzzy,
+            wildcard=wildcard,
+            boosts=boosts,
+            debug=debug,
+            page_size=page_size,
+            page=page,
+            domain=domain,
+            vocabulary=vocabulary,
+            standard_concept=standard_concept,
+        )
+
+        return SearchResult(data)
+
+    def details(self, concept_id: int) -> ConceptDetails:
+        """
+        Get detailed information for a specific concept.
+
+        Args:
+            concept_id: The concept ID to get details for
+
+        Returns:
+            ConceptDetails object
+        """
+        return self._client.get_concept_details(concept_id)
+
+    def relationships(
+        self,
+        concept_id: int,
+        *,
+        relationship_id: Optional[str] = None,
+        only_standard: bool = False,
+    ) -> ConceptRelationship:
+        """
+        Get relationships for a specific concept.
+
+        Args:
+            concept_id: The concept ID to get relationships for
+            relationship_id: Filter by relationship type
+            only_standard: Only include standard concepts
+
+        Returns:
+            ConceptRelationship object
+        """
+        return self._client.get_concept_relationships(
+            concept_id=concept_id,
+            relationship_id=relationship_id,
+            only_standard=only_standard,
+        )
+
+    def graph(
+        self,
+        concept_id: int,
+        *,
+        depth: int = 10,
+        zoom_level: int = 4,
+    ) -> ConceptRelationsGraph:
+        """
+        Get relationship graph for a specific concept.
+
+        Args:
+            concept_id: The concept ID to get graph for
+            depth: Maximum depth of relationships to traverse
+            zoom_level: Zoom level for the graph
+
+        Returns:
+            ConceptRelationsGraph object
+        """
+        return self._client.get_concept_graph(
+            concept_id=concept_id,
+            depth=depth,
+            zoom_level=zoom_level,
+        )
+
+    def summary(self, concept_id: int) -> Dict[str, Any]:
+        """
+        Get a comprehensive summary for a concept.
+
+        This aggregates details, relationships, and graph information.
+
+        Args:
+            concept_id: The concept ID to summarize
+
+        Returns:
+            Dictionary containing details, relationships, and graph
+        """
+        details = self.details(concept_id)
+        relationships = self.relationships(concept_id)
+        graph = self.graph(concept_id)
+
+        return {
+            "details": details,
+            "relationships": relationships,
+            "graph": graph,
+        }
+
+    @staticmethod
+    def capabilities() -> Dict[str, Dict[str, Any]]:
+        """
+        Get machine-readable manifest of all supported verbs.
+
+        Returns:
+            Dictionary containing capabilities information
+        """
+        return {
+            "search": {
+                "endpoint": "/concepts",
+                "auth": "anonymous|bearer",
+                "outputs": ["models", "list", "dataframe", "json", "yaml", "csv"],
+            },
+            "details": {
+                "endpoint": "/concepts/{id}",
+                "auth": "anonymous|bearer",
+                "outputs": ["model", "json"],
+            },
+            "relationships": {
+                "endpoint": "/concepts/{id}/relationships",
+                "auth": "anonymous|bearer",
+                "outputs": ["model", "json"],
+            },
+            "graph": {
+                "endpoint": "/concepts/{id}/relations",
+                "auth": "anonymous|bearer",
+                "outputs": ["model", "json"],
+            },
+            "summary": {
+                "composed_of": ["details", "relationships", "graph"],
+                "outputs": ["dict"],
+            },
+        }
+
+
+# Type hint for return annotation - needed at the end to avoid circular imports
+# This import is used for type hints only, which is why it's placed at the bottom
+from .search_result import SearchResult  # noqa: E402