openstack/python-swiftclient
Code Issues Proposed changes

enable autodocumentation for utils module; docstring fixes

Browse Source 
This commit adds the utils module to those for which Sphinx
automatically generates documentation from docstrings. (Many of the
functions here may be of little interest to users, but
`generate_temp_url`, at least, definitely deserves to be in the
documentation; in this way, this commit can be seen as a spiritual
companion to ca70dd9e.)

Also, a few markup errors and perceived infelicities in existing
docstrings are amended.

Change-Id: I8c66a23cb359d7dd9302a16459fad9825fedb690
This commit is contained in:
Zack M. Davis 2015-09-10 14:37:32 -07:00
parent a2c84e0c93
commit 6b3638ecec
4 changed files with 19 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
doc/source/swiftclient.rst
View File

@ -24,3 +24,8 @@ swiftclient.multithreading
========================== ==========================
.. automodule:: swiftclient.multithreading .. automodule:: swiftclient.multithreading
swiftclient.utils
=================
.. automodule:: swiftclient.utils

2
swiftclient/client.py
View File

@ -1011,7 +1011,7 @@ def put_object(url, token=None, container=None, name=None, contents=None,
container name is expected to be part of the url container name is expected to be part of the url
:param name: object name to put; if None, the object name is expected to be :param name: object name to put; if None, the object name is expected to be
part of the url part of the url
:param contents: a string, a file like object or an iterable :param contents: a string, a file-like object or an iterable
to read object data from; to read object data from;
if None, a zero-byte put will be done if None, a zero-byte put will be done
:param content_length: value to send as content-length header; also limits :param content_length: value to send as content-length header; also limits

8
swiftclient/service.py
View File

@ -1298,10 +1298,10 @@ class SwiftService(object):
The SwiftUploadObject source may be one of: The SwiftUploadObject source may be one of:
file - A file like object (with a read method) * A file-like object (with a read method)
path - A string containing the path to a local file * A string containing the path to a local
or directory file or directory
None - Indicates that we want an empty object * None, to indicate that we want an empty object
:param options: A dictionary containing options to override the global :param options: A dictionary containing options to override the global
options specified during the service object creation. options specified during the service object creation.

18
swiftclient/utils.py
View File

@ -70,14 +70,14 @@ def generate_temp_url(path, seconds, key, method, absolute=False):
Swift object. Swift object.
:param path: The full path to the Swift object. Example: :param path: The full path to the Swift object. Example:
/v1/AUTH_account/c/o. /v1/AUTH_account/c/o.
:param seconds: The amount of time in seconds the temporary URL will :param seconds: The amount of time in seconds the temporary URL will
be valid for. be valid for.
:param key: The secret temporary URL key set on the Swift cluster. :param key: The secret temporary URL key set on the Swift
To set a key, run 'swift post -m cluster. To set a key, run 'swift post -m
"Temp-URL-Key:b3968d0207b54ece87cccc06515a89d4"' "Temp-URL-Key: <substitute tempurl key here>"'
:param method: A HTTP method, typically either GET or PUT, to allow for :param method: A HTTP method, typically either GET or PUT, to allow
this temporary URL. for this temporary URL.
:raises: ValueError if seconds is not a positive integer :raises: ValueError if seconds is not a positive integer
:raises: TypeError if seconds is not an integer :raises: TypeError if seconds is not an integer
:return: the path portion of a temporary URL :return: the path portion of a temporary URL
@ -152,7 +152,7 @@ class ReadableToIterable(object):
Wrap a filelike object and act as an iterator. Wrap a filelike object and act as an iterator.
It is recommended to use this class only on files opened in binary mode. It is recommended to use this class only on files opened in binary mode.
Due to the Unicode changes in python 3 files are now opened using an Due to the Unicode changes in Python 3, files are now opened using an
encoding not suitable for use with the md5 class and because of this encoding not suitable for use with the md5 class and because of this
hit the exception on every call to next. This could cause problems, hit the exception on every call to next. This could cause problems,
especially with large files and small chunk sizes. especially with large files and small chunk sizes.
@ -200,7 +200,7 @@ class LengthWrapper(object):
""" """
Wrap a filelike object with a maximum length. Wrap a filelike object with a maximum length.
Fix for https://github.com/kennethreitz/requests/issues/1648 Fix for https://github.com/kennethreitz/requests/issues/1648.
It is recommended to use this class only on files opened in binary mode. It is recommended to use this class only on files opened in binary mode.
""" """
def __init__(self, readable, length, md5=False): def __init__(self, readable, length, md5=False):