seqslab-cli 3.2.1.post0

Atgenomix SeqsLab Command Line Tool

Contributors Stargazers Issues License

Atgenomix SeqsLab V3 CLI

Command-line interface of Atgenomix SeqsLab, a cloud-native biomedical informatics (BioMed IT) platform
Explore the docs »

Report issue · Request feature

Table of Contents

1. Overview
   • Underlying Technology
2. Getting Started
   • Prerequisites
   • Interactive Mode
   • CLI Mode
3. Development
   • Authentication with the SeqsLab API
4. Roadmap
5. Contributing
6. License
7. Contact
8. Acknowledgements

Overview

Working alongside the web-based SeqsLab Console, the CLI enables bioinformaticians to easily build custom scripts and automate workflows on SeqsLab.

Common use cases for the CLI include the following:

• Automate processing of sequencing data, including uploading and downloading of datasets to/from the SeqsLab Data Hub
• Submit workflow run requests on demand via SeqsLab Workflow Execution Service (WES) APIs, and integrate with local downstream analysis tools
• View records of platform activities for auditing purposes

Underlying Technology

The SeqsLab CLI is built using the following:

• SeqsLab APIs
• Python-Nubia
• MSAL Python
• Azure SDK
• aiohttp

Note: The mechanisms for secure information storage are built around a keyring service.

Getting Started

Prerequisites

• Python 3.8 or later

• A Python virtual environment

  Install the SeqsLab CLI.

  pip3 install seqslab-cli
  

• A keyring backend

  The SeqsLab CLI supports the following keyring backends:

  • macOS Keychain
  • Freedesktop Secret Service (requires secretstorage)
  • KDE4 & KDE5 KWallet (requires dbus)
  • Windows Credential Locker

  Note: See the Python keyring library documentation for more information about using keyring on a headless Linux system in a Docker container.

• (macOS devices) The following packages:

  • pkg-config
  • dbus
  • glib

  You can install the required packages using Homebrew.

  # install packages:
  brew install dbus
  brew install pkg-config 
  brew install glib
  

Interactive Mode

This mode provides fish-style auto-completion functionality that is user-friendly, especially for beginners.

• Run interactive mode.

  virtualenv .venv
  source .venv/bin/activate
  export PYTHONPATH=$(pwd)
  python3 seqslab/cli.py
  

• Display the available commands.

  seqslab> help
  

CLI Mode

In this mode, the SeqsLab CLI works exactly like any traditional Linux-based command-line utility.

Development

Commands are defined as normal Python functions with @command and @argument decorators. Super commands are implemented as Python class objects, and instance methods decorated with @command are sub-commands. In non-interactive mode, you can set @command-decorated functions to return an int, which is used as the Linux return code.

By default, the framework loads commands from the python/seqslab/commands module directory. Atgenomix recommends implementing your program structure under the commands directory.

from termcolor import cprint
from nubia import argument, command
@command("hello")
@argument("name", type=str, positional=True, description="Your name") 
def hello(name: str) -> int:
    """
    command help, or the command won't be loaded.
    """
    cprint(f"Hello {name}!", "green")
    return 0
@command
class SuperCommand:
  """super-command command help"""

  def __init__(self):
    self._shared = "shared variable value"

  @property
  def shared(self) -> str:
    return self._shared

  @command(aliases=["echo"])
  @argument("first",
            type=str,
            positional=False,
            description="firstname",
            aliases=["f"])
  @argument("last",
            type=str,
            positional=False,
            description="lastname",
            aliases=["l"])
  def cprint(self, first: str, last: str) -> int:
      """
      sub-command help message.
      """
      cprint(f"{first} {last}", "red")
      return 0

Authentication with the SeqsLab API

Regardless of the mode (interactive or non-interactive) that you intend to use, you must sign in to authenticate the session. The SeqsLab CLI follows the OAuth 2.0 Device Authorization Grant (external URL) process.

• Specify the platform backend to be used when launching the SeqsLab CLI. The default value is azure.

  seqslab --backend azure
  

• Sign in to the SeqsLab API and obtain API tokens with a single command. By default, the sign-in command uses the Device Code Flow for browserless systems.

  auth signin
  

  Set the device-code argument to True. By default, the sign-in process uses the Authorization Code Flow.

  auth signin device-code=True
  

• Obtain an API access token for interacting with SeqsLab API apps.

  from seqslab.auth.commands import Auth
  
  token = Auth.get_token()
  access = token.get("tokens").get("access")
  # use token in your request header, ex: Authorization: Bearer {access}
  attrs = token.get("attrs")
  # attrs is a dictionary containing the information about the signing-in user.
  

  Auth.get_token() automatically refreshes the access token upon expiration. When users attempt to sign in to the SeqsLab API before a new access token is generated, the function returns None.

  Access tokens are persistently cached in the system-supported secret service, such as Freedesktop Secret Service and macOS Keychain. As a result, valid access tokens can be used across multiple SeqsLab CLI sessions.

Roadmap

See the list of proposed features and known issues.

Contributing

The repository currently does not accept contributions but will eventually be opened to the community.

License

See License.

Contact

Main contact: Allen Chang

Email: [e-mail]

Project repository: https://github.com/atgenomix

Acknowledgements

• Facebook Incubator
• Microsoft identity platform
• GA4GH
• Best-README-Template