diff options
author | Jenkins <jenkins@review.openstack.org> | 2016-08-24 23:59:34 +0000 |
---|---|---|
committer | Gerrit Code Review <review@openstack.org> | 2016-08-24 23:59:34 +0000 |
commit | b57044a85301ac5a5fbfb119968aee8d78b6b7bf (patch) | |
tree | ef15ce4525ce7d572cead919841053a18d02235a /doc | |
parent | b1539d9c0feaaf26783e7cab3962219e036994ba (diff) | |
parent | 4a2465fb12ff7287b62b6941fb8ae43e100adc25 (diff) | |
download | python-swiftclient-b57044a85301ac5a5fbfb119968aee8d78b6b7bf.tar.gz |
Merge "Add copy object method"
Diffstat (limited to 'doc')
-rw-r--r-- | doc/manpages/swift.1 | 13 | ||||
-rw-r--r-- | doc/source/cli.rst | 14 | ||||
-rw-r--r-- | doc/source/service-api.rst | 82 |
3 files changed, 105 insertions, 4 deletions
diff --git a/doc/manpages/swift.1 b/doc/manpages/swift.1 index efcb8e4..5d21c18 100644 --- a/doc/manpages/swift.1 +++ b/doc/manpages/swift.1 @@ -79,6 +79,19 @@ For more details and options see swift post \-\-help. \fBExample\fR: post \-m Color:Blue \-m Size:Large .RE +\fBcopy\fR [\fIcommand-options\fR] \fIcontainer\fR \fIobject\fR +.RS 4 +Copies an object to a new destination or adds user metadata to the object (current +user metadata will be preserved, in contrast with the post command) depending +on the args given. The \-\-destination option sets the destination in the form +/container/object. If not set, the object will be copied onto itself which is useful +for adding metadata. The \-M or \-\-fresh\-metadata option copies the object without +the existing user metadata. The \-m or \-\-meta option is always allowed and is used +to define the user metadata items to set in the form Name:Value (this option +can be repeated). +For more details and options see swift copy \-\-help. +.RE + \fBdownload\fR [\fIcommand-options\fR] [\fIcontainer\fR] [\fIobject\fR] [\fIobject\fR] [...] .RS 4 Downloads everything in the account (with \-\-all), or everything in a diff --git a/doc/source/cli.rst b/doc/source/cli.rst index bbbfa3d..9bb229d 100644 --- a/doc/source/cli.rst +++ b/doc/source/cli.rst @@ -200,6 +200,20 @@ Delete of manifest objects will be deleted as well, unless you specify the ``--leave-segments`` option. +Copy +---- + + ``copy [command-options] container object`` + + Copies an object to a new destination or adds user metadata to an object. Depending + on the options supplied, you can preserve existing metadata in contrast to the post + command. The ``--destination`` option sets the copy target destination in the form + ``/container/object``. If not set, the object will be copied onto itself which is useful + for adding metadata. You can use the ``-M`` or ``--fresh-metadata`` option to copy + an object without existing user meta data, and the ``-m`` or ``--meta`` option + to define user meta data items to set in the form ``Name:Value``. You can repeat + this option. For example: ``copy -m Color:Blue -m Size:Large``. + Capabilities ------------ diff --git a/doc/source/service-api.rst b/doc/source/service-api.rst index 6610743..ea530b0 100644 --- a/doc/source/service-api.rst +++ b/doc/source/service-api.rst @@ -220,6 +220,17 @@ Options are downloaded in lexically-sorted order. Setting this option to ``True`` gives the same shuffling behaviour as the CLI. + ``destination``: ``None`` + When copying objects, this specifies the destination where the object + will be copied to. The default of None means copy will be the same as + source. + + ``fresh_metadata``: ``None`` + When copying objects, this specifies that the object metadata on the + source will *not* be applied to the destination object - the + destination object will have a new fresh set of metadata that includes + *only* the metadata specified in the meta option if any at all. + Other available options can be found in ``swiftclient/service.py`` in the source code for ``python-swiftclient``. Each ``SwiftService`` method also allows for an optional dictionary to override those specified at init time, and the @@ -738,13 +749,76 @@ Example The code below demonstrates the use of ``delete`` to remove a given list of objects from a specified container. As the objects are deleted the transaction -id of the relevant request is printed along with the object name and number -of attempts required. By printing the transaction id, the printed operations +ID of the relevant request is printed along with the object name and number +of attempts required. By printing the transaction ID, the printed operations can be easily linked to events in the swift server logs: .. literalinclude:: ../../examples/delete.py :language: python +Copy +~~~~ + +Copy can be called to copy an object or update the metadata on the given items. + +Each element of the object list may be a plain string of the object name, or a +``SwiftCopyObject`` that allows finer control over the options applied to each +of the individual copy operations (destination, fresh_metadata, options). + +Destination should be in format /container/object; if not set, the object will be +copied onto itself. Fresh_metadata sets mode of operation on metadata. If not set, +current object user metadata will be copied/preserved; if set, all current user +metadata will be removed. + +Returns an iterator over the results generated for each object copy (and may +also include the results of creating destination containers). + +When a string is given for the object name, destination and fresh metadata will +default to None and None, which result in adding metadata to existing objects. + +Successful copy results are dictionaries as described below: + +.. code-block:: python + + { + 'action': 'copy_object', + 'success': True, + 'container': <container>, + 'object': <object>, + 'destination': <destination>, + 'headers': {}, + 'fresh_metadata': <boolean>, + 'response_dict': <HTTP response details> + } + +Any failure in a copy operation will return a failure dictionary as described +below: + +.. code-block:: python + + { + 'action': 'copy_object', + 'success': False, + 'container': <container>, + 'object': <object>, + 'destination': <destination>, + 'headers': {}, + 'fresh_metadata': <boolean>, + 'response_dict': <HTTP response details>, + 'error': <error>, + 'traceback': <traceback>, + 'error_timestamp': <timestamp> + } + +Example +------- + +The code below demonstrates the use of ``copy`` to add new user metadata for +objects a and b, and to copy object c to d (with added metadata). + +.. literalinclude:: ../../examples/copy.py + :language: python + Capabilities ~~~~~~~~~~~~ @@ -767,7 +841,7 @@ returned with the contents described below: } The contents of the capabilities dictionary contain the core swift capabilities -under the key ``swift``, all other keys show the configuration options for +under the key ``swift``; all other keys show the configuration options for additional middlewares deployed in the proxy pipeline. An example capabilities dictionary is given below: @@ -822,7 +896,7 @@ Example ^^^^^^^ The code below demonstrates the use of ``capabilities`` to determine if the -Swift cluster supports static large objects, and if so, the maximum number of +Swift cluster supports static large objects, and if so, the maximum number of segments that can be described in a single manifest file, along with the size restrictions on those objects: |