Feature/extra endpoints

README.md

@@ -24,6 +24,7 @@ The client defaults to the v2 API. For v1 usage, see [V1.md](V1.md).
 
 - **Uploads**: Create, retrieve, and manage file uploads
 - **Datasets**: Create, list, retry, cancel, and delete datasets
+- **Entities**: Query entity metadata across datasets
 - **Jobs**: List available dataset jobs
 - **Health**: Check API health status
 
@@ -69,9 +70,11 @@ upload = Upload(
 )
 upload_id = client.uploads.create(upload)
 
-# Get upload by ID or name
+# Get upload by ID
 upload = client.uploads.get_by_id(upload_id)
-upload = client.uploads.get_by_name("My Upload")
+
+# Get upload sample metadata
+metadata = client.uploads.get_sample_metadata(upload_id)
 
 # Update sample metadata
 sample_metadata = SampleMetadata(data=[
@@ -81,6 +84,14 @@ sample_metadata = SampleMetadata(data=[
 ])
 client.uploads.update_sample_metadata(upload_id, sample_metadata)
 
+# Query uploads with filters and pagination
+result = client.uploads.query(status=["completed"], source=["maxquant"], search="my upload", page=1)
+uploads = result["data"]
+pagination = result["pagination"]
+
+# Delete an upload
+client.uploads.delete(upload_id)
+
 # Wait for upload processing to complete
 upload = client.uploads.wait_until_complete(upload_id)
 ```
@@ -100,9 +111,20 @@ dataset = Dataset(
 )
 dataset_id = client.datasets.create(dataset)
 
-# List datasets for an upload
+# Get a single dataset by ID (includes error_message)
+dataset = client.datasets.get_by_id(dataset_id)
+
+# List datasets for an upload (uses the query endpoint internally)
 datasets = client.datasets.list_by_upload(upload_id)
 
+# Query datasets with filters and pagination
+result = client.datasets.query(upload_id=upload_id, state=["COMPLETED"], type=["INTENSITY"], page=1)
+datasets = result["data"]
+pagination = result["pagination"]
+
+# Get a presigned URL for table download (csv or parquet)
+url = client.datasets.download_table_url(dataset_id, "table_name", format="csv")
+
 # Find the initial intensity dataset
 initial = client.datasets.find_initial_dataset(upload_id)
 
@@ -119,6 +141,14 @@ client.datasets.delete(dataset_id)
 ds = client.datasets.wait_until_complete(upload_id, dataset_id)
 ```
 
+## Entities
+
+```python
+# Query entity metadata (proteins, genes, peptides) across datasets
+result = client.entities.query(keyword="BRCA1", dataset_ids=["dataset-id-1", "dataset-id-2"])
+entities = result["results"]
+```
+
 ## Jobs
 
 ```python

examples/dataset/download_table.py

@@ -0,0 +1,42 @@
+"""
+Example of downloading a dataset table using the MD Python client
+"""
+
+import os
+
+from dotenv import load_dotenv
+
+from md_python import MDClient
+
+load_dotenv()
+
+
+def download_table_example():
+    """Example of getting a presigned URL for a dataset table download"""
+
+    # Initialize client (replace with your actual API token)
+    client = MDClient(api_token=os.getenv("API_TOKEN"))
+
+    # Dataset ID and table name (replace with actual values)
+    dataset_id = "YOUR_DATASET_ID"
+    table_name = "YOUR_TABLE_NAME"
+
+    # Get a CSV download URL
+    try:
+        url = client.datasets.download_table_url(dataset_id, table_name, format="csv")
+        print(f"CSV download URL: {url}")
+    except Exception as e:
+        print(f"Error getting CSV download URL: {e}")
+
+    # Get a Parquet download URL
+    try:
+        url = client.datasets.download_table_url(
+            dataset_id, table_name, format="parquet"
+        )
+        print(f"Parquet download URL: {url}")
+    except Exception as e:
+        print(f"Error getting Parquet download URL: {e}")
+
+
+if __name__ == "__main__":
+    download_table_example()

examples/dataset/get_by_id.py

@@ -0,0 +1,36 @@
+"""
+Example of getting a dataset by ID using the MD Python client
+"""
+
+import os
+
+from dotenv import load_dotenv
+
+from md_python import MDClient
+
+load_dotenv()
+
+
+def get_dataset_by_id_example():
+    """Example of getting a single dataset by ID"""
+
+    # Initialize client (replace with your actual API token)
+    client = MDClient(api_token=os.getenv("API_TOKEN"))
+
+    # Dataset ID to retrieve (replace with actual dataset ID)
+    dataset_id = "YOUR_DATASET_ID"
+
+    try:
+        dataset = client.datasets.get_by_id(dataset_id)
+        if dataset:
+            print(f"Dataset found: {dataset.name}")
+            print(f"State: {dataset.state}")
+            print(dataset)
+        else:
+            print(f"Dataset {dataset_id} not found")
+    except Exception as e:
+        print(f"Error getting dataset: {e}")
+
+
+if __name__ == "__main__":
+    get_dataset_by_id_example()

examples/dataset/query.py

@@ -0,0 +1,58 @@
+"""
+Example of querying datasets using the MD Python client
+"""
+
+import os
+
+from dotenv import load_dotenv
+
+from md_python import MDClient
+
+load_dotenv()
+
+
+def query_datasets_example():
+    """Example of querying datasets with various filters"""
+
+    # Initialize client (replace with your actual API token)
+    client = MDClient(api_token=os.getenv("API_TOKEN"))
+
+    # Query all datasets (paginated)
+    try:
+        result = client.datasets.query(page=1)
+        print(f"Found {len(result['data'])} datasets on page 1")
+        print(f"Pagination: {result['pagination']}")
+    except Exception as e:
+        print(f"Error querying datasets: {e}")
+
+    # Query datasets for a specific upload
+    try:
+        result = client.datasets.query(upload_id="YOUR_UPLOAD_ID")
+        for ds in result["data"]:
+            print(
+                f"  {ds['id']}: {ds.get('name', 'unnamed')} ({ds.get('state', 'unknown')})"
+            )
+    except Exception as e:
+        print(f"Error querying datasets: {e}")
+
+    # Query with state and type filters
+    try:
+        result = client.datasets.query(
+            state=["COMPLETED"],
+            type=["INTENSITY"],
+            page=1,
+        )
+        print(f"Found {len(result['data'])} completed intensity datasets")
+    except Exception as e:
+        print(f"Error querying datasets: {e}")
+
+    # Query with a search term
+    try:
+        result = client.datasets.query(search="pairwise")
+        print(f"Found {len(result['data'])} datasets matching 'pairwise'")
+    except Exception as e:
+        print(f"Error querying datasets: {e}")
+
+
+if __name__ == "__main__":
+    query_datasets_example()

examples/upload/delete.py

@@ -0,0 +1,35 @@
+"""
+Example of deleting an upload using the MD Python client
+"""
+
+import os
+
+from dotenv import load_dotenv
+
+from md_python import MDClient
+
+load_dotenv()
+
+
+def delete_upload_example():
+    """Example of deleting an upload by ID"""
+
+    # Initialize client (replace with your actual API token)
+    client = MDClient(api_token=os.getenv("API_TOKEN"))
+
+    # Upload ID to delete (replace with actual upload ID)
+    upload_id = "YOUR_UPLOAD_ID"
+
+    # Delete the upload
+    try:
+        success = client.uploads.delete(upload_id)
+        if success:
+            print(f"Upload {upload_id} deleted successfully!")
+        else:
+            print(f"Failed to delete upload {upload_id}")
+    except Exception as e:
+        print(f"Error deleting upload: {e}")
+
+
+if __name__ == "__main__":
+    delete_upload_example()

examples/upload/query.py

@@ -0,0 +1,58 @@
+"""
+Example of querying uploads using the MD Python client
+"""
+
+import os
+
+from dotenv import load_dotenv
+
+from md_python import MDClient
+
+load_dotenv()
+
+
+def query_uploads_example():
+    """Example of querying uploads with various filters"""
+
+    # Initialize client (replace with your actual API token)
+    client = MDClient(api_token=os.getenv("API_TOKEN"))
+
+    # Query all uploads (paginated)
+    try:
+        result = client.uploads.query(page=1)
+        print(f"Found {len(result['data'])} uploads on page 1")
+        print(f"Pagination: {result['pagination']}")
+    except Exception as e:
+        print(f"Error querying uploads: {e}")
+
+    # Query with a search term
+    try:
+        result = client.uploads.query(search="my experiment")
+        for upload in result["data"]:
+            print(f"  {upload['id']}: {upload['name']}")
+    except Exception as e:
+        print(f"Error querying uploads: {e}")
+
+    # Query with status and source filters
+    try:
+        result = client.uploads.query(
+            status=["completed"],
+            source=["maxquant"],
+            page=1,
+        )
+        print(f"Found {len(result['data'])} completed maxquant uploads")
+    except Exception as e:
+        print(f"Error querying uploads: {e}")
+
+    # Query with sample metadata filters
+    try:
+        result = client.uploads.query(
+            sample_metadata=[{"key": "condition", "value": "treated"}],
+        )
+        print(f"Found {len(result['data'])} uploads matching metadata filter")
+    except Exception as e:
+        print(f"Error querying uploads: {e}")
+
+
+if __name__ == "__main__":
+    query_uploads_example()

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "md-python"
-version = "0.2.2"
+version = "0.2.3"
 description = "Python client for Mass Dynamics API"
 readme = "README.md"
 requires-python = ">=3.11"

src/md_python/base_client.py

@@ -3,7 +3,7 @@
 """
 
 import os
-from typing import Optional
+from typing import Any, Optional
 
 import requests
 from dotenv import load_dotenv
@@ -44,6 +44,7 @@ def _make_request(
         endpoint: str,
         headers: Optional[dict] = None,
         json: Optional[dict] = None,
+        **kwargs: Any,
     ) -> requests.Response:
         """Make HTTP request to the API"""
         url = f"{self.base_url}{endpoint}"
@@ -52,4 +53,6 @@ def _make_request(
         if headers:
             request_headers.update(headers)
 
-        return requests.request(method, url, headers=request_headers, json=json)
+        return requests.request(
+            method, url, headers=request_headers, json=json, **kwargs
+        )

src/md_python/client_v2.py

@@ -6,11 +6,11 @@
 
 from .base_client import BaseMDClient
 from .resources import Health
-from .resources.v2 import Datasets, Jobs, Uploads
+from .resources.v2 import Datasets, Entities, Jobs, Uploads
 
 
 class MDClientV2(BaseMDClient):
-    """V2 API client — uploads, datasets, jobs, health"""
+    """V2 API client — uploads, datasets, entities, jobs, health"""
 
     ACCEPT_HEADER = "application/vnd.md-v2+json"
 
@@ -19,4 +19,5 @@ def __init__(self, api_token: Optional[str] = None, base_url: Optional[str] = No
         self.health = Health(self)
         self.uploads = Uploads(self)
         self.datasets = Datasets(self)
+        self.entities = Entities(self)
         self.jobs = Jobs(self)