diff --git a/HISTORY.md b/HISTORY.md index 9beaf5c8f2..b4d56603eb 100644 --- a/HISTORY.md +++ b/HISTORY.md @@ -1,3 +1,11 @@ +# In Progress + +## Improvements +* Add `Group` and `Object` to docs [#1040](https://github.com/TileDB-Inc/TileDB-Py/pull/1040) + +## Bug Fixes +* Correct `Group.__repr__` to call correct `_dump` function [#1040](https://github.com/TileDB-Inc/TileDB-Py/pull/1040) + # TileDB-Py 0.14.1 Release Notes ## TileDB Embedded updates: @@ -11,7 +19,6 @@ ## API Changes * Addition of `Group` and `Object` classes to support improved groups [#1022](https://github.com/TileDB-Inc/TileDB-Py/pull/1022) - # TileDB-Py 0.13.3 Release Notes ## TileDB Embedded updates: diff --git a/doc/requirements_doc.txt b/doc/requirements_doc.txt index dd5b94cd4d..231c14799a 100644 --- a/doc/requirements_doc.txt +++ b/doc/requirements_doc.txt @@ -1,3 +1,4 @@ docutils < 0.18 +jinja2==3.0.0 -r ../requirements_dev.txt diff --git a/doc/source/python-api.rst b/doc/source/python-api.rst index 970a580987..bd565290c5 100644 --- a/doc/source/python-api.rst +++ b/doc/source/python-api.rst @@ -139,6 +139,20 @@ Query Condition .. autoclass:: tiledb.QueryCondition :members: +Group +----- + +.. autoclass:: tiledb.Group + :members: + +Object +------ + +.. autoclass:: tiledb.Object + + .. autoattribute:: uri + .. autoattribute:: type + Object Management ----------------- diff --git a/tiledb/cc/object.cc b/tiledb/cc/object.cc index dd0ee68bb9..13452c2621 100644 --- a/tiledb/cc/object.cc +++ b/tiledb/cc/object.cc @@ -19,12 +19,12 @@ void init_object(py::module &m) { .def(py::init()) .def_property_readonly("_type", &Object::type) - .def_property_readonly("uri", &Object::uri) + .def_property_readonly("_uri", &Object::uri) .def("__repr__", &Object::to_str) - .def_static("object", &Object::object) - .def_static("remove", &Object::remove) - .def_static("move", &Object::move); + .def_static("_object", &Object::object) + .def_static("_remove", &Object::remove) + .def_static("_move", &Object::move); } } // namespace libtiledbcpp diff --git a/tiledb/group.py b/tiledb/group.py index dca893379f..ca08a8d354 100644 --- a/tiledb/group.py +++ b/tiledb/group.py @@ -12,24 +12,20 @@ class Group(lt.Group): """ Support for organizing multiple arrays in arbitrary directory hierarchies. - Group members may be any number of nested groups and arrays. Members are - stored as `tiledb.Object`s which indicate the member's URI and type. + + Group members may be any number of nested groups and arrays. Members are stored as tiledb.Objects which indicate the member's URI and type. Groups may contain associated metadata similar to array metadata where - keys are strings. Singleton values may be of type int, float, str, or bytes. - Multiple values of the same type may be placed in containers of type list, - tuple, or 1-D np.ndarray. The values within containers are limited to type - int or float. + keys are strings. Singleton values may be of type int, float, str, or bytes. Multiple values of the same type may be placed in containers of type list, tuple, or 1-D np.ndarray. The values within containers are limited to type int or float. - See more at: - https://docs.tiledb.com/main/background/key-concepts-and-data-format#arrays-and-groups + See more at: https://docs.tiledb.com/main/background/key-concepts-and-data-format#arrays-and-groups :param uri: The URI to the Group - :type str + :type uri: str :param mode: Read mode ('r') or write mode ('w') - :type str + :type mode: str :param ctx: A TileDB context - :type tiledb.Ctx + :type ctx: tiledb.Ctx **Example:** @@ -171,9 +167,9 @@ def create(uri: str, ctx: "Ctx" = None): Create a new Group. :param uri: The URI to the to-be created Group - :type str + :type uri: str :param ctx: A TileDB context - :type tiledb.Ctx + :type ctx: tiledb.Ctx """ _ctx = ctx or default_ctx() cctx = lt.Context(_ctx.__capsule__(), False) @@ -184,7 +180,7 @@ def open(self, mode: str = "r"): Open a Group in read mode ("r") or write mode ("w"). :param mode: Read mode ('r') or write mode ('w') - :type str + :type mode: str """ if mode not in Group._mode_to_query_type: raise ValueError(f"invalid mode {mode}") @@ -203,11 +199,11 @@ def add(self, uri: str, name: str = None, relative: bool = False): Adds a member to the Group. :param uri: The URI of the member to add - :type str - :param relative: Whether the path of the URI is a relative path (default=False) + :type uri: str + :param relative: Whether the path of the URI is a relative path (default=relative: False) :type bool :param name: An optional name for the Group (default=None) - :type str + :type name: str """ if name: self._add(uri, relative, name) @@ -219,9 +215,9 @@ def __getitem__(self, member: Union[int, str]) -> "Object": Retrieve a member from the Group as an Object. :param member: The index or name of the member - :type Union[int, str] + :type member: Union[int, str] :return: The member as an Object - :type Object + :rtype: Object """ from .object import Object @@ -231,14 +227,14 @@ def __getitem__(self, member: Union[int, str]) -> "Object": ) obj = self._member(member) - return Object(obj._type, obj.uri) + return Object(obj._type, obj._uri) def remove(self, member: str): """ Remove a member from the Group. :param member: The URI or name of the member - :type str + :type member: str """ if not isinstance(member, str): raise TypeError(f"Unexpected member type '{type(member)}': expected str") @@ -250,7 +246,7 @@ def __delitem__(self, uri: str): Remove a member from the group. :param uri: The URI to the member - :type str + :type uri: str """ self._remove(uri) @@ -258,44 +254,36 @@ def __iter__(self): return iter(self[i] for i in range(len(self))) def __repr__(self): - return self.dump(True) + return self._dump(True) @property def meta(self) -> GroupMetadata: """ - The metadata of the Group contained as a key-value structure. - - :return: The Group's metadata - :type GroupMetadata + :return: The Group's metadata as a key-value structure + :rtype: GroupMetadata """ return self._meta @property def isopen(self) -> bool: """ - Indicates whether or not the Group is open. - :return: Whether or not the Group is open - :type bool + :rtype: bool """ return self._isopen @property def uri(self) -> str: """ - The URI of the Group. - :return: URI of the Group - :type str + :rtype: str """ return self._uri @property def mode(self) -> str: """ - Indicates if the Group is opened in read mode ('r') or write mode ('w'). - :return: Read mode ('r') or write mode ('w') - :type str + :rtype: str """ return self._query_type_to_mode[self._query_type] diff --git a/tiledb/object.py b/tiledb/object.py index e3298ac4f3..f439cac910 100644 --- a/tiledb/object.py +++ b/tiledb/object.py @@ -17,10 +17,19 @@ class Object(lt.Object): def __init__(self, type: lt.ObjectType, uri: str): super().__init__(type, uri) + @property + def uri(self) -> str: + """ + :return: URI of the Object. + :rtype: str + """ + return self._uri + @property def type(self) -> type: """ - Valid TileDB object types are Array and Group. + :return: Valid TileDB object types are Array and Group. + :rtype: type """ if self._type not in self._obj_type_to_class: raise KeyError(f"Unknown object type: {self._type}") diff --git a/tiledb/tests/test_group.py b/tiledb/tests/test_group.py index 18b6df21ab..9877f31e4a 100644 --- a/tiledb/tests/test_group.py +++ b/tiledb/tests/test_group.py @@ -1,7 +1,6 @@ import os import numpy as np import pytest -from numpy.testing import assert_array_equal import tiledb from tiledb.tests.common import DiskTestCase @@ -121,7 +120,7 @@ def values_equal(lhs, rhs): # assert "int" not in grp.meta # grp.close() - def test_group_members(self): + def test_group_members(self, capfd): grp_path = self.path("test_group_members") tiledb.Group.create(grp_path) @@ -155,6 +154,10 @@ def test_group_members(self): assert grp[1].type in type_to_basename assert type_to_basename[grp[1].type] == os.path.basename(grp[1].uri) + assert "test_group_members GROUP" in repr(grp) + assert "|-- test_group_members ARRAY" in repr(grp) + assert "|-- test_group_0 GROUP" in repr(grp) + grp.close() grp.open("w")