-
Notifications
You must be signed in to change notification settings - Fork 10
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: browsable API reference on GitHub Pages
- Loading branch information
Showing
16 changed files
with
1,803 additions
and
114 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,38 @@ | ||
name: Building and publishing documentation | ||
|
||
on: | ||
push: | ||
branches: [master] | ||
|
||
jobs: | ||
docs: | ||
runs-on: ubuntu-latest | ||
|
||
steps: | ||
- name: Check out code | ||
uses: actions/checkout@v3 | ||
|
||
- name: Set up Python | ||
uses: actions/setup-python@v4 | ||
with: | ||
python-version: "3.11" | ||
|
||
- name: Install requirements | ||
run: | | ||
pip install -r requirements.txt | ||
pip install -r tests/requirements.txt | ||
- name: Install app | ||
run: pip install . | ||
|
||
- name: Create markdown documents | ||
run: | | ||
lazydocs \ | ||
--output-path="./docs/docstrings" \ | ||
--overview-file="README.md" \ | ||
--src-base-url="https://github.com/ohsu-comp-bio/py-tes/blob/master/" | ||
--validate \ | ||
"./tes" | ||
- name: Build docs | ||
run: mkdocs build |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,4 +1,4 @@ | ||
name: py-test_file | ||
name: Linting and testing | ||
|
||
on: [pull_request] | ||
|
||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
nav: | ||
- Overview: README.md | ||
- ... |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,149 @@ | ||
py-tes | ||
====== | ||
|
||
_py-tes_ is a library for interacting with servers implementing the [GA4GH Task Execution Schema](https://github.com/ga4gh/task-execution-schemas). | ||
|
||
|
||
### Install | ||
|
||
Available on [PyPI](https://pypi.org/project/py-tes/). | ||
|
||
``` | ||
pip install py-tes | ||
``` | ||
|
||
### Example | ||
|
||
```python | ||
import tes | ||
|
||
# define task | ||
task = tes.Task( | ||
executors=[ | ||
tes.Executor( | ||
image="alpine", | ||
command=["echo", "hello"] | ||
) | ||
] | ||
) | ||
|
||
# create client | ||
cli = tes.HTTPClient("https://funnel.example.com", timeout=5) | ||
|
||
# access endpoints | ||
service_info = cli.get_service_info() | ||
task_id = cli.create_task(task) | ||
task_info = cli.get_task(task_id, view="BASIC") | ||
cli.cancel_task(task_id) | ||
tasks_list = cli.list_tasks(view="MINIMAL") # default view | ||
``` | ||
|
||
### How to... | ||
|
||
> Makes use of the objects above... | ||
#### ...export a model to a dictionary | ||
|
||
```python | ||
task_dict = task.as_dict(drop_empty=False) | ||
``` | ||
|
||
`task_dict` contents: | ||
|
||
```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 | ||
|
||
```python | ||
task_json = task.as_json() # also accepts `drop_empty` arg | ||
``` | ||
|
||
`task_json` contents: | ||
|
||
```console | ||
{"executors": [{"image": "alpine", "command": ["echo", "hello"]}]} | ||
``` | ||
|
||
#### ...pretty print a model | ||
|
||
```python | ||
print(task.as_json(indent=3)) # keyword args are passed to `json.dumps()` | ||
``` | ||
|
||
Output: | ||
|
||
```json | ||
{ | ||
"executors": [ | ||
{ | ||
"image": "alpine", | ||
"command": [ | ||
"echo", | ||
"hello" | ||
] | ||
} | ||
] | ||
} | ||
``` | ||
|
||
#### ...access a specific task from the task list | ||
|
||
```python | ||
specific_task = tasks_list.tasks[5] | ||
``` | ||
|
||
`specific_task` contents: | ||
|
||
```console | ||
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 | ||
|
||
```python | ||
for t in tasks_list[:3]: | ||
print(t.as_json(indent=3)) | ||
``` | ||
|
||
Output: | ||
|
||
```console | ||
{ | ||
"id": "task_A2GFS4", | ||
"state": "RUNNING" | ||
} | ||
{ | ||
"id": "task_O8G1PZ", | ||
"state": "CANCELED" | ||
} | ||
{ | ||
"id": "task_W246I6", | ||
"state": "COMPLETE" | ||
} | ||
``` | ||
|
||
#### ...instantiate a model from a JSON representation | ||
|
||
```python | ||
task_from_json = tes.client.unmarshal(task_json, tes.Task) | ||
``` | ||
|
||
`task_from_json` contents: | ||
|
||
```console | ||
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 | ||
print(task_from_json == task) | ||
``` | ||
|
||
Output: | ||
|
||
```console | ||
True | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,4 @@ | ||
title: API Reference | ||
nav: | ||
- Overview: README.md | ||
- ... |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,48 @@ | ||
<!-- markdownlint-disable --> | ||
|
||
# API Overview | ||
|
||
## Modules | ||
|
||
- [`client`](./client.md#module-client): TES access methods and helper functions. | ||
- [`models`](./models.md#module-models): TES models, converters, validators and helpers. | ||
- [`utils`](./utils.md#module-utils): Exceptions and utilities. | ||
|
||
## Classes | ||
|
||
- [`client.HTTPClient`](./client.md#class-httpclient): HTTP client class for interacting with the TES API. | ||
- [`models.Base`](./models.md#class-base): `attrs` base class for all TES and helper models. | ||
- [`models.CancelTaskRequest`](./models.md#class-canceltaskrequest): `attrs` model class for `POST /tasks/{id}:cancel` request parameters. | ||
- [`models.CancelTaskResponse`](./models.md#class-canceltaskresponse): TES `tesCancelTaskResponse` `attrs` model class. | ||
- [`models.CreateTaskResponse`](./models.md#class-createtaskresponse): TES `tesCreateTaskResponse` `attrs` model class. | ||
- [`models.Executor`](./models.md#class-executor): TES `tesExecutor` `attrs` model class. | ||
- [`models.ExecutorLog`](./models.md#class-executorlog): TES `tesExecutorLog` `attrs` model class. | ||
- [`models.GetTaskRequest`](./models.md#class-gettaskrequest): `attrs` model class for `GET /tasks/{id}` request parameters. | ||
- [`models.Input`](./models.md#class-input): TES `tesInput` `attrs` model class. | ||
- [`models.ListTasksRequest`](./models.md#class-listtasksrequest): `attrs` model class for `GET /tasks` request parameters. | ||
- [`models.ListTasksResponse`](./models.md#class-listtasksresponse): TES `tesListTasksResponse` `attrs` model class. | ||
- [`models.Output`](./models.md#class-output): TES `tesOutput` `attrs` model class. | ||
- [`models.OutputFileLog`](./models.md#class-outputfilelog): TES `tesOutputFileLog` `attrs` model class. | ||
- [`models.Resources`](./models.md#class-resources): TES `tesResources` `attrs` model class. | ||
- [`models.ServiceInfo`](./models.md#class-serviceinfo): TES `tesServiceInfo` `attrs` model class. | ||
- [`models.ServiceInfoRequest`](./models.md#class-serviceinforequest): `attrs` model class for `GET /service-info` request parameters. | ||
- [`models.Task`](./models.md#class-task): TES `tesTask` `attrs` model class. | ||
- [`models.TaskLog`](./models.md#class-tasklog): TES `tesTaskLog` `attrs` model class. | ||
- [`utils.TimeoutError`](./utils.md#class-timeouterror) | ||
- [`utils.UnmarshalError`](./utils.md#class-unmarshalerror): Raised when a JSON string cannot be unmarshalled to a TES model. | ||
|
||
## Functions | ||
|
||
- [`client.process_url`](./client.md#function-process_url) | ||
- [`models.datetime_json_handler`](./models.md#function-datetime_json_handler): JSON handler for `datetime` objects. | ||
- [`models.int64conv`](./models.md#function-int64conv): Convert string to `int64`. | ||
- [`models.list_of`](./models.md#function-list_of): `attrs` validator for lists of a given type. | ||
- [`models.strconv`](./models.md#function-strconv): Explicitly cast a string-like value or list thereof to string(s). | ||
- [`models.timestampconv`](./models.md#function-timestampconv): Convert string to `datetime`. | ||
- [`utils.camel_to_snake`](./utils.md#function-camel_to_snake): Converts camelCase to snake_case. | ||
- [`utils.unmarshal`](./utils.md#function-unmarshal): Unmarshal a JSON string to a TES model. | ||
|
||
|
||
--- | ||
|
||
_This file was automatically generated via [lazydocs](https://github.com/ml-tooling/lazydocs)._ |
Oops, something went wrong.