Skip to main content

A Python library to easily build CubicWeb clients

Project description


A Python library to easily build CubicWeb clients:

It also provides a simple command line tool (cwrql) to execute simple requests.


client side:

server side:


cwclientlib implements a cwproxy_for(instance) function that will build a CWProxy for the given instance, reading authentication credentials from a configuration file (can be a ini file, json or yaml). The default configuration file name is ~/.config/cwclientlibrc (using the ini file format), but this can be changed using the CWCLCONF environment variable. For example:

david@perseus:~$ cat ~/.config/cwclientlibrc
url =
token-id = my_cwo_token
secret = <my-secret>

url =
token-id = my_elo_token
secret = <my-secret>

url = https://my.intranet/activites
auth-mech = kerberos

makes it possible to write:

david@perseus:~$ cwrql cwo "Any N,S WHERE P eid 1251664, P name N, P summary S"
projman a project management tool

david@perseus:~$ cwrql -v ejsonexport -j cwo "Any P WHERE P eid 1251664"
[{"description": "It reads project descriptions [...]",
"modification_date": "2015/02/13 18:12:40",
"icon_format": null,
"description_format": "text/rest",
"summary": "a project management tool",
"downloadurl": "",
"cwuri": "",
"__cwetype__": "Project",
"eid": 1251664,
"creation_date": "2006/09/28 17:44:38",
"homepage": null,
"debian_source_package": null,
"name": "projman"}]


from cwclientlib import cwproxy_for

client = cwproxy_for('cwo')
# or client = cwproxy_for('')
query = 'Any X WHERE X is Ticket, X concerns P, P name "cwclientlib"'
resp = client.rql(query)
data = resp.json()

Note that the config file may contain credentials, so its permissions must be readable only by the user (checked on posix platforms only).

Using signed requests

Once the cube signedrequest is added, in the WebUI:

  1. View a CWUser and click the action add an AuthToken
  2. Give an identifier to the token and make it enabled
  3. Use the token identifier and the token in your source code

Using Kerberos

Just make sure Python-Kerberos and Requests-Kerberos are installed. The cubicweb server must, indeed, support kerberos-based authentication.


You can define url and credentials for commonly used cubicweb endpoints in a config file. By default, on Linux, it will be a ini file located at $HOME/.config/cwclientlibrc but you may define the CWCLCONF environmentvariable to specify it. This config file can also be a YAML (file name must end with .yaml) or a JSON file (.json).

The file will look like:

url =
token-id = my token id
secret = <my secret>

url = https://my.intranet
auth-mech = kerberos
server-ca = /path/to/ca-bundle.pem

Command line tools

cwclientlib comes with 3 simple command-line tools allowing to easily request a cubicweb application from a shell:

cwrql to make RQL queries:

david@perseus:~$ cwrql -h
Usage: cwrql [options] (url|instance_id) rqlquery [rqlquery2] ...

  -h, --help         show this help message and exit
  -j, --json         produce JSON data
  -v VID, --vid=VID  vid to use (default is jsonexport)
  -S, --no-ssl       do NOT verify ssl server certificate; ignored if --ca is
  -c CA, --ca=CA     Bundle CA to use to verify server certificate
  -w, --rqlio        use rqlio
david@perseus:~$ cwrql  cwo  "Any VN, VS WHERE V version_of P,
> P name 'cwclientlib', V num VN, V in_state S, S name VS"
0.2.1 published
0.3.0 dev
0.2.0 published
0.1.0 published

cwget to make any king of GET request (ie. call a specific cubicweb controller):

david@perseus:~$ cwget cwo /testconfig/1251730 \
vid=apycot.get_configuration  environment=4209277
[{"pylint_threshold": "7", "install": "python_setup", "pycoverage_threshold": "70"}]

cwshell to connect to a cubicweb endopint and start an interactive python shell with a few additional builtins rql and client. This shell also provides RQL auto-completion:

david@perseus:~$ cwshell cwo
You are connected to
>>> client.execute('Any X WHERE X is P
Patch               Plan                Project             ProjectEnvironment
>>> rql('Any P, N WHERE X is Project, X name P ,V version_of X, V in_state S, V num N, S name "ready"')
[[u'cubicweb-pyramid', u'0.2.0'], [u'cubicweb-simplefacet', u'0.3.2']]

Available extra builtins:

client:is the CWProxy instance connected to the cubicweb endpoint.
rql:shortcut for client.execute().

Python examples

Simple read only query:

from cwclientlib import cwproxy

client = cwproxy.CWProxy('')
query = 'Any X WHERE X is Ticket, X concerns P, P name "cwclientlib"'
resp = client.rql(query)
data = resp.json()

Creating an entity, authenticating with signedrequest with credentials read from the config file:

from cwclientlib import cwproxy_for

client = cwproxy_for('cwo')
queries = [('INSERT CWUser U: U login %(l)s, U upassword %(p)s',
            {'l': 'Babar', 'p': 'cubicweb rulez & 42'}), ]
resp = client.rqlio(queries)
data = resp.json()

Creating an entity, authenticating with signedrequest building the authentifier by hand:

from cwclientlib import cwproxy

auth = cwproxy.SignedRequestAuth('my token', '6ed44d82172211e49d9777269ec78bae')
client = cwproxy.CWProxy('', auth)
queries = [('INSERT CWUser U: U login %(l)s, U upassword %(p)s',
            {'l': 'Babar', 'p': 'cubicweb rulez & 42'}), ]
resp = client.rqlio(queries)
data = resp.json()

Creating a file entity, authenticating with signedrequest:

from io import BytesIO
from cwclientlib import cwproxy_for

client = cwproxy_for('cwo')
queries = [('INSERT File F: F data %(content)s, F data_name %(fname)s',
            {'content': BytesIO('some binary data'), 'fname': 'toto.bin'})]
resp = client.rqlio(queries)
data = resp.json()

Using builders helpers, authenticating explicitely with the kerberos authentifier:

from cwclientlib import cwproxy, builders
from requests_kerberos import HTTPKerberosAuth, OPTIONAL

auth = HTTPKerberosAuth(mutual_authentication=OPTIONAL)
client = cwproxy.CWProxy('', auth)
queries = [builders.create_entity('CWUser', login='Babar', upassword='secret'),
           ('SET U in_group G WHERE U eid %(eid)s, G name "users"', {'eid': '__r0'}),
resp = client.rqlio(queries)
data = resp.json()

Project details

Release history Release notifications

This version
History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
cwclientlib-0.5.2.tar.gz (30.1 kB) Copy SHA256 hash SHA256 Source None Jan 13, 2017

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page