diff options
Diffstat (limited to 'src/pybind/rados.py')
| -rw-r--r-- | src/pybind/rados.py | 391 |
1 files changed, 238 insertions, 153 deletions
diff --git a/src/pybind/rados.py b/src/pybind/rados.py index e543ff79305..360984f7319 100644 --- a/src/pybind/rados.py +++ b/src/pybind/rados.py @@ -172,7 +172,10 @@ class Rados(object): """librados python wrapper""" def require_state(self, *args): """ - Checks if the Rados object is in a special state + Checks if the ``Rados`` object is in a special state. + Typically used by other methods to ensure that the handle + is in a state such as "configuring," "connecting", + "connected", etc. before proceeding with method operations. :raises: RadosStateError """ @@ -236,7 +239,7 @@ Rados object in state %s." % (self.state)) def version(self): """ - Get the version number of the ``librados`` C library. + Gets the version number of the ``librados`` C library. :returns: a tuple of ``(major, minor, extra)`` components of the librados version @@ -250,7 +253,7 @@ Rados object in state %s." % (self.state)) def conf_read_file(self, path=None): """ - Configure the cluster handle using a Ceph config file. + Configures the cluster handle using a Ceph config file. :param path: path to the config file :type path: str @@ -265,8 +268,8 @@ Rados object in state %s." % (self.state)) def conf_parse_argv(self, args): """ - Parse known arguments from args, and remove; returned - args contain only those unknown to ceph + Parses known arguments from args, and removes; returned + args contain only those unknown to Ceph. """ self.require_state("configuring", "connected") if not args: @@ -288,12 +291,12 @@ Rados object in state %s." % (self.state)) def conf_get(self, option): """ - Get the value of a configuration option + Gets the value of a configuration option. - :param option: which option to read + :param option: The option to get. :type option: str - :returns: str - value of the option or None + :returns: str - The value of the option or None. :raises: :class:`TypeError` """ self.require_state("configuring", "connected") @@ -316,11 +319,11 @@ Rados object in state %s." % (self.state)) def conf_set(self, option, val): """ - Set the value of a configuration option + Sets the value of a configuration option. - :param option: which option to set + :param option: The option to set. :type option: str - :param option: value of the option + :param option: The value of the option. :type option: str :raises: :class:`TypeError`, :class:`ObjectNotFound` @@ -337,7 +340,7 @@ Rados object in state %s." % (self.state)) def connect(self, timeout=0): """ - Connect to the cluster. + Connects to the cluster. """ self.require_state("configuring") ret = run_in_thread(self.librados.rados_connect, (self.cluster,), @@ -348,21 +351,21 @@ Rados object in state %s." % (self.state)) def get_cluster_stats(self): """ - Read usage info about the cluster + Reads usage info about the cluster. - This tells you total space, space used, space available, and number - of objects. These are not updated immediately when data is written, - they are eventually consistent. + Cluster stats tell you total space, space used, space available, and + number of objects. Stats are not updated immediately when data is + written, but they are eventually consistent. - :returns: dict - contains the following keys: + :returns: dict - Contains the following keys: - *``kb`` (int) - total space + - ``kb`` (int) - Total space. - *``kb_used`` (int) - space used + - ``kb_used`` (int) - Space used. - *``kb_avail`` (int) - free space available + - ``kb_avail`` (int) - Free space available. - *``num_objects`` (int) - number of objects + - ``num_objects`` (int) - Number of objects. """ stats = rados_cluster_stat_t() @@ -380,11 +383,11 @@ Rados object in state %s." % (self.state)) """ Checks if a given pool exists. - :param pool_name: name of the pool to check + :param pool_name: The name of the pool to check. :type pool_name: str :raises: :class:`TypeError`, :class:`Error` - :returns: bool - whether the pool exists, false otherwise. + :returns: bool - True if the pool exists, false otherwise. """ self.require_state("connected") if not isinstance(pool_name, str): @@ -400,17 +403,17 @@ Rados object in state %s." % (self.state)) def create_pool(self, pool_name, auid=None, crush_rule=None): """ - Create a pool: - - with default settings: if auid=None and crush_rule=None - - owned by a specific auid: auid given and crush_rule=None - - with a specific CRUSH rule: if auid=None and crush_rule given - - with a specific CRUSH rule and auid: if auid and crush_rule given + Create a pool: \n + - **With default settings:** if ``auid=None`` and ``crush_rule=None`` \n + - **Owned by a specific auid:** auid given and ``crush_rule=None`` \n + - **With a specific CRUSH rule:** if ``auid=None`` and crush_rule given \n + - **With a specific CRUSH rule and auid:** if auid and crush_rule given \n - :param pool_name: name of the pool to create + :param pool_name: The name of the pool to create. :type pool_name: str - :param auid: the id of the owner of the new pool + :param auid: The id of the owner of the new pool. :type auid: int - :param crush_rule: rule to use for placement in the new pool + :param crush_rule: The rule to use for placement in the new pool. :type crush_rule: str :raises: :class:`TypeError`, :class:`Error` @@ -443,12 +446,12 @@ Rados object in state %s." % (self.state)) def delete_pool(self, pool_name): """ - Delete a pool and all data inside it. + Deletes a pool and all data inside it. The pool is removed from the cluster immediately, but the actual data is deleted in the background. - :param pool_name: name of the pool to delete + :param pool_name: The name of the pool to delete. :type pool_name: str :raises: :class:`TypeError`, :class:`Error` @@ -481,7 +484,7 @@ Rados object in state %s." % (self.state)) def get_fsid(self): """ - Get the fsid of the cluster as a hexadecimal string. + Get the ``fsid`` of the cluster as a hexadecimal string. :raises: :class:`Error` :returns: str - cluster fsid @@ -497,12 +500,12 @@ Rados object in state %s." % (self.state)) def open_ioctx(self, ioctx_name): """ - Create an io context + Creates an I/O context. - The io context allows you to perform operations within a particular + The I/O context allows you to perform operations within a particular pool. - :param ioctx_name: name of the pool + :param ioctx_name: The name of the pool. :type ioctx_name: str :raises: :class:`TypeError`, :class:`Error` @@ -632,7 +635,7 @@ class ObjectIterator(object): def next(self): """ - Get the next object name and locator in the pool + Get the next object name and locator in the pool. :raises: StopIteration :returns: next rados.Ioctx Object @@ -660,10 +663,10 @@ class XattrIterator(object): def next(self): """ - Get the next xattr on the object + Gets the next XATTR on the object. :raises: StopIteration - :returns: pair - of name and value of the next Xattr + :returns: pair - The name and value of the next XATTR. """ name_ = c_char_p(0) val_ = c_char_p(0) @@ -707,10 +710,10 @@ ioctx '%s'" % self.ioctx.name) def next(self): """ - Get the next Snapshot + Gets the next snapshot. :raises: :class:`Error`, StopIteration - :returns: Snap - next snapshot + :returns: Snap - The next snapshot. """ if (self.cur_snap >= self.max_snap): raise StopIteration @@ -770,7 +773,7 @@ class Completion(object): This does not imply that the safe callback has finished. - :returns: whether the operation is safe + :returns: True if the operation is safe. """ return run_in_thread(self.ioctx.librados.rados_aio_is_safe, (self.rados_comp,)) @@ -892,21 +895,21 @@ class Ioctx(object): def aio_write(self, object_name, to_write, offset=0, oncomplete=None, onsafe=None): """ - Write data to an object asynchronously + Writes data to an object asynchronously. Queues the write and returns. - :param object_name: name of the object + :param object_name: The name of the object. :type object_name: str - :param to_write: data to write + :param to_write: The data to write. :type to_write: str - :param offset: byte offset in the object to begin writing at + :param offset: The beginning byte offset. :type offset: int - :param oncomplete: what to do when the write is safe and complete in memory - on all replicas + :param oncomplete: What to do when the write is safe and complete in memory + on all replicas. :type oncomplete: completion - :param onsafe: what to do when the write is safe and complete on storage - on all replicas + :param onsafe: What to do when the write is safe and complete on storage + on all replicas. :type onsafe: completion :raises: :class:`Error` @@ -924,21 +927,21 @@ class Ioctx(object): def aio_write_full(self, object_name, to_write, oncomplete=None, onsafe=None): """ - Asychronously write an entire object + Asychronously writes an entire object. The object is filled with the provided data. If the object exists, it is atomically truncated and then written. Queues the write and returns. - :param object_name: name of the object + :param object_name: The name of the object. :type object_name: str - :param to_write: data to write + :param to_write: The data to write. :type to_write: str - :param oncomplete: what to do when the write is safe and complete in memory - on all replicas + :param oncomplete: What to do when the write is safe and complete in memory + on all replicas. :type oncomplete: completion - :param onsafe: what to do when the write is safe and complete on storage - on all replicas + :param onsafe: What to do when the write is safe and complete on storage + on all replicas. :type onsafe: completion :raises: :class:`Error` @@ -955,21 +958,21 @@ class Ioctx(object): def aio_append(self, object_name, to_append, oncomplete=None, onsafe=None): """ - Asychronously append data to an object + Asychronously appends data to an object. Queues the write and returns. - :param object_name: name of the object + :param object_name: The name of the object. :type object_name: str - :param to_append: data to append + :param to_append: The data to append. :type to_append: str - :param offset: byte offset in the object to begin writing at + :param offset: The beginning byte offset. :type offset: int - :param oncomplete: what to do when the write is safe and complete in memory - on all replicas + :param oncomplete: What to do when the write is safe and complete in memory + on all replicas. :type oncomplete: completion - :param onsafe: what to do when the write is safe and complete on storage - on all replicas + :param onsafe: What to do when the write is safe and complete on storage + on all replicas. :type onsafe: completion :raises: :class:`Error` @@ -986,7 +989,7 @@ class Ioctx(object): def aio_flush(self): """ - Block until all pending writes in an io context are safe + Blocks until all pending writes in an I/O context are safe. :raises: :class:`Error` """ @@ -996,20 +999,20 @@ class Ioctx(object): def aio_read(self, object_name, length, offset, oncomplete): """ - Asychronously read data from an object + Asychronously reads data from an object. - oncomplete will be called with the returned read value as + ``oncomplete`` will be called with the returned read value as well as the completion: oncomplete(completion, data_read) - :param object_name: name of the object to read from + :param object_name: The name of the object. :type object_name: str - :param length: the number of bytes to read + :param length: The number of bytes to read. :type length: int - :param offset: byte offset in the object to begin reading from + :param offset: The beginning byte offset. :type offset: int - :param oncomplete: what to do when the read is complete + :param oncomplete: What to do when the read is complete. :type oncomplete: completion :raises: :class:`Error` @@ -1029,7 +1032,7 @@ class Ioctx(object): def require_ioctx_open(self): """ - Checks if the rados.Ioctx object state is 'open' + Checks if the rados.Ioctx object state is ``open``. :raises: IoctxStateError """ @@ -1038,7 +1041,7 @@ class Ioctx(object): def change_auid(self, auid): """ - Attempt to change an io context's associated auid "owner." + Attempts to change an I/O context's associated auid "owner." Requires that you have write permission on both the current and new auid. @@ -1054,15 +1057,15 @@ class Ioctx(object): def set_locator_key(self, loc_key): """ - Set the key for mapping objects to pgs within an io context. + Sets the key for mapping objects to placement groups within an I/O context. The key is used instead of the object name to determine which placement groups an object is put in. This affects all subsequent - operations of the io context - until a different locator key is - set, all objects in this io context will be placed in the same pg. + operations of the I/O context - until a different locator key is + set, all objects in this I/O context will be placed in the same PG. - :param loc_key: the key to use as the object locator, or NULL to discard - any previously set key + :param loc_key: The key to use as the object locator, or NULL to discard + any previously set key. :type loc_key: str :raises: :class:`TypeError` @@ -1076,7 +1079,7 @@ class Ioctx(object): def get_locator_key(self): """ - Get the locator_key of context + Gets the ``locator_key`` of the context. :returns: locator_key """ @@ -1084,11 +1087,11 @@ class Ioctx(object): def close(self): """ - Close a rados.Ioctx object. + Closes a ``rados.Ioctx`` object. - This just tells librados that you no longer need to use the io context. + Tells ``librados`` that you no longer need to use the I/O context. It may not be freed immediately if there are pending asynchronous - requests on it, but you should not use an io context again after + requests on it, but you should not use an I/O context again after calling this function on it. """ if self.state == "open": @@ -1098,13 +1101,13 @@ class Ioctx(object): def write(self, key, data, offset=0): """ - Write data to an object synchronously + Write data to an object synchronously. - :param key: name of the object + :param key: The name of the object. :type key: str - :param data: data to write + :param data: The data to write. :type data: str - :param offset: byte offset in the object to begin writing at + :param offset: The beginning byte offset. :type offset: int :raises: :class:`TypeError` @@ -1134,14 +1137,14 @@ written." % (self.name, ret, length)) def write_full(self, key, data): """ - Write an entire object synchronously. + Writes an entire object synchronously. The object is filled with the provided data. If the object exists, it is atomically truncated and then written. - :param key: name of the object + :param key: The name of the object. :type key: str - :param data: data to write + :param data: The data to write. :type data: str :raises: :class:`TypeError` @@ -1165,18 +1168,18 @@ written." % (self.name, ret, length)) def read(self, key, length=8192, offset=0): """ - Write data to an object synchronously + Writes data to an object synchronously. - :param key: name of the object + :param key: The name of the object. :type key: str - :param length: the number of bytes to read (default=8192) + :param length: The number of bytes to read (default=8192). :type length: int - :param offset: byte offset in the object to begin reading at + :param offset: The beginning byte offset. :type offset: int :raises: :class:`TypeError` :raises: :class:`Error` - :returns: str - data read from object + :returns: str - Data read from the object. """ self.require_ioctx_open() if not isinstance(key, str): @@ -1191,34 +1194,34 @@ written." % (self.name, ret, length)) def get_stats(self): """ - Get pool usage statistics + Gets pool usage statistics. - :returns: dict - contains the following keys: + :returns: dict - Contains the following keys: - *``num_bytes`` (int) - size of pool in bytes + - ``num_bytes`` (int) - Size of pool in bytes. \n - *``num_kb`` (int) - size of pool in kbytes + - ``num_kb`` (int) - Size of pool in kbytes. \n - *``num_objects`` (int) - number of objects in the pool + - ``num_objects`` (int) - Number of objects in the pool. \n - *``num_object_clones`` (int) - number of object clones + - ``num_object_clones`` (int) - Number of object clones. \n - *``num_object_copies`` (int) - number of object copies + - ``num_object_copies`` (int) - Number of object copies. \n - *``num_objects_missing_on_primary`` (int) - number of objets + - ``num_objects_missing_on_primary`` (int) - Number of objects. \n missing on primary - *``num_objects_unfound`` (int) - number of unfound objects + - ``num_objects_unfound`` (int) - Number of unfound objects. \n - *``num_objects_degraded`` (int) - number of degraded objects + - ``num_objects_degraded`` (int) - Number of degraded objects. \n - *``num_rd`` (int) - bytes read + - ``num_rd`` (int) - Bytes read. \n - *``num_rd_kb`` (int) - kbytes read + - ``num_rd_kb`` (int) - Kbytes read. \n - *``num_wr`` (int) - bytes written + - ``num_wr`` (int) - Bytes written. \n - *``num_wr_kb`` (int) - kbytes written + - ``num_wr_kb`` (int) - Kbytes written. \n """ self.require_ioctx_open() stats = rados_pool_stat_t() @@ -1241,16 +1244,16 @@ written." % (self.name, ret, length)) def remove_object(self, key): """ - Delete an object + Deletes an object. This does not delete any snapshots of the object. - :param key: the name of the object to delete + :param key: The name of the object to delete. :type key: str :raises: :class:`TypeError` :raises: :class:`Error` - :returns: bool - True on success + :returns: bool - True on success. """ self.require_ioctx_open() if not isinstance(key, str): @@ -1263,19 +1266,19 @@ written." % (self.name, ret, length)) def trunc(self, key, size): """ - Resize an object + Resizes an object. If this enlarges the object, the new area is logically filled with zeroes. If this shrinks the object, the excess data is removed. - :param key: the name of the object to resize + :param key: The name of the object to resize. :type key: str - :param size: the new size of the object in bytes + :param size: The new size of the object in bytes. :type size: int :raises: :class:`TypeError` :raises: :class:`Error` - :returns: int - 0 on success, otherwise raises error + :returns: int - 0 on success, otherwise raises error. """ self.require_ioctx_open() @@ -1289,9 +1292,9 @@ written." % (self.name, ret, length)) def stat(self, key): """ - Get object stats (size/mtime) + Gets object stats (size/mtime). - :param key: the name of the object to get stats from + :param key: The name of the object. :type key: str :raises: :class:`TypeError` @@ -1313,16 +1316,16 @@ written." % (self.name, ret, length)) def get_xattr(self, key, xattr_name): """ - Get the value of an extended attribute on an object. + Gets the value of an extended attribute on an object. - :param key: the name of the object to get xattr from + :param key: The name of the object. :type key: str - :param xattr_name: which extended attribute to read + :param xattr_name: The name of the extended attribute. :type xattr_name: str :raises: :class:`TypeError` :raises: :class:`Error` - :returns: str - value of the xattr + :returns: str - The value of the extended attribute. """ self.require_ioctx_open() if not isinstance(xattr_name, str): @@ -1343,9 +1346,9 @@ written." % (self.name, ret, length)) def get_xattrs(self, oid): """ - Start iterating over xattrs on an object. + Start iterating over XATTRs on an object. - :param oid: the name of the object to get xattrs from + :param oid: The name of the object. :type key: str :raises: :class:`TypeError` @@ -1359,23 +1362,23 @@ written." % (self.name, ret, length)) ret = run_in_thread(self.librados.rados_getxattrs, (self.io, oid, byref(it))) if ret != 0: - raise make_ex(ret, "Failed to get rados xattrs for object %r" % oid) + raise make_ex(ret, "Failed to get RADOS XATTRS for object %r" % oid) return XattrIterator(self, it, oid) def set_xattr(self, key, xattr_name, xattr_value): """ - Set an extended attribute on an object. + Sets an extended attribute on an object. - :param key: the name of the object to set xattr to + :param key: The name of the object. :type key: str - :param xattr_name: which extended attribute to set + :param xattr_name: The name of the extended attribute to set. :type xattr_name: str - :param xattr_value: the value of the extended attribute + :param xattr_value: The value of the extended attribute. :type xattr_value: str :raises: :class:`TypeError` :raises: :class:`Error` - :returns: bool - True on success, otherwise raise an error + :returns: bool - True on success, otherwise raise an error. """ self.require_ioctx_open() if not isinstance(key, str): @@ -1395,9 +1398,9 @@ written." % (self.name, ret, length)) """ Removes an extended attribute on from an object. - :param key: the name of the object to remove xattr from + :param key: The name of the object. :type key: str - :param xattr_name: which extended attribute to remove + :param xattr_name: The name of the extended attribute to remove. :type xattr_name: str :raises: :class:`TypeError` @@ -1418,7 +1421,7 @@ written." % (self.name, ret, length)) def list_objects(self): """ - Get ObjectIterator on rados.Ioctx object. + Gets ``ObjectIterator`` on ``rados.Ioctx`` object. :returns: ObjectIterator """ @@ -1427,7 +1430,7 @@ written." % (self.name, ret, length)) def list_snaps(self): """ - Get SnapIterator on rados.Ioctx object. + Gets ``SnapIterator`` on ``rados.Ioctx`` object. :returns: SnapIterator """ @@ -1436,9 +1439,9 @@ written." % (self.name, ret, length)) def create_snap(self, snap_name): """ - Create a pool-wide snapshot + Creates a pool-wide snapshot. - :param snap_name: the name of the snapshot + :param snap_name: The name of the snapshot. :type snap_name: str :raises: :class:`TypeError` @@ -1454,9 +1457,9 @@ written." % (self.name, ret, length)) def remove_snap(self, snap_name): """ - Removes a pool-wide snapshot + Removes a pool-wide snapshot. - :param snap_name: the name of the snapshot + :param snap_name: The name of the snapshot. :type snap_name: str :raises: :class:`TypeError` @@ -1472,14 +1475,14 @@ written." % (self.name, ret, length)) def lookup_snap(self, snap_name): """ - Get the id of a pool snapshot + Lookup a pool's snapshot by name. - :param snap_name: the name of the snapshot to lookop + :param snap_name: The name of the snapshot to lookup. :type snap_name: str :raises: :class:`TypeError` :raises: :class:`Error` - :returns: Snap - on success + :returns: Snap - On success. """ self.require_ioctx_open() if not isinstance(snap_name, str): @@ -1493,12 +1496,12 @@ written." % (self.name, ret, length)) def get_last_version(self): """ - Return the version of the last object read or written to. + Returns the version of the last object read or written. This exposes the internal version number of the last object read or - written via this io context + written via this I/O context. - :returns: version of the last object used + :returns: The version of the last object used. """ self.require_ioctx_open() return run_in_thread(self.librados.rados_get_last_version, (self.io,)) @@ -1531,28 +1534,69 @@ class Object(object): if self.state != "exists": raise ObjectStateError("The object is %s" % self.state) - @set_object_locator + def read(self, length = 1024*1024): + """ + Writes data to an object synchronously. + + :param length: The number of bytes to read (default=8192). + :type length: int + :param offset: The beginning byte offset. + :type offset: int + + :raises: :class:`TypeError` + :raises: :class:`Error` + :returns: str - Data read from the object. + """ self.require_object_exists() ret = self.ioctx.read(self.key, length, self.offset) self.offset += len(ret) return ret - @set_object_locator + def write(self, string_to_write): + """ + Write data to an object synchronously. + + :param data: The data to write. + :type data: str + :param offset: The beginning byte offset. + :type offset: int + + :raises: :class:`TypeError` + :raises: :class:`IncompleteWriteError` + :raises: :class:`LogicError` + :returns: int - number of bytes written + """ self.require_object_exists() ret = self.ioctx.write(self.key, string_to_write, self.offset) self.offset += ret return ret - @set_object_locator + def remove(self): + """ + Deletes the object. + + This does not delete any snapshots of the object. + + :raises: :class:`TypeError` + :raises: :class:`Error` + :returns: bool - True on success. + """ self.require_object_exists() self.ioctx.remove_object(self.key) self.state = "removed" - @set_object_locator + def stat(self): + """ + Gets object stats (size/mtime). + + :raises: :class:`TypeError` + :raises: :class:`Error` + :returns: (size,timestamp) + """ self.require_object_exists() return self.ioctx.stat(self.key) @@ -1560,23 +1604,64 @@ class Object(object): self.require_object_exists() self.offset = position - @set_object_locator + def get_xattr(self, xattr_name): + """ + Gets the value of an extended attribute on the object. + + :param xattr_name: The name of the extended attribute. + :type xattr_name: str + + :raises: :class:`TypeError` + :raises: :class:`Error` + :returns: str - The value of the extended attribute. + """ self.require_object_exists() return self.ioctx.get_xattr(self.key, xattr_name) - @set_object_locator + def get_xattrs(self): + """ + Start iterating over XATTRs on the object. + + :raises: :class:`TypeError` + :raises: :class:`Error` + :returns: XattrIterator + """ self.require_object_exists() return self.ioctx.get_xattrs(self.key) - @set_object_locator + def set_xattr(self, xattr_name, xattr_value): + """ + Sets an extended attribute on the object. + + :param xattr_name: The name of the extended attribute to set. + :type xattr_name: str + :param xattr_value: The value of the extended attribute. + :type xattr_value: str + + :raises: :class:`TypeError` + :raises: :class:`Error` + :returns: bool - True on success, otherwise raise an error. + """ + self.require_object_exists() return self.ioctx.set_xattr(self.key, xattr_name, xattr_value) - @set_object_locator + def rm_xattr(self, xattr_name): + """ + Removes an extended attribute on from the object. + + :param xattr_name: The name of the extended attribute to remove. + :type xattr_name: str + + :raises: :class:`TypeError` + :raises: :class:`Error` + :returns: bool - True on success, otherwise raise an error + """ + self.require_object_exists() return self.ioctx.rm_xattr(self.key, xattr_name) |