From 1cf952e0f673b40dd5d26f76ab8d2bbeb2cb0af5 Mon Sep 17 00:00:00 2001
From: Daniel <d.hornung@indiscale.com>
Date: Thu, 13 Apr 2023 12:28:04 +0200
Subject: [PATCH] DOC: Documentation only.
---
src/caosdb/cached.py | 40 +++++++++++++++++++++++++++-------
src/caosdb/common/models.py | 2 +-
src/caosdb/utils/get_entity.py | 12 +++++-----
src/doc/conf.py | 2 +-
unittests/test_cached.py | 2 +-
5 files changed, 41 insertions(+), 17 deletions(-)
diff --git a/src/caosdb/cached.py b/src/caosdb/cached.py
index c1356567..ff885c11 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 20e09810..a95ff637 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 e5ba949b..a27aafa9 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 54d75bd0..5632fd79 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 19c7769c..d1f86068 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)
--
GitLab