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
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
:param name: object name to put; if None, the object name is expected to be
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;
if None, a zero-byte put will be done
: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:
file - A file like object (with a read method)
path - A string containing the path to a local file
or directory
None - Indicates that we want an empty object
* A file-like object (with a read method)
* A string containing the path to a local
file or directory
* None, to indicate that we want an empty object
:param options: A dictionary containing options to override the global
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.
: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
be valid for.
:param key: The secret temporary URL key set on the Swift cluster.
To set a key, run 'swift post -m
"Temp-URL-Key:b3968d0207b54ece87cccc06515a89d4"'
:param method: A HTTP method, typically either GET or PUT, to allow for
this temporary URL.
be valid for.
:param key: The secret temporary URL key set on the Swift
cluster. To set a key, run 'swift post -m
"Temp-URL-Key: <substitute tempurl key here>"'
:param method: A HTTP method, typically either GET or PUT, to allow
for this temporary URL.
:raises: ValueError if seconds is not a positive integer
:raises: TypeError if seconds is not an integer
:return: the path portion of a temporary URL
@ -152,7 +152,7 @@ class ReadableToIterable(object):
Wrap a filelike object and act as an iterator.
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
hit the exception on every call to next. This could cause problems,
especially with large files and small chunk sizes.
@ -200,7 +200,7 @@ class LengthWrapper(object):
"""
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.
"""
def __init__(self, readable, length, md5=False):