docs/index.rst

   1 .. libjuju documentation master file, created by
   2    sphinx-quickstart on Thu May 19 11:21:38 2016.
   3    You can adapt this file completely to your liking, but it should at least
   4    contain the root `toctree` directive.
   5
   6 A Python library for Juju
   7 =========================
   8
   9 NOTE: This is pre-release software. The implementation is usable but
  10 not complete.
  11
  12 Please report bugs at https://github.com/juju/python-libjuju/issues.
  13
  14
  15 Requirements
  16 ------------
  17
  18 * Python 3.5+
  19 * Juju 2.0+
  20
  21
  22 Design Notes
  23 ------------
  24
  25 * Asynchronous - uses asyncio and async/await features of python 3.5
  26 * Websocket-level bindings are programmatically generated (indirectly) from the
  27   Juju golang code, ensuring full api coverage
  28 * Provides an OO layer which encapsulates much of the websocket api and
  29   provides familiar nouns and verbs (e.g. Model.deploy(), Application.add_unit(),
  30   etc.)
  31
  32
  33 Installation
  34 ------------
  35
  36     git clone https://github.com/juju/python-libjuju.git
  37     cd python-libjuju
  38     python setup.py install  # make sure python is 3.5+
  39
  40
  41 Quickstart
  42 ----------
  43 Here's a simple example that shows basic usage of the library. The example
  44 connects to the currently active Juju model, deploys a single unit of the
  45 ubuntu charm, then exits.
  46
  47 More examples can be found in the `examples/` directory of the source tree,
  48 and in the documentation.
  49
  50
  51 .. code:: python
  52
  53   #!/usr/bin/python3.5
  54
  55   import asyncio
  56   import logging
  57
  58   from juju.model import Model
  59
  60
  61   async def run():
  62       # Create a Model instance. We need to connect our Model to a Juju api
  63       # server before we can use it.
  64       model = Model()
  65
  66       # Connect to the currently active Juju model
  67       await model.connect_current()
  68
  69       # Deploy a single unit of the ubuntu charm, using revision 0 from the
  70       # stable channel of the Charm Store.
  71       ubuntu_app = await model.deploy(
  72           'ubuntu-0',
  73           application_name='ubuntu',
  74           series='xenial',
  75           channel='stable',
  76       )
  77
  78       # Disconnect from the api server and cleanup.
  79       model.disconnect()
  80
  81       # Stop the asyncio event loop.
  82       model.loop.stop()
  83
  84
  85   def main():
  86       # Set logging level to debug so we can see verbose output from the
  87       # juju library.
  88       logging.basicConfig(level=logging.DEBUG)
  89
  90       # Quiet logging from the websocket library. If you want to see
  91       # everything sent over the wire, set this to DEBUG.
  92       ws_logger = logging.getLogger('websockets.protocol')
  93       ws_logger.setLevel(logging.INFO)
  94
  95       # Create the asyncio event loop
  96       loop = asyncio.get_event_loop()
  97
  98       # Queue up our `run()` coroutine for execution
  99       loop.create_task(run())
 100
 101       # Start the event loop
 102       loop.run_forever()
 103
 104
 105   if __name__ == '__main__':
 106       main()
 107
 108
 109 Table of Contents
 110 -----------------
 111
 112 .. toctree::
 113    :glob:
 114    :maxdepth: 3
 115
 116    narrative/index
 117    API Docs <api/modules>
 118
 119
 120
 121 Indices and tables
 122 ==================
 123
 124 * :ref:`genindex`
 125 * :ref:`modindex`
 126 * :ref:`search`
 127