+++ /dev/null
-# Front Matter
-
-A python library for Juju.
-
-NOTE: This is early work-in-progress, pre-alpha software. There is very little
-implementation here yet. The design itself is not complete. Comments on the
-design, good or bad, are welcomed. Use cases are also appreciated as they will
-shape the design.
-
-The goal is to end up with a feature-full and officially supported python
-library for Juju.
-
-The focus right now is on Juju 2+ only.
-
-# Design Notes
-
-* Require python3.5+ (async/await) and juju-2.0+
-* Auto-generate async (and sync? see below) websocket client from juju golang code
-* Present an object-oriented interface to all the features of the Juju CLI
-* Do as much as possible through the API so that the library can be used
- without actually installing Juju
-
-# Implementation Status
-
-There is an async websocket client that is auto-generated (indirectly) from the
-juju golang code so that the entire api is supported. This is mostly working.
-There will probably a synchronous client as well because why not.
-
-On top of that will be an object-oriented layer that supports the full range of
-operations that one could perform with the CLI (at least), which uses the
-websocket client underneath but presents a friendlier interface. One advantage
-of using an async client is that we can have a live-updating object layer,
-where user code is informed of changes that are occurring to the underlying
-juju model in real time. There is an example of what this might look like in
-examples/livemodel.py.
-
-# Example Use Cases
-
-See the `examples/` directory for some simple working examples.
-
-## Simple bootstrap/deploy
-
-```python
-"""
-This doesn't work yet! It's an example of what usage might
-look like in the future.
-
-"""
-from juju import Juju
-
-juju = Juju()
-lxd = juju.get_cloud('lxd')
-controller = lxd.bootstrap('lxd-test')
-model = controller.get_model('default')
-
-# We might want an async and blocking version of deploy()?
-model.deploy('mediawiki-single')
-
-mediawiki = model.get_application('mediawiki')
-mediawiki.expose()
-
-```
--- /dev/null
+docs/readme.rst
\ No newline at end of file
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
-A Python library for Juju
-=========================
-NOTE: This is pre-release software. The implementation is usable but
-not complete.
-
-Please report bugs at https://github.com/juju/python-libjuju/issues.
-
-
-Requirements
-------------
-
-* Python 3.5+
-* Juju 2.0+
-
-
-Design Notes
-------------
-
-* Asynchronous - uses asyncio and async/await features of python 3.5
-* Websocket-level bindings are programmatically generated (indirectly) from the
- Juju golang code, ensuring full api coverage
-* Provides an OO layer which encapsulates much of the websocket api and
- provides familiar nouns and verbs (e.g. Model.deploy(), Application.add_unit(),
- etc.)
-
-
-Installation
-------------
-
- git clone https://github.com/juju/python-libjuju.git
- cd python-libjuju
- python setup.py install # make sure python is 3.5+
-
-
-Quickstart
-----------
-Here's a simple example that shows basic usage of the library. The example
-connects to the currently active Juju model, deploys a single unit of the
-ubuntu charm, then exits.
-
-More examples can be found in the `examples/` directory of the source tree,
-and in the documentation.
-
-
-.. code:: python
-
- #!/usr/bin/python3.5
-
- import asyncio
- import logging
-
- from juju.model import Model
-
-
- async def run():
- # Create a Model instance. We need to connect our Model to a Juju api
- # server before we can use it.
- model = Model()
-
- # Connect to the currently active Juju model
- await model.connect_current()
-
- # Deploy a single unit of the ubuntu charm, using revision 0 from the
- # stable channel of the Charm Store.
- ubuntu_app = await model.deploy(
- 'ubuntu-0',
- application_name='ubuntu',
- series='xenial',
- channel='stable',
- )
-
- # Disconnect from the api server and cleanup.
- model.disconnect()
-
- # Stop the asyncio event loop.
- model.loop.stop()
-
-
- def main():
- # Set logging level to debug so we can see verbose output from the
- # juju library.
- logging.basicConfig(level=logging.DEBUG)
-
- # Quiet logging from the websocket library. If you want to see
- # everything sent over the wire, set this to DEBUG.
- ws_logger = logging.getLogger('websockets.protocol')
- ws_logger.setLevel(logging.INFO)
-
- # Create the asyncio event loop
- loop = asyncio.get_event_loop()
-
- # Queue up our `run()` coroutine for execution
- loop.create_task(run())
-
- # Start the event loop
- loop.run_forever()
-
-
- if __name__ == '__main__':
- main()
+.. include:: readme.rst
Table of Contents
--- /dev/null
+A Python library for Juju
+=========================
+
+Source code: https://github.com/juju/python-libjuju
+
+Bug reports: https://github.com/juju/python-libjuju/issues
+
+Documentation: https://pythonhosted.org/juju/
+
+
+Requirements
+------------
+
+* Python 3.5+
+* Juju 2.0+
+
+
+Design Notes
+------------
+
+* Asynchronous - uses asyncio and async/await features of python 3.5
+* Websocket-level bindings are programmatically generated (indirectly) from the
+ Juju golang code, ensuring full api coverage
+* Provides an OO layer which encapsulates much of the websocket api and
+ provides familiar nouns and verbs (e.g. Model.deploy(), Application.add_unit(),
+ etc.)
+
+
+Installation
+------------
+
+.. code:: bash
+
+ pip install juju
+
+
+Quickstart
+----------
+Here's a simple example that shows basic usage of the library. The example
+connects to the currently active Juju model, deploys a single unit of the
+ubuntu charm, then exits.
+
+More examples can be found in the `examples/` directory of the source tree,
+and in the documentation.
+
+
+.. code:: python
+
+ #!/usr/bin/python3.5
+
+ import asyncio
+ import logging
+
+ from juju.model import Model
+
+
+ async def run():
+ # Create a Model instance. We need to connect our Model to a Juju api
+ # server before we can use it.
+ model = Model()
+
+ # Connect to the currently active Juju model
+ await model.connect_current()
+
+ # Deploy a single unit of the ubuntu charm, using revision 0 from the
+ # stable channel of the Charm Store.
+ ubuntu_app = await model.deploy(
+ 'ubuntu-0',
+ application_name='ubuntu',
+ series='xenial',
+ channel='stable',
+ )
+
+ # Disconnect from the api server and cleanup.
+ model.disconnect()
+
+ # Stop the asyncio event loop.
+ model.loop.stop()
+
+
+ def main():
+ # Set logging level to debug so we can see verbose output from the
+ # juju library.
+ logging.basicConfig(level=logging.DEBUG)
+
+ # Quiet logging from the websocket library. If you want to see
+ # everything sent over the wire, set this to DEBUG.
+ ws_logger = logging.getLogger('websockets.protocol')
+ ws_logger.setLevel(logging.INFO)
+
+ # Create the asyncio event loop
+ loop = asyncio.get_event_loop()
+
+ # Queue up our `run()` coroutine for execution
+ loop.create_task(run())
+
+ # Start the event loop
+ loop.run_forever()
+
+
+ if __name__ == '__main__':
+ main()
-# until https://github.com/juju/theblues/pull/46 and https://github.com/juju/theblues/pull/47
-# are merged, this depends on the following fork:
-git+https://github.com/johnsca/theblues@libjuju#egg=theblues
-python-dateutil==2.6.0
+--index-url https://pypi.python.org/simple/
+
+-e .
],
include_package_data=True,
maintainer='Juju Ecosystem Engineering',
- maintainer_email='juju@lists.ubunut.com',
+ maintainer_email='juju@lists.ubuntu.com',
description=('Python library for Juju'),
+ url='https://github.com/juju/python-libjuju',
license='Apache 2',
classifiers=[
"Development Status :: 3 - Alpha",
projects / osm / N2VC.git / commitdiff