cdapython 2.1.0__tar.gz → 2.2.1__tar.gz

{cdapython-2.1.0 → cdapython-2.2.1}/CHANGELOG.md

@@ -1,3 +1,7 @@
+2026-10-01: 2.2.1: fix help text typo for `column_values()`
+
+2026-08-25: 2.2.0: add support for harmonized controlled-vocabulary metadata retrieval (slims, synonyms, containing terms); see help text for the `add_extras` flag in the `get_data()` and `summarize()` functions
+
 2026-04-07: 2.1.0: add `search_terms` support; obsolesce `disease_slims` POC in deference to upcoming full version
 
 2025-12-09: 2.0.14: add sort postproc to POC `disease_slims` return column

{cdapython-2.1.0 → cdapython-2.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cdapython
-Version: 2.1.0
+Version: 2.2.1
 Summary: NCI CRDC CDA front-end user interface library
 License-File: LICENSE
 Requires-Python: >=3.9,<4.0
@@ -11,10 +11,11 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Requires-Dist: cda-client (>=2.1.0)
 Requires-Dist: pandas (>=2.2.3,<3.0.0)
 Requires-Dist: pyyaml (>=6.0.0)
-Requires-Dist: tabulate (>=0.9.0)
+Requires-Dist: tabulate (>=0.10.0)
 Description-Content-Type: text/markdown
 
 # cdapython

{cdapython-2.1.0 → cdapython-2.2.1}/cdapython/__init__.py

@@ -1,5 +1,4 @@
-from cdapython.application_utilities import get_api_url, set_api_url
-from cdapython.discover import cda_functions, column_values, columns, release_metadata, tables
+from cdapython.discover import cda_extra_metadata_columns, cda_functions, column_values, columns, get_api_url, release_metadata, set_api_url, tables
 from cdapython.summarize import expand_file_results, expand_subject_results, intersect_file_results, intersect_subject_results, summarize_files, summarize_subjects
 from cdapython.get_data import get_file_data, get_subject_data
 

{cdapython-2.1.0 → cdapython-2.2.1}/cdapython/discover.py

@@ -8,7 +8,6 @@ import cda_client.api.columns.columns_endpoint_columns_get
 import cda_client.api.release_metadata.release_metadata_endpoint_release_metadata_get
 import cda_client.api.column_values.column_values_endpoint_column_values_column_post
 
-from cdapython.application_utilities import get_api_url
 from cda_client.errors import UnexpectedStatus
 from cdapython.logging_wrappers import get_logger
 
@@ -22,6 +21,47 @@ from cdapython.logging_wrappers import get_logger
 #############################################################################################################################
 
 
+#############################################################################################################################
+#
+# get_api_url(): Return the current system URL for the CDA REST API.
+#
+#############################################################################################################################
+
+def get_api_url():
+    """
+    Return the currently-set URL pointing to the CDA REST API.
+    """
+
+    # System default.
+    default_api_url = 'https://cda.datacommons.cancer.gov'
+
+    # Has the user set a non-default URL?
+    local_api_url = os.environ.get( '__CDA_API_URL' )
+
+    if local_api_url is not None and len( local_api_url ) > 0:
+        return local_api_url
+    else:
+        return default_api_url
+
+#############################################################################################################################
+#
+# set_api_url(): Set the current system URL for the CDA REST API.
+#
+#############################################################################################################################
+
+def set_api_url( new_api_url ):
+    """
+    Set the current system URL for the CDA REST API.
+    """
+
+    # Do some basic sanity checking.
+    if re.search( r'^https*:\/\/', new_api_url ) is None:
+        raise RuntimeError( 'set_api_url(): Only HTTP and HTTPS URLs are allowed.' )
+    elif len( new_api_url ) > 100:
+        raise RuntimeError( 'set_api_url(): Whatever that was, it wasn\'t the URL of the CDA REST API.' )
+
+    os.environ['__CDA_API_URL'] = new_api_url
+
 #############################################################################################################################
 #
 # cda_functions(): Return a list of user-facing cdapython functions useful for both scripting and interactive data sessions.
@@ -62,6 +102,7 @@ def cda_functions():
             'disable_file_logging',
             'get_api_url',
             'set_api_url',
+            'cda_extra_metadata_columns',
             'cda_functions'
     ]
 
@@ -71,6 +112,24 @@ def cda_functions():
 #
 #############################################################################################################################
 
+#############################################################################################################################
+#
+# cda_extra_metadata_columns(): Return a list of available metadata annotations that provide context for some harmonized CDA
+#   fields.
+#
+#############################################################################################################################
+
+def cda_extra_metadata_columns():
+    # extra_metadata_columns is enumerated by cda_extra_metadata_columns() in desired column-display order for return_data_as='':
+    extra_metadata_columns = [ 'synonym_terms', 'slim_terms', 'containing_terms' ]
+    return extra_metadata_columns
+
+#############################################################################################################################
+#
+# END cda_extra_metadata_columns()
+#
+#############################################################################################################################
+
 #############################################################################################################################
 #
 # tables(): Return a list of all searchable CDA data tables.
@@ -789,7 +848,7 @@ def column_values(
 
         data_source ( string; optional ):
             Restrict returned values to the given upstream data source. Current
-            valid values are 'GC', 'GDC', 'PDC', 'IDC' and 'ICDC'.
+            valid values are 'CTDC', 'GC', 'GDC', 'PDC', 'IDC' and 'ICDC'.
             Defaults to None (no filter).
 
         force( boolean; optional ):
@@ -876,6 +935,7 @@ def column_values(
             include_external_refs=None,
             return_data_as=return_data_as,
             output_file=output_file,
+            add_extras=None,
             sort_by=sort_by,
             log=log
         )
@@ -937,7 +997,7 @@ def column_values(
 
     # Warn the user if an override hasn't been requested.
     if not force and column in expensive_columns:
-        log.warning( f"'{column}' has a very large number of values; retrieval is blocked by default. To perform this query, use column_values( ..., 'force=True' )." )
+        log.warning( f"'{column}' has a very large number of values; retrieval is blocked by default. To perform this query, use column_values( ..., force=True )." )
         return
 
     #############################################################################################################################