From b753e7214da8ee694368c39b8818e8b51856cc05 Mon Sep 17 00:00:00 2001
From: Daniel <d.hornung@indiscale.com>
Date: Thu, 13 Apr 2023 10:39:37 +0200
Subject: [PATCH] DOC: Worked on the documentation.
---
CHANGELOG.md | 2 +-
src/doc/tutorials/Data-Insertion.rst | 10 +++++-----
src/doc/tutorials/Entity-Getters.rst | 19 ++++++++++---------
src/doc/tutorials/caching.rst | 27 +++++++++++++--------------
4 files changed, 29 insertions(+), 29 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b14e227f..d6f7c5f1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,7 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Added ###
- Added location argument to `src/caosdb/utils/checkFileSystemConsistency.py`
- Entity getters: `get_entity_by_<name/id/path>`
-- Cached versions of entity getters and of execute_query (cached_query)
+- Cached versions of entity getters and of `execute_query` (`cached_query`)
### Changed ###
diff --git a/src/doc/tutorials/Data-Insertion.rst b/src/doc/tutorials/Data-Insertion.rst
index c1b40159..82df0769 100644
--- a/src/doc/tutorials/Data-Insertion.rst
+++ b/src/doc/tutorials/Data-Insertion.rst
@@ -224,14 +224,14 @@ list-valued attribute in Python, as the following example illustrates.
.. note::
- Properties of Entities, that shall be updated, need to have IDs. Let's look at an
+ Properties of Entities that shall be updated need to have IDs. Let's look at an
example:
.. code:: python
experiment = db.Record(id=1111).retrieve()
experiment.add_property(name='date', value="2020-01-01")
- retrieved.update() # Fails! The date Property needs to have an ID.
+ retrieved.update() # Fails! The 'date' Property needs to have an ID.
The easiest way to get around this is to use the corresponding entity getter:
@@ -239,10 +239,10 @@ The easiest way to get around this is to use the corresponding entity getter:
experiment = db.Record(id=1111).retrieve()
experiment.add_property(db.get_entity_by_name('date'), value="2020-01-01")
- retrieved.update() # Works!
+ retrieved.update() # Works!
-There are also the functions ``get_entity_by_path`` and ``get_entity_by_id``. You can easily use
-cached versions of those functions (see :doc:`Entity Getters<Entity-Getters>`).
+There also are the functions ``get_entity_by_path`` and ``get_entity_by_id``. You can easily use
+cached versions of those functions (see :doc:`caching options<caching>`).
File Update
diff --git a/src/doc/tutorials/Entity-Getters.rst b/src/doc/tutorials/Entity-Getters.rst
index 383d9432..50ed1320 100644
--- a/src/doc/tutorials/Entity-Getters.rst
+++ b/src/doc/tutorials/Entity-Getters.rst
@@ -2,14 +2,15 @@
Entity Getters
==============
-There is a very frequent situation when using PyCaosDB: You need to get a specific Entity from the
-remote server. For example, you need the Property Entity in order to make an update. Sure, you can
-do a ``db.Entity().retrieve()`` or submit a query, but there is an even faster way which also helps
-preventing errors:
+There is a very frequent situation when working with PyCaosDB: You need to get a specific Entity
+from the remote server. For example, you need the Property Entity in order to make an update. Sure,
+you can do a ``db.Entity().retrieve()`` or submit a query, but there is an even faster way which
+also helps preventing errors:
-- get_entity_by_name
-- get_entity_by_id
-- get_entity_by_path
+- ``get_entity_by_name``
+- ``get_entity_by_id``
+- ``get_entity_by_path``
-You can call them with a single argument (name/id/path). Since those, are ofte used quite
-frequently, you might want to look at the :doc:`caching options<caching>`
+You can call these functions with a single argument (name/id/path). Since these functions are
+frequently used with the same arguments over and over again, you might want to look at the
+:doc:`caching options<caching>`.
diff --git a/src/doc/tutorials/caching.rst b/src/doc/tutorials/caching.rst
index 76f0d45d..ef4b55ad 100644
--- a/src/doc/tutorials/caching.rst
+++ b/src/doc/tutorials/caching.rst
@@ -4,12 +4,12 @@ Caching
.. note::
-Caching is great, because it can speed up things considerably. But it can also create mean pit
-falls if the cache is not cleared when needed and you work with outdated data. Thus, please use
-the cache with care and make sure to clear it when needed.
+ Caching is great, because it can speed up things considerably. But it can also create dangerous
+ pitfalls if the cache is not cleared when needed and you work with outdated data. Thus, please use
+ the cache with care and make sure to clear it when needed.
-Python provides great tools to create caching. For example, it is very easy to create a
-cached version of the ``get_entity_by_name`` function using Python's ``lru_cache``:
+Python provides great tools for caching. For example, you could define a ``cached_get_by_name``
+function, easily created from ``get_entity_by_name`` using Python's ``lru_cache``:
.. code:: python
@@ -21,9 +21,8 @@ cached version of the ``get_entity_by_name`` function using Python's ``lru_cache
# reset the cache with
cached_get_by_name.cache_clear()
-For convenience we also provide the ``caosdb.cached`` module that defines the functions
-``cached_query`` and ``cached_get_by``. They share a single cache with a single size. Let's have a
-look:
+For convenience, PyCaosDB provides the ``caosdb.cached`` module that defines the functions
+``cached_query`` and ``cached_get_by``, they use a shared cache. Let's have a look:
.. code:: python
@@ -32,24 +31,24 @@ look:
qresult = cached_query('FIND Experiment WITH parameter=1')
# you can inspect the cache
print(cache_info())
- # this will not cause server request since it is cached
+ # this will not cause a server request since it is cached
rt1 = cached_get_by(name='RT1')
# you can clear the cache with
cache_clear()
- # If you want to have a cache with a different size, you can initialize it (again). Old cached
+ # If you want to have a cache with a custom size, you can initialize it (again). Old cached
# data is lost.
initialize_cache(size=10)
-In case you want to add Entities manually to the cache (e.g. because you happen to have the one
-million entites that you will be using already at hand from another query), you can do so with
+If you want to manually add entities to the cache, you can do it yourself. This is useful when you
+have entities on hand from previous queries that you want to add.
.. code:: python
from caosdb.cached import fill_cache, AccessType
- # Here, items needs to be a dict with Entity IDs as keys and the Entities as values
+ # Here, items must be a dict with Entity IDs as keys and the Entities as values.
fill_cache(items, AccessType.EID, unique=True)
- # if you now use IDs that where in items, they are taken from the cache
+ # If you now use IDs that were in items, they are taken from the cache.
e1 = cached_get_by(eid=10001)
For the cached entity getter functions (``cached_get_by``) you need to set ``unique=True``.
--
GitLab