diff --git a/src/caosdb/cached.py b/src/caosdb/cached.py index c1356567a9ca98476f21e7cea8f9158547369a47..ff885c115a04432229e6ae95217b2a8acaac7d14 100644 --- a/src/caosdb/cached.py +++ b/src/caosdb/cached.py @@ -51,9 +51,13 @@ class AccessType(Enum): def cached_get_entity_by(eid: Union[str, int] = None, name: str = None, path: str = None, query: str = None) -> Entity: - """ returns a single entity that is identified uniquely by one of the arguments + """Return a single entity that is identified uniquely by one argument. + +You must supply exactly one argument. + +If a query phrase is given, the result must be unique. If this is not what you need, use +:func:`cached_query` instead. - You must supply exactly one of the arguments. """ count = 0 if eid is not None: @@ -109,29 +113,49 @@ def _cached_access(kind: AccessType, value: Union[str, int], unique=True): raise ValueError(f"Unknown AccessType: {kind}") + def cache_clear() -> None: - """ Empty the cache that is used by cached_query and cached_get_entity_by """ + """Empty the cache that is used by `cached_query` and `cached_get_entity_by`.""" _cached_access.cache_clear() def cache_info(): - """ Empty the cache that is used by cached_query and cached_get_entity_by """ + """Empty the cache that is used by `cached_query` and `cached_get_entity_by`.""" return _cached_access.cache_info() def cache_initialize(maxsize=DEFAULT_SIZE) -> None: - """ Create a new cache with the given size for cached_query and cached_get_entity_by + """Create a new cache with the given size for `cached_query` and `cached_get_entity_by`. The old cache is removed with all its content. + """ global _cached_access _cached_access = lru_cache(maxsize=maxsize)(_cached_access.__wrapped__) -def fill_cache(items: dict, kind: AccessType = AccessType.EID, unique=True) -> None: - """ add Entities to the cache manually +def fill_cache(items: dict, kind: AccessType = AccessType.EID, unique: bool = True) -> None: + """Add entries to the cache manually. + + This allows to fill the cache without actually submitting queries. Note that this does not + overwrite existing entries with the same keys. + +Parameters +---------- + +items: dict + A dictionary with the entries to go into the cache. The keys must be compatible with the + AccessType given in ``kind`` + +kind: AccessType, optional + The AccessType, for example ID, name, path or query. + +unique: bool, optional + If True, fills the cache for :func:`cached_get_entity_by`, presumably with + :class:`caosdb.Entity<caosdb.common.models.Entity>` objects. If False, the cache should be filled + with :class:`caosdb.Container<caosdb.common.models.Container>` objects, for use with + :func:`cached_query`. - This allows to fill the cache without actually submitting queries. """ # 1. add the given items to the corresponding dummy dict cache _DUMMY_CACHE.update(items) diff --git a/src/caosdb/common/models.py b/src/caosdb/common/models.py index 20e09810ba466d59cf7a82d68cad19fefb45b10b..a95ff637ebf67fb3c264a3e6fe7a19e856de75f8 100644 --- a/src/caosdb/common/models.py +++ b/src/caosdb/common/models.py @@ -4371,7 +4371,7 @@ def execute_query(q, unique=False, raise_exception_on_error=True, cache=True, fl Whether the query is expected to have only one entity as result. Defaults to False. raise_exception_on_error : bool - Whether an exception should be raises when there are errors in the + Whether an exception should be raised when there are errors in the resulting entities. Defaults to True. cache : bool Whether to use the query cache (equivalent to adding a "cache" flag). diff --git a/src/caosdb/utils/get_entity.py b/src/caosdb/utils/get_entity.py index e5ba949b4c67ae91f65bc65f70356b42eaba17dd..a27aafa99ffe3759a46876a5bcd5e686d631b1dc 100644 --- a/src/caosdb/utils/get_entity.py +++ b/src/caosdb/utils/get_entity.py @@ -19,22 +19,22 @@ # along with this program. If not, see <https://www.gnu.org/licenses/>. # -""" convenience functions to retrieve a specific entity """ +"""Convenience functions to retrieve a specific entity.""" -from ..common.models import execute_query, Entity from typing import Union +from ..common.models import execute_query, Entity def get_entity_by_name(name: str) -> Entity: - """returns the result of a unique query that uses the name to find the correct entity + """Return the result of a unique query that uses the name to find the correct entity. Submits the query "FIND ENTITY WITH name='{name}'". """ - return execute_query(f"", unique=True) + return execute_query(f"FIND ENTITY WITH name='{name}'", unique=True) def get_entity_by_id(eid: Union[str, int]) -> Entity: - """returns the result of a unique query that uses the id to find the correct entity + """Return the result of a unique query that uses the id to find the correct entity. Submits the query "FIND ENTITY WITH id='{eid}'". """ @@ -42,7 +42,7 @@ def get_entity_by_id(eid: Union[str, int]) -> Entity: def get_entity_by_path(path: str) -> Entity: - """returns the result of a unique query that uses the path to find the correct entity + """Return the result of a unique query that uses the path to find the correct file. Submits the query "FIND FILE WHICH IS STORED AT '{path}'". """ diff --git a/src/doc/conf.py b/src/doc/conf.py index 54d75bd0e70138d3c90020e6058edb4403f838f0..5632fd790b451316c3a0984117eb0bd52a4f6e84 100644 --- a/src/doc/conf.py +++ b/src/doc/conf.py @@ -25,7 +25,7 @@ import sphinx_rtd_theme # noqa: E402 # -- Project information ----------------------------------------------------- project = 'pycaosdb' -copyright = '2022, IndiScale GmbH' +copyright = '2023, IndiScale GmbH' author = 'Daniel Hornung' # The short X.Y version diff --git a/unittests/test_cached.py b/unittests/test_cached.py index 19c7769cc7729bc82a7665f038a154e81aba237d..d1f8606844833a3d21441fd6426f13d3e382607c 100644 --- a/unittests/test_cached.py +++ b/unittests/test_cached.py @@ -19,7 +19,7 @@ # along with this program. If not, see <https://www.gnu.org/licenses/>. # -""" test entity_getters module """ +""" Test the caosdb.cached module """ from caosdb.cached import (cached_get_entity_by, cache_clear, cache_info, fill_cache, AccessType, cache_initialize, cached_query)