Package: pontoon
Copyright (c) 2016 Ross DugganPermission is hereby granted, free of charge, to any person obtaining a copyof this software and associated documentation files (the "Software"), to dealin the Software without restriction, including without limitation the rightsto use, copy, modify, merge, publish, distribute, sublicense, and/or sellcopies of the Software, and to permit persons to whom the Software isfurnished to do so, subject to the following conditions:The above copyright notice and this permission notice shall be included inall copies or substantial portions of the Software.THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS ORIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THEAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHERLIABILITY, 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 INTHE SOFTWARE.Description: pontoon=======A Python CLI (and library) for `DigitalOcean <https://digitalocean.com>`__.Introduction------------Pontoon makes interacting with Digital Ocean on the command line smoothsailing.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. ForDroplets, 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 isdestroyed, it's fine to use the name again.Anything "recommended" (like secure-erasing the drive on termination) isoptional, but enabled by default.Installation------------Install via pip:::$ pip install pontoonTo install the latest (development, unstable) release:::$ pip install https://github.com/duggan/pontoon/archive/master.zipIf you'd like to package pontoon for your favourite OS, feel free to doso (and please send a PR to this README!)More options are on the way.CLI Usage---------Configure~~~~~~~~~Set up your credentials and preferences:::$ pontoon configureYou'll be prompted for your Digital Ocean API credentials (`availablehere <https://cloud.digitalocean.com/api_access>`__), and whether youwant to use existing SSH credentials or for them to be generated (usingOpenSSH).The rest are preferences, and can be set at any time by runningconfigure again, editing the ``~/.pontoon`` config file (YAML format),or by specifying them with options on the command line.Create your first Droplet!~~~~~~~~~~~~~~~~~~~~~~~~~~Now you can create your first droplet:::$ pontoon droplet create foobarCreating Droplet foobar (512MB using Ubuntu 12.04 x64 in Amsterdam 1)..........activeSSH into your Droplet~~~~~~~~~~~~~~~~~~~~~If everything's configured correctly, you should be able to SSH intoyour Droplet like so:::$ pontoon droplet ssh foobarWelcome to Ubuntu 12.04 LTS (GNU/Linux 3.2.0-23-virtual x86_64)* Documentation:  https://help.ubuntu.com/Last login: Fri May  3 18:23:56 2013root@foobar:~#List your Droplets~~~~~~~~~~~~~~~~~~::$ pontoon droplet listfoobar:         (512MB, Ubuntu 12.04 x64, Amsterdam 1, 192.0.2.128, active)or for more detail:::$ pontoon droplet list --detailfoobarid:                  998name:                foobarsize:                512MBimage:               Ubuntu 12.04 x64region:              Amsterdam 1status:              activelocked:              Falseprivate_ip_address:  Nonecreated_at:          2013-11-09T13:22:40Zbackups_active:      Falseip_address:          192.0.2.128Contributing------------Pull requests for bugs are always welcome! New functionality shouldgenerally be preceded by a discussion, though if you've writtensomething that you needed and want to contribute back, a pull request isa fine way to start that discussion :tada:All of the code in pontoon is`PEP-8 <http://www.python.org/dev/peps/pep-0008/>`__ audited (using`pytest-pep8 <https://pypi.python.org/pypi/pytest-pep8>`__), and there'sa full suite of tests written for `py.test <http://pytest.org/>`__(library code) and `Bats <https://github.com/sstephenson/bats>`__(interface). Contributions should, therefore, include tests and pass aPEP-8 audit.Running the tests~~~~~~~~~~~~~~~~~Tests are run via `Tox <https://tox.readthedocs.org>`__.For example, to test the library, CLI and coverage for Python 2.7, run:::$ pip install tox$ tox -e py27,lib,cli,coverageThe ``.travis.yml`` file in this repository enumerates all the teststhat are performed.The CLI tests require `BATS <https://github.com/sstephenson/bats>`__,and PEP8 checks are performed in both the ``lib`` tests and ``cli``tests.On OSX, bats can be installed with homebrew:::$ brew install batsOn Debian/Ubuntu, I've set up a PPA for easy installation of bats:::$ add-apt-repository ppa:duggan/bats$ apt-get update$ apt-get install batsDebugging~~~~~~~~~Set the ``DEBUG`` environment variable (to anything) to enable debugoutput for pontoon.This will give a step through of most methods being executed during acommand, like so:::$ DEBUG=1 pontoon droplet destroy foobar2013-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 andthe arguments to that method (positional as brackets, keywords ascurlies).This functionality is implemented by the ``@debug`` decorator, the codefor which can be seen at ``pontoon/log.py``.Mocking~~~~~~~Set the ``MOCK`` environment variable (to anything) to return mockrequest data instead of querying Digital Ocean.This is implemented solely for end-to-end testing of the CLI, but you mayfind 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=latestPlatform: UNKNOWNClassifier: Development Status :: 4 - BetaClassifier: Intended Audience :: DevelopersClassifier: Natural Language :: EnglishClassifier: License :: OSI Approved :: MIT LicenseClassifier: Topic :: Internet :: WWW/HTTPClassifier: Programming Language :: PythonClassifier: Programming Language :: Python :: 2.6Classifier: Programming Language :: Python :: 2.7Classifier: Programming Language :: Python :: 3.2Classifier: Programming Language :: Python :: 3.3Classifier: Programming Language :: Python :: 3.4Classifier: Programming Language :: Python :: 3.5Classifier: Programming Language :: Python :: Implementation :: PyPy