Lineage API support (#76)

* Add lineage API
* Format sample code
* Update setup.py to be compatible with newer versions of Python
* Add additional args to lineage API
* setup.cfg: change description-file to description_file, remove test alias and coverage configuration

Author: labkey-alan

CHANGE.txt

@@ -2,6 +2,13 @@
 LabKey Python Client API News
 +++++++++++
 
+What's New in the LabKey 3.2.0 package
+==============================
+
+*Release date: 09/10/2024*
+- Add lineage API to experiment module
+    - Accessible via API wrappers e.g. api.experiment.lineage()
+
 What's New in the LabKey 3.1.0 package
 ==============================
 

README.md

@@ -93,7 +93,8 @@ from labkey.api_wrapper import APIWrapper
 
 print("Create an APIWrapper")
 labkey_server = 'localhost:8080'
-container_path = 'Tutorials/HIV Study'  # in this example, Tutorials is a project name and HIV study is a subfolder under it.
+# in this example, Tutorials is a project name and HIV study is a subfolder under it.
+container_path = 'Tutorials/HIV Study'
 contextPath = 'labkey'
 schema = 'core'
 table = 'Users'
@@ -119,22 +120,23 @@ LabKey Server v15.1 and later.
 This package is maintained by [LabKey](http://www.labkey.com/). If you have any questions or need support, please use
 the [LabKey Server developer support forum](https://www.labkey.org/home/developer/forum/project-start.view).
 
+To install the necessary dependencies for local development you can run the following command:
+
+```bash
+pip install -e .
+```
+
 When contributing changes please use `Black` to format your code. To run Black follow these instructions:
 1. Install black: `pip install black`
 2. Run black: `black .`
 3. Commit the newly formatted code.
 
 ### Testing
-If you are looking to contribute please run the tests before issuing a PR. The tests can be initiated by running
-
-```bash
-$ python setup.py test
-```
-
-This runs the tests using [pytest](https://docs.pytest.org/en/latest/contents.html). If you'd like to run pytest directly you can install the testing dependencies in your virtual environment with:
+If you are looking to contribute please run the tests before issuing a PR. To run the tests you'll need to install the
+additional testing dependencies, to do this run:
 
 ```bash
-$ pip install -e .[test]
+$ pip install -e '.[test]'
 ```
 
 Then, the tests can be run with
@@ -150,4 +152,5 @@ $ pytest . -m "integration"
 ```
 
 ### Maintainers
-Package maintainer's can reference the [Python Package Maintenance](https://docs.google.com/document/d/13nVxwyctH4YZ6gDhcrOu9Iz6qGFPAxicE1VHiVYpw9A/) document (requires permission) for updating releases.
+Package maintainer's can reference the [Python Package Maintenance](https://docs.google.com/document/d/13nVxwyctH4YZ6gDhcrOu9Iz6qGFPAxicE1VHiVYpw9A/) document (requires permission) for updating
+releases.

labkey/__init__.py

@@ -14,6 +14,6 @@
 # limitations under the License.
 #
 __title__ = "labkey"
-__version__ = "3.1.0"
+__version__ = "3.2.0"
 __author__ = "LabKey"
 __license__ = "Apache License 2.0"

labkey/experiment.py

@@ -218,6 +218,70 @@ def save_batches(
     return None
 
 
+def lineage(
+    server_context: ServerContext,
+    lsids: List[str],
+    children: bool = None,
+    container_path: str = None,
+    cpas_type: str = None,
+    depth: int = None,
+    exp_type: str = None,
+    include_inputs_and_outputs: bool = None,
+    include_properties: bool = None,
+    include_run_steps: bool = None,
+    parents: bool = None,
+    run_protocol_lsid: str = None,
+):
+    """
+    :param server_context: A LabKey server context. See utils.create_server_context.
+    :param lsids: Array of LSIDs for the seed ExpData, ExpMaterials, or ExpRun
+    :param children: Include children in the lineage response. Defaults to true.
+    :param container_path: labkey container path if not already set in context
+    :param cpas_type: Optional LSID of a SampleSet or DataClass to filter the response. Defaults to include all.
+    :param depth: An optional depth argument. Defaults to include all.
+    :param exp_type: Optional experiment type to filter response -- either "Data", "Material", or "ExperimentRun".
+    Defaults to include all.
+    :param include_inputs_and_outputs: Include inputs and outputs in the lineage response.
+    :param include_properties: Include properties in the lineage response.
+    :param include_run_steps: Include run steps in the lineage response.
+    :param parents: Include parents in the lineage response. Defaults to true.
+    :param run_protocol_lsid: Optional Exp Run Protocol Lsid to filter response. Defaults to include all.
+    """
+    lineage_url = server_context.build_url(
+        "experiment", "lineage.api", container_path=container_path
+    )
+    payload = {"lsids": lsids}
+
+    if children is not None:
+        payload["children"] = children
+
+    if cpas_type is not None:
+        payload["cpasType"] = cpas_type
+
+    if depth is not None:
+        payload["depth"] = depth
+
+    if exp_type is not None:
+        payload["expType"] = exp_type
+
+    if include_inputs_and_outputs is not None:
+        payload["includeInputsAndOutputs"] = include_inputs_and_outputs
+
+    if include_properties is not None:
+        payload["includeProperties"] = include_properties
+
+    if include_run_steps is not None:
+        payload["includeRunSteps"] = include_run_steps
+
+    if parents is not None:
+        payload["parents"] = parents
+
+    if run_protocol_lsid is not None:
+        payload["runProtocolLsid"] = run_protocol_lsid
+
+    return server_context.make_request(lineage_url, payload=payload, method="POST")
+
+
 class ExperimentWrapper:
     """
     Wrapper for all of the API methods exposed in the experiment module. Used by the APIWrapper class.
@@ -237,3 +301,33 @@ def save_batch(self, assay_id: int, batch: Batch) -> Optional[Batch]:
     @functools.wraps(save_batches)
     def save_batches(self, assay_id: int, batches: List[Batch]) -> Optional[List[Batch]]:
         return save_batches(self.server_context, assay_id, batches)
+
+    @functools.wraps(lineage)
+    def lineage(
+        self,
+        lsids: List[str],
+        children: bool = None,
+        container_path: str = None,
+        cpas_type: str = None,
+        exp_type: str = None,
+        depth: int = None,
+        include_properties: bool = None,
+        include_inputs_and_outputs: bool = None,
+        include_run_steps: bool = None,
+        parents: bool = None,
+        run_protocol_lsid: str = None,
+    ):
+        return lineage(
+            self.server_context,
+            lsids,
+            children,
+            container_path,
+            cpas_type,
+            depth,
+            exp_type,
+            parents,
+            include_inputs_and_outputs,
+            include_properties,
+            include_run_steps,
+            run_protocol_lsid,
+        )

samples/domain_example.py

@@ -18,7 +18,7 @@
 from labkey.query import QueryFilter
 
 labkey_server = "localhost:8080"
-container_path = 'Tutorials/HIV Study' # Full project/folder container path
+container_path = "Tutorials/HIV Study"  # Full project/folder container path
 context_path = "labkey"
 api = APIWrapper(labkey_server, container_path, context_path, use_ssl=False)
 

samples/experiment_example.py

@@ -17,7 +17,7 @@
 from labkey.experiment import Batch, Run
 
 labkey_server = "localhost:8080"
-container_path = 'Tutorials/HIV Study' # Full project/folder container path
+container_path = "Tutorials/HIV Study"  # Full project/folder container path
 context_path = "labkey"
 api = APIWrapper(labkey_server, container_path, context_path, use_ssl=False)
 

samples/experiment_platemetadata_example.py

@@ -17,7 +17,7 @@
 from labkey.experiment import Batch, Run
 
 labkey_server = "localhost:8080"
-container_path = 'Tutorials/assay' # Full project/folder container path
+container_path = "Tutorials/assay"  # Full project/folder container path
 context_path = "labkey"
 api = APIWrapper(labkey_server, container_path, context_path, use_ssl=False)
 assay_id = 310  # provide one from your server

samples/query_examples.py

@@ -30,7 +30,7 @@
 
 print("Create a server context")
 labkey_server = "localhost:8080"
-container_path = 'Tutorials/HIV Study' # Full project/folder container path
+container_path = "Tutorials/HIV Study"  # Full project/folder container path
 context_path = "labkey"
 api = APIWrapper(labkey_server, container_path, context_path, use_ssl=False)
 

samples/security_example.py

@@ -17,7 +17,7 @@
 from labkey.exceptions import ServerNotFoundError
 
 labkey_server = "localhost:8080"
-container_path = 'Tutorials/HIV Study' # Full project/folder container path
+container_path = "Tutorials/HIV Study"  # Full project/folder container path
 contextPath = "labkey"
 api = APIWrapper(labkey_server, container_path, contextPath, use_ssl=False)
 

setup.cfg

@@ -1,9 +1,2 @@
 [metadata]
-description-file = README.md
-
-[aliases]
-test=pytest
-
-[coverage:html]
-directory = build/coverage_html
-title = Test coverage report for labkey
+description_file = README.md