ENH: add entity getters and cached functions

Summary

Added:

• Entity getters: get_entity_by_<name/id/path> to retrieve single Entities identified via some attribute
• Cached versions of entity getters and of execute_query (cached_query)

Focus

You might want to look at the documentation first (build it with make doc). lru_cache is used for caching. lru_cache does not have the ability to add items to the cache manually. Thus, a dumb cache was added to allow this (see code).

Test Environment

unit tests.

I did not add integration test due to two reasons:

1. the getter functions are defined via the query that is sent. We do not need to test the query function here.
2. the getter functions and the execute_query function are mocked such that everything can be tested as unit test. (Those functions are the only connection to the server that would require integration tests)

Check List for the Author

Please, prepare your MR for a review. Be sure to write a summary and a focus and create gitlab comments for the reviewer. They should guide the reviewer through the changes, explain your changes and also point out open questions. For further good practices have a look at our review guidelines

• All automated tests pass
• Reference related issues
• Up-to-date CHANGELOG.md (or not necessary)
• Up-to-date JSON schema (or not necessary)
• Appropriate user and developer documentation (or not necessary)
  • How do I use the software? Assume "stupid" users.
  • How do I develop or debug the software? Assume novice developers.
• Annotations in code (Gitlab comments)
  • Intent of new code
  • Problems with old code
  • Why this implementation?

Check List for the Reviewer

• I understand the intent of this MR
• All automated tests pass
• Up-to-date CHANGELOG.md (or not necessary)
• Appropriate user and developer documentation (or not necessary)
• The test environment setup works and the intended behavior is reproducible in the test environment
• In-code documentation and comments are up-to-date.
• Check: Are there specifications? Are they satisfied?

For further good practices have a look at our review guidelines.

src/caosdb/cached.py

@@ -2,8 +2,9 @@
 #
 # This file is a part of the CaosDB Project.
 #
-# Copyright (C) 2023 Henrik tom Wörden <h.tomwoerden@indiscale.com>
 # Copyright (C) 2023 IndiScale GmbH <info@indiscale.com>
+# Copyright (C) 2023 Henrik tom Wörden <h.tomwoerden@indiscale.com>
+# Copyright (C) 2023 Daniel Hornung <d.hornung@indiscale.com>
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU Affero General Public License as
@@ -23,14 +24,14 @@
 This module provides some cached versions of functions that retrieve Entities from a remote server.
 """
 
-from typing import Union
+from enum import Enum
 from functools import lru_cache
+from typing import Union
+
 from .utils import get_entity
 from .common.models import execute_query, Entity, Container
 
 
-from enum import Enum
-
 # roughly 1GB for typical entity sizes
 DEFAULT_SIZE = 33333
 
@@ -40,7 +41,7 @@ _DUMMY_CACHE = {}
 
 class AccessType(Enum):
     """Different access types for cached queries.  Needed for filling the cache manually with
-:func:`fill_cache` .
+:func:`cache_fill` .
 
     """
     QUERY = 1
@@ -84,7 +85,7 @@ If a query phrase is given, the result must be unique.  If this is not what you
 
 
 def cached_query(query_string) -> Container:
-    """A cached version of the :func:`caosdb.execute_query<caosdb.common.models.execute_query>` function.
+    """A cached version of :func:`caosdb.execute_query<caosdb.common.models.execute_query>`.
 
 All additional arguments are at their default values.
 
@@ -120,21 +121,28 @@ def cache_clear() -> None:
 
 
 def cache_info():
-    """Empty the cache that is used by `cached_query` and `cached_get_entity_by`."""
+    """Return info about the cache that is used by `cached_query` and `cached_get_entity_by`.
+
+Returns
+-------
+
+out: named tuple
+  See the standard library :func:`functools.lru_cache` for details."""
     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`.
 
-    The old cache is removed with all its content.
+    This implies a call of :func:`cache_clear`, the old cache is emptied.
 
     """
+    cache_clear()
     global _cached_access
     _cached_access = lru_cache(maxsize=maxsize)(_cached_access.__wrapped__)
 
 
-def fill_cache(items: dict, kind: AccessType = AccessType.EID, unique: bool = True) -> None:
+def cache_fill(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