pontoon 0.2.4

Copyright (c) 2016 Ross Duggan

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.

Description: pontoon
=======

A Python CLI (and library) for `Digital
Ocean <https://digitalocean.com>`__.

Introduction
------------

Pontoon makes interacting with Digital Ocean on the command line smooth
sailing.

It is designed for human consumption, and aims to have good defaults.

It also happens to be a library.

Caveats
-------

Pontoon has one rule it imposes on top of Digital Ocean:

***Names are unique.***

Unique names make for a much easier command line experience. For
Droplets, names are hostnames, and hostnames should be unique anyway;
it's just a good idea.

They don't have to be unique *forever* though; once a Droplet is
destroyed, it's fine to use the name again.

Anything "recommended" (like secure-erasing the drive on termination) is
optional, but enabled by default.

Installation
------------

Install via pip:

::

$pipinstallpontoonToinstallthelatest(development,unstable)release:::$ pip install https://github.com/duggan/pontoon/archive/master.zip

If you'd like to package pontoon for your favourite OS, feel free to do
so (and please send a PR to this README!)

More options are on the way.

CLI Usage
---------

Configure
~~~~~~~~~

Set up your credentials and preferences:

::

$\text{Missing open brace for subscript}$ pontoon droplet create foobar
Creating Droplet foobar (512MB using Ubuntu 12.04 x64 in Amsterdam 1)...
.......active

SSH into your Droplet
~~~~~~~~~~~~~~~~~~~~~

If everything's configured correctly, you should be able to SSH into
your Droplet like so:

::

$\text{You can't use 'macro parameter character \#' in math mode}$ pontoon droplet list
foobar: (512MB, Ubuntu 12.04 x64, Amsterdam 1, 192.0.2.128, active)

or for more detail:

::

$\text{Missing open brace for subscript}$ pip install tox
$\text{Missing open brace for subscript}$ brew install bats

On Debian/Ubuntu, I've set up a PPA for easy installation of bats:

::

$add-apt-repositoryppa:duggan/bats$ apt-get update
$apt-getinstallbatsDebuggingSetthe‘‘DEBUG‘‘environmentvariable(toanything)toenabledebugoutputforpontoon.Thiswillgiveastepthroughofmostmethodsbeingexecutedduringacommand,likeso:::$ DEBUG=1 pontoon droplet destroy foobar
2013-11-09 18:37:06,187 [pontoon.configure:DEBUG] combined: (){}
2013-11-09 18:37:06,187 [pontoon.configure:DEBUG] read_config: (){}
Destroying foobar and scrubbing data...
2013-11-09 18:37:06,204 [pontoon.droplet:DEBUG] destroy: (<pontoon.droplet.Droplet instance at 0x10ce1fd40>, 'foobar', False){}
2013-11-09 18:37:06,204 [pontoon.droplet:DEBUG] id_from_name: (<pontoon.droplet.Droplet instance at 0x10ce1fd40>, 'foobar'){}
2013-11-09 18:37:06,204 [pontoon.droplet:DEBUG] list: (<pontoon.droplet.Droplet instance at 0x10ce1fd40>,){}
2013-11-09 18:37:06,205 [pontoon.pontoon:DEBUG] render: (<pontoon.pontoon.Pontoon instance at 0x10ce1fcf8>, 'droplets', '/droplets'){}
2013-11-09 18:37:06,205 [pontoon.pontoon:DEBUG] request: (<pontoon.pontoon.Pontoon instance at 0x10ce1fcf8>, '/droplets'){'params': {}, 'method': 'GET'}
2013-11-09 18:37:07,498 [pontoon.pontoon:DEBUG] render: (<pontoon.pontoon.Pontoon instance at 0x10ce1fcf8>, 'event_id', '/droplets/998/destroy'){'params': {'scrub_data': 1}}
2013-11-09 18:37:07,498 [pontoon.pontoon:DEBUG] request: (<pontoon.pontoon.Pontoon instance at 0x10ce1fcf8>, '/droplets/998/destroy'){'params': {'scrub_data': 1}, 'method': 'GET'}

A timestamp, followed by the module, debug level, the method called and
the arguments to that method (positional as brackets, keywords as
curlies).

This functionality is implemented by the ``@debug`` decorator, the code
for which can be seen at ``pontoon/log.py``.

Mocking
~~~~~~~

Set the ``MOCK`` environment variable (to anything) to return mock
request data instead of querying Digital Ocean.

This is implemented solely for end-to-end testing of the CLI, but you may
find it useful in some other scenarios.

.. |Build Status on Linux| image:: https://travis-ci.org/duggan/pontoon.png?branch=master
:target: https://travis-ci.org/duggan/pontoon
.. |Build status on Windows| image:: https://ci.appveyor.com/api/projects/status/rljdp3isvaj2pl3q?svg=true
:target: https://ci.appveyor.com/project/duggan/pontoon
.. |Coverage Status| image:: https://coveralls.io/repos/duggan/pontoon/badge.png?branch=master
:target: https://coveralls.io/r/duggan/pontoon?branch=master
.. |Doc Status| image:: https://readthedocs.org/projects/pontoon/badge/?version=latest
:target: http://pontoon.readthedocs.org/en/latest/?badge=latest


Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.2
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: Implementation :: PyPy