discotoolkit 1.2.2__tar.gz → 1.3.0__tar.gz

{discotoolkit-1.2.2 → discotoolkit-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: discotoolkit
-Version: 1.2.2
+Version: 1.3.0
 Summary: DISCOtoolkit is an python package that allows users to access data and use the tools provided by the DISCO database.
 Home-page: https://disco.bii.a-star.edu.sg/
 Author: Li Mengwei, Rom Uddamvathanak
@@ -43,7 +43,7 @@ Dynamic: summary
 -->
 [![Documentation](https://img.shields.io/badge/docs-disco.bii.a--star.edu.sg-blue)](https://disco.bii.a-star.edu.sg/v1/docs/toolkit/guide/) [![Downloads](https://static.pepy.tech/personalized-badge/discotoolkit?period=total&units=international_system&left_color=black&right_color=orange&left_text=Downloads)](https://pepy.tech/project/discotoolkit) [![PyPI version](https://img.shields.io/pypi/v/discotoolkit)](https://pypi.org/project/discotoolkit)
 
-# DISCOtoolkit 1.2.2
+# DISCOtoolkit 1.3.0
 
 DISCOtoolkit is a Python package for accessing the data and tools of the [DISCO database](https://disco.bii.a-star.edu.sg/) (DISCO v1). Read the documentation, with tutorials and the API reference, at [disco.bii.a-star.edu.sg/v1/docs/toolkit/guide](https://disco.bii.a-star.edu.sg/v1/docs/toolkit/guide/).
 
@@ -52,7 +52,7 @@ DISCOtoolkit is a Python package for accessing the data and tools of the [DISCO
 - CELLiD: cell type annotation
 - scEnrichment: gene set enrichment using DISCO DEGs
 
-> **Use DISCO v1.** The toolkit is developed and tested against **DISCO v1**, which is the default, and that is the server we recommend. DISCO v2 has its own R package ([DISCOtoolkit](https://github.com/JinmiaoChenLab/DISCOtoolkit)). The Python package can be pointed at a v2 server, but that is not tested; see [Choosing a server](#choosing-a-server).
+> **For DISCO v1.** The toolkit is built for and tested against **DISCO v1**, which it uses by default. DISCO v2 is not supported; it has its own R package, [DISCOtoolkit](https://github.com/JinmiaoChenLab/DISCOtoolkit).
 
 ## Quickstart (Google Colab)
 
@@ -96,17 +96,17 @@ python -m ipykernel install --user --name disco --display-name "disco"
 python -m pip install -U discotoolkit
 ```
 
-## Choosing a server
+## Server
 
 ```python
 import discotoolkit as dt
 
-dt.get_server()                       # 'https://disco.bii.a-star.edu.sg/disco_v3_api/'  (DISCO v1, the default)
-dt.set_server("v2")                   # DISCO v2 (not tested; DISCO v1 is the supported server)
-dt.set_server("https://my.server/disco_v3_api/")   # any server with the same API
+dt.get_server()                       # 'https://disco.bii.a-star.edu.sg/disco_v3_api/'  (DISCO v1)
+dt.set_server("https://my.mirror/disco_v3_api/")   # a mirror or test copy of DISCO v1
 ```
 
-or set the `DISCO_API_URL` environment variable before importing the package.
+or set the `DISCO_API_URL` environment variable before importing the package. The tests use this
+to run against a local copy of DISCO v1.
 
 ## Testing
 

{discotoolkit-1.2.2 → discotoolkit-1.3.0}/README.md

@@ -8,7 +8,7 @@
 -->
 [![Documentation](https://img.shields.io/badge/docs-disco.bii.a--star.edu.sg-blue)](https://disco.bii.a-star.edu.sg/v1/docs/toolkit/guide/) [![Downloads](https://static.pepy.tech/personalized-badge/discotoolkit?period=total&units=international_system&left_color=black&right_color=orange&left_text=Downloads)](https://pepy.tech/project/discotoolkit) [![PyPI version](https://img.shields.io/pypi/v/discotoolkit)](https://pypi.org/project/discotoolkit)
 
-# DISCOtoolkit 1.2.2
+# DISCOtoolkit 1.3.0
 
 DISCOtoolkit is a Python package for accessing the data and tools of the [DISCO database](https://disco.bii.a-star.edu.sg/) (DISCO v1). Read the documentation, with tutorials and the API reference, at [disco.bii.a-star.edu.sg/v1/docs/toolkit/guide](https://disco.bii.a-star.edu.sg/v1/docs/toolkit/guide/).
 
@@ -17,7 +17,7 @@ DISCOtoolkit is a Python package for accessing the data and tools of the [DISCO
 - CELLiD: cell type annotation
 - scEnrichment: gene set enrichment using DISCO DEGs
 
-> **Use DISCO v1.** The toolkit is developed and tested against **DISCO v1**, which is the default, and that is the server we recommend. DISCO v2 has its own R package ([DISCOtoolkit](https://github.com/JinmiaoChenLab/DISCOtoolkit)). The Python package can be pointed at a v2 server, but that is not tested; see [Choosing a server](#choosing-a-server).
+> **For DISCO v1.** The toolkit is built for and tested against **DISCO v1**, which it uses by default. DISCO v2 is not supported; it has its own R package, [DISCOtoolkit](https://github.com/JinmiaoChenLab/DISCOtoolkit).
 
 ## Quickstart (Google Colab)
 
@@ -61,17 +61,17 @@ python -m ipykernel install --user --name disco --display-name "disco"
 python -m pip install -U discotoolkit
 ```
 
-## Choosing a server
+## Server
 
 ```python
 import discotoolkit as dt
 
-dt.get_server()                       # 'https://disco.bii.a-star.edu.sg/disco_v3_api/'  (DISCO v1, the default)
-dt.set_server("v2")                   # DISCO v2 (not tested; DISCO v1 is the supported server)
-dt.set_server("https://my.server/disco_v3_api/")   # any server with the same API
+dt.get_server()                       # 'https://disco.bii.a-star.edu.sg/disco_v3_api/'  (DISCO v1)
+dt.set_server("https://my.mirror/disco_v3_api/")   # a mirror or test copy of DISCO v1
 ```
 
-or set the `DISCO_API_URL` environment variable before importing the package.
+or set the `DISCO_API_URL` environment variable before importing the package. The tests use this
+to run against a local copy of DISCO v1.
 
 ## Testing
 

{discotoolkit-1.2.2 → discotoolkit-1.3.0}/discotoolkit/GlobalVariable.py

@@ -2,13 +2,13 @@
 Settings shared by the rest of the package: logging, the request timeout and --
 most importantly -- which DISCO server the toolkit talks to.
 
-By default the toolkit talks to DISCO v1 (https://disco.bii.a-star.edu.sg). DISCO v1 is the
-server the toolkit is developed and tested against, and the one we recommend. Other servers
-are possible but untested (the "v2" preset in particular):
+The toolkit is built for, and tested against, DISCO v1 (https://disco.bii.a-star.edu.sg), and
+talks to it by default. DISCO v2 is not supported: it has its own R package (DISCOtoolkit).
+
+For a mirror or a test copy of DISCO v1 there is still a way to point it elsewhere:
 
     import discotoolkit as dt
-    dt.set_server("v2")                          # a named preset
-    dt.set_server("https://my.server/disco_v3_api/")   # any server with the same API
+    dt.set_server("https://my.mirror/disco_v3_api/")
 
 or set the DISCO_API_URL environment variable before importing the package.
 """
@@ -21,19 +21,26 @@ logging.basicConfig(level=logging.INFO)
 # seconds to wait for the server; the reference downloads are tens of MB
 timeout = 600
 
-# The API roots the toolkit knows by name. Both serve the same `toolkit/...` endpoints.
+# The API roots the toolkit knows by name.
 SERVERS = {
     "v1": "https://disco.bii.a-star.edu.sg/disco_v3_api/",
-    "v2": "https://immunesinglecell.org/disco_v3_api/",
 }
 DEFAULT_SERVER = "v1"
 
+# Removed in 1.3.0: the toolkit was never tested against DISCO v2, which has its own R package.
+_UNSUPPORTED = {
+    "v2": "DISCO v2 is not supported by the Python toolkit, which is built and tested for DISCO v1 "
+          "(the default). For DISCO v2 use its R package: https://github.com/JinmiaoChenLab/DISCOtoolkit",
+}
+
 
 def _normalise(server: str) -> str:
     """Turn a preset name or a URL into an API root that ends with exactly one '/'."""
     if not isinstance(server, str) or not server.strip():
         raise ValueError("server must be a preset name (%s) or a URL" % ", ".join(SERVERS))
     server = server.strip()
+    if server.lower() in _UNSUPPORTED:
+        raise ValueError(_UNSUPPORTED[server.lower()])
     if server.lower() in SERVERS:
         return SERVERS[server.lower()]
     if not server.lower().startswith(("http://", "https://")):
@@ -50,8 +57,8 @@ def set_server(server: str) -> str:
     """Choose which DISCO server the toolkit uses for the rest of the session.
 
     Args:
-        server (str): "v1", "v2", or the full URL of an API root such as
-            "https://disco.bii.a-star.edu.sg/disco_v3_api/".
+        server (str): "v1" (DISCO v1, the default), or the full URL of the API root of a mirror
+            or test copy of DISCO v1, such as "http://127.0.0.1:8889/disco_v3_api/".
 
     Returns:
         str: the API root now in use.

{discotoolkit-1.2.2 → discotoolkit-1.3.0}/discotoolkit/__init__.py

@@ -5,4 +5,4 @@ from .CELLiD import *
 from .GeneSearch import *
 from .GlobalVariable import set_server, get_server
 
-__version__ = "1.2.2"
+__version__ = "1.3.0"

{discotoolkit-1.2.2 → discotoolkit-1.3.0}/discotoolkit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: discotoolkit
-Version: 1.2.2
+Version: 1.3.0
 Summary: DISCOtoolkit is an python package that allows users to access data and use the tools provided by the DISCO database.
 Home-page: https://disco.bii.a-star.edu.sg/
 Author: Li Mengwei, Rom Uddamvathanak
@@ -43,7 +43,7 @@ Dynamic: summary
 -->
 [![Documentation](https://img.shields.io/badge/docs-disco.bii.a--star.edu.sg-blue)](https://disco.bii.a-star.edu.sg/v1/docs/toolkit/guide/) [![Downloads](https://static.pepy.tech/personalized-badge/discotoolkit?period=total&units=international_system&left_color=black&right_color=orange&left_text=Downloads)](https://pepy.tech/project/discotoolkit) [![PyPI version](https://img.shields.io/pypi/v/discotoolkit)](https://pypi.org/project/discotoolkit)
 
-# DISCOtoolkit 1.2.2
+# DISCOtoolkit 1.3.0
 
 DISCOtoolkit is a Python package for accessing the data and tools of the [DISCO database](https://disco.bii.a-star.edu.sg/) (DISCO v1). Read the documentation, with tutorials and the API reference, at [disco.bii.a-star.edu.sg/v1/docs/toolkit/guide](https://disco.bii.a-star.edu.sg/v1/docs/toolkit/guide/).
 
@@ -52,7 +52,7 @@ DISCOtoolkit is a Python package for accessing the data and tools of the [DISCO
 - CELLiD: cell type annotation
 - scEnrichment: gene set enrichment using DISCO DEGs
 
-> **Use DISCO v1.** The toolkit is developed and tested against **DISCO v1**, which is the default, and that is the server we recommend. DISCO v2 has its own R package ([DISCOtoolkit](https://github.com/JinmiaoChenLab/DISCOtoolkit)). The Python package can be pointed at a v2 server, but that is not tested; see [Choosing a server](#choosing-a-server).
+> **For DISCO v1.** The toolkit is built for and tested against **DISCO v1**, which it uses by default. DISCO v2 is not supported; it has its own R package, [DISCOtoolkit](https://github.com/JinmiaoChenLab/DISCOtoolkit).
 
 ## Quickstart (Google Colab)
 
@@ -96,17 +96,17 @@ python -m ipykernel install --user --name disco --display-name "disco"
 python -m pip install -U discotoolkit
 ```
 
-## Choosing a server
+## Server
 
 ```python
 import discotoolkit as dt
 
-dt.get_server()                       # 'https://disco.bii.a-star.edu.sg/disco_v3_api/'  (DISCO v1, the default)
-dt.set_server("v2")                   # DISCO v2 (not tested; DISCO v1 is the supported server)
-dt.set_server("https://my.server/disco_v3_api/")   # any server with the same API
+dt.get_server()                       # 'https://disco.bii.a-star.edu.sg/disco_v3_api/'  (DISCO v1)
+dt.set_server("https://my.mirror/disco_v3_api/")   # a mirror or test copy of DISCO v1
 ```
 
-or set the `DISCO_API_URL` environment variable before importing the package.
+or set the `DISCO_API_URL` environment variable before importing the package. The tests use this
+to run against a local copy of DISCO v1.
 
 ## Testing
 

{discotoolkit-1.2.2 → discotoolkit-1.3.0}/discotoolkit.egg-info/SOURCES.txt

@@ -19,6 +19,7 @@ discotoolkit.egg-info/requires.txt
 discotoolkit.egg-info/top_level.txt
 tests/test_docs.py
 tests/test_gene_search.py
+tests/test_metadata_helpers.py
 tests/test_reference_loading.py
 tests/test_server_contract.py
 tests/test_settings.py

{discotoolkit-1.2.2 → discotoolkit-1.3.0}/setup.py

@@ -6,7 +6,7 @@ with open("requirements.txt", "r") as f:
 
 setup(
     name='discotoolkit',
-    version="1.2.2",
+    version="1.3.0",
     url='https://disco.bii.a-star.edu.sg/',
     author='Li Mengwei, Rom Uddamvathanak',
     author_email='uddamvathanak_rom@immunol.a-star.edu.sg',

discotoolkit-1.3.0/tests/test_metadata_helpers.py

@@ -0,0 +1,49 @@
+"""
+The metadata helpers people use to discover what they can filter on: list_all_columns and
+list_metadata_item. No network: the metadata table is faked.
+
+    python tests/test_metadata_helpers.py
+"""
+import os
+import sys
+from unittest import mock
+
+import pandas as pd
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+from discotoolkit import GetMetadata  # noqa: E402
+
+TABLE = pd.DataFrame({
+    "sample_id": ["S1", "S2", "S3"],
+    "tissue": ["lung", "lung", "blood"],
+    "platform": ["10x3'", "10x5'", "10x3'"],
+})
+
+
+def test_list_all_columns_names_every_metadata_field():
+    with mock.patch.object(GetMetadata, "get_disco_metadata", return_value=TABLE):
+        assert GetMetadata.list_all_columns() == ["sample_id", "tissue", "platform"]
+
+
+def test_list_metadata_item_gives_each_value_once():
+    with mock.patch.object(GetMetadata, "get_disco_metadata", return_value=TABLE):
+        assert sorted(GetMetadata.list_metadata_item("platform")) == ["10x3'", "10x5'"]
+        assert GetMetadata.list_metadata_item("no_such_field") is None
+
+
+def _run_all():
+    tests = [(n, f) for n, f in sorted(globals().items()) if n.startswith("test_") and callable(f)]
+    failed = 0
+    for name, fn in tests:
+        try:
+            fn()
+            print("  PASS  %s" % name)
+        except Exception as error:
+            failed += 1
+            print("  FAIL  %s\n          %s: %s" % (name, type(error).__name__, error))
+    print("\n%d/%d passed" % (len(tests) - failed, len(tests)))
+    return 1 if failed else 0
+
+
+if __name__ == "__main__":
+    sys.exit(_run_all())

{discotoolkit-1.2.2 → discotoolkit-1.3.0}/tests/test_settings.py

@@ -41,15 +41,29 @@ def test_api_url_joins_paths_with_exactly_one_slash():
     assert g.api_url("/toolkit/getSampleMetadata") == g.get_server() + "toolkit/getSampleMetadata"
 
 
-def test_named_presets_and_urls():
+def test_v1_preset_and_urls_of_a_mirror():
     g = load()
-    assert g.set_server("v2") == "https://immunesinglecell.org/disco_v3_api/"
-    assert g.api_url("x") == "https://immunesinglecell.org/disco_v3_api/x"      # takes effect at once
+    assert g.set_server("http://127.0.0.1:8889/disco_v3_api") == "http://127.0.0.1:8889/disco_v3_api/"
+    assert g.api_url("x") == "http://127.0.0.1:8889/disco_v3_api/x"             # takes effect at once
     assert g.set_server("V1") == g.SERVERS["v1"]                                 # preset names are case-insensitive
     assert g.set_server("https://example.org/api") == "https://example.org/api/"  # trailing slash added
     assert g.set_server("http://localhost:8889/disco_v3_api///") == "http://localhost:8889/disco_v3_api/"
 
 
+def test_disco_v2_is_refused_with_a_pointer_to_the_r_package():
+    g = load()
+    before = g.get_server()
+    for name in ("v2", "V2"):
+        try:
+            g.set_server(name)
+        except ValueError as error:
+            assert "R package" in str(error) and "DISCOtoolkit" in str(error), error
+        else:
+            raise AssertionError("set_server(%r) was accepted" % name)
+    assert g.get_server() == before
+    assert list(g.SERVERS) == ["v1"]
+
+
 def test_bad_servers_are_rejected_without_changing_the_current_one():
     g = load()
     before = g.get_server()
@@ -64,14 +78,20 @@ def test_bad_servers_are_rejected_without_changing_the_current_one():
 
 
 def test_environment_variable_sets_the_starting_server():
-    assert load("v2").get_server() == "https://immunesinglecell.org/disco_v3_api/"
     assert load("https://example.org/disco_v3_api").get_server() == "https://example.org/disco_v3_api/"
+    # asking for v2 through the environment fails loudly rather than quietly using v1
+    try:
+        load("v2")
+    except ValueError:
+        pass
+    else:
+        raise AssertionError("DISCO_API_URL=v2 was accepted")
 
 
 def test_old_prefix_variable_still_readable():
     g = load()
-    g.set_server("v2")
-    assert g.prefix_disco_url == "https://immunesinglecell.org/disco_v3_api/"
+    g.set_server("https://example.org/disco_v3_api/")
+    assert g.prefix_disco_url == "https://example.org/disco_v3_api/"
 
 
 def _run_all():