Metadata-Version: 2.1
Name: pitcrew
Version: 0.0.2
Summary: AsyncIO-powered python DSL for running commands locally, on docker, or over ssh.
Home-page: http://pitcrew.io
Author: joshbuddy
Author-email: joshbuddy@gmail.com
License: MIT
Platform: UNKNOWN
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.6.0
Description-Content-Type: text/markdown
Requires-Dist: aiofiles (==0.4.0)
Requires-Dist: aiounittest (==1.1.0)
Requires-Dist: altgraph (==0.16.1)
Requires-Dist: appdirs (==1.4.3)
Requires-Dist: asn1crypto (==0.24.0)
Requires-Dist: asyncssh (==1.16.1)
Requires-Dist: attrs (==19.1.0)
Requires-Dist: black (==18.9b0)
Requires-Dist: bleach (==3.1.0)
Requires-Dist: certifi (==2019.3.9)
Requires-Dist: cffi (==1.12.3)
Requires-Dist: chardet (==3.0.4)
Requires-Dist: Click (==7.0)
Requires-Dist: cryptography (==2.6.1)
Requires-Dist: docutils (==0.14)
Requires-Dist: entrypoints (==0.3)
Requires-Dist: flake8 (==3.7.7)
Requires-Dist: future (==0.17.1)
Requires-Dist: githubrelease (==1.5.8)
Requires-Dist: idna (==2.8)
Requires-Dist: Jinja2 (==2.10.1)
Requires-Dist: jinja2-highlight (==0.6.1)
Requires-Dist: LinkHeader (==0.4.3)
Requires-Dist: livereload (==2.6.0)
Requires-Dist: macholib (==1.11)
Requires-Dist: Markdown (==3.1)
Requires-Dist: markdown2 (==2.3.7)
Requires-Dist: MarkupSafe (==1.1.1)
Requires-Dist: mccabe (==0.6.1)
Requires-Dist: mkdocs (==1.0.4)
Requires-Dist: netaddr (==0.7.19)
Requires-Dist: pefile (==2019.4.18)
Requires-Dist: pkginfo (==1.5.0.1)
Requires-Dist: pur (==5.2.2)
Requires-Dist: pycodestyle (==2.5.0)
Requires-Dist: pycparser (==2.19)
Requires-Dist: pydoc-markdown (==2.0.5)
Requires-Dist: pyflakes (==2.1.1)
Requires-Dist: Pygments (==2.3.1)
Requires-Dist: PyInstaller (==3.4)
Requires-Dist: PyYAML (==5.1)
Requires-Dist: readme-renderer (==24.0)
Requires-Dist: requests (==2.21.0)
Requires-Dist: requests-toolbelt (==0.9.1)
Requires-Dist: six (==1.12.0)
Requires-Dist: toml (==0.10.0)
Requires-Dist: tornado (==6.0.2)
Requires-Dist: tqdm (==4.31.1)
Requires-Dist: twine (==1.13.0)
Requires-Dist: urllib3 (==1.24.2)
Requires-Dist: webencodings (==0.5.1)


# 🔧 Pitcrew

AsyncIO-powered python DSL for running commands locally, on docker, or over ssh.

[![CircleCI](https://circleci.com/gh/joshbuddy/pitcrew.svg?style=svg)](https://circleci.com/gh/joshbuddy/pitcrew)

## What does Pitcrew do?

<table>
    <tr>
        <td>Pitcrew can run commands</td>
        <td><code>
            $ crew sh date
        </code></td>
    </tr>
    <tr>
        <td>...or over ssh</td>
        <td><code>
            $ crew sh -p providers.ssh -P '{"hosts": ["192.168.0.1"]}' date
        </code></td>
    </tr>
    <tr>
        <td>on hundreds of hosts!</td>
        <td><code>
            $ crew sh -p providers.ssh -P '{"hosts": ["192.168.0.1-100"]}' date
        </code></td>
    </tr>
    <tr>
        <td>Crew can also run tasks</td>
        <td><code>
            $ crew run install.homebrew
        </code></td>
    </tr>
    <tr>
        <td>Tasks are either other shell commands, or other tasks, for example,
        this provisions Cloudfront, SSL and S3 and builds and deploys docs to pitcrew.io</td>
        <td><code>
            $ crew run examples.deploy_pitcrew
        </code></td>
    </tr>
    <tr>
        <td>You can list available tasks</td>
        <td><code>
            $ crew list
        </code></td>
    </tr>
    <tr>
        <td>...edit an existing task</td>
        <td><code>
            $ crew edit examples.deploy_pitcrew
            # opens in $EDITOR
        </code></td>
    </tr>
    <tr>
        <td>or create a new task!</td>
        <td><code>
            $ crew new some.new.task
        </code></td>
    </tr>
</table>

## Installation

### From binary

To install pitcrew in your home directory, run the following:

```
curl -fsSL "https://github.com/joshbuddy/pitcrew/releases/latest/download/crew-$(uname)" > crew
chmod u+x crew
./crew run crew.install --dest="$HOME/crew"
```

### From PyPi

To install from the Python Package Index, run the following:

```
pip install pitcrew
crew run crew.install --dest="$HOME/crew"
```

### From source

```
git clone https://github.com/joshbuddy/pitcrew
cd pitcrew
python3.6 -m venv env
env/bin/pip installer -r requirements.txt
```

## Concepts

A command or set of commands is called a **task**. A **context** runs tasks either locally, on docker or over ssh.
A **provider** generates contexts.

### Tasks

Tasks are either composed from other tasks or invoking a command on a shell.

An example of a *task* might be reading a file. `fs.read(path)` reads a file as bytes and returns it:

### `pitcrew/tasks/fs/read.py`

```python
import base64
from pitcrew import task


@task.arg("path", desc="The file to read", type=str)
@task.returns("The bytes of the file")
class FsRead(task.BaseTask):
    """Read value of path into bytes"""

    async def run(self) -> bytes:
        code, out, err = await self.sh_with_code(f"cat {self.params.esc_path}")
        assert code == 0, "exitcode was not zero"
        return out

```

Other tasks might include writing a file, installing xcode or cloning a git repository. All the currently available
tasks are listed at [docs/tasks.md](docs/tasks.md). The api available in a task is available at [docs/api.md#crewtask](docs/api.md#crewtask).

### Contexts

An example of a *context* might be over ssh, or even locally. Learn more about contexts at [docs/api.md#crewcontext](docs/api.md#crewcontext).

### Providers

A *provider* is a task with a specific return type. The return type is an async iterator which returns contexts.

## Usage

For detailed usage, see [docs/cli.md](docs/cli.md) for more details.

### Run a command

Pitcrew allows running a command using `bin/crew sh -- [shell command]`.

For example `crew sh ls /` will list the "/" directory locally.

You can run this across three hosts via ssh using `crew sh -p providers.ssh -P '{"hosts": ["192.168.0.1", "192.168.0.2", "192.168.0.3"]}' ls /`.

### Run a task

Pitcrew allows running a task using `crew run [task name] <task args>`. This will normally target your local machine unless you use the `-p` flag to select a different provider.

### See available tasks

To see all the available tasks run `crew list`. This will show all available tasks which are stored in `crew/tasks`.

### Make a new task

To see all the available tasks run `crew new [task_name]`. This will create a template of a new task.

### Run tests

To run an ad-hoc command use . For tasks use `crew run [task-name] <args>`.

### Get CLI help

To see the whole list of commands available from the command-line, run `crew help`.


