Metadata-Version: 1.1
Name: beam
Version: 0.4.0
Summary: A lightweight wrapper for the SolusVM client API.
Home-page: https://github.com/gebn/beam
Author: George Brighton
Author-email: oss@gebn.co.uk
License: MIT
Description: beam
        ====
        
        .. image:: https://img.shields.io/pypi/status/beam.svg
           :target: https://pypi.python.org/pypi/beam
        .. image:: https://img.shields.io/pypi/v/beam.svg
           :target: https://pypi.python.org/pypi/beam
        .. image:: https://img.shields.io/pypi/pyversions/beam.svg
           :target: https://pypi.python.org/pypi/beam
        .. image:: https://travis-ci.org/gebn/beam.svg?branch=master
           :target: https://travis-ci.org/gebn/beam
        .. image:: https://coveralls.io/repos/github/gebn/beam/badge.svg?branch=master
           :target: https://coveralls.io/github/gebn/beam?branch=master
        
        A lightweight wrapper for the SolusVM client API.
        
        Features
        --------
        
        -  Query a host's memory, bandwidth, IP addresses and storage usage.
        -  Boot, reboot and shutdown machines.
        -  Configurable to work with any SolusVM provider.
        -  Command line client and intuitive Python module for your own scripts.
        
        Setup
        -----
        
        1. Run ``pip install beam`` to download the module.
        2. Create your ``.beam.ini`` inventory file as below.
        
        Inventory
        ~~~~~~~~~
        
        The inventory file holds information about your hosting provider(s) and host(s),
        so beam knows how to contact the relevant API endpoints and what credentials to
        use. Here's a sample file:
        
        .. code::
        
           [special:vendors]
           ramnode = https://vpscp.ramnode.com
           vendor2 = https://vendor2-panel.com
           default = ramnode
        
           [nyc-1]
           key = nyc-1_host_key
           hash = nyc-1_host_hash
        
           [ams-1]
           key = ams-1_host_key
           hash = ams-1_host_hash
           vendor = vendor2
        
        This file defines two hosts, ``nyc-1``, hosted with RamNode, and ``ams-1``,
        hosted with FlipHost. At the top are the vendor names in a special vendors
        section (all other sections are assumed to represent hosts). The format maps a
        vendor name to their base endpoint for the SolusVM API. The ``default``
        directive indicates the implicit vendor of every host, and must be specified if
        more than one vendor is defined.
        
        Each host has its own section. The correct ``key`` and ``hash`` values can be
        optained from the SolusVM control panel used by your vendor. If a host is not
        provided by the default vendor, a ``vendor`` directive specifies the correct
        one.
        
        Usage
        -----
        
        Beam provides both a Python library for programmatic access to your hosts, and
        a simple CLI that wraps it in a couple of lines of code.
        
        CLI
        ~~~
        
        The CLI client can be used to find information about a single host.
        
        .. code::
        
            $ beam --help
            usage: beam [-h] [-V]
                        (-A {boot,reboot,shutdown} | -a ATTRIBUTES [ATTRIBUTES ...])
                        [host]
        
            A lightweight wrapper for the SolusVM client API.
        
            positional arguments:
              host                  the identifier of the host whose information to
                                    retrieve
        
            optional arguments:
              -h, --help            show this help message and exit
              -V, --version         show program's version number and exit
              -A {boot,reboot,shutdown}, --action {boot,reboot,shutdown}
                                    an action to execute against the host
              -a ATTRIBUTES [ATTRIBUTES ...], --attributes ATTRIBUTES [ATTRIBUTES ...]
                                    one or more attributes of the host to retrieve
            $ beam -a bandwidth.free_percentage
            0.4983459835
            $ beam nyc-1 -a primary_ip
            2604:180:2:32b::498b
            $ beam ams-1 -a is_online memory.used_bytes
            True
            34578234983
            $ beam nyc-1 -A shutdown
            OK
        
        Library
        ~~~~~~~
        
        .. code:: python
        
            import beam
        
            # shutdown a specific host
            host = beam.host('nyc-1')  # name, key or hash
            if host.is_online:
                host.shutdown()
        
            # boot all offline hosts
            [host.boot() for host in beam.hosts() if not host.is_online]
        
            # get a list of hosts using above 90% of their memory
            hosts = [host for host in beam.hosts()
                     if host.memory.used_percentage > .9]
        
            # get a list of hosts with less than 10 GiB of storage left
            hosts = [host for host in beam.hosts()
                     if host.storage.free_bytes < 1024 ** 3 * 10]
        
        Roadmap
        -------
        
        -  Generate documentation.
        -  Increase unit test coverage to 100%, and implement some integration tests.
        
        Etymology
        ---------
        
        Although "solus" means alone, that's a tad depressing. Solus also conjures up
        images of the sun for me. The sun *beam*\ s down - and the name was available on
        PyPI - so beam it was.
        
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
