add escalator cli framework

JIRA:ESCALATOR-36

This patch will support escalatorclient,and this is just the frame of
escalatorclient,with this code you can use 'python setup.py sdist' to
generate escalatorclient package.

Change-Id: Id7b602345f7cb78bb548b589d1297a201056699a
Signed-off-by: Zhou Ya <zhou.ya@zte.com.cn>

5 files changed, 313 insertions, 0 deletions

diff --git a/client/doc/Makefile b/client/doc/Makefile
new file mode 100644
index 0000000..430e5a3
--- /dev/null
+++ b/client/doc/Makefile
@@ -0,0 +1,90 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SPHINXSOURCE  = source
+PAPER         =
+BUILDDIR      = build
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SPHINXSOURCE)
+
+.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html      to make standalone HTML files"
+	@echo "  dirhtml   to make HTML files named index.html in directories"
+	@echo "  pickle    to make pickle files"
+	@echo "  json      to make JSON files"
+	@echo "  htmlhelp  to make HTML files and a HTML help project"
+	@echo "  qthelp    to make HTML files and a qthelp project"
+	@echo "  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  changes   to make an overview of all changed/added/deprecated items"
+	@echo "  linkcheck to check all external links for integrity"
+	@echo "  doctest   to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+	-rm -rf $(BUILDDIR)/*
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/python-keystoneclient.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/python-keystoneclient.qhc"
+
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
+	      "run these through (pdf)latex."
+
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."
diff --git a/client/doc/source/apiv2.rst b/client/doc/source/apiv2.rst
new file mode 100644
index 0000000..0695b2a
--- /dev/null
+++ b/client/doc/source/apiv2.rst
@@ -0,0 +1,27 @@
+Python API v1
+=============
+
+To create a client::
+
+   from keystoneclient.auth.identity import v2 as identity
+   from keystoneclient import session
+   from escalatorclient import Client
+
+   auth = identity.Password(auth_url=AUTH_URL,
+                            username=USERNAME,
+                            password=PASSWORD,
+                            tenant_name=PROJECT_ID)
+
+   sess = session.Session(auth=auth)
+   token = auth.get_token(sess)
+
+   escalator = Client('1', endpoint=OS_IMAGE_ENDPOINT, token=token)
+
+
+List
+----
+List nodes you can access::
+
+   for node in escalator.nodes.list():
+      print node
+
diff --git a/client/doc/source/conf.py b/client/doc/source/conf.py
new file mode 100644
index 0000000..1cfaad2
--- /dev/null
+++ b/client/doc/source/conf.py
@@ -0,0 +1,72 @@
+# -*- coding: utf-8 -*-
+#
+
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__),
+                '..', '..')))
+
+
+# -- General configuration ----------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = ['sphinx.ext.autodoc', 'oslosphinx']
+
+# autodoc generation is a bit aggressive and a nuisance when doing heavy
+# text edit cycles.
+# execute "export SPHINX_DEBUG=1" in your terminal to disable
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = 'python-escalatorclient'
+copyright = u'OpenStack Foundation'
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+add_module_names = True
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# Grouping the document tree for man pages.
+# List of tuples 'sourcefile', 'target', u'title', u'Authors name', 'manual'
+
+man_pages = [
+    ('man/escalator', 'escalator', u'Client for OpenStack Images API',
+     [u'OpenStack Foundation'], 1),
+]
+# -- Options for HTML output --------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  Major themes that come with
+# Sphinx are currently 'default' and 'sphinxdoc'.
+# html_theme = 'nature'
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = '%sdoc' % project
+
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass
+# [howto/manual]).
+latex_documents = [
+    (
+        'index',
+        '%s.tex' % project,
+        u'%s Documentation' % project,
+        u'OpenStack Foundation',
+        'manual'
+    ),
+]
diff --git a/client/doc/source/index.rst b/client/doc/source/index.rst
new file mode 100644
index 0000000..ec7d4ef
--- /dev/null
+++ b/client/doc/source/index.rst
@@ -0,0 +1,37 @@
+Python API
+==========
+In order to use the python api directly, you must first obtain an auth token and identify which endpoint you wish to speak to. Once you have done so, you can use the API like so::
+
+    >>> from escalatorclient import Client
+    >>> escalator = Client('1', endpoint=OS_IMAGE_ENDPOINT, token=OS_AUTH_TOKEN)
+    >>> image = escalator.images.create(name="My Test Image")
+    >>> print image.status
+    'queued'
+    >>> image.update(data=open('/tmp/myimage.iso', 'rb'))
+    >>> print image.status
+    'active'
+    >>> image.update(properties=dict(my_custom_property='value'))
+    >>> with open('/tmp/copyimage.iso', 'wb') as f:
+            for chunk in image.data:
+                f.write(chunk)
+    >>> image.delete()
+
+For an API v2 example see also :doc:`apiv2`.
+
+Command-line Tool
+=================
+In order to use the CLI, you must provide your OpenStack username, password, tenant, and auth endpoint. Use the corresponding configuration options (``--os-username``, ``--os-password``, ``--os-tenant-id``, and ``--os-auth-url``) or set them in environment variables::
+
+    export OS_USERNAME=user
+    export OS_PASSWORD=pass
+    export OS_TENANT_ID=b363706f891f48019483f8bd6503c54b
+    export OS_AUTH_URL=http://auth.example.com:5000/v2.0
+
+The command line tool will attempt to reauthenticate using your provided credentials for every request. You can override this behavior by manually supplying an auth token using ``--os-image-url`` and ``--os-auth-token``. You can alternatively set these environment variables::
+
+    export OS_IMAGE_URL=http://escalator.example.org:9292/
+    export OS_AUTH_TOKEN=3bcc3d3a03f44e3d8377f9247b0ad155
+
+Once you've configured your authentication parameters, you can run ``escalator help`` to see a complete listing of available commands.
+
+See also :doc:`/man/escalator`.
\ No newline at end of file
diff --git a/client/doc/source/man/escalator.rst b/client/doc/source/man/escalator.rst
new file mode 100644
index 0000000..40536ec
--- /dev/null
+++ b/client/doc/source/man/escalator.rst
@@ -0,0 +1,87 @@
+==============================
+:program:`escalator` CLI man page
+==============================
+
+.. program:: escalator
+.. highlight:: bash
+
+SYNOPSIS
+========
+
+:program:`escalator` [options] <command> [command-options]
+
+:program:`escalator help`
+
+:program:`escalator help` <command>
+
+
+DESCRIPTION
+===========
+
+The :program:`escalator` command line utility interacts with OpenStack Images
+Service (escalator).
+
+In order to use the CLI, you must provide your OpenStack username, password,
+project (historically called tenant), and auth endpoint. You can use
+configuration options :option:`--os-username`, :option:`--os-password`,
+:option:`--os-tenant-id`, and :option:`--os-auth-url` or set corresponding
+environment variables::
+
+    export OS_USERNAME=user
+    export OS_PASSWORD=pass
+    export OS_TENANT_ID=b363706f891f48019483f8bd6503c54b
+    export OS_AUTH_URL=http://auth.example.com:5000/v2.0
+
+The command line tool will attempt to reauthenticate using provided
+credentials for every request. You can override this behavior by manually
+supplying an auth token using :option:`--os-image-url` and
+:option:`--os-auth-token` or by setting corresponding environment variables::
+
+    export OS_IMAGE_URL=http://escalator.example.org:9292/
+    export OS_AUTH_TOKEN=3bcc3d3a03f44e3d8377f9247b0ad155
+
+
+You can select an API version to use by :option:`--os-image-api-version`
+option or by setting corresponding environment variable::
+
+    export OS_IMAGE_API_VERSION=2
+
+OPTIONS
+=======
+
+To get a list of available commands and options run::
+
+    escalator help
+
+To get usage and options of a command::
+
+    escalator help <command>
+
+
+EXAMPLES
+========
+
+Get information about image-create command::
+
+    escalator help image-create
+
+See available images::
+
+    escalator image-list
+
+Create new image::
+
+    escalator image-create --name foo --disk-format=qcow2 \
+                        --container-format=bare --is-public=True \
+                        --copy-from http://somewhere.net/foo.img
+
+Describe a specific image::
+
+    escalator image-show foo
+
+
+BUGS
+====
+
+escalator client is hosted in Launchpad so you can view current bugs at
+https://bugs.launchpad.net/python-escalatorclient/.