Add basic interaction with PhysioNet API.

Author: tompollard

README.md

@@ -10,12 +10,104 @@ pip install physionet
 
 ## Usage
 
+### API Client
+
+Interact with the PhysioNet API to explore and search published projects:
+
+```python
+from physionet import PhysioNetClient
+
+# Create a client instance
+client = PhysioNetClient()
+
+# List all published projects
+projects = client.projects.list_published()
+print(f"Total projects: {len(projects)}")
+
+# Display first few projects
+for project in projects[:5]:
+    print(f"{project.slug} v{project.version}: {project.title}")
+
+# Search for projects
+ecg_projects = client.projects.search('ECG')
+print(f"Found {len(ecg_projects)} ECG-related projects")
+
+# Get all versions of a project
+versions = client.projects.list_versions('mimic-iv-demo')
+for version in versions:
+    print(f"Version {version.version}: {version.title}")
+
+# Get detailed information about a specific version
+details = client.projects.get_details('mimic-iv-demo', '2.2')
+print(f"Title: {details.title}")
+print(f"DOI: {details.doi}")
+print(f"Published: {details.publish_datetime}")
+print(f"Size: {details.main_storage_size} bytes")
+```
+
+### Authenticated Requests
+
+For endpoints that require authentication (e.g., downloading checksums):
+
+```python
+from physionet import PhysioNetClient
+
+# Create client with authentication
+client = PhysioNetClient(
+    username='your_username',
+    password='your_password'
+)
+
+# Download checksums file
+client.projects.download_checksums(
+    'mimic-iv-demo',
+    '2.2',
+    'checksums.txt'
+)
+
+# Or use environment variables
+# Set PHYSIONET_USERNAME and PHYSIONET_PASSWORD
+from physionet.api.utils import get_credentials_from_env
+
+username, password = get_credentials_from_env()
+client = PhysioNetClient(username=username, password=password)
+```
+
+### Using Context Manager
+
+```python
+from physionet import PhysioNetClient
+
+# Automatically close session when done
+with PhysioNetClient() as client:
+    projects = client.projects.list_published()
+    print(f"Found {len(projects)} projects")
+```
+
+### Utility Functions
+
+```python
+from physionet.api.utils import format_size
+
+# Format bytes to human-readable size
+size = format_size(16224447)
+print(size)  # "15.47 MB"
+```
+
+## Error Handling
+
 ```python
-import physionet as pn
+from physionet import PhysioNetClient
+from physionet.api.exceptions import NotFoundError, RateLimitError, ForbiddenError
 
-# Download a dataset
-pn.download('ptbdb', 'data/ptbdb')
+client = PhysioNetClient()
 
-# List all datasets
-pn.list_datasets()
+try:
+    details = client.projects.get_details('nonexistent-project', '1.0')
+except NotFoundError:
+    print("Project not found")
+except RateLimitError:
+    print("Rate limit exceeded, please wait before retrying")
+except ForbiddenError:
+    print("Access denied - check credentials or project permissions")
 ```

physionet/__init__.py

@@ -0,0 +1,3 @@
+from .api import PhysioNetClient
+
+__all__ = ["PhysioNetClient"]

physionet/api/__init__.py

@@ -0,0 +1,17 @@
+from .client import PhysioNetClient
+from .exceptions import (
+    PhysioNetAPIError,
+    BadRequestError,
+    ForbiddenError,
+    NotFoundError,
+    RateLimitError,
+)
+
+__all__ = [
+    "PhysioNetClient",
+    "PhysioNetAPIError",
+    "BadRequestError",
+    "ForbiddenError",
+    "NotFoundError",
+    "RateLimitError",
+]

physionet/api/client.py

@@ -0,0 +1,101 @@
+import requests
+from typing import Optional, Dict, Any
+from urllib.parse import urljoin
+
+from .exceptions import (
+    PhysioNetAPIError,
+    BadRequestError,
+    ForbiddenError,
+    NotFoundError,
+    RateLimitError,
+)
+from .endpoints import ProjectsAPI
+
+
+class PhysioNetClient:
+    """Main client for interacting with PhysioNet API v1."""
+
+    def __init__(
+        self,
+        base_url: str = "https://physionet.org",
+        username: Optional[str] = None,
+        password: Optional[str] = None,
+        timeout: int = 30,
+    ):
+        """
+        Initialize PhysioNet API client.
+
+        Args:
+            base_url: Base URL for PhysioNet (default: https://physionet.org)
+            username: Optional username for authenticated requests
+            password: Optional password for authenticated requests
+            timeout: Request timeout in seconds
+        """
+        self.base_url = base_url.rstrip("/")
+        self.api_base = f"{self.base_url}/api/v1/"
+        self.timeout = timeout
+        self.session = requests.Session()
+
+        if username and password:
+            self.session.auth = (username, password)
+
+        self.session.headers.update({"User-Agent": "PhysioNet-Python-Client/1.0", "Accept": "application/json"})
+
+        self.projects = ProjectsAPI(self)
+
+    def _make_request(
+        self, method: str, endpoint: str, params: Optional[Dict[str, Any]] = None, **kwargs
+    ) -> requests.Response:
+        """
+        Make HTTP request to API.
+
+        Args:
+            method: HTTP method (GET, POST, etc.)
+            endpoint: API endpoint path
+            params: Query parameters
+            **kwargs: Additional arguments for requests
+
+        Returns:
+            Response object
+
+        Raises:
+            PhysioNetAPIError: On API errors
+            requests.RequestException: On network errors
+        """
+        url = urljoin(self.api_base, endpoint)
+
+        response = self.session.request(method=method, url=url, params=params, timeout=self.timeout, **kwargs)
+
+        if response.status_code >= 400:
+            self._handle_error(response)
+
+        return response
+
+    def _handle_error(self, response: requests.Response):
+        """Handle API error responses."""
+        try:
+            error_data = response.json()
+            error_msg = error_data.get("error", str(error_data))
+        except Exception:
+            error_msg = response.text or response.reason
+
+        if response.status_code == 400:
+            raise BadRequestError(error_msg)
+        elif response.status_code == 403:
+            raise ForbiddenError(error_msg)
+        elif response.status_code == 404:
+            raise NotFoundError(error_msg)
+        elif response.status_code == 429:
+            raise RateLimitError(error_msg)
+        else:
+            raise PhysioNetAPIError(f"HTTP {response.status_code}: {error_msg}")
+
+    def close(self):
+        """Close the session."""
+        self.session.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()

physionet/api/endpoints.py

@@ -0,0 +1,118 @@
+from typing import List, Optional, Iterator
+from physionet.api.models import PublishedProject, ProjectVersion, ProjectDetail
+
+
+class ProjectsAPI:
+    """API methods for interacting with projects."""
+
+    def __init__(self, client):
+        self.client = client
+
+    def list_published(self) -> List[PublishedProject]:
+        """
+        List all published projects.
+
+        Returns:
+            List of PublishedProject objects
+
+        Note:
+            The API returns all projects in a single response (no pagination).
+        """
+        response = self.client._make_request("GET", "projects/published/")
+        data = response.json()
+
+        return [PublishedProject.from_dict(p) for p in data]
+
+    def iter_published(self) -> Iterator[PublishedProject]:
+        """
+        Iterator that yields all published projects.
+
+        Yields:
+            PublishedProject objects
+
+        Note:
+            This is a convenience method that iterates over list_published() results.
+        """
+        for project in self.list_published():
+            yield project
+
+    def search(self, search_term: str, resource_type: Optional[List[str]] = None) -> List[PublishedProject]:
+        """
+        Search published projects.
+
+        Args:
+            search_term: Search keywords
+            resource_type: Filter by resource type(s), or ['all'] for all types
+
+        Returns:
+            List of matching PublishedProject objects
+        """
+        params = {"search_term": search_term}
+
+        if resource_type:
+            params["resource_type"] = resource_type
+
+        response = self.client._make_request("GET", "projects/search/", params=params)
+        data = response.json()
+
+        return [PublishedProject.from_dict(p) for p in data]
+
+    def list_versions(self, project_slug: str) -> List[ProjectVersion]:
+        """
+        List all versions of a project.
+
+        Args:
+            project_slug: Project identifier
+
+        Returns:
+            List of ProjectVersion objects
+        """
+        endpoint = f"projects/{project_slug}/versions/"
+        response = self.client._make_request("GET", endpoint)
+        data = response.json()
+
+        return [
+            ProjectVersion(
+                slug=v["slug"],
+                title=v["title"],
+                version=v["version"],
+                abstract=v["abstract"],
+                citation=v["citation"],
+            )
+            for v in data
+        ]
+
+    def get_details(self, project_slug: str, version: str) -> ProjectDetail:
+        """
+        Get detailed information about a specific project version.
+
+        Args:
+            project_slug: Project identifier
+            version: Version number
+
+        Returns:
+            ProjectDetail object
+        """
+        endpoint = f"projects/{project_slug}/versions/{version}/"
+        response = self.client._make_request("GET", endpoint)
+        data = response.json()
+
+        return ProjectDetail.from_dict(data)
+
+    def download_checksums(self, project_slug: str, version: str, output_path: str):
+        """
+        Download SHA256 checksums file for a project.
+
+        Args:
+            project_slug: Project identifier
+            version: Version number
+            output_path: Path to save the checksums file
+
+        Note:
+            Requires authentication and project access permissions.
+        """
+        endpoint = f"projects/published/{project_slug}/{version}/sha256sums/"
+        response = self.client._make_request("GET", endpoint)
+
+        with open(output_path, "wb") as f:
+            f.write(response.content)

physionet/api/exceptions.py

@@ -0,0 +1,28 @@
+class PhysioNetAPIError(Exception):
+    """Base exception for PhysioNet API errors."""
+
+    pass
+
+
+class BadRequestError(PhysioNetAPIError):
+    """Raised when API returns 400 Bad Request."""
+
+    pass
+
+
+class ForbiddenError(PhysioNetAPIError):
+    """Raised when API returns 403 Forbidden."""
+
+    pass
+
+
+class NotFoundError(PhysioNetAPIError):
+    """Raised when API returns 404 Not Found."""
+
+    pass
+
+
+class RateLimitError(PhysioNetAPIError):
+    """Raised when API returns 429 Too Many Requests."""
+
+    pass