Revision 1acf67a7

b/snf-astakos-client/docs/Makefile
1
# Makefile for Sphinx documentation
2
#
3

  
4
# You can set these variables from the command line.
5
SPHINXOPTS    =
6
SPHINXBUILD   = sphinx-build
7
PAPER         =
8
BUILDDIR      = _build
9

  
10
# Internal variables.
11
PAPEROPT_a4     = -D latex_paper_size=a4
12
PAPEROPT_letter = -D latex_paper_size=letter
13
ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
14
# the i18n builder cannot share the environment and doctrees with the others
15
I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
16

  
17
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
18

  
19
help:
20
	@echo "Please use \`make <target>' where <target> is one of"
21
	@echo "  html       to make standalone HTML files"
22
	@echo "  dirhtml    to make HTML files named index.html in directories"
23
	@echo "  singlehtml to make a single large HTML file"
24
	@echo "  pickle     to make pickle files"
25
	@echo "  json       to make JSON files"
26
	@echo "  htmlhelp   to make HTML files and a HTML help project"
27
	@echo "  qthelp     to make HTML files and a qthelp project"
28
	@echo "  devhelp    to make HTML files and a Devhelp project"
29
	@echo "  epub       to make an epub"
30
	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
31
	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
32
	@echo "  text       to make text files"
33
	@echo "  man        to make manual pages"
34
	@echo "  texinfo    to make Texinfo files"
35
	@echo "  info       to make Texinfo files and run them through makeinfo"
36
	@echo "  gettext    to make PO message catalogs"
37
	@echo "  changes    to make an overview of all changed/added/deprecated items"
38
	@echo "  linkcheck  to check all external links for integrity"
39
	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
40

  
41
clean:
42
	-rm -rf $(BUILDDIR)/*
43

  
44
html:
45
	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
46
	@echo
47
	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
48

  
49
dirhtml:
50
	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
51
	@echo
52
	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
53

  
54
singlehtml:
55
	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
56
	@echo
57
	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
58

  
59
pickle:
60
	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
61
	@echo
62
	@echo "Build finished; now you can process the pickle files."
63

  
64
json:
65
	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
66
	@echo
67
	@echo "Build finished; now you can process the JSON files."
68

  
69
htmlhelp:
70
	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
71
	@echo
72
	@echo "Build finished; now you can run HTML Help Workshop with the" \
73
	      ".hhp project file in $(BUILDDIR)/htmlhelp."
74

  
75
qthelp:
76
	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
77
	@echo
78
	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
79
	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
80
	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/synnefo.qhcp"
81
	@echo "To view the help file:"
82
	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/synnefo.qhc"
83

  
84
devhelp:
85
	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
86
	@echo
87
	@echo "Build finished."
88
	@echo "To view the help file:"
89
	@echo "# mkdir -p $$HOME/.local/share/devhelp/synnefo"
90
	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/synnefo"
91
	@echo "# devhelp"
92

  
93
epub:
94
	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
95
	@echo
96
	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
97

  
98
latex:
99
	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
100
	@echo
101
	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
102
	@echo "Run \`make' in that directory to run these through (pdf)latex" \
103
	      "(use \`make latexpdf' here to do that automatically)."
104

  
105
latexpdf:
106
	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
107
	@echo "Running LaTeX files through pdflatex..."
108
	$(MAKE) -C $(BUILDDIR)/latex all-pdf
109
	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
110

  
111
text:
112
	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
113
	@echo
114
	@echo "Build finished. The text files are in $(BUILDDIR)/text."
115

  
116
man:
117
	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
118
	@echo
119
	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
120

  
121
texinfo:
122
	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
123
	@echo
124
	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
125
	@echo "Run \`make' in that directory to run these through makeinfo" \
126
	      "(use \`make info' here to do that automatically)."
127

  
128
info:
129
	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
130
	@echo "Running Texinfo files through makeinfo..."
131
	make -C $(BUILDDIR)/texinfo info
132
	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
133

  
134
gettext:
135
	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
136
	@echo
137
	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
138

  
139
changes:
140
	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
141
	@echo
142
	@echo "The overview file is in $(BUILDDIR)/changes."
143

  
144
linkcheck:
145
	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
146
	@echo
147
	@echo "Link check complete; look for any errors in the above output " \
148
	      "or in $(BUILDDIR)/linkcheck/output.txt."
149

  
150
doctest:
151
	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
152
	@echo "Testing of doctests in the sources finished, look at the " \
153
	      "results in $(BUILDDIR)/doctest/output.txt."
b/snf-astakos-client/docs/conf.py
1
import sys
2
import os
3

  
4
sys.path.insert(0, os.path.abspath('..'))
5
from astakosclient.version import __version__
6

  
7
project = u'nnefo'
8
copyright = u'2012-2013, GRNET'
9
version = __version__
10
release = __version__
11
html_title = 'synnefo ' + version
12

  
13
templates_path = ['_templates']
14
source_suffix = '.rst'
15
master_doc = 'index'
16
exclude_patterns = ['_build']
17
pygments_style = 'sphinx'
18
html_theme = 'default'
19
html_theme_options = {
20
    'collapsiblesidebar': 'true',
21
    'footerbgcolor':    '#55b577',
22
    'footertextcolor':  '#000000',
23
    'sidebarbgcolor':   '#ffffff',
24
    'sidebarbtncolor':  '#f2f2f2',
25
    'sidebartextcolor': '#000000',
26
    'sidebarlinkcolor': '#328e4a',
27
    'relbarbgcolor':    '#55b577',
28
    'relbartextcolor':  '#ffffff',
29
    'relbarlinkcolor':  '#ffffff',
30
    'bgcolor':          '#ffffff',
31
    'textcolor':        '#000000',
32
    'headbgcolor':      '#ffffff',
33
    'headtextcolor':    '#000000',
34
    'headlinkcolor':    '#c60f0f',
35
    'linkcolor':        '#328e4a',
36
    'visitedlinkcolor': '#63409b',
37
    'codebgcolor':      '#eeffcc',
38
    'codetextcolor':    '#333333'
39
}
40

  
41
html_static_path = ['_static']
42
htmlhelp_basename = 'synnefodoc'
43

  
44
intersphinx_mapping = {
45
    'pithon': ('http://docs.python.org/', None),
46
    'django': ('https://docs.djangoproject.com/en/dev/',
47
               'https://docs.djangoproject.com/en/dev/_objects/')
48
}
49

  
50
SYNNEFO_DOCS_BASE_URL = 'http://docs.dev.grnet.gr/'
51
SYNNEFO_PROJECTS = {
52
    'synnefo': 'dev',
53
    'pithos': 'dev',
54
    'snf-webproject': 'dev',
55
    'snf-common': 'dev',
56
    'snf-image': 'dev',
57
    'snf-cyclades-app': 'dev'
58
}
59

  
60
for name, ver in SYNNEFO_PROJECTS.iteritems():
61
    intersphinx_mapping[name.replace("-", "")] = (SYNNEFO_DOCS_BASE_URL +
62
                                                  '%s/%s/' % (name, ver),
63
                                                  None)
64

  
65
extensions = ['sphinx.ext.autodoc',
66
              'sphinx.ext.intersphinx',
67
              'sphinx.ext.todo',
68
              'sphinx.ext.viewcode']
b/snf-astakos-client/docs/index.rst
1
.. _snf-astakos-client:
2

  
3
Component snf-astakos-client
4
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5

  
6
synnefo component :ref:`snf-common <snf-common>` defines a default client
7
for the :ref:`astakos <astakos>` service. It is designed to be minimal,
8
hence easily debugged and unit tested.
9

  
10
It uses the user's authentication token to query astakos for:
11
    * User's info
12
    * Usernames of given uuids
13
    * Uuids of given usernames
14

  
15
It can also query astakos with a service's auth token for:
16
    * Usernames of given uuids
17
    * Uuids of given usernames
18

  
19
Additionally there are options for using the objpool library to
20
pool the http connections.
21

  
22

  
23
Basic example
24
=============
25

  
26
The astakosclient module provides the AstakosClient class. This section
27
demonstrates how to get user's info using astakosclient.
28

  
29
.. code-block:: python
30

  
31
    from astakosclient import AstakosClient
32

  
33
    client = AstakosClient("https://accounts.example.com")
34
    user_info = client.authenticate("UQpYas7ElzWGD5yCcEXtjw==")
35
    print user_info['username']
36

  
37
Another example where we ask for the uuid of user user1@example.com
38

  
39
.. code-block:: python
40

  
41
    from astakosclient import AstakosClient
42

  
43
    client = AstakosClient("https://accounts.example.com")
44
    username = client.getDisplayName("UQpYas7ElzWGD5yCcEXtjw==",
45
                                     "b3de8eb0-3958-477e-als9-789af8dd352c")
46
    print username
47

  
48

  
49
Classes and functions
50
=====================
51

  
52
This section describes in depth the API of astakosclient.
53

  
54
Astakos Client
55
--------------
56

  
57
*class* astakosclient.\ **AstakosClient(**\ astakos_url,
58
retry=0, use_pool=False, pool_size=8, logger=None\ **)**
59

  
60
    Initialize an instance of **AstakosClient** given the *astakos_url*.
61
    Optionally one can specify if we are going to use a pool, the pool_size
62
    and the number of retries if the connection fails.
63

  
64
    This class provides the following methods:
65

  
66
    **authenticate(**\ token, usage=False\ **)**
67
        Given a valid authentication token it returns a dict with the
68
        correspoinding user's info. If usage is set to True more
69
        information about user's resources will be returned.
70
        In case of error raise an AstakosClientException exception.
71

  
72
    **getDisplayNames(**\ token, uuids\ **)**
73
        Given a valid authentication token and a list of uuids
74
        return a uuid_catalog, that is a dictionary with the given
75
        uuids as keys and the corresponding user names as values.
76
        Invalid uuids will not be in the dictionary.
77
        In case of error raise an AstakosClientException exception.
78

  
79
    **getDisplayName(**\ token, uuid\ **)**
80
        Given a valid authentication token and a uuid (as string)
81
        return the corresponding user name (as string).
82
        In case of invalid uuid raise NoDisplayName exception.
83
        In case of error raise an AstakosClientException exception.
84

  
85
    **getServiceDisplayNames(**\ token, uuids\ **)**
86
        Same as getDisplayNames but called with a service's token.
87

  
88
    **getServiceDisplayName(**\ token, uuid\ **)**
89
        Same as getDisplayName but called with a service's token.
90

  
91
    **getUUIDs(**\ token, display_names\ **)**
92
        Given a valid authentication token and a list of usernames
93
        return a displayname_catalog, that is a dictionary with the given
94
        usernames as keys and the corresponding uuids as values.
95
        Invalid usernames will not be in the dictionary.
96
        In case of error raise an AstakosClientException exception.
97

  
98
    **getUUID(**\ token, display_name\ **)**
99
        Given a valid authentication token and a username (as string)
100
        return the corresponding uuid (as string).
101
        In case of invalid user name raise NoUUID exception.
102
        In case of error raise an AstakosClientException exception.
103

  
104
    **getServiceUUIDs(**\ token, uuids\ **)**
105
        Same as getUUIDs but called with a service's token.
106

  
107
    **getServiceUUID(**\ token, uuid\ **)**
108
        Same as getUUID but called with a service's token.
109

  
110
    **getServices()**
111
        Return a list of dicts with the registered services.
112

  
113

  
114
Public Functions
115
----------------
116

  
117
**getTokenFromCookie(**\ request, cookie_name\ **)**
118
    Given a django request object and astako's cookie name
119
    extract user's token from it.
120

  
121

  
122
Exceptions and Errors
123
=====================
124

  
125
*exception* **AstakosClientException**
126
    Raised in case of an error. It contains an error message and the
127
    corresponding http status code. Other exceptions raise by astakosclient
128
    module are derived from this one.
129

  
130
*exception* **BadRequest**
131
    Raised in case of a Bad Request, with status 400.
132

  
133
*exception* **Unauthorized**
134
    Raised in case of Invalid token (unauthorized access), with status 401.
135

  
136
*exception* **Forbidden**
137
    The server understood the request, but is refusing to fulfill it.
138
    Status 401.
139

  
140
*exception* **NotFound**
141
    The server has not found anything matching the Request-URI. Status 404.
142

  
143
*exception* **NoDisplayName**
144
    Raised by getDisplayName and getServiceDisplayName when an invalid
145
    uuid was given.
146

  
147
*exception* **NoUUID**
148
    Raised by *getUUID* and *getServiceUUID* when an invalid
149
    username was given.

Also available in: Unified diff