# Shipyard BP Utils

Readme based of version 1.0.0a1

## Table of Contents

- [Overview](#overview)
    - [Args](#args)
    - [Artifacts](#artifacts)
        - [Logs](#logs)
        - [Responses](#responses)
        - [Variables](#variables)
    - [Custom Artifacts](#custom-artifacts)
    - [Files](#files)
    - [Text](#text)

### Overview

This package is a collection of utils that are intended for universal use across all Shipyard Blueprints.

#### Args

These Utils are used to handle common parsing of arguments from the application to the blueprint along with handling
common env var manipulations.

#### Artifacts

This util mainly manages the creation of files and folders so that the blueprint can store data for cross blueprint
communication.

By default, it has the following artifacts:

- logs: shipyard-vendor/artifacts/logs
- responses: shipyard-vendor/artifacts/responses
- variables: shipyard-vendor/artifacts/variables

##### Logs

This artifact is used to store logs that are generated by the blueprint. Prior to it was uses to store responses and
variables.
Currently, does not have a strong use case but later may be useful to add a handler to the Shipyard Logger to log to
this artifact.
Another use case which currently is most likely not be possible is to store the attempt logs

##### Responses

This artifact is used to store responses that are generated by the blueprint.
example

```python
from shipyard_bp_utils.artifacts import Artifacts

artifacts = Artifacts('jira')

response = jira.create_issue(fields=fields)
artifacts.responses.write_json('create_issue', response)
artifacts.variables.write_json('new_issue', response['issueId'])
```

if needed to pull values from another vessel you can do the following:

```python
from shipyard_bp_utils.artifacts import Artifacts

artifacts = Artifacts('jira')

response = artifacts.responses.read_json('create_issue')
```

##### Variables

This artifact is used to store variables that are generated by the blueprint.
The difference between the expectation of responses and variables is variables should contain the final result/side
effect of the vessal run that may be needed by another vessel and not the raw response details of individual responses
of a http requests.

for example:

```python
from shipyard_bp_utils.artifacts import Artifacts

artifacts = Artifacts('slack')

response = slack.send_message(channel=channel, text=text)
artifacts.responses.write_json('send_message', response)
artifacts.variables.write_json('message',
                               {'message_ts': response['ts'],
                                'channel': response['channel'],
                                'contain_attachment': False})
``` 

if needed to pull values from another vessel you can do the following:

```python
from shipyard_bp_utils.artifacts import Artifacts

artifacts = Artifacts('slack')

message_details = artifacts.variables.read_json('message')
# alternatively: message_details = artifacts.variables.read('message','json')
if message_details['contain_attachment']:
    print('There was a report sent this week')
else:
    print('There was no report sent this week. Did something go wrong?')
```

#### Custom Artifacts

You can also create custom artifacts if you need to store data that is not a response or variable.
For example, if you wanted to store the details of a user that was created by the blueprint you could do the following:

```python
from shipyard_bp_utils.artifacts import Artifacts

artifacts = Artifacts('jira')
artifacts.users = artifacts.SubFolder('users')

response = jira.users.write('create_user', 'name='
test_user
',**user_details)
response = jira.response.write_json('create_user', response)
```

Note: If you need the behaivor of what was once `logs.determine_base_artifact_folder` you can do the following:

```python
from shipyard_bp_utils.artifacts import Artifacts

base_artifact_folder = Artifacts('jira').base_folder
```

### Files

This util is used for common file manipulation and folder management.
It is used to create, read, update, and delete files and folders.

### Text

This util is used for common text manipulation.
Currently unused
