From 5ad9b9d20df199802417d1a5480942afeccbf119 Mon Sep 17 00:00:00 2001 From: Tim Van Steenburgh Date: Tue, 20 Dec 2016 11:17:03 -0500 Subject: [PATCH] Cleanup for first release --- README.md | 62 ---------------------------- README.rst | 1 + docs/index.rst | 101 +--------------------------------------------- docs/readme.rst | 102 +++++++++++++++++++++++++++++++++++++++++++++++ requirements.txt | 7 ++-- setup.py | 3 +- 6 files changed, 109 insertions(+), 167 deletions(-) delete mode 100644 README.md create mode 120000 README.rst create mode 100644 docs/readme.rst diff --git a/README.md b/README.md deleted file mode 100644 index 37ec461..0000000 --- a/README.md +++ /dev/null @@ -1,62 +0,0 @@ -# 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() - -``` diff --git a/README.rst b/README.rst new file mode 120000 index 0000000..c750ce5 --- /dev/null +++ b/README.rst @@ -0,0 +1 @@ +docs/readme.rst \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index a38e3a4..4c3b90f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,107 +3,8 @@ 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 diff --git a/docs/readme.rst b/docs/readme.rst new file mode 100644 index 0000000..efb8495 --- /dev/null +++ b/docs/readme.rst @@ -0,0 +1,102 @@ +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() diff --git a/requirements.txt b/requirements.txt index 6c000e9..cd8c47d 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,4 +1,3 @@ -# 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 . diff --git a/setup.py b/setup.py index fe53cb0..de262e4 100644 --- a/setup.py +++ b/setup.py @@ -29,8 +29,9 @@ setup( ], 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", -- 2.17.1