cdapython 2.0.14__tar.gz → 2.2.0__tar.gz

cdapython-2.2.0/CHANGELOG.md

@@ -0,0 +1,27 @@
+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
+
+2025-12-09: 2.0.13: add POC `include_disease_slims` Boolean flag to `get_data()`
+
+2025-10-31: 2.0.12: standardize debug-layer SQL echo; adjust `column_values()` to handle known pathologies
+
+2025-10-27: 2.0.11: _cough_ bugfix for previous
+
+2025-10-27: 2.0.10: integrate `column_values()` parameter validation with shared validation library; expand support for `column_values( data_source )` to accept list values in addition to single strings
+
+2025-10-22: 2.0.9: parametrize `data_source` check in `column_values()`
+
+2025-10-20: 2.0.8: rename CDS to GC throughout
+
+2025-10-08: 2.0.7: fix malformed column metadata selector inside `collate=True` provenance management in `get_data()`
+
+2025-09-17: 2.0.6: update ternary numeric comparison handling for latest API ternary operator syntax support
+
+2025-08-18: 2.0.2: update PyYAML build dependency
+
+2025-08-18: 2.0.1: update default API URL
+
+2025-08-18: 2.0.0: initial public release to PyPI

{cdapython-2.0.14 → cdapython-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cdapython
-Version: 2.0.14
+Version: 2.2.0
 Summary: NCI CRDC CDA front-end user interface library
 License-File: LICENSE
 Requires-Python: >=3.9,<4.0
@@ -11,10 +11,10 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
-Requires-Dist: cda-client (>=2.0.0)
-Requires-Dist: pandas (>=2.2.3)
+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.0.14 → cdapython-2.2.0}/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.0.14 → cdapython-2.2.0}/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.
@@ -866,6 +925,7 @@ def column_values(
             cached_column_metadata=cached_column_metadata,
             valid_data_sources=valid_data_sources,
             table=None,
+            search_list=list(),
             column=column,
             match_from_file=None,
             data_source=data_source,
@@ -875,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
         )
@@ -888,7 +949,7 @@ def column_values(
     # Set default sort_by value.
     if sort_by == '':
         if return_data_as in [ '', 'dataframe', 'tsv' ]:
-            sort_by = 'count'
+            sort_by = 'count:desc'
         elif return_data_as in [ 'list' ]:
             sort_by = 'value'
         else: