README.md

   1 # Front Matter
   2
   3 A python library for Juju.
   4
   5 NOTE: This is early work-in-progress, pre-alpha software. There is very little
   6 implementation here yet. The design itself is not complete.  Comments on the
   7 design, good or bad, are welcomed. Use cases are also appreciated as they will
   8 shape the design.
   9
  10 The goal is to end up with a feature-full and officially supported python
  11 library for Juju.
  12
  13 The focus right now is on Juju 2+ only.
  14
  15 # Design Notes
  16
  17 * Require python3.5+ (async/await) and juju-2.0+
  18 * Auto-generate async (and sync? see below) websocket client from juju golang code
  19 * Present an object-oriented interface to all the features of the Juju CLI
  20 * Do as much as possible through the API so that the library can be used
  21         without actually installing Juju
  22
  23 # Implementation Status
  24
  25 There is an async websocket client that is auto-generated (indirectly) from the
  26 juju golang code so that the entire api is supported. This is mostly working.
  27 There will probably a synchronous client as well because why not.
  28
  29 On top of that will be an object-oriented layer that supports the full range of
  30 operations that one could perform with the CLI (at least), which uses the
  31 websocket client underneath but presents a friendlier interface. One advantage
  32 of using an async client is that we can have a live-updating object layer,
  33 where user code is informed of changes that are occurring to the underlying
  34 juju model in real time. There is an example of what this might look like in
  35 examples/livemodel.py.
  36
  37 # Example Use Cases
  38
  39 See the `examples/` directory for some simple working examples.
  40
  41 ## Simple bootstrap/deploy
  42
  43 ```python
  44 """
  45 This doesn't work yet! It's an example of what usage might
  46 look like in the future.
  47
  48 """
  49 from juju import Juju
  50
  51 juju = Juju()
  52 lxd = juju.get_cloud('lxd')
  53 controller = lxd.bootstrap('lxd-test')
  54 model = controller.get_model('default')
  55
  56 # We might want an async and blocking version of deploy()?
  57 model.deploy('mediawiki-single')
  58
  59 mediawiki = model.get_application('mediawiki')
  60 mediawiki.expose()
  61
  62 ```