Add IDCClient() singleton feature

README.md

@@ -39,9 +39,9 @@ $ pip install --upgrade idc-index
 Instantiate `IDCClient`, which provides the interface for main operations.
 
 ```python
-from idc_index import index
+from idc_index import IDCClient
 
-client = index.IDCClient()
+client = IDCClient.client()
 ```
 
 You can use [IDC Portal](https://imaging.datacommons.cancer.gov/explore) to

idc_index/index.py

@@ -39,6 +39,24 @@ class IDCClient:
     CITATION_FORMAT_JSON = "application/vnd.citationstyles.csl+json"
     CITATION_FORMAT_BIBTEX = "application/x-bibtex"
 
+    # Singleton pattern
+    # NOTE: In the future, one may want to use multiple clients e.g. for sub-datasets so a attribute-singleton as shown bewlo seems a better option.
+    # _instance: IDCClient
+    # def __new__(cls):
+    #     if not hasattr(cls, "_instance") or getattr(cls, "_instance") is None:
+    #         instance = super(IDCClient, cls).__new__(cls)
+    #         setattr(cls, "_instance", instance)
+    #     return cls._instance
+
+    _client: IDCClient
+
+    @classmethod
+    def client(cls) -> IDCClient:
+        if not hasattr(cls, "_client") or getattr(cls, "_client") is None:
+            setattr(cls, "_client", IDCClient())
+
+        return cls._client
+
     def __init__(self):
         file_path = idc_index_data.IDC_INDEX_PARQUET_FILEPATH
 

tests/idcindex.py

@@ -10,7 +10,7 @@
 import pandas as pd
 import pytest
 from click.testing import CliRunner
-from idc_index import cli, index
+from idc_index import IDCClient, cli
 
 # Run tests using the following command from the root of the repository:
 # python -m unittest -vv tests/idcindex.py
@@ -25,7 +25,7 @@ def _change_test_dir(request, monkeypatch):
 
 class TestIDCClient(unittest.TestCase):
     def setUp(self):
-        self.client = index.IDCClient()
+        self.client = IDCClient()
         self.download_from_manifest = cli.download_from_manifest
         self.download_from_selection = cli.download_from_selection
         self.download = cli.download
@@ -423,6 +423,35 @@ def test_cli_download_from_manifest(self):
             )
             assert len(os.listdir(temp_dir)) != 0
 
+    def test_singleton_attribute(self):
+        # singleton, initialized on first use
+        i1 = IDCClient.client()
+        i2 = IDCClient.client()
+
+        # new instances created via constructor (through init)
+        i3 = IDCClient()
+        i4 = self.client
+
+        # all must be not none
+        assert i1 is not None
+        assert i2 is not None
+        assert i3 is not None
+        assert i4 is not None
+
+        # singletons must return the same instance
+        assert i1 == i2
+
+        # new instances must be different
+        assert i1 != i3
+        assert i1 != i4
+        assert i3 != i4
+
+        # all must be instances of IDCClient
+        assert isinstance(i1, IDCClient)
+        assert isinstance(i2, IDCClient)
+        assert isinstance(i3, IDCClient)
+        assert isinstance(i4, IDCClient)
+
     def test_cli_download(self):
         runner = CliRunner()
         with runner.isolated_filesystem():