firecloud 0.15.0

====================
1. Description
====================

FireCloud API bindings and FireCloud Service Selector (FISS)
Command-Line interface.

FireCloud:
https://software.broadinstitute.org/firecloud/

Github:
https://github.com/broadinstitute/fiss

====================
2. Contents
====================
1. Description
2. Contents
3. Requirements
4. Release Notes
5. FISS
6. Low-Level API
7. High-Level Classes
8. Yapsy Plugin System

This package contains low-level api bindings to FireCloud services,
high-level class abstractions for workspaces and entities, and the FISS
command-line tool for scripting FireCloud Tasks.

====================
3. Requirements
====================

Install this package via pip:
% pip install firecloud

Or download the source and install with setup.py:
% python setup.py install

This package depends on yapsy, oauth2client, and requests.

FireCloud uses the Google Cloud SDK (https://cloud.google.com/sdk/) to manage
authorization. To use the firecloud CLI or API, you must install the SDK and
login locally with

gcloud auth application-default login

**Note: FireCloud encryts all web traffic with TLSv1.2. Some versions of
python will not function correctly, and must be recompiled with openssl
v1.02 or later. If recompiling is not an option, there is also a
dockerized version of the tool available on docker hub
(https://hub.docker.com/r/broadgdac/fiss/).

% docker pull broadgdac/fiss

====================
4. Release Notes
====================
v0.15.0 - New 'config_validate' and 'runnable' commands for evaluating configurations
against the state of the data model in a workspace.

v0.14.1 - Bugfixes and validation for supervisor mode. Make flow_set_acl smarter,
and make the snapshot_id argument be optional, defaulting to the latest.

v0.14.0 - proj_list command for listing available billing projects. Rename
recover_supervisor to supervise_recover, for conceptual symmetry.

v0.13.2 - Fix getting workspace attributes when not using the attributes flag.

v0.13.1 - More helpful error checking for loadfile format during entity_import.

v0.13.0 - Some fixes to match API changes in FireCloud Orchestration and
several new commands:

supervise -- a robust mechanism of submitting related
workflows similar to Firehose workflows. Workflows described in DOT
can be submitted and monitored in one command, and fissfc will
monitor the entire workflow until completion.

recover_supervisor -- supervise saves workflow execution state after
each API call, so that the monitor can be restarted with this
command in case of a FISS crash.

attr_set -- set attributes in a workspace.

attr_delete -- delete attributes in a workspace.

attr_copy -- copy attributes from one workspace to another.

entity_copy -- copy entities from one workspace to another. Note that
referential constraints currently limit the ability to overwrite
entities in the target workspace.

v0.12.0 - Large refactor of argument handling for FISS. Almost all arguments
are now passed using flags instead of positional arguments, enabling
the argument namespace to be shared by command iterators. This allows
sset_loop (a new looping command) to call multiple FISS commands
without having to reparse arguments.

New FISS command for submitting workflows, 'flow_submit'.

v0.11.0 - New endpoint for paginated entity queries, also used by attr_get
to more reliably return attributes on large workspaces.

Also added new FISS command `attr_fill_null`, which will assign null
sentinel files to entities which do not have a valid attribute. This,
in a sense, "fills in" the sparse matrix of data for a given list of
attributes.

v0.10.1 - Fix Py3 compatibility issues.

v0.10.0 - Remove `fiss` entrypoint, to not overwrite fiss 1.0 installs. New fiss
"mop" command, to clean files that are not referenced in a workspace
attribute from the underlying google bucket.

v0.9.6 - Fix expected response code for entity_import

v0.9.5 - Fix urllib compatibility issue in upload_entities

v0.9.4 - Add ability to change inputs and other configuration details in a
workspace configuration

v0.9.3 - Improved documentation. Fixed url for method configurations in a workspace.

v0.9.2 - Remove file-based check for getting application default credentials,
improving support for Jupyter-based sessions.

v0.9.1 - Fix expected return code for flow_new.

v0.9.0 - Replace Httplib2 with Requests, which resolves the SSL handshake issue
for python3. Added six to required packages, making FireCloud fully
compatible with python 2 & 3. Add links to FireCloud's swagger
documentation.

v0.8.1 - Improved test coverage. Enhanced interactive classes. Fixed error logic
to match new server response.

v0.8.0 - firecloud.api now boasts 100% coverage of existing (useful) API endpoints.

Several api endpoints for manipulating NIH credentials and profile info
will deliberately remain unimplemented unless a good reason arises. Any
discrepancies are noted in the api module's docstring; see
help(firecloud.api) for a lengthy overview.

New Method and Configuration objects.
>>> m = Method("broad-firecloud-gdac", "gistic2", 1)


v0.7.4 - FISS functions can now display their source code with the -F option.

v0.7.3 - Improved documentation, with docstrings for every public function.
This enables python's builtin help system to be used from the REPL.
To see all the available firecloud api calls:
% python
>>> import firecloud
>>> help(firecloud.api)

v0.7.2 - Fix some commands that broke with the API changes

v0.7.1 - Add workspace functions for importing entities and creating entity sets.

v0.7.0 - Renamed package "firecloud", replacing "fissfc"
- firecloud_cli.py renamed fiss.py
- firecloud_api.py renamed api.py
Added workspace class for more flexible python interactivity. Example:
>>> w = Workspace.new("broad-firecloud-testing", "my_workspace")
>>> w.bucket()
"fc-92e4ic0a-60fb-454a-8ue0-d0efea803421"
>>> w.lock()
Added better error messaging for unexpected FireCloud Errors

v0.6.2 - Add '--protected' option for workspace creation.

v0.6.1 - Firecloud production API is now https://api.firecloud.org/api

v0.6.0 - Refactored the argument structure for inferring a default project.
Instead of passing the namespace as an optional input to a
subcommand, the project can be overriden explicitly with the -p
top-level flag. This cleans up the syntax for many commands, and
makes the help clearer.

Add --all option to space_list
attr_get:
* attributes now given a a list of positional arguments,
instead of comma-separated
* entity type limited to firecloud supported entities
Fixed help messages for many commands


v0.5.0 - Add python 3 support, so that fissfc should be installable to
either version. A TLS issue may still prevent fissfc from
working on some versions of python.

v0.4.1 - Add attr_get subcommand, as a replacement for fiss annot_get.
Clarify error message.

v0.4.0 - Implement default value for google project into most subcommands

v0.3.2 - Add check in firecloud_api for the existence of gcloud credentials

v0.3.1 - Add confirmation prompt for delete commands, and a
Flag to override them.

v0.3.0 - Added support for Yapsy plugins.

v0.0.1 - Initial Release

=====================================
5. FireCloud Service Selector (FISS)
=====================================

FISS enables high-level commands to be executed directly from the command line,
and is installed locally to /usr/local/bin/fiss.

FISS includes several forms of self-documentation. Type

% fiss --help

to get an overview. To list available commands, run

% fiss -l

Each command includes it's own help:

% fiss space_list -h

and as a bonus, to see how a command is implemented (including the underlying api calls),
use the "-F" option:

% fiss -F space_list

===========================
6. FireCloud Low-Level API
===========================
The following is a list of available endpoints as of v0.9.3. Swagger
documentation for the FireCloud orchestration layer is available at
https://api.firecloud.org/. See help(firecloud.api) for more details.

abort_submission()
clone_workspace()
copy_config_from_repo()
copy_config_to_repo()
copy_entities()
create_submission()
create_workspace()
create_workspace_config()
delete_entity()
delete_pair()
delete_pair_set()
delete_participant()
delete_participant_set()
delete_repository_method()
delete_sample()
delete_sample_set()
delete_workspace()
delete_workspace_config()
get_config_template()
get_entities()
get_entities_tsv()
get_entities_with_type()
get_entity()
get_inputs_outputs()
get_repository_config()
get_repository_config_acl()
get_repository_method()
get_repository_method_acl()
get_status()
get_submission()
get_submission_queue()
get_workflow_outputs()
get_workspace()
get_workspace_acl()
get_workspace_config()
list_billing_projects()
list_entity_types()
list_repository_configs()
list_repository_methods()
list_submissions()
list_workspace_configs()
list_workspaces()
lock_workspace()
ping()
rename_workspace_config()
unlock_workspace()
update_repository_config_acl()
update_repository_method()
update_repository_method_acl()
update_workspace_acl()
update_workspace_attributes()
update_workspace_config()
upload_entities()
upload_entities_tsv()
validate_config()

=======================
7. High-Level Classes
=======================

Workspace (firecloud.workspace.Workspace)
Entity (firecloud.entity.Entity)
Submisssion (firecloud.submission.Submission)
Config (firecloud.config.Config)

==========================
8. Yapsy plugins for FISS
==========================

The FISS CLI includes a yapsy-based plugin system for defining additional
command line options. Documentation coming soon.