discotoolkit 1.2.1__tar.gz → 1.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: discotoolkit
-Version: 1.2.1
+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.1
+# 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
 
-> **DISCO v1 and v2.** The toolkit talks to **DISCO v1** by default. DISCO v2 has its own R package ([DISCOtoolkit](https://github.com/JinmiaoChenLab/DISCOtoolkit)); the Python package can still be pointed at a v2 server, 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
-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
 
@@ -117,7 +117,7 @@ python tests/test_settings.py           # offline: server selection logic
 python tests/test_version.py            # offline: setup.py and __init__.py agree on the version
 python tests/test_docs.py               # offline: notebooks are clean, every public function is in the API reference
 python tests/test_server_contract.py    # online: does the server answer everything the toolkit needs?
-python tests/test_server_contract.py https://immunesinglecell.org/disco_v3_api/   # check another server
+python tests/test_server_contract.py <api root>   # check another server
 ```
 
 GitHub Actions runs these, and installs the package on Python 3.9-3.12, on every push. Maintainers: see [RELEASING.md](RELEASING.md) for how a release, and its documentation, is published.

{discotoolkit-1.2.1 → 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.1
+# 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
 
-> **DISCO v1 and v2.** The toolkit talks to **DISCO v1** by default. DISCO v2 has its own R package ([DISCOtoolkit](https://github.com/JinmiaoChenLab/DISCOtoolkit)); the Python package can still be pointed at a v2 server, 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
-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
 
@@ -82,7 +82,7 @@ python tests/test_settings.py           # offline: server selection logic
 python tests/test_version.py            # offline: setup.py and __init__.py agree on the version
 python tests/test_docs.py               # offline: notebooks are clean, every public function is in the API reference
 python tests/test_server_contract.py    # online: does the server answer everything the toolkit needs?
-python tests/test_server_contract.py https://immunesinglecell.org/disco_v3_api/   # check another server
+python tests/test_server_contract.py <api root>   # check another server
 ```
 
 GitHub Actions runs these, and installs the package on Python 3.9-3.12, on every push. Maintainers: see [RELEASING.md](RELEASING.md) for how a release, and its documentation, is published.

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

@@ -2,12 +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). To use
-another server:
+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.
 """
@@ -20,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://")):
@@ -49,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.1 → 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.1"
+__version__ = "1.3.0"

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: discotoolkit
-Version: 1.2.1
+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.1
+# 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
 
-> **DISCO v1 and v2.** The toolkit talks to **DISCO v1** by default. DISCO v2 has its own R package ([DISCOtoolkit](https://github.com/JinmiaoChenLab/DISCOtoolkit)); the Python package can still be pointed at a v2 server, 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
-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
 
@@ -117,7 +117,7 @@ python tests/test_settings.py           # offline: server selection logic
 python tests/test_version.py            # offline: setup.py and __init__.py agree on the version
 python tests/test_docs.py               # offline: notebooks are clean, every public function is in the API reference
 python tests/test_server_contract.py    # online: does the server answer everything the toolkit needs?
-python tests/test_server_contract.py https://immunesinglecell.org/disco_v3_api/   # check another server
+python tests/test_server_contract.py <api root>   # check another server
 ```
 
 GitHub Actions runs these, and installs the package on Python 3.9-3.12, on every push. Maintainers: see [RELEASING.md](RELEASING.md) for how a release, and its documentation, is published.

{discotoolkit-1.2.1 → 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.1 → discotoolkit-1.3.0}/setup.py

@@ -6,7 +6,7 @@ with open("requirements.txt", "r") as f:
 
 setup(
     name='discotoolkit',
-    version="1.2.1",
+    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.2.1 → discotoolkit-1.3.0}/tests/test_docs.py

@@ -72,6 +72,28 @@ def test_api_reference_names_only_things_that_exist():
         assert re.search(r"^(def|class)\s+%s\b" % name, source, re.M), "%s.%s is gone" % (module, name)
 
 
+def test_tutorials_link_to_pages_not_to_notebook_files_and_not_to_the_v2_site():
+    problems = []
+    for path in sorted(glob.glob(os.path.join(ROOT, "docs", "*.ipynb"))):
+        text = "\n".join("".join(c["source"]) for c in json.load(open(path, encoding="utf-8"))["cells"])
+        name = os.path.basename(path)
+        # a relative link to another .ipynb works on GitHub but is a dead link on the site
+        for target in re.findall(r"\]\(([^)\s]+)\)", text):
+            if target.endswith(".ipynb") and not target.startswith("http"):
+                problems.append("%s links to the file %s; link to the page on the docs site" % (name, target))
+        if "immunesinglecell.org" in text:
+            problems.append("%s sends readers to the DISCO V2 site; V1 is the supported server" % name)
+    assert not problems, "; ".join(problems)
+
+
+def test_the_changelog_has_notes_for_the_current_version():
+    # the release workflow builds the GitHub Release text from it, and refuses a version without notes
+    version = re.search(r'__version__\s*=\s*"([^"]+)"', read("discotoolkit/__init__.py")).group(1)
+    assert re.search(r"^## %s\b" % re.escape(version), read("CHANGELOG.md"), re.M), (
+        "add a '## %s' section to CHANGELOG.md before releasing" % version
+    )
+
+
 def _run_all():
     tests = [(n, f) for n, f in sorted(globals().items()) if n.startswith("test_") and callable(f)]
     failed = 0

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.1 → discotoolkit-1.3.0}/tests/test_server_contract.py

@@ -5,7 +5,7 @@ Needs only `requests`, so it runs anywhere -- including a fresh Colab notebook:
 
     !pip install requests
     !python tests/test_server_contract.py                                # DISCO v1 (default)
-    !python tests/test_server_contract.py https://immunesinglecell.org/disco_v3_api/   # another server
+    !python tests/test_server_contract.py <api root>                                   # another server
 
 or with pytest:  DISCO_API_URL=<api root> pytest tests/test_server_contract.py
 

{discotoolkit-1.2.1 → 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():