Skip to content
Snippets Groups Projects
Verified Commit f2988c64 authored by Daniel Hornung's avatar Daniel Hornung
Browse files

WIP: Rename caosdb -> linkahead (docs)

parent 53ffa88a
No related branches found
No related tags found
1 merge request!111MAINT: LinkAhead rename
Showing
with 107 additions and 108 deletions
......@@ -4,7 +4,7 @@ Administration
The Python script ``caosdb_admin.py`` should be used for administrative tasks.
Call ``caosdb_admin.py --help`` to see how to use it.
The most common task is to create a new user (in the CaosDB realm) and set a
The most common task is to create a new user (in the LinkAhead realm) and set a
password for the user (note that a user typically needs to be activated):
.. code:: console
......
========================
The concepts of PyCaosDB
========================
===========================
The concepts of PyLinkAhead
===========================
- `Configuration <configuration>`
# Configuration of PyCaosDB #
The behavior of PyCaosDB is defined via a configuration that is provided using configuration files.
PyCaosDB tries to read from the inifile specified in the environment variable `PYCAOSDBINI` or
# Configuration of PyLinkAhead #
The behavior of PyLinkAhead is defined via a configuration that is provided using configuration files.
PyLinkAhead tries to read from the inifile specified in the environment variable `PYCAOSDBINI` or
alternatively in `~/.pycaosdb.ini` upon import. After that, the ini file `pycaosdb.ini` in the
current working directory will be read additionally, if it exists.
......@@ -10,7 +10,7 @@ it as a starting point.
Typically, you need to change at least the `url` and `username` fields as required. (Ask your
CaosDB administrator or IT crowd if you do not know what to put there, but for the demo instance at
LinkAhead administrator or IT crowd if you do not know what to put there, but for the demo instance at
https://demo.indiscale.com, `username=admin` and `password=caosdb` should work).
## Authentication ##
......@@ -46,7 +46,7 @@ username=YOUR_USERNAME
## SSL Certificate ##
In some cases (especially if you are testing CaosDB) you might need to supply an SSL certificate to
In some cases (especially if you are testing LinkAhead) you might need to supply an SSL certificate to
allow SSL encryption.
The `cacert` option sets the path to the ssl certificate for the connection:
......@@ -59,7 +59,7 @@ cacert=/path/to/caosdb.ca.pem
## Further Settings ##
`debug=0` ensures that debug information is **not** printed to the terminal every time you interact
with CaosDB which makes the experience much less verbose. Set it to 1 or 2 in case you want to help
with LinkAhead which makes the experience much less verbose. Set it to 1 or 2 in case you want to help
debugging (which I hope will not be necessary for this tutorial) or if you want to learn more about
the internals of the protocol.
......
# The future of the CaosDB Python Client
# The future of the LinkAhead Python Client
The current Python client has done us great services but its structure and the
way it is used sometimes feels outdated and clumsy. In this document we sketch
......@@ -47,7 +47,7 @@ function:
- `depth`: Maximum recursion depth
- `references`: Whether to use the supplied db.Container to resolve
references. This allows offline usage. Set it to None if you want to
automatically retrieve entities from the current CaosDB connection.
automatically retrieve entities from the current LinkAhead connection.
In order to allow a quick look at the object structures an easily readable
serialization is provided by the `to_dict` function. It has the following
......@@ -174,7 +174,7 @@ print("The new record has the ID:", inserted.id)
```
### Factory method
While creating an Entity will not talk to a CaosDB server and can thus be done offline, the factory method
While creating an Entity will not talk to a LinkAhead server and can thus be done offline, the factory method
`create_record` allows to
1. Retrieve the parent and set attributes according to inheritance
2. Use a container to resolve the parent and set attributes
......
......@@ -18,7 +18,7 @@ In the following, you'll learn how to
Prerequisites
-------------
This example needs some preparations regarding your CaosDB setup that have to
This example needs some preparations regarding your LinkAhead setup that have to
(or, for the sake of simplicity, should) be done outside the actual Python
example script.
......@@ -61,7 +61,7 @@ Clone the schemata into the same directory containing the below script via
$ git clone https://github.com/leibniz-zmt/zmt-metadata-schema.git
Furthermore, we'll need the `CaosDB Advanced User Tools
Furthermore, we'll need the `LinkAhead Advanced User Tools
<https://gitlab.com/caosdb/caosdb-advanced-user-tools>`_ for loading the
metadata schemata from the json files, so install them via
......@@ -109,13 +109,13 @@ Your complete ``global_entities_permissions.xml`` might then look like
.. note::
Note that you have to restart your CaosDB server after modifying the
Note that you have to restart your LinkAhead server after modifying the
``global_entities_permissions.xml``.
The code
--------
After having applied all of the above prerequisites and restarting your CaosDB
After having applied all of the above prerequisites and restarting your LinkAhead
server, execute the following code.
:download:`Download full code<curator_permissions.py>`
......
PyCaosDB Code Gallery
=====================
PyLinkAhead Code Gallery
========================
This chapter collects code examples which can be immediately run against an empty CaosDB instance.
This chapter collects code examples which can be immediately run against an empty LinkAhead instance.
.. note::
These examples require a configuration file with valid server and user/password settings. Refer
to the :ref:`Configuration <Configuration of PyCaosDB>` section for details.
to the :ref:`Configuration <Configuration of PyLinkAhead>` section for details.
.. toctree::
:maxdepth: 2
......
"""
Run a simulation and store the values into CaosDB.
Run a simulation and store the values into LinkAhead.
>>> main() # doctest: +ELLIPSIS
These distances resulted in small x,y, values:
......@@ -13,7 +13,7 @@ from caosadvancedtools.table_converter import to_table
def setup_caosdb():
"""Create the data model and insert it into CaosDB
"""Create the data model and insert it into LinkAhead
The data model consists of the following RecordTypes:
......@@ -35,7 +35,7 @@ def setup_caosdb():
The data model of course also contains the corresponding properties for these RecordTypes.
"""
cont = db.Container() # Container to insert all Entities at once into CaosDB
cont = db.Container() # Container to insert all Entities at once into LinkAhead
# create Properties
cont.append(db.Property("x", datatype=db.DOUBLE))
cont.append(db.Property("y", datatype=db.DOUBLE))
......@@ -74,7 +74,7 @@ def simulations(n, t_max):
# Get the parameters and result
initial, result = run_simulation(run=i, t_max=t_max)
# Prepare CaosDB insertion
# Prepare LinkAhead insertion
run = db.Record().add_parent("SoftwareRun").add_property("Software", value=software.id)
parameters = (db.Record().add_parent("Parameters").add_property("x", initial[0])
.add_property("y", initial[1]).add_property("z", initial[2]))
......@@ -83,7 +83,7 @@ def simulations(n, t_max):
run.add_property("Parameters", value=parameters).add_property("Result", value=result_record)
cont = db.Container()
cont.extend([run, parameters, result_record])
cont.insert() # Insert everything of this run into CaosDB.
cont.insert() # Insert everything of this run into LinkAhead.
def run_simulation(run, t_max):
......
......@@ -6,7 +6,7 @@ This code example
1. sets up the data model
2. runs simulations
3. stores the simulation parameters and results into CaosDB
3. stores the simulation parameters and results into LinkAhead
4. retrieves the parameters for interesting results.
:download:`Download code<simulation.py>`
......
* High Level API
In addition to the old standard pylib API, new versions of pylib ship with a high level API
that facilitates usage of CaosDB entities within data analysis scripts. In a nutshell that
API exposes all properties of CaosDB Records as standard python attributes making their
that facilitates usage of LinkAhead entities within data analysis scripts. In a nutshell that
API exposes all properties of LinkAhead Records as standard python attributes making their
access easier.
Or to spell it out directly in Python:
......@@ -38,9 +38,9 @@ Furthermore there are a few utility functions which expose very practical shorth
- ~create_record~: Create a new high level entity using the name of a record type and a list of key value pairs as properties.
- ~load_external_record~: Retrieve a record with a specific name and return it as high level entity.
- ~create_entity_container~: Convert a high level entity into a standard entity including all sub entities.
- ~query~: Do a CaosDB query and return the result as a container of high level objects.
- ~query~: Do a LinkAhead query and return the result as a container of high level objects.
So as a first example, you could retrieve any record from CaosDB and use it using its high level representation:
So as a first example, you could retrieve any record from LinkAhead and use it using its high level representation:
#+BEGIN_SRC python
from caosdb.high_level_api import query
......@@ -69,9 +69,9 @@ to achieve the same result:
#+END_SRC
Resolving subproperties makes use of the "resolve_reference" function provided by the high level
entity class (~CaosDBPythonEntity~), with the following parameters:
entity class (~LinkAheadPythonEntity~), with the following parameters:
- ~deep~: Whether to use recursive retrieval
- ~references~: Whether to use the supplied db.Container to resolve references. This allows offline usage. Set it to None if you want to automatically retrieve entities from the current CaosDB connection.
- ~references~: Whether to use the supplied db.Container to resolve references. This allows offline usage. Set it to None if you want to automatically retrieve entities from the current LinkAhead connection.
- ~visited~: Needed for recursion, set this to None.
Objects in the high level representation can be serialized to a simple yaml form using the function
......@@ -95,25 +95,25 @@ As described in the section [[Quickstart]] the two functions ~convert_to_python_
entities beetween the high level and the standard representation.
The high level entities are represented using the following classes from the module ~caosdb.high_level_api~:
- ~CaosDBPythonEntity~: Base class of the following entity classes.
- ~CaosDBPythonRecord~
- ~CaosDBPythonRecordType~
- ~CaosDBPythonProperty~
- ~CaosDBPythonMultiProperty~: **WARNING** Not implemented yet.
- ~CaosDBPythonFile~: Used for file entities and provides an additional ~download~ function for being able to directly retrieve files from CaosDB.
- ~LinkAheadPythonEntity~: Base class of the following entity classes.
- ~LinkAheadPythonRecord~
- ~LinkAheadPythonRecordType~
- ~LinkAheadPythonProperty~
- ~LinkAheadPythonMultiProperty~: **WARNING** Not implemented yet.
- ~LinkAheadPythonFile~: Used for file entities and provides an additional ~download~ function for being able to directly retrieve files from LinkAhead.
In addition, there are the following helper structures which are realized as Python data classes:
- ~CaosDBPropertyMetaData~: For storing meta data about properties.
- ~CaosDBPythonUnresolved~: The base class of unresolved "things".
- ~CaosDBPythonUnresolvedParent~: Parents of entities are stored as unresolved parents by default, storing an id or a name of a parent (or both).
- ~CaosDBPythonUnresolvedReference~: An unresolved reference is a reference property with an id which has not (yet) been resolved to an Entity.
- ~LinkAheadPropertyMetaData~: For storing meta data about properties.
- ~LinkAheadPythonUnresolved~: The base class of unresolved "things".
- ~LinkAheadPythonUnresolvedParent~: Parents of entities are stored as unresolved parents by default, storing an id or a name of a parent (or both).
- ~LinkAheadPythonUnresolvedReference~: An unresolved reference is a reference property with an id which has not (yet) been resolved to an Entity.
The function "resolve_references" can be used to recursively replace ~CaosDBPythonUnresolvedReferences~ into members of type ~CaosDBPythonRecords~
or ~CaosDBPythonFile~.
The function "resolve_references" can be used to recursively replace ~LinkAheadPythonUnresolvedReferences~ into members of type ~LinkAheadPythonRecords~
or ~LinkAheadPythonFile~.
Each property stored in a CaosDB record corresponds to:
- a member attribute of ~CaosDBPythonRecord~ **and**
- an entry in a dict called "metadata" storing a CaosDBPropertyMetadata object with the following information about proeprties:
Each property stored in a LinkAhead record corresponds to:
- a member attribute of ~LinkAheadPythonRecord~ **and**
- an entry in a dict called "metadata" storing a LinkAheadPropertyMetadata object with the following information about proeprties:
- ~unit~
- ~datatype~
- ~description~
......@@ -166,6 +166,6 @@ Records are created by the `create_record` function. Parameter values can be set
#+END_SRC
At any position in the algorithm you are free to:
- Convert this model to the standard python API and insert or update the records in a running instance of CaosDB.
- Serialize this model in the high level API yaml format. This enables the CaosDB crawler to pickup the file and synchronize it with a running instance
of CaosDB.
- Convert this model to the standard python API and insert or update the records in a running instance of LinkAhead.
- Serialize this model in the high level API yaml format. This enables the LinkAhead crawler to pickup the file and synchronize it with a running instance
of LinkAhead.
......@@ -2,15 +2,14 @@ High Level API
==============
In addition to the old standard pylib API, new versions of pylib ship
with a high level API that facilitates usage of CaosDB entities within
with a high level API that facilitates usage of LinkAhead entities within
data analysis scripts. In a nutshell that API exposes all properties of
CaosDB Records as standard python attributes making their access easier.
LinkAhead Records as standard python attributes making their access easier.
Or to speak it out directly in Python:
.. code:: python
import caosdb as db
# Old API:
r = db.Record()
......@@ -50,10 +49,10 @@ practical shorthands:
return it as high level entity.
- ``create_entity_container``: Convert a high level entity into a
standard entity including all sub entities.
- ``query``: Do a CaosDB query and return the result as a container of
- ``query``: Do a LinkAhead query and return the result as a container of
high level objects.
So as a first example, you could retrieve any record from CaosDB and use
So as a first example, you could retrieve any record from LinkAhead and use
it using its high level representation:
.. code:: python
......@@ -87,12 +86,12 @@ series of commands to achieve the same result:
Resolving subproperties makes use of the "resolve\ :sub:`reference`"
function provided by the high level entity class
(``CaosDBPythonEntity``), with the following parameters:
(``LinkAheadPythonEntity``), with the following parameters:
- ``deep``: Whether to use recursive retrieval
- ``references``: Whether to use the supplied db.Container to resolve
references. This allows offline usage. Set it to None if you want to
automatically retrieve entities from the current CaosDB connection.
automatically retrieve entities from the current LinkAhead connection.
- ``visited``: Needed for recursion, set this to None.
Objects in the high level representation can be serialized to a simple
......@@ -125,35 +124,35 @@ beetween the high level and the standard representation.
The high level entities are represented using the following classes from
the module ``caosdb.high_level_api``:
- ``CaosDBPythonEntity``: Base class of the following entity classes.
- ``CaosDBPythonRecord``
- ``CaosDBPythonRecordType``
- ``CaosDBPythonProperty``
- ``CaosDBPythonMultiProperty``: **WARNING** Not implemented yet.
- ``CaosDBPythonFile``: Used for file entities and provides an
- ``LinkAheadPythonEntity``: Base class of the following entity classes.
- ``LinkAheadPythonRecord``
- ``LinkAheadPythonRecordType``
- ``LinkAheadPythonProperty``
- ``LinkAheadPythonMultiProperty``: **WARNING** Not implemented yet.
- ``LinkAheadPythonFile``: Used for file entities and provides an
additional ``download`` function for being able to directly retrieve
files from CaosDB.
files from LinkAhead.
In addition, there are the following helper structures which are
realized as Python data classes:
- ``CaosDBPropertyMetaData``: For storing meta data about properties.
- ``CaosDBPythonUnresolved``: The base class of unresolved "things".
- ``CaosDBPythonUnresolvedParent``: Parents of entities are stored as
- ``LinkAheadPropertyMetaData``: For storing meta data about properties.
- ``LinkAheadPythonUnresolved``: The base class of unresolved "things".
- ``LinkAheadPythonUnresolvedParent``: Parents of entities are stored as
unresolved parents by default, storing an id or a name of a parent
(or both).
- ``CaosDBPythonUnresolvedReference``: An unresolved reference is a
- ``LinkAheadPythonUnresolvedReference``: An unresolved reference is a
reference property with an id which has not (yet) been resolved to an
Entity.
The function "resolve\ :sub:`references`" can be used to recursively
replace ``CaosDBPythonUnresolvedReferences`` into members of type
``CaosDBPythonRecords`` or ``CaosDBPythonFile``.
replace ``LinkAheadPythonUnresolvedReferences`` into members of type
``LinkAheadPythonRecords`` or ``LinkAheadPythonFile``.
Each property stored in a CaosDB record corresponds to:
Each property stored in a LinkAhead record corresponds to:
- a member attribute of ``CaosDBPythonRecord`` **and**
- an entry in a dict called "metadata" storing a CaosDBPropertyMetadata
- a member attribute of ``LinkAheadPythonRecord`` **and**
- an entry in a dict called "metadata" storing a LinkAheadPropertyMetadata
object with the following information about proeprties:
- ``unit``
......
Welcome to PyCaosDB's documentation!
====================================
Welcome to PyLinkAhead's documentation!
=======================================
.. toctree::
:maxdepth: 2
......@@ -16,7 +16,7 @@ Welcome to PyCaosDB's documentation!
Code gallery <gallery/index>
API documentation<_apidoc/caosdb>
This is the documentation for the Python client library for CaosDB, ``PyCaosDB``.
This is the documentation for the Python client library for LinkAhead, ``PyLinkAhead``.
This documentation helps you to :doc:`get started<README_SETUP>`, explains the most important
:doc:`concepts<concepts>` and offers a range of :doc:`tutorials<tutorials/index>`.
......
......@@ -4,12 +4,12 @@ Data Insertion
Data Models
~~~~~~~~~~~
Data is stored and structured in CaosDB using a concept of RecordTypes, Properties, Records etc. If
you do not know what these are, please look at the chapter :doc:`Data
Model<caosdb-server:Data-Model>` in the CaosDB server documentation.
Data is stored and structured in LinkAhead using a concept of RecordTypes, Properties, Records etc.
If you do not know what these are, please look at the chapter :doc:`Data
Model<caosdb-server:Data-Model>` in the LinkAhead server documentation.
In order to insert some actual data, we need to create a data model
using RecordTypes and Properties (You may skip this if you use a CaosDB
using RecordTypes and Properties (You may skip this if you use a LinkAhead
instance that already has the required types). When you create a new Property
you must supply a datatype. So, let’s create a simple
Property called “a” of datatype double. This is very easy in pylib:
......@@ -65,13 +65,13 @@ all properties of the parent RecordType with the chosen importance (and properti
importance) to the child RecordType
automatically upon insertion. See the chapter on `importance
<https://docs.indiscale.com/caosdb-server/specification/RecordType.html#importance>`_ in the
documentation of the CaosDB server for more information on the importance and inheritance of
documentation of the LinkAhead server for more information on the importance and inheritance of
properties.
.. note::
The inherited properties will only be visible after the insertion since they are set by the
CaosDB server, not by the Python client.
LinkAhead server, not by the Python client.
Insert Actual Data
......@@ -111,7 +111,7 @@ record as its source data. Since we know that the id of the experiment record is
The experiment record's id is used as the value of the ``Experiment`` property
of the analysis Record (note how we use the RecordType ``Experiment`` as a
``REFERENCE`` property here). Sending a CaosDB query like ``FIND RECORD
``REFERENCE`` property here). Sending a LinkAhead query like ``FIND RECORD
Experiment WHICH IS REFERENCED BY A Analysis WITH date=2020-01-08`` would now
return our original experiment record.
......@@ -141,7 +141,7 @@ Finally, we can also insert both records at the same time using a
cont = db.Container().extend([rec, ana]) # Add experiment and analysis
# records to our container
cont.insert() # Insert both at the same time, the CaosDB server will
cont.insert() # Insert both at the same time, the LinkAhead server will
# resolve the reference upon insertion.
All three ways result in an Analysis record which references an Experiment
......
......@@ -2,7 +2,7 @@
Entity Getters
==============
There is a very frequent situation when working with PyCaosDB: You need to get a specific Entity
There is a very frequent situation when working with PyLinkAhead: 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:
......
......@@ -11,7 +11,7 @@ If you have not yet, configure a connection with the demo instance. E.g.:
... username="admin",
... password="caosdb")
A basic Analysis of data in CaosDB could start like:
A basic Analysis of data in LinkAhead could start like:
>>>
>>> analyses = db.execute_query("FIND RECORD Analysis with quality_factor")
......
......@@ -21,7 +21,7 @@ function, easily created from ``get_entity_by_name`` using Python's ``lru_cache`
# reset the cache with
cached_get_by_name.cache_clear()
For convenience, PyCaosDB provides the ``caosdb.cached`` module that defines the functions
For convenience, PyLinkAhead provides the ``caosdb.cached`` module that defines the functions
``cached_query`` and ``cached_get_entity_by``, they use a shared cache. Let's have a look:
.. code:: python
......
Complex Data Models
-------------------
With CaosDB it is possible to create very complex data models.
With LinkAhead it is possible to create very complex data models.
E.g. it is possible to add properties to properties to cover complex relations
in data management workflows.
......
......@@ -8,12 +8,12 @@ pip3 install --user --no-deps .
```
in
```bash
CaosDB/data_models
LinkAhead/data_models
```
Change to the appropriate directory
```bash
cd CaosDB/data_models
cd LinkAhead/data_models
```
There are "data models" defined in
```bash
......
......@@ -3,9 +3,9 @@ Error Handling
==============
In case of erroneous transactions, connection problems and a lot of
other cases, PyCaosDB may raise specific errors in order to pinpoint
other cases, PyLinkAhead may raise specific errors in order to pinpoint
the problem as precisely as possible. Some of these errors a
representations of errors in the CaosDB server, others stem from
representations of errors in the LinkAhead server, others stem from
problems that occurred on the client side.
The errors and exceptions are ordered hierarchically form the most
......@@ -16,20 +16,20 @@ following. For more information on specific error types, see also the
.. note::
Starting from PyCaosDB 0.5, the error handling has changed
Starting from PyLinkAhead 0.5, the error handling has changed
significantly. New error classes have been introduced and the
behavior of ``TransactionError`` and ``EntityError`` has been
re-worked. In the following, only the "new" errors are
discussed. Please refer to the documentation of PyCaosDB 0.4.1 and
discussed. Please refer to the documentation of PyLinkAhead 0.4.1 and
earlier for the old error handling.
CaosDBException
----------------
LinkAheadException
------------------
``CaosDBException`` is the most generic exception and all other error classes inherit
``LinkAheadException`` is the most generic exception and all other error classes inherit
from this one. Because of its generality, it doesn't tell you much
except that some component of PyCaosDB raised an exception. If you
want to catch all possible CaosDB errors, this is the class to use.
except that some component of PyLinkAhead raised an exception. If you
want to catch all possible LinkAhead errors, this is the class to use.
TransactionError
----------------
......@@ -116,7 +116,7 @@ HTTP Errors
-----------
An ``HTTPClientError`` or an ``HTTPServerError`` is raised in case of
http(s) connection problems caused by the Python client or the CaosDB
http(s) connection problems caused by the Python client or the LinkAhead
server, respectively. There are the following subclasses of
``HTTPClientError`` that are used to specify the connection problem:
......@@ -130,7 +130,7 @@ server, respectively. There are the following subclasses of
Other Errors
------------
There are further subclasses of ``CaosDBException`` that are raised in
There are further subclasses of ``LinkAheadException`` that are raised in
case of faulty configurations or other problems. They should be rather
self-explanatory from their names; see the :doc:`source code<../_apidoc/caosdb.exceptions>`
for further information.
......
First Steps
===========
You should have a working connection to a CaosDB instance now. If not, please check out the
You should have a working connection to a LinkAhead instance now. If not, please check out the
:doc:`Getting Started secton</README_SETUP>`.
If you are not yet familiar with Records, RecordTypes and Properties used in CaosDB,
If you are not yet familiar with Records, RecordTypes and Properties used in LinkAhead,
please check out the respective part in the `Web Interface tutorial`_.
You should also know the basics of the CaosDB Query Language (a tutorial is
You should also know the basics of the LinkAhead Query Language (a tutorial is
`here <https://docs.indiscale.com/caosdb-webui/tutorials/query.html>`_).
We recommend that you connect to the `demo instance`_ (hosted by `Indiscale`_) in order to try out
......@@ -120,7 +120,7 @@ If the files are large data files, it is often a better idea to only retrieve th
Summary
-------
Now you know how to use Python to send queries to CaosDB and you can access
Now you know how to use Python to send queries to LinkAhead and you can access
the result Records and their properties.
The next tutorial shows how to make some meaningful use of this.
......
PyCaosDB Tutorials
==================
PyLinkAhead Tutorials
=====================
This chapter contains tutorials that lead you from the first steps to
advanced usage of the Python client.
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment