openstack
/
openstacksdk
Code Issues Proposed changes

cloud: Update docstrings for object store functions 

Change-Id: I4c4193c94852ed790c2a90b1202cc1519d39df21
Signed-off-by: Stephen Finucane <stephenfin@redhat.com>
This commit is contained in:
Stephen Finucane 2022-05-26 12:28:46 +01:00
parent 6fd5f99dc6
commit a3b6dcdf4f
2 changed files with 105 additions and 92 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

196
openstack/cloud/_object_store.py
View File

@ -44,13 +44,14 @@ class ObjectStoreCloudMixin:
self._raw_clients['object-store'] = raw_client
return self._raw_clients['object-store']
# TODO(stephenfin): Remove 'full_listing' as it's a noop
def list_containers(self, full_listing=True, prefix=None):
"""List containers.
:param full_listing: Ignored. Present for backwards compat
:returns: list of Munch of the container objects
:param prefix: Only objects with this prefix will be returned.
(optional)
:returns: A list of object store ``Container`` objects.
:raises: OpenStackCloudException on operation error.
"""
return list(self.object_store.containers(prefix=prefix))
@ -58,15 +59,15 @@ class ObjectStoreCloudMixin:
def search_containers(self, name=None, filters=None):
"""Search containers.
:param string name: container name.
:param filters: a dict containing additional filters to use.
:param string name: Container name.
:param filters: A dict containing additional filters to use.
OR
A string containing a jmespath expression for further filtering.
Example:: "[?last_name==`Smith`] | [?other.gender]==`Female`]"
:returns: a list of ``munch.Munch`` containing the containers.
:raises: ``OpenStackCloudException``: if something goes wrong during
:returns: A list of object store ``Container`` objects matching the
search criteria.
:raises: ``OpenStackCloudException``: If something goes wrong during
the OpenStack API call.
"""
containers = self.list_containers()
@ -78,8 +79,9 @@ class ObjectStoreCloudMixin:
:param str name:
Name of the container to get metadata for.
:param bool skip_cache:
Ignore the cache of container metadata for this container.o
Ignore the cache of container metadata for this container.
Defaults to ``False``.
:returns: An object store ``Container`` object if found, else None.
"""
if skip_cache or name not in self._container_cache:
try:
@ -94,10 +96,10 @@ class ObjectStoreCloudMixin:
def create_container(self, name, public=False):
"""Create an object-store container.
:param str name:
Name of the container to create.
:param bool public:
Whether to set this container to be public. Defaults to ``False``.
:param str name: Name of the container to create.
:param bool public: Whether to set this container to be public.
Defaults to ``False``.
:returns: The created object store ``Container`` object.
"""
container = self.get_container(name)
if container:
@ -131,17 +133,8 @@ class ObjectStoreCloudMixin:
def update_container(self, name, headers):
"""Update the metadata in a container.
:param str name:
Name of the container to create.
:param dict headers:
Key/Value headers to set on the container.
"""
"""Update the metadata in a container.
:param str name:
Name of the container to update.
:param dict headers:
Key/Value headers to set on the container.
:param str name: Name of the container to update.
:param dict headers: Key/Value headers to set on the container.
"""
self.object_store.set_container_metadata(
name, refresh=False, **headers)
@ -149,12 +142,10 @@ class ObjectStoreCloudMixin:
def set_container_access(self, name, access, refresh=False):
"""Set the access control list on a container.
:param str name:
Name of the container.
:param str access:
ACL string to set on the container. Can also be ``public``
or ``private`` which will be translated into appropriate ACL
strings.
:param str name: Name of the container.
:param str access: ACL string to set on the container. Can also be
``public`` or ``private`` which will be translated into appropriate
ACL strings.
:param refresh: Flag to trigger refresh of the container properties
"""
if access not in OBJECT_CONTAINER_ACLS:
@ -171,6 +162,10 @@ class ObjectStoreCloudMixin:
"""Get the control list from a container.
:param str name: Name of the container.
:returns: The contol list for the container.
:raises: :class:`~openstack.exceptions.OpenStackCloudException` if the
container was not found or container access could not be
determined.
"""
container = self.get_container(name, skip_cache=True)
if not container:
@ -191,11 +186,17 @@ class ObjectStoreCloudMixin:
The object-storage service publishes a set of capabilities that
include metadata about maximum values and thresholds.
:returns: An object store ``Info`` object.
"""
return self.object_store.get_info()
def get_object_segment_size(self, segment_size):
"""Get a segment size that will work given capabilities"""
"""Get a segment size that will work given capabilities.
:param segment_size:
:returns: A segment size.
"""
return self.object_store.get_object_segment_size(segment_size)
def is_object_stale(
@ -205,12 +206,10 @@ class ObjectStoreCloudMixin:
:param container: Name of the container.
:param name: Name of the object.
:param filename: Path to the file.
:param file_md5:
Pre-calculated md5 of the file contents. Defaults to None which
means calculate locally.
:param file_sha256:
Pre-calculated sha256 of the file contents. Defaults to None which
means calculate locally.
:param file_md5: Pre-calculated md5 of the file contents. Defaults to
None which means calculate locally.
:param file_sha256: Pre-calculated sha256 of the file contents.
Defaults to None which means calculate locally.
"""
return self.object_store.is_object_stale(
container, name, filename,
@ -236,6 +235,7 @@ class ObjectStoreCloudMixin:
:param name: Name for the directory marker object within the container.
:param headers: These will be passed through to the object creation
API as HTTP Headers.
:returns: The created object store ``Object`` object.
"""
headers['content-type'] = 'application/directory'
@ -247,11 +247,19 @@ class ObjectStoreCloudMixin:
**headers)
def create_object(
self, container, name, filename=None,
md5=None, sha256=None, segment_size=None,
use_slo=True, metadata=None,
generate_checksums=None, data=None,
**headers):
self,
container,
name,
filename=None,
md5=None,
sha256=None,
segment_size=None,
use_slo=True,
metadata=None,
generate_checksums=None,
data=None,
**headers,
):
"""Create a file object.
Automatically uses large-object segments if needed.
@ -282,7 +290,7 @@ class ObjectStoreCloudMixin:
uploads of identical data. (optional, defaults to True)
:param metadata: This dict will get changed into headers that set
metadata of the object
:returns: The created object store ``Object`` object.
:raises: ``OpenStackCloudException`` on operation error.
"""
return self.object_store.create_object(
@ -303,7 +311,7 @@ class ObjectStoreCloudMixin:
metadata of the object
:param headers: These will be passed through to the object update
API as HTTP Headers.
:returns: None
:raises: ``OpenStackCloudException`` on operation error.
"""
meta = metadata.copy() or {}
@ -316,12 +324,9 @@ class ObjectStoreCloudMixin:
:param container: Name of the container to list objects in.
:param full_listing: Ignored. Present for backwards compat
:param string prefix:
only objects with this prefix will be returned.
:param prefix: Only objects with this prefix will be returned.
(optional)
:returns: list of Munch of the objects
:returns: A list of object store ``Object`` objects.
:raises: OpenStackCloudException on operation error.
"""
return list(self.object_store.objects(
@ -332,15 +337,15 @@ class ObjectStoreCloudMixin:
def search_objects(self, container, name=None, filters=None):
"""Search objects.
:param string name: object name.
:param filters: a dict containing additional filters to use.
:param string name: Object name.
:param filters: A dict containing additional filters to use.
OR
A string containing a jmespath expression for further filtering.
Example:: "[?last_name==`Smith`] | [?other.gender]==`Female`]"
:returns: a list of ``munch.Munch`` containing the objects.
:raises: ``OpenStackCloudException``: if something goes wrong during
:returns: A list of object store ``Object`` objects matching the
search criteria.
:raises: ``OpenStackCloudException``: If something goes wrong during
the OpenStack API call.
"""
objects = self.list_objects(container)
@ -352,21 +357,23 @@ class ObjectStoreCloudMixin:
:param string container: Name of the container holding the object.
:param string name: Name of the object to delete.
:param dict meta: Metadata for the object in question. (optional, will
be fetched if not provided)
be fetched if not provided)
:returns: True if delete succeeded, False if the object was not found.
:raises: OpenStackCloudException on operation error.
"""
try:
self.object_store.delete_object(
name, ignore_missing=False, container=container)
name, ignore_missing=False, container=container,
)
return True
except exceptions.SDKException:
return False
def delete_autocreated_image_objects(self, container=None,
segment_prefix=None):
def delete_autocreated_image_objects(
self,
container=None,
segment_prefix=None,
):
"""Delete all objects autocreated for image uploads.
This method should generally not be needed, as shade should clean up
@ -379,12 +386,19 @@ class ObjectStoreCloudMixin:
:param str segment_prefix: Prefix for the image segment names to
delete. If not given, all image upload segments present are
deleted.
:returns: True if deletion was successful, else False.
"""
return self.object_store._delete_autocreated_image_objects(
container, segment_prefix=segment_prefix
)
def get_object_metadata(self, container, name):
"""Get object metadata.
:param container:
:param name:
:returns: The object metadata.
"""
return self.object_store.get_object_metadata(
name, container
).metadata
@ -392,13 +406,11 @@ class ObjectStoreCloudMixin:
def get_object_raw(self, container, obj, query_string=None, stream=False):
"""Get a raw response object for an object.
:param string container: name of the container.
:param string obj: name of the object.
:param string query_string:
query args for uri. (delimiter, prefix, etc.)
:param bool stream:
Whether to stream the response or not.
:param string container: Name of the container.
:param string obj: Name of the object.
:param string query_string: Query args for uri. (delimiter, prefix,
etc.)
:param bool stream: Whether to stream the response or not.
:returns: A `requests.Response`
:raises: OpenStackCloudException on operation error.
"""
@ -418,18 +430,22 @@ class ObjectStoreCloudMixin:
return endpoint
def stream_object(
self, container, obj, query_string=None, resp_chunk_size=1024):
self,
container,
obj,
query_string=None,
resp_chunk_size=1024,
):
"""Download the content via a streaming iterator.
:param string container: name of the container.
:param string obj: name of the object.
:param string query_string:
query args for uri. (delimiter, prefix, etc.)
:param int resp_chunk_size:
chunk size of data to read. Only used if the results are
:returns:
An iterator over the content or None if the object is not found.
:param string container: Name of the container.
:param string obj: Name of the object.
:param string query_string: Query args for uri. (delimiter, prefix,
etc.)
:param int resp_chunk_size: Chunk size of data to read. Only used if
the results are
:returns: An iterator over the content or None if the object is not
found.
:raises: OpenStackCloudException on operation error.
"""
try:
@ -443,22 +459,19 @@ class ObjectStoreCloudMixin:
resp_chunk_size=1024, outfile=None, stream=False):
"""Get the headers and body of an object
:param string container: name of the container.
:param string obj: name of the object.
:param string query_string:
query args for uri. (delimiter, prefix, etc.)
:param int resp_chunk_size:
chunk size of data to read. Only used if the results are
being written to a file or stream is True.
:param string container: Name of the container.
:param string obj: Name of the object.
:param string query_string: Query args for uri. (delimiter, prefix,
etc.)
:param int resp_chunk_size: Chunk size of data to read. Only used if
the results are being written to a file or stream is True.
(optional, defaults to 1k)
:param outfile:
Write the object to a file instead of returning the contents.
If this option is given, body in the return tuple will be None.
outfile can either be a file path given as a string, or a
:param outfile: Write the object to a file instead of returning the
contents. If this option is given, body in the return tuple will be
None. outfile can either be a file path given as a string, or a
File like object.
:returns: Tuple (headers, body) of the object, or None if the object
is not found (404).
is not found (404).
:raises: OpenStackCloudException on operation error.
"""
try:
@ -476,8 +489,7 @@ class ObjectStoreCloudMixin:
return None
def _wait_for_futures(self, futures, raise_on_error=True):
'''Collect results or failures from a list of running future tasks.'''
"""Collect results or failures from a list of running future tasks."""
results = []
retries = []

1
openstack/object_store/v1/_proxy.py
View File

@ -996,6 +996,7 @@ class Proxy(proxy.Proxy):
:param str segment_prefix: Prefix for the image segment names to
delete. If not given, all image upload segments present are
deleted.
:returns: True if deletion was succesful, else False.
"""
if container is None:
container = self._connection._OBJECT_AUTOCREATE_CONTAINER