cellannotation · rm1113 · Oct 6, 2025 · Oct 3, 2025 · Oct 3, 2025 · Oct 3, 2025
diff --git a/.github/workflows/python-app.yml b/.github/workflows/python-app.yml
@@ -17,8 +17,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ['3.9', '3.10', '3.11']
-        constrain: ["-c constrain_min.txt", ""]
+        python-version: ['3.9', '3.10', '3.11', '3.12', '3.13']
     steps:
     - uses: actions/checkout@v4
     - name: Set up Python ${{ matrix.python-version }}
@@ -30,7 +29,7 @@ jobs:
         python -m pip install --upgrade pip
         python -m pip install --upgrade uv
         uv pip install --system flake8 pytest
-        if [ -f requirements.txt ]; then uv pip install --system -U -r requirements.txt; fi
+        uv pip install --system -r pyproject.toml
     - name: Lint with flake8
       run: |
         # stop the build if there are Python syntax errors or undefined names

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,6 +1,18 @@
 # Changelog
 
-## [Unreleased]
+## [v1.0.0] - 2025-10-03
+
+### First stable release
+
+- **search_datasets** endpoint
+- **search_cells** endpoint
+- **download_urls** endpoint
+- **dataset_metadata** endpoint
+- **embedding_data** endpoint
+- **heatmap** endpoint
+- **differential_expression** endpoint
+- **session management** with token-based authentication
+
 
 ## [v0.0.1] - 2024-12-12
 

diff --git a/README.md b/README.md
@@ -1,154 +1,59 @@
-# Python client for CAP GraphQL API
 
-Python client uses Ariadne code generation https://ariadnegraphql.org/blog/2023/02/02/ariadne-codegen to generate pydantic models and graphQL client.  
+# Python client for Cell-Annotation-Platform GraphQL API
+[![PyPI version](https://img.shields.io/pypi/v/cap-sc-client)](https://pypi.org/project/cap-sc-client/)
 
-1. Add new queries to `queries.graphql`
-2. Run `ariadne-codegen`
+The Python package provides a simple interface to interact with the [Cell Annotation Platform](https://celltype.info/) (CAP) GraphQL API. The package allows to search for datasets, cell labels metadata and get molecular profiles of cell types published on CAP.
 
-# API calls
+## Installation
 
-Create CAP object `cap = Cap()` and use it to access public API endpoints.
+```bash
+pip install -U cap-sc-client
+```
 
-If you plan to use CAP API endpoints that require authoriization please set environment variables either `CAP_LOGIN` / `CAP_PWD` or `CAP_TOKEN` with custom token that you can get from CAP UI. CAP will automatically use this information to authenticate you during authorized endpoints requests.
+## Basic usage
 
-## Search datasets
-```Python
-cap.search_datasets(search=None, organism=None, tissue=None, assay=None, limit = 50, offset=0, sort=[])
-```
-returns CAP published datasets searched by a keyword that could be filtered by `organism`, `tissue` or `assay`.
-The result could be paginated using `limit`, `offset` and sorted using `sort` and `ASC`, `DESC` keywords
-
-Example:
-```Python 
-cap.search_datasets(
-    search="blood"
-    organism=["Homo sapiens"], 
-    tissue=["stomach","pyloric antrum"],
-    assay=["10x 3' v1"],
-    sort=[{'name':'ASC'}]
-)
-```
-Result:
-```Python
-{
-    'results': [
-        {
-            'id': '420', 
-            'name': 'Charting human development ...',
-            'description': 'Developing human multi-organ ...',
-            'cellCount': 155232,
-            'labelsets': [
-                {
-                    'id': '3714', 
-                    'name': 'assay', 
-                    'description': None, 
-                    'labels': [
-                        {
-                            'id': '25154', 
-                            'name': "10x 3' v2", 
-                            'count': 146343,
-                            'typename__': 'Label'
-                        }
-                        ...
-                    ],
-                    'typename__': 'Labelset'
-                }
-                ...
-            ],
-            'project': {
-                'version': 1.0,
-                'id': '263', 
-                'name': 'Charting human ...', 
-                'owner': {
-                    'displayName': 'CAP Data Upload'
-                },
-                'typename__': 'Project'
-            }            
-        }
-    ...
-    ]
-}
-```
-## Dataset download URLs
-```Python
-cap.download_urls(id)
-```
-returns URLs for published dataset files: annData, Seurat, JSON (zip), JSON (tar)
+The main goal of the package is to provide an interface to access CAP datasets and cell label annotations collection via standard python toolings like pandas dataframes.
 
-Example:
-```Python
-cap.download_urls(678)
 ```
-Result:
-```Python
-{
-    'downloadUrls': {
-        'annDataUrl': 'https://storage.googleapis.com/...h5ad',
-        'seuratUrl': None,
-        'capJsonUrlTar': 'https://storage.googleapis.com/...h5ad.json.tar',
-        'capJsonUrlZip': 'https://storage.googleapis.com/...h5ad.json.zip',
-        'typename__': 'DatasetDownloadUrlsResponse'
-    }
-}
+>>> from cap_sc_client import CapClient
+>>> cp = CapClient()
+>>> datasets = cp.search_datasets(limit=5, offset=0, organism=["Homo sapiens"])
+>>> datasets.head()
+     id                           name  cell_count                        project
+0  1427  Skin fibroblasts   - Pan-d...    337376.0  {'id': '613', 'name': 'Pan...
+1  1426  Skin fibroblast scRNA-seq ...    153546.0  {'id': '613', 'name': 'Pan...
+2  1157  Single cell atlas of the h...     72788.0  {'id': '544', 'name': 'Sin...
+3  1156  snRNA-seq of human retina ...   3177310.0  {'id': '544', 'name': 'Sin...
+4  1154  snRNA-seq of human retina ...    691008.0  {'id': '544', 'name': 'Sin...
+>>> labels = cp.search_cell_labels(limit=10, offset=0)
+>>> labels[["full_name", "ontology_term_exists", "marker_genes"]]
+             full_name  ontology_term_exists         marker_genes
+0  cycling stromal ...                 True   [MKI67, TOP2A, C...
+1  alveolar type 1 ...                 True          [PDPN, HOPX]
+2    mesoderm 2 (ZEB2)                False                [ZEB2]
+3          acinar cell                 True               [PRSS1]
+4               neuron                 True               [STMN2]
+5   smooth muscle cell                 True   [DES, CNN1, ACTA...
+6        ciliated cell                 True               [FOXJ1]
+7         Schwann cell                 True                 [MPZ]
+8     pancreatic cells                False                [PDX1]
+9            club cell                 True             [SCGB1A1]
 ```
 
-## Search cell labels
-```Python
-cap.search_cell_labels(search=None, organism=None, tissue=None, assay=None, limit = 50, offset=0, sort=[])
-```
-returns cell labels from CAP published datasets searched by a keyword that could be filtered by `organism`, `tissue` or `assay`.
-The result could be paginated using `limit`, `offset` and sorted using `sort` and `ASC`, `DESC` keywords
-
-Example:
-```Python 
-cap.search_cell_labels(
-    search="blood"
-    organism=["Homo sapiens"], 
-    tissue=["stomach","pyloric antrum"],
-    assay=["10x 3' v1"],
-    sort=[{'name':'ASC'}]
-)
-```
-Result:
-```Python
-{
-    'lookupCells': [
-        {
-            'id': '51853', 
-            'fullName': 'progenitor cell', 
-            'name': 'progenitor cell', 
-            'ontologyTermExists': True, 
-            'ontologyTermId': 'CL:0011026', 
-            'ontologyTerm': 'progenitor cell', 
-            'synonyms': ['unknown'], 
-            'categoryOntologyTermExists': True, 
-            'categoryOntologyTermId': 'CL:0011115', 
-            'categoryOntologyTerm': 'precursor cell', 
-            'categoryFullName': 'precursor cell', 
-            'markerGenes': ['EOMES'], 
-            'canonicalMarkerGenes': ['unknown'], 
-            'count': 53089, 
-            'ontologyAssessment': None,
-            'labelset': {
-                'id': '6387', 
-                'name': 'cell_type', 
-                'description': 'An atlas ...', 
-                'dataset': {
-                    'id': '532', 
-                    'name': 'Second Trimester ...', 
-                    'project': {
-                        'id': '305', 
-                        'name': 'Human developing neocortex by area', 
-                        'version': 1,
-                        'typename__': 'Project'
-                    },
-                    'typename__': 'Dataset'
-                },
-                'typename__': 'Labelset'
-            },
-            'typename__': 'Label'
-        }
-        ...
-    ]
-}
-```
+There is also a `MDSession` class that allows to interact molecular profile of cell types within specific dataset. However, this class requires user to be familiar with CAP MD page. For more examples please refer to [examples](./examples/) folder and GitHub Wiki for detailed documentation. 
+
+## Documentation
+
+Detailed documentation is available on [GitHub Wiki](https://github.com/cellannotation/cap-python-client/wiki).
+
+
+## Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md).
+
+## Development
+
+This project uses [Ariadne code generation](https://ariadnegraphql.org/blog/2023/02/02/ariadne-codegen) to generate pydantic models and graphQL client. In case of need to update or add new queries please follow the steps below:
+
+1. Add new queries to [queries.graphql](./queries.graphql)
+2. Run `ariadne-codegen`
diff --git a/cap_client/__init__.py → cap_sc_client/__init__.py b/cap_client/__init__.py → cap_sc_client/__init__.py