pyquo is a library which offers bindings for the quolab REST API in python.
pyquo is designed to be compatbile with both python2 and python3
$ pip install pyquo
There are two ways of authenticating against Quolab's API. The first
method is using the UserAuthenticator which uses BasicAuth
.
from pyquo.authenticator import UserAuthenticator
auth = UserAuthenticator(username='user', password='pass')
However, the prefered way of authenticating would be by using the
TokenAuthenticator
.
from pyquo.authenticator import TokenAuthenticator
auth = TokenAuthenticator(token='your-token-here')
In order to generate a token the following pyquo code can be used:
from pyquo.Session import Session
from pyquo.authenticator import UserAuthenticator, TokenAuthenticator
session = Session(
base_url="https://qlab.quo/",
global_session=True,
auth=UserAuthenticator(username="<username>", password="<password>")
)
print(TokenAuthenticator.create_token(session, "1y"))
For more information on the expires_in
(e.g. 1y = 1 year) field, please
consult the quolab REST API documentation
In order to interact with the quolab api, a Session
instance is required. This
can be created as follows:
from pyquo.session import Session
s = Session(base_url="https://<url>/", global_session=True, auth=auth, verify=False)
When interacting with a single quolab instance, it is recommended to set
global_session
to True
. When interacting with multiple sessions at once,
e.g. retreiving information mutliple nodes, you will be required to store the
session, and pass it around with your queries.
pyquo implements (sys-)facts, (sys-)references and annotations as pyquo.model object instances. For example, a case model can be created as follows:
[In:] from pyquo.models import Case
[In:] case = Case(id='2981693283194043a185c0cc9412ad83')
[Out:] case(2981693283194043a185c0cc9412ad83)
case
is a 'handle' object for the case with the case id
'2981693283194043a185c0cc9412ad83'. This handle can now be used to perform
read/store/update/delete operations on the case.
[In:] case.get()
[In:] case.name
[Out:] "Fancy case name"
[In:] case.name = "Renamed case"
[In:] case.save()
[In:] case.get().name
[Out:] "Renamed case"
(Sys-)Facts can have incoming and outgoing (sys-)references, which can be queried as follows:
[In:] references = case.references()
[Out:] [case(2981693283194043a185c0cc9412ad83)→associated-with→user(test),
case(2981693283194043a185c0cc9412ad83)→encases→ipynb(Untitled1.ipynb)]
This will show all outgoing references. In order to show incoming references,
the incoming
parameter needs to be set to True
(case.references(incoming=True)
)
It is possible to filter for sysrefs
using fact.references(refs=SysRef)
.
Further the associated facts behind the references can be filtered (e.g. Files and Mutexes only) using:
[In:] fact.references(facts=(models.File, models.Mutex))
While the reference type can also be filtered using:
[In:] fact.references[models.Contains](facts=(models.File, models.Mutex))
The obtained references have a source
and a target
property which resolves
to an instance of the related fact. E.g.
[In:] reference
[Out:] case(2981693283194043a185c0cc9412ad83)→encases→ipynb(Untitled1.ipynb)
[In:] reference.source
[Out:] case(2981693283194043a185c0cc9412ad83)
[In:] reference.target
[Out:] ipynb(Untitled1.ipynb)
It is also possible to obtain the source
and target
facts directly, by
using the properties fact.ancestors
and fact.descendants
.
Fact annotations can be queries as follows:
fact.annotations(annotations=pyquo.models.KnownAs, limit=3)
annotations=<pyquo.Model>
allows serverside filtering for annotations of a
given type, while limit=1
allows limiting the number of results returned by a
given query.
From time to time it can occur that pyquo is not flexible enough to cover each and every usecase/api feature which is why raw queries have been made possible in pyquo:
from pyquo.session import Query
foo = {
"class": "annotation",
"type": "known-as",
"aggregate": "first",
"fact": {
"type": "function",
"id": [f.id for f in functions],
"aggregate": "group"
}
}
for i in Query.generate(foo, session):
print(i)
print(Query.execute(foo, session))
The Query.generate(foo, session)
method will execute the given query and
return a deserialized pyquo object, while result = Query.execute(foo, session)
will return the raw query result as a dictionary.
Furhter examples can be found here Example.md