Skip to content

GitLab

Commit 4067cdaf authored by Stavros Sachtouris's avatar Stavros Sachtouris
Browse files

Fix sphinx auto-doc syntax warning

parent b8e90894
Hide whitespace changes
Inline Side-by-side
docs/installation.rst
View file @ 4067cdaf
......@@ -12,7 +12,7 @@ Installing from source (git repos.)
Ubuntu and Debian packages
^^^^^^^^^^^^^^^^^^^^^^^^^^
Max OS
Mac OS
------
Windows
......
docs/man/kamaki.rst
View file @ 4067cdaf
......@@ -60,10 +60,12 @@ store
Options
-------
--help, -h Show help message and exit.
-v Use verbose output.
-d Use debug output.
-o KEY=VAL Override a config value (can be used multiple times)
.. code-block:: console
--help, -h Show help message and exit.
-v Use verbose output.
-d Use debug output.
-o KEY=VAL Override a config value (can be used multiple times)
Commands
......
docs/overview.rst
View file @ 4067cdaf
......@@ -4,7 +4,7 @@ Overview
History
-------
Here, at the *Greek Research and Technology Network*, we have been developing an IaaS cloud management software called **synnefo** (or **+nefo**) that is accessed and managed via an extended OpenStack Compute API v1.1. Synnefo has been deployed in many environments to cover multiple needs. For example, the `~okeanos `_ IaaS service, running in our datacenters, is used to offer services for the Greek Research and Academic Community.
Here, at the *Greek Research and Technology Network*, we have been developing an IaaS cloud management software called **synnefo** (or **+nefo**) that is accessed and managed via an extended OpenStack Compute API v1.1. Synnefo has been deployed in many environments to cover multiple needs. For example, the `~okeanos <http://okeanos.grnet.gr>`_ IaaS service, running in our datacenters, is used to offer services for the Greek Research and Academic Community.
From the early start, we needed a simple command-line tool to test the OpenStack API. That's why we developed *kamaki*, which proved to be powerful and intuitive enough, to be used not only for testing purposes but also as a complete Openstack Compute API v1.1 client, able to manage our cloud from the command line.
......
docs/usage.rst
View file @ 4067cdaf
......@@ -107,7 +107,7 @@ Typically, commands consist of a group name (e.g. store for storage commands) on
$ kamaki store list mycontainer
Example 3.1.1: List stored files in container mycontainer
Example 3.1.1: List stored files in container mycontainer.
Example 2.3.2 showcases a command without parameters (the group is "server", the command is "list").
......@@ -118,7 +118,7 @@ The "server" command group is also refered in the following example.
$ kamaki server info 42
Example 3.1.2: Show information about a user-managed VM with id 42
Example 3.1.2 Show information about a user-managed VM with id 42
Client commands can feature an arbitarry number of terms:
......@@ -134,7 +134,7 @@ The following pattern applies to all client commands up to version 0.6.1:
kamaki <group> <command> [arguments]
The commands supported in version 0.6.1 are described bellow, grouped by service. The examples showcase a sample set of group commands and were run in the kamaki interactive shell:
The commands supported in version 0.6.1 are described bellow, grouped by service. The examples showcase a sample set of group commands. The kamaki interactive shell has been chosen as the execution enviroment:
astakos (Identity Manager)
""""""""""""""""""""""""""
......@@ -146,7 +146,7 @@ astakos (Identity Manager)
Showcase: get user information, provided the token was set
.. code-block:: console
:emphasize-lines: 1, 2, 12
:emphasize-lines: 3-11
[kamaki]:astakos
[astakos]:authenticate
......@@ -172,7 +172,7 @@ flavor (Compute/Cyclades)
Showcase: show details for flavor with id 43
.. code-block:: console
:emphasize-lines: 1, 2, 9
:emphasize-lines: 3-8
[kamaki]: flavor
[flavor]: info 43
......@@ -208,7 +208,7 @@ image (Compute/Cyclades + Glance)
Showcase: show a list of public images, list the properties of Debian Base
.. code-block:: console
:emphasize-lines: 1, 2, 14, 23
:emphasize-lines: 3-13,15-22
[kamaki]:image
[image]:list
......@@ -260,7 +260,7 @@ server (Compute/Cyclades)
Showcase: Create a server: Show create help, find a flavor and an image make a server. Wait for server to be build, get server details. Note that the progress bar feature is optional (see )
.. code-block:: console
:emphasize-lines: 1, 2, 17, 34, 41, 57, 60, 67
:emphasize-lines: 3-16,18-33,35-40,42-56,58,59,61-66
[kamaki]:server
[server]:create -h
......@@ -279,22 +279,17 @@ Showcase: Create a server: Show create help, find a flavor and an image make a s
--config CONFIG Path to configuration file
-s, --silent Do not output anything
[server]:/image list
1395fdfb-51b4-419f-bb02-f7d632860611 (Ubuntu Desktop LTS (Long Term Support))
1395fdfb-51b4-419f-bb02-f7d632860611 (Ubuntu Desktop LTS)
1580deb4-edb3-4496-a27f-7a246c4c0528 (Ubuntu Desktop)
18a82962-43eb-4b32-8e28-8f8880af89d7 (Kubuntu LTS (Long Term Support))
6aa6eafd-dccb-422d-a904-67fe2bdde87e (Debian Desktop)
6b5681e4-7502-46ae-b1e9-9fd837932095 (maelstrom)
78262ee7-949e-4d70-af3a-85360c3de57a (Windows Server 2012)
86bc2414-0fb3-4898-a637-240292243302 (Fedora)
926ab1c5-2d85-49d4-aebe-0fce712789b9 (Windows Server 2008)
b2dffe52-64a4-48c3-8a4c-8214cc3165cf (Debian Base)
baf2321c-57a0-4a69-825d-49f49cea163a (CentOS)
c1d27b46-d875-4f5c-b7f1-f39b5af62905 (Kubuntu)
|18a82962-43eb-4b32-8e28-8f8880af89d7 (Kubuntu LTS)
|6aa6eafd-dccb-422d-a904-67fe2bdde87e (Debian Desktop)
|6b5681e4-7502-46ae-b1e9-9fd837932095 (maelstrom)
|78262ee7-949e-4d70-af3a-85360c3de57a (Windows Server 2012)
|86bc2414-0fb3-4898-a637-240292243302 (Fedora)
|926ab1c5-2d85-49d4-aebe-0fce712789b9 (Windows Server 2008)
|b2dffe52-64a4-48c3-8a4c-8214cc3165cf (Debian Base)
|baf2321c-57a0-4a69-825d-49f49cea163a (CentOS)
|c1d27b46-d875-4f5c-b7f1-f39b5af62905 (Kubuntu)
[server]:/flavor info 1
SNF:disk_template: drbd
cpu : 1
......
kamaki/clients/pithos.py
View file @ 4067cdaf
......@@ -670,17 +670,15 @@ class PithosClient(PithosRestAPI):
read_permition=False,
write_permition=False):
"""Give read/write permisions to an object.
@param object is the object to change sharing permissions
onto
@param read_permition is a list of users and user groups that
get read permition for this object
False means all previous read permissions
will be removed
@param write_perimition is a list of users and user groups to
get write permition for this object
False means all previous read permissions
will be removed
@param object is the object to change sharing permissions onto
@param read_permition is a list of users and user groups that get
read permition for this object False means all previous read
permissions will be removed
@param write_perimition is a list of users and user groups to get
write permition for this object False means all previous read
permissions will be removed
"""
perms = dict(read='' if not read_permition else read_permition,
write='' if not write_permition else write_permition)
r = self.object_post(object, update=True, permissions=perms)
......@@ -694,6 +692,7 @@ class PithosClient(PithosRestAPI):
to caller application, e.g. a progress bar. Its next is called
whenever a block is uploaded
"""
self.assert_container()
meta = self.get_container_info()
blocksize = int(meta['x-container-block-size'])
......@@ -732,10 +731,11 @@ class PithosClient(PithosRestAPI):
source_file,
upload_cb=None):
"""Overwrite a part of an object with given source file
@start the part of the remote object to start overwriting from,
in bytes
@start the part of the remote object to start overwriting from, in
bytes
@end the part of the remote object to stop overwriting to, in bytes
"""
self.assert_container()
meta = self.get_container_info()
blocksize = int(meta['x-container-block-size'])
......
kamaki/clients/pithos_rest_api.py
View file @ 4067cdaf
......@@ -48,10 +48,11 @@ class PithosRestAPI(StorageClient):
@param until (string): optional timestamp
--- --- optional request headers ---
@param if_modified_since (string): Retrieve if account has changed
since provided timestamp
since provided timestamp
@param if_unmodified_since (string): Retrieve if account has not
change since provided timestamp
change since provided timestamp
"""
self.assert_account()
path = path4url(self.account)
......@@ -75,20 +76,21 @@ class PithosRestAPI(StorageClient):
""" Full Pithos+ GET at account level
--- request parameters ---
@param limit (integer): The amount of results requested
(server will use default value if None)
(server will use default value if None)
@param marker (string): Return containers with name
lexicographically after marker
lexicographically after marker
@param format (string): reply format can be json or xml
(default: json)
(default: json)
@param shared (bool): If true, only shared containers will be
included in results
included in results
@param until (string): optional timestamp
--- --- optional request headers ---
@param if_modified_since (string): Retrieve if account has changed
since provided timestamp
since provided timestamp
@param if_unmodified_since (string): Retrieve if account has not
changed since provided timestamp
changed since provided timestamp
"""
self.assert_account()
self.set_param('format', format, iff=format is not None)
......@@ -117,17 +119,15 @@ class PithosRestAPI(StorageClient):
@param update (bool): if True, Do not replace metadata/groups
--- request headers ---
@groups (dict): Optional user defined groups in the form
{ 'group1':['user1', 'user2', ...],
'group2':['userA', 'userB', ...], ...
}
{ 'group1':['user1', 'user2', ...],
'group2':['userA', 'userB', ...], }
@metadata (dict): Optional user defined metadata in the form
{ 'name1': 'value1',
'name2': 'value2', ...
}
{ 'name1': 'value1', 'name2': 'value2', ... }
@param quota(integer): If supported, sets the Account quota
@param versioning(string): If supported, sets the Account versioning
to 'auto' or some other supported versioning string
to 'auto' or some other supported versioning string
"""
self.assert_account()
self.set_param('update', iff=update)
......@@ -156,10 +156,11 @@ class PithosRestAPI(StorageClient):
@param until (string): optional timestamp
--- optional request headers ---
@param if_modified_since (string): Retrieve if account has changed
since provided timestamp
since provided timestamp
@param if_unmodified_since (string): Retrieve if account has not
changed since provided timestamp
changed since provided timestamp
"""
self.assert_container()
self.set_param('until', until, iff=until is not None)
......@@ -188,27 +189,28 @@ class PithosRestAPI(StorageClient):
""" Full Pithos+ GET at container level
--- request parameters ---
@param limit (integer): The amount of results requested
(server qill use default value if None)
(server qill use default value if None)
@param marker (string): Return containers with name lexicographically
after marker
after marker
@param prefix (string): Return objects starting with prefix
@param delimiter (string): Return objects up to the delimiter
@param path (string): assume prefix = path and delimiter = /
(overwrites prefix and delimiter)
(overwrites prefix and delimiter)
@param format (string): reply format can be json or xml (default:json)
@param meta (list): Return objects that satisfy the key queries in
the specified comma separated list (use <key>, !<key> for
existence queries, <key><op><value> for value queries, where <op>
can be one of =, !=, <=, >=, <, >)
the specified comma separated list (use <key>, !<key> for
existence queries, <key><op><value> for value queries, where <op>
can be one of =, !=, <=, >=, <, >)
@param shared (bool): If true, only shared containers will be included
in results
@param until (string): optional timestamp
--- --- optional request headers ---
@param if_modified_since (string): Retrieve if account has changed
since provided timestamp
since provided timestamp
@param if_unmodified_since (string): Retrieve if account has not
changed since provided timestamp
changed since provided timestamp
"""
self.assert_container()
self.set_param('format', format, iff=format is not None)
......@@ -307,8 +309,9 @@ class PithosRestAPI(StorageClient):
""" Full Pithos+ DELETE at container level
--- request parameters ---
@param until (timestamp string): if defined, container is purged up to
that time
that time
"""
self.assert_container()
self.set_param('until', until, iff=until is not None)
......@@ -331,14 +334,15 @@ class PithosRestAPI(StorageClient):
@param version (string): optional version identified
--- request headers ---
@param if_etag_match (string): if provided, return only results
with etag matching with this
with etag matching with this
@param if_etag_not_match (string): if provided, return only results
with etag not matching with this
with etag not matching with this
@param if_modified_since (string): Retrieve if account has changed
since provided timestamp
since provided timestamp
@param if_unmodified_since (string): Retrieve if account has not
changed since provided timestamp
changed since provided timestamp
"""
self.assert_container()
self.set_param('version', version, iff=version is not None)
......@@ -373,14 +377,15 @@ class PithosRestAPI(StorageClient):
@param data_range (string): Optional range of data to retrieve
@param if_range (bool):
@param if_etag_match (string): if provided, return only results
with etag matching with this
with etag matching with this
@param if_etag_not_match (string): if provided, return only results
with etag not matching with this
with etag not matching with this
@param if_modified_since (string): Retrieve if account has changed
since provided timestamp
since provided timestamp
@param if_unmodified_since (string): Retrieve if account has not
changed since provided timestamp
changed since provided timestamp
"""
self.assert_container()
self.set_param('format', format, iff=format is not None)
......@@ -427,35 +432,35 @@ class PithosRestAPI(StorageClient):
@param hashmap (bool): Optional hashmap provided instead of data
--- request headers ---
@param if_etag_match (string): if provided, return only results
with etag matching with this
with etag matching with this
@param if_etag_not_match (string): if provided, return only results
with etag not matching with this
with etag not matching with this
@param etag (string): The MD5 hash of the object (optional to check
written data)
written data)
@param content_length (integer): The size of the data written
@param content_type (string): The MIME content type of the object
@param transfer_encoding (string): Set to chunked to specify
incremental uploading (if used, Content-Length is ignored)
incremental uploading (if used, Content-Length is ignored)
@param copy_from (string): The source path in the form
/<container>/<object>
/<container>/<object>
@param move_from (string): The source path in the form
/<container>/<object>
/<container>/<object>
@param source_account (string): The source account to copy/move from
@param source_version (string): The source version to copy from
@param conent_encoding (string): The encoding of the object
@param content_disposition (string): Presentation style of the object
@param manifest (string): Object parts prefix in
/<container>/<object> form
/<container>/<object> form
@param permissions (dict): Object permissions in the form (all fields
are optional)
{ 'read':[user1, group1, user2, ...],
'write':['user3, group2, group3, ...]
}
are optional)
{ 'read':[user1, group1, user2, ...],
'write':['user3, group2, group3, ...] }
@param public (bool): If true, Object is publicly accessible,
if false, not
if false, not
@param metadata (dict): Optional user defined metadata in the form
{'meta-key-1':'meta-value-1', 'meta-key-2':'meta-value-2', ...}
{'meta-key-1':'meta-value-1', 'meta-key-2':'meta-value-2', ...}
"""
self.assert_container()
self.set_param('format', format, iff=format is not None)
......@@ -516,30 +521,29 @@ class PithosRestAPI(StorageClient):
@param format (string): json (default) or xml
@param ignore_content_type (bool): Ignore the supplied Content-Type
--- request headers ---
@param if_etag_match (string): if provided, copy only results
with etag matching with this
@param if_etag_match (string): if provided, copy only results
with etag matching with this
@param if_etag_not_match (string): if provided, copy only results
with etag not matching with this
with etag not matching with this
@param destination (string): The destination path in the form
/<container>/<object>
/<container>/<object>
@param destination_account (string): The destination account to copy to
@param content_type (string): The MIME content type of the object
@param content_encoding (string): The encoding of the object
@param content_disposition (string): Object resentation style
@param source_version (string): The source version to copy from
@param permissions (dict): Object permissions in the form
(all fields are optional)
{ 'read':[user1, group1, user2, ...],
'write':['user3, group2, group3, ...]
}
permissions override source permissions,
removing any old permissions
(all fields are optional)
{ 'read':[user1, group1, user2, ...],
'write':['user3, group2, group3, ...] }
@permissions override source permissions, removing any old permissions
@param public (bool): If true, Object is publicly accessible
@param metadata (dict): Optional user defined metadata in the form
{'meta-key-1':'meta-value-1', 'meta-key-2':'meta-value-2', ...}
Metadata are appended to the source metadata. In case of same
keys, they replace the old metadata
{'meta-key-1':'meta-value-1', 'meta-key-2':'meta-value-2', ...}
Metadata are appended to the source metadata. In case of same keys,
they replace the old metadata
"""
self.assert_container()
self.set_param('format', format, iff=format is not None)
......@@ -594,26 +598,26 @@ class PithosRestAPI(StorageClient):
@param format (string): json (default) or xml
@param ignore_content_type (bool): Ignore the supplied Content-Type
--- request headers ---
@param if_etag_match (string): if provided, return only results
with etag matching with this
@param if_etag_match (string): if provided, return only results
with etag matching with this
@param if_etag_not_match (string): if provided, return only results
with etag not matching with this
with etag not matching with this
@param destination (string): The destination path in the form
/<container>/<object>
/<container>/<object>
@param destination_account (string): The destination account to copy to
@param content_type (string): The MIME content type of the object
@param content_encoding (string): The encoding of the object
@param content_disposition (string): Object presentation style
@param source_version (string): The source version to copy from
@param permissions (dict): Object permissions in the form
(all fields are optional)
{ 'read':[user1, group1, user2, ...],
'write':['user3, group2, group3, ...]
}
(all fields are optional)
{ 'read':[user1, group1, user2, ...],
'write':['user3, group2, group3, ...] }
@param public (bool): If true, Object is publicly accessible
@param metadata (dict): Optional user defined metadata in the form
{'meta-key-1':'meta-value-1', 'meta-key-2':'meta-value-2', ...}
{'meta-key-1':'meta-value-1', 'meta-key-2':'meta-value-2', ...}
"""
self.assert_container()
self.set_param('format', format, iff=format is not None)
......@@ -672,31 +676,31 @@ class PithosRestAPI(StorageClient):
@param update (bool): Do not replace metadata
--- request headers ---
@param if_etag_match (string): if provided, return only results
with etag matching with this
with etag matching with this
@param if_etag_not_match (string): if provided, return only results
with etag not matching with this
with etag not matching with this
@param content_length (string): The size of the data written
@param content_type (string): The MIME content type of the object
@param content_range (string): The range of data supplied
@param transfer_encoding (string): Set to chunked to specify
incremental uploading (if used, Content-Length is ignored)
incremental uploading (if used, Content-Length is ignored)
@param content_encoding (string): The encoding of the object
@param content_disposition (string): Object presentation style
@param source_object (string): Update with data from the object at
path /<container>/<object>
path /<container>/<object>
@param source_account (string): The source account to update from
@param source_version (string): The source version to copy from
@param object_bytes (integer): The updated objects final size
@param manifest (string): Object parts prefix as /<container>/<object>
@param permissions (dict): Object permissions in the form (all fields
are optional)
{ 'read':[user1, group1, user2, ...],
'write':['user3, group2, group3, ...]
}
are optional)
{ 'read':[user1, group1, user2, ...],
'write':['user3, group2, group3, ...] }
@param public (bool): If true, Object is publicly accessible
@param metadata (dict): Optional user defined metadata in the form
{'meta-key-1':'meta-value-1', 'meta-key-2':'meta-value-2', ...}
{'meta-key-1':'meta-value-1', 'meta-key-2':'meta-value-2', ...}
"""
self.assert_container()
self.set_param('format', format, iff=format is not None)
......
kamaki/clients/utils.py
View file @ 4067cdaf
......@@ -34,6 +34,7 @@
def matches(val1, val2, exactMath=True):
"""Case Insenstive match"""
if exactMath:
return True if val1.lower() == val2.lower() else False
else:
......@@ -44,6 +45,7 @@ def filter_out(d, prefix, exactMatch=False):
"""@return a dict that contains the entries of d
that are NOT prefixed with prefic
"""
ret = {}
for key, val in d.items():
if not matches(key, prefix, exactMath=exactMatch):
......@@ -55,6 +57,7 @@ def filter_in(d, prefix, exactMatch=False):
"""@return a dict that contains only the entries of d
that are prefixed with prefix
"""
ret = {}
for key, val in d.items():
if matches(key, prefix, exactMath=exactMatch):
......@@ -65,6 +68,7 @@ def filter_in(d, prefix, exactMatch=False):
def prefix_keys(d, prefix):
"""@return a sallow copy of d with all its keys prefixed with prefix
"""
ret = {}
for key, val in d.items():
ret[prefix + key] = val
......@@ -75,6 +79,7 @@ def path4url(*args):
"""@return a string with all args in the form /arg1/arg2/...
@param args must be strings
"""
path = ''
for arg in args:
suffix = unicode(arg)
......@@ -92,14 +97,9 @@ def path4url(*args):
def params4url(params):
"""@return a string with all params in the form ?key1=val1&key2=val2&...
e.g. input
{'key1':'val1', 'key2':None, 'key3':'val3'}
will return
?key1=val1&key2&key3=val3
@param should be a dict.
Use params['somekey']=None for params that will apear without
a value at the final string
"""
assert(type(params) is dict)
result = ''
dlmtr = '?'
......@@ -112,6 +112,7 @@ def params4url(params):
def list2str(alist, seperator=','):
"""@return a string of comma seperated elements of the list"""
ret = ''
slist = sorted(alist)
for item in slist:
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment