develop → master: 1.1.0 Release update 🐍 ✨ (#71)

* Add required files for docs site: https://py-tes.readthedocs.io * Update test suite to remove unittest dependency in favor of pytest (`feature/pytest`) (#70) * Update ReadTheDocs Page * Update tests to use pytest "style/format" tests * Add missing `pytest` import * Update models and test files * Fix linting error in test_client.py * Fix lint error in docs/conf.py * Update version to 1.1.0 in tes/__init__.py * Add `setuptools` to `.readthedocs.yaml` to find the `tes` package * Add initial example Colab notebooks to README * Update README.md * Add release links to README.md
ohsu-comp-bio · Dec 6, 2024 · 6a03539 · 6a03539
1 parent 42edcce
commit 6a03539
Show file tree

Hide file tree

Showing 29 changed files with 2,113 additions and 826 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -33,4 +33,5 @@ jobs:
               tes
 
       - name: Build docs
-        run: mkdocs build
+        run: mkdocs build && mkdocs gh-deploy --force
+
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
@@ -9,7 +9,19 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        version: ["3.7", "3.8", "3.9", "3.10", "3.11", "3.12"]
+        # TODO: Handle multiple TES versions here, currently we're only testing against TES 1.1
+        # - py-tes v1.0 — TES 1.0
+        # - py-tes v1.1 — TES 1.1
+        # tes-version:
+        #   - "1.0"
+        #   - "1.1"
+        python-version:
+          - "3.7"
+          - "3.8"
+          - "3.9"
+          - "3.10"
+          - "3.11"
+          - "3.12"
 
     steps:
       - name: Check out code
@@ -18,7 +30,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v4
         with:
-          python-version: ${{ matrix.version }}
+          python-version: ${{ matrix.python-version }}
 
       - name: Install requirements
         run: |
@@ -42,6 +54,6 @@ jobs:
 
       - name: Run integration tests
         run: |
-          /bin/bash -c "$(curl -fsSL https://github.com/ohsu-comp-bio/funnel/releases/download/0.11.0-rc.5/install.sh)" -- 0.11.0-rc.5
+          /bin/bash -c "$(curl -fsSL https://github.com/ohsu-comp-bio/funnel/releases/latest/download/install.sh)"
           funnel server --LocalStorage.AllowedDirs $HOME run &
           pytest tests/integration
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -0,0 +1,34 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+    # You can also specify other tool versions:
+    # nodejs: "19"
+    # rust: "1.64"
+    # golang: "1.19"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+formats:
+  - pdf
+  - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+   install:
+     - method: setuptools
+       path: .
+     - requirements: docs/requirements.txt
diff --git a/README.md b/README.md
@@ -1,24 +1,58 @@
 # py-tes 🐍
 
-[![GitHub Actions Test Status](https://img.shields.io/github/actions/workflow/status/ohsu-comp-bio/py-tes/tests.yml?logo=github)](https://github.com/ohsu-comp-bio/py-tes/actions) [![image](https://coveralls.io/repos/github/ohsu-comp-bio/py-tes/badge.svg?branch=master)](https://coveralls.io/github/ohsu-comp-bio/py-tes?branch=master) [![image](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Build Status][build-badge]][build]
 
-*py-tes* is a library for interacting with servers implementing the
-[GA4GH Task Execution
-Schema](https://github.com/ga4gh/task-execution-schemas).
+[![Test Coverage][coverage-badge]][coverage]
 
-## Install ⚡
+[![License][license-badge]][license]
 
-Available on [PyPI](https://pypi.org/project/py-tes/).
+[![PyPI][pypi-badge]][pypi]
 
-    pip install py-tes
+[build-badge]: https://img.shields.io/github/actions/workflow/status/ohsu-comp-bio/py-tes/tests.yml?logo=github
+[build]: https://github.com/ohsu-comp-bio/py-tes/actions
+[coverage-badge]: https://coveralls.io/repos/github/ohsu-comp-bio/py-tes/badge.svg?branch=master
+[coverage]: https://coveralls.io/github/ohsu-comp-bio/py-tes?branch=master
+[license-badge]: https://img.shields.io/badge/License-MIT-yellow.svg
+[license]: https://opensource.org/licenses/MIT
+[pypi-badge]: https://img.shields.io/pypi/v/py-tes
+[pypi]: https://pypi.org/project/py-tes/
 
-## Example ✍️
+_py-tes_ is a library for interacting with servers implementing the [GA4GH Task Execution Schema](https://github.com/ga4gh/task-execution-schemas).
 
+# Quick Start ⚡
 
-``` python
+| TES version     | py-tes version         | Example Notebook (_Coming soon!_)             |
+|-----------------|------------------------|-----------------------------------------------|
+| [1.1][tes-v1.1] | [1.1.0][py-tes-v1.1.0] | [![Open in Colab][colab-badge]][colab-v1.1.0] |
+| [1.0][tes-v1.1] | [1.0.0][py-tes-v1.0.0] | [![Open in Colab][colab-badge]][colab-v1.0.0] |
+
+[tes-v1.1]: https://github.com/ga4gh/task-execution-schemas/releases/tag/v1.1
+[tes-v1.0]: https://github.com/ga4gh/task-execution-schemas/releases/tag/v1.1
+
+[py-tes-v1.1.0]: https://github.com/ohsu-comp-bio/py-tes/releases/tag/1.1.0
+[py-tes-v1.0.0]: https://github.com/ohsu-comp-bio/py-tes/releases/tag/1.0.0
+
+[colab-badge]: https://colab.research.google.com/assets/colab-badge.svg
+[colab-v1.1.0]: https://colab.research.google.com/github/ohsu-comp-bio/py-tes/blob/develop/examples/v1_1_0.ipynb
+[colab-v1.0.0]: https://colab.research.google.com/github/ohsu-comp-bio/py-tes/blob/develop/examples/v1_0_0.ipynb
+
+# Installation 🌀
+
+Install `py-tes` from [PyPI](https://pypi.org/project/py-tes/) and run it in your script:
+
+```sh
+➜ pip install py-tes
+
+➜ python example.py
+```
+
+## example.py 🐍
+
+```py
 import tes
+import json
 
-# define task
+# Define task
 task = tes.Task(
     executors=[
         tes.Executor(
@@ -28,89 +62,90 @@ task = tes.Task(
     ]
 )
 
-# create client
-cli = tes.HTTPClient("https://tes.example.com", timeout=5)
+# Create client
+cli = tes.HTTPClient("http://localhost:8000", timeout=5)
 
-# access endpoints
-service_info = cli.get_service_info()
+# Create and run task
 task_id = cli.create_task(task)
+cli.wait(task_id, timeout=5)
+
+# Fetch task info
 task_info = cli.get_task(task_id, view="BASIC")
-cli.cancel_task(task_id)
-tasks_list = cli.list_tasks(view="MINIMAL")  # default view
+j = json.loads(task_info.as_json())
+
+# Pretty print task info
+print(json.dumps(j, indent=2))
 ```
 
-## How to...
+# How to...
 
 > Makes use of the objects above...
 
-### ...export a model to a dictionary
+## ...export a model to a dictionary
 
-``` python
+```python
 task_dict = task.as_dict(drop_empty=False)
 ```
 
 `task_dict` contents:
 
-``` console
+```console
 {'id': None, 'state': None, 'name': None, 'description': None, 'inputs': None, 'outputs': None, 'resources': None, 'executors': [{'image': 'alpine', 'command': ['echo', 'hello'], 'workdir': None, 'stdin': None, 'stdout': None, 'stderr': None, 'env': None}], 'volumes': None, 'tags': None, 'logs': None, 'creation_time': None}
 ```
 
-### ...export a model to JSON
+## ...export a model to JSON
 
-``` python
+```python
 task_json = task.as_json()  # also accepts `drop_empty` arg
 ```
 
 `task_json` contents:
 
-``` console
+```console
 {"executors": [{"image": "alpine", "command": ["echo", "hello"]}]}
 ```
 
-### ...pretty print a model
+## ...pretty print a model
 
-``` python
+```python
 print(task.as_json(indent=3))  # keyword args are passed to `json.dumps()`
 ```
 
 Output:
 
-``` json
+```json
 {
-   "executors": [
-      {
-         "image": "alpine",
-         "command": [
-            "echo",
-            "hello"
-         ]
-      }
-   ]
+  "executors": [
+    {
+      "image": "alpine",
+      "command": ["echo", "hello"]
+    }
+  ]
 }
 ```
 
-### ...access a specific task from the task list
+## ...access a specific task from the task list
 
-``` python
+```py
 specific_task = tasks_list.tasks[5]
 ```
 
 `specific_task` contents:
 
-``` console
+```sh
 Task(id='393K43', state='COMPLETE', name=None, description=None, inputs=None, outputs=None, resources=None, executors=None, volumes=None, tags=None, logs=None, creation_time=None)
 ```
 
-### ...iterate over task list items
+## ...iterate over task list items
 
-``` python
+```py
 for t in tasks_list[:3]:
     print(t.as_json(indent=3))
 ```
 
 Output:
 
-``` console
+```sh
 {
    "id": "task_A2GFS4",
    "state": "RUNNING"
@@ -125,31 +160,31 @@ Output:
 }
 ```
 
-### ...instantiate a model from a JSON representation
+## ...instantiate a model from a JSON representation
 
-``` python
+```py
 task_from_json = tes.client.unmarshal(task_json, tes.Task)
 ```
 
 `task_from_json` contents:
 
-``` console
+```sh
 Task(id=None, state=None, name=None, description=None, inputs=None, outputs=None, resources=None, executors=[Executor(image='alpine', command=['echo', 'hello'], workdir=None, stdin=None, stdout=None, stderr=None, env=None)], volumes=None, tags=None, logs=None, creation_time=None)
 ```
 
 Which is equivalent to `task`:
 
-``` python
+```py
 print(task_from_json == task)
 ```
 
 Output:
 
-``` console
+```sh
 True
 ```
 
-## Additional Resources 📚
+# Additional Resources 📚
 
 - [ga4gh-tes](https://github.com/microsoft/ga4gh-tes) : C# implementation of the GA4GH TES API; provides distributed batch task execution on Microsoft Azure
 
@@ -161,8 +196,8 @@ True
 
 - [Nextflow](https://www.nextflow.io/): Nextflow enables scalable and reproducible scientific workflows using software containers. It allows the adaptation of pipelines written in the most common scripting languages.
 
-- [GA4GH TES](https://www.ga4gh.org/product/task-execution-service-tes/): Main page for the Task Execution Schema — a standardized schema and API for describing batch execution tasks. 
+- [GA4GH TES](https://www.ga4gh.org/product/task-execution-service-tes/): Main page for the Task Execution Schema — a standardized schema and API for describing batch execution tasks.
 
-- [TES GitHub](https://github.com/ga4gh/task-execution-schemas): Source repo for the Task Execution Schema 
+- [TES GitHub](https://github.com/ga4gh/task-execution-schemas): Source repo for the Task Execution Schema
 
-- [Awesome TES](https://github.com/ohsu-comp-bio/awesome-tes): A curated list of awesome GA4GH TES projects and programs 
+- [Awesome TES](https://github.com/ohsu-comp-bio/awesome-tes): A curated list of awesome GA4GH TES projects and programs