From abee39ba87452a3a6c8633e7d74c3b960e3cd6f6 Mon Sep 17 00:00:00 2001 From: "Jeffrey N. Johnson" Date: Mon, 21 Oct 2024 09:51:26 -0700 Subject: [PATCH 1/6] Trying to repair GitHub pages deployment. --- .github/workflows/gh-pages.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml index 05ecd4d..f6f709a 100644 --- a/.github/workflows/gh-pages.yml +++ b/.github/workflows/gh-pages.yml @@ -42,7 +42,7 @@ jobs: - name: Build run: uv run --dev mkdocs build --verbose - - if: ${{ github.event_name == 'push' }} + - if: ${{ github.event_name == 'push' }} || ${{ github.event_name == 'workflow_dispatch' }} name: GitHub Pages action uses: JamesIves/github-pages-deploy-action@v4 with: From 7200d18fae55abc5a34d79180d231db5035e11d8 Mon Sep 17 00:00:00 2001 From: "Jeffrey N. Johnson" Date: Mon, 21 Oct 2024 12:14:15 -0700 Subject: [PATCH 2/6] Updating GH pages deployment settings. --- .github/workflows/gh-pages.yml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml index f6f709a..77cbc23 100644 --- a/.github/workflows/gh-pages.yml +++ b/.github/workflows/gh-pages.yml @@ -44,16 +44,17 @@ jobs: - if: ${{ github.event_name == 'push' }} || ${{ github.event_name == 'workflow_dispatch' }} name: GitHub Pages action - uses: JamesIves/github-pages-deploy-action@v4 + uses: JamesIves/github-pages-deploy-action@v4.6.8 with: # Do not remove existing pr-preview pages clean-exclude: pr-preview folder: ./site/ + force: false # don't force-push, which overwrites previews # If it's a PR from within the same repo, deploy to a preview page # For security reasons, PRs from forks cannot write into gh-pages for now - if: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository }} name: Preview docs - uses: rossjrw/pr-preview-action@v1 + uses: rossjrw/pr-preview-action@v1.4.8 with: source-dir: ./site/ From ec01b725565be4d9aa8ed23fb04c74392db5aadf Mon Sep 17 00:00:00 2001 From: "Jeffrey N. Johnson" Date: Mon, 21 Oct 2024 12:16:06 -0700 Subject: [PATCH 3/6] Updating content to test site push. --- docs/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/index.md b/docs/index.md index 00359b3..3dbb32b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,2 +1,3 @@ # dtspy: a Python client for the [Data Transfer System](https://kbase.github.io/dts/) +Check back soon! From 54447359388223008900fd5814ad2b89b53af5ae Mon Sep 17 00:00:00 2001 From: "Jeffrey N. Johnson" Date: Mon, 21 Oct 2024 15:19:55 -0700 Subject: [PATCH 4/6] A first stab at an Overview. --- docs/index.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 56 insertions(+), 2 deletions(-) diff --git a/docs/index.md b/docs/index.md index 3dbb32b..45030e9 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,3 +1,57 @@ -# dtspy: a Python client for the [Data Transfer System](https://kbase.github.io/dts/) +# dtspy: a Python client for the Data Transfer System (DTS) -Check back soon! +The `dtspy` Python client allows you to use the [DTS](https://kbase.github.io/dts/) +to search for files and transfer them between several organizations supported +by the Department of Energy (DOE) Biological and Environmental Research (BER) +program: + +* [JGI Data Portal (JDP)](https://data.jgi.doe.gov/) +* [DOE National Microbiome Data Collaborative (NMDC)](https://microbiomedata.org/) +* [DOE Biology Knowledgebase(KBase)](https://www.kbase.us) +* More coming soon! + +You can use `dtspy` to create a client that connects to a DTS server, and use +that client to + +* search for data files within databases supported by the above organizations, + obtaining their canonical IDs and metadata identifying their provenance +* request the transfer of one or more of these data files between databases by + using canonical file IDs + +## Installation + +`dtspy` requires Python 3.12 or greater. We recommend installing it in a +[virtual environment](https://docs.python.org/3/library/venv.html) alongside any +tools or workflows you use to analyze the data you're searching for and +transferring. You can install `dtspy` using `pip` (or `pip3`): + +``` +pip install dtspy +``` + +The DTS uses KBase's authentication server, so you also need a +[KBase developer account](https://docs.kbase.us/development/create-a-kbase-developer-account) +with a [credential (token)](https://kbase.github.io/kb_sdk_docs/tutorial/3_initialize.html#set-up-your-developer-credentials). + +To avoid putting your developer token in your Python scripts, you can store it +in an environment variable like `DTS_KBASE_DEV_TOKEN`. We'll use this environment +variable to access your token in the examples below. + +## Quickstart + +Here's an example how you can create a DTS client connected to a server, +search for files within the JGI Data Portal, and print their metadata: + +``` +import dts +import os + +token = os.getenv('DTS_KBASE_DEV_TOKEN') +dts_client = dts.Client(api_key = token, + server = "https://lb-dts.staging.kbase.us") + +results = dts_client.search(database = 'jdp', + query = 'prochlorococcus') +print(results) + +``` From cf39f429ac2afefbabdc6773dbbdc6e977941822 Mon Sep 17 00:00:00 2001 From: "Jeffrey N. Johnson" Date: Tue, 22 Oct 2024 14:35:00 -0700 Subject: [PATCH 5/6] Fleshing things out a bit. --- docs/index.md | 44 +++++++++++++++++++++++++++----------------- 1 file changed, 27 insertions(+), 17 deletions(-) diff --git a/docs/index.md b/docs/index.md index 45030e9..56f7218 100644 --- a/docs/index.md +++ b/docs/index.md @@ -18,40 +18,50 @@ that client to * request the transfer of one or more of these data files between databases by using canonical file IDs +## Prerequisites for Using `dtspy` + +To use the DTS Python client, you need + +* Python 3.12 +* an [ORCID account](https://orcid.org/register) +* a [KBase developer account](https://docs.kbase.us/development/create-a-kbase-developer-account) with a + [developer token](https://kbase.github.io/kb_sdk_docs/tutorial/3_initialize.html#set-up-your-developer-credentials) + +DTS uses KBase's authentication server, so the token associates your DTS client +with your KBase account, allowing you to transfer files to it. + ## Installation -`dtspy` requires Python 3.12 or greater. We recommend installing it in a -[virtual environment](https://docs.python.org/3/library/venv.html) alongside any -tools or workflows you use to analyze the data you're searching for and -transferring. You can install `dtspy` using `pip` (or `pip3`): +We recommend installing `dtspy` in a [virtual environment](https://docs.python.org/3/library/venv.html) +alongside any tools or workflows you use to analyze the data you're working with. +You can install `dtspy` using `pip` (or `pip3`): ``` pip install dtspy ``` -The DTS uses KBase's authentication server, so you also need a -[KBase developer account](https://docs.kbase.us/development/create-a-kbase-developer-account) -with a [credential (token)](https://kbase.github.io/kb_sdk_docs/tutorial/3_initialize.html#set-up-your-developer-credentials). - -To avoid putting your developer token in your Python scripts, you can store it -in an environment variable like `DTS_KBASE_DEV_TOKEN`. We'll use this environment -variable to access your token in the examples below. - ## Quickstart -Here's an example how you can create a DTS client connected to a server, -search for files within the JGI Data Portal, and print their metadata: +Below is an example describing how to create a DTS client connected to a server, +search for files within the JGI Data Portal, and print their metadata. + ``` import dts import os +# to avoid putting your developer token in your Python scripts, store it +# in an environment variable like `DTS_KBASE_DEV_TOKEN` token = os.getenv('DTS_KBASE_DEV_TOKEN') + +# connect to the DTS server dts_client = dts.Client(api_key = token, server = "https://lb-dts.staging.kbase.us") -results = dts_client.search(database = 'jdp', - query = 'prochlorococcus') -print(results) +# search the JGI Data Portal for files related to prochlorococcus, a small +# marine cyanobacteria +files = dts_client.search(database = 'jdp', + query = 'prochlorococcus') +print(files) ``` From 21f77e55875e0ed717be321ab18494985bbb3dea Mon Sep 17 00:00:00 2001 From: "Jeffrey N. Johnson" Date: Wed, 23 Oct 2024 11:39:48 -0700 Subject: [PATCH 6/6] Adding Python markup syntax. --- docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index 56f7218..47957f5 100644 --- a/docs/index.md +++ b/docs/index.md @@ -46,7 +46,7 @@ Below is an example describing how to create a DTS client connected to a server, search for files within the JGI Data Portal, and print their metadata. -``` +```py import dts import os