modules/libjuju/docs/readme.rst

   1 A Python library for Juju
   2 =========================
   3
   4 Source code: https://github.com/juju/python-libjuju
   5
   6 Bug reports: https://github.com/juju/python-libjuju/issues
   7
   8 Documentation: https://pythonlibjuju.readthedocs.io/en/latest/
   9
  10
  11 Requirements
  12 ------------
  13
  14 * Python 3.5+
  15 * Juju 2.0+
  16
  17
  18 Design Notes
  19 ------------
  20
  21 * Asynchronous - uses asyncio and async/await features of python 3.5
  22 * Websocket-level bindings are programmatically generated (indirectly) from the
  23   Juju golang code, ensuring full api coverage
  24 * Provides an OO layer which encapsulates much of the websocket api and
  25   provides familiar nouns and verbs (e.g. Model.deploy(), Application.add_unit(),
  26   etc.)
  27
  28
  29 Installation
  30 ------------
  31
  32 .. code:: bash
  33
  34   pip3 install juju
  35
  36
  37 Quickstart
  38 ----------
  39 Here's a simple example that shows basic usage of the library. The example
  40 connects to the currently active Juju model, deploys a single unit of the
  41 ubuntu charm, then exits.
  42
  43 More examples can be found in the `examples/` directory of the source tree,
  44 and in the documentation.
  45
  46
  47 .. code:: python
  48
  49   #!/usr/bin/python3
  50
  51   import logging
  52   import sys
  53
  54   from juju import loop
  55   from juju.model import Model
  56
  57
  58   async def deploy():
  59       # Create a Model instance. We need to connect our Model to a Juju api
  60       # server before we can use it.
  61       model = Model()
  62
  63       # Connect to the currently active Juju model
  64       await model.connect_current()
  65
  66       try:
  67           # Deploy a single unit of the ubuntu charm, using the latest revision
  68           # from the stable channel of the Charm Store.
  69           ubuntu_app = await model.deploy(
  70             'ubuntu',
  71             application_name='ubuntu',
  72             series='xenial',
  73             channel='stable',
  74           )
  75
  76           if '--wait' in sys.argv:
  77               # optionally block until the application is ready
  78               await model.block_until(lambda: ubuntu_app.status == 'active')
  79       finally:
  80           # Disconnect from the api server and cleanup.
  81           await model.disconnect()
  82
  83
  84   def main():
  85       logging.basicConfig(level=logging.INFO)
  86
  87       # If you want to see everything sent over the wire, set this to DEBUG.
  88       ws_logger = logging.getLogger('websockets.protocol')
  89       ws_logger.setLevel(logging.INFO)
  90
  91       # Run the deploy coroutine in an asyncio event loop, using a helper
  92       # that abstracts loop creation and teardown.
  93       loop.run(deploy())
  94
  95
  96   if __name__ == '__main__':
  97       main()