.. -*- coding: utf-8 -*-
=============
CwClientLib
=============
Summary
-------
A Python library to easily build CubicWeb_ clients:
* execute RQL_ queries remotely (using rqlcontroller_),
* access instances that requires authentication (using signedrequest_).
It also provides a simple command line tool (cwrql) to execute simple requests.
Requirements
------------
client side:
- requests_ (>= 2.0)
server side:
- CubicWeb (>= 3.18.3) with the cubes rqlcontroller_ and signedrequest_
Configuration
-------------
``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:
.. code-block:: bash
david@perseus:~$ cat ~/.config/cwclientlibrc
[cwo]
url = https://www.cubicweb.org/
token-id = my_cwo_token
secret = <my-secret>
[elo]
url = https://www.logilab.org
token-id = my_elo_token
secret = <my-secret>
makes it possible to write:
.. code-block:: bash
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": "http://download.logilab.org/pub/projman",
"cwuri": "http://www.logilab.org/873",
"__cwetype__": "Project",
"eid": 1251664,
"creation_date": "2006/09/28 17:44:38",
"homepage": null,
"debian_source_package": null,
"name": "projman"}]
or:
.. code-block:: python
from cwclientlib import cwproxy_for
client = cwproxy_for('cwo')
# or client = cwproxy_for('https://www.cubicweb.org/')
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:
#. View a ``CWUser`` and click the action ``add an AuthToken``
#. Give an identifier to the token and make it enabled
#. Use the token identifier and the token in your source code
Configuration
-------------
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:
.. code-block:: ini
[cwo]
url = https://www.cubicweb.org/
token-id = my token id
secret = <my secret>
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:
.. code-block:: bash
david@perseus:~$ cwrql -h
Usage: cwrql [options] (url|instance_id) rqlquery [rqlquery2] ...
Options:
-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
given
-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):
.. code-block:: bash
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:
.. code-block:: bash
david@perseus:~$ cwshell cwo
You are connected to https://www.cubicweb.org
>>> 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:
.. code-block:: python
from cwclientlib import cwproxy
client = cwproxy.CWProxy('http://www.cubicweb.org/')
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:
.. code-block:: python
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:
.. code-block:: python
from cwclientlib import cwproxy
auth = cwproxy.SignedRequestAuth('my token', '6ed44d82172211e49d9777269ec78bae')
client = cwproxy.CWProxy('https://www.cubicweb.org/', 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_:
.. code-block:: python
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()
.. _CubicWeb: http://www.cubicweb.org/
.. _RQL: http://docs.cubicweb.org/annexes/rql/language
.. _rqlcontroller: http://www.cubicweb.org/project/cubicweb-rqlcontroller/
.. _signedrequest: http://www.cubicweb.org/project/cubicweb-signedrequest/
.. _requests: http://docs.python-requests.org/en/latest/
Raw data
{
"_id": null,
"home_page": "https://forge.extranet.logilab.fr/cubicweb/cwclientlib",
"name": "cwclientlib",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9.2",
"maintainer_email": null,
"keywords": null,
"author": "LOGILAB S.A. (Paris, FRANCE)",
"author_email": "contact@logilab.fr",
"download_url": "https://files.pythonhosted.org/packages/f4/8c/441419ceff6c914fb1dcb2b887efbebc894e46fd8270477e89d228796612/cwclientlib-1.4.3.tar.gz",
"platform": null,
"description": ".. -*- coding: utf-8 -*-\n\n=============\n CwClientLib\n=============\n\nSummary\n-------\n\nA Python library to easily build CubicWeb_ clients:\n\n* execute RQL_ queries remotely (using rqlcontroller_),\n* access instances that requires authentication (using signedrequest_).\n\nIt also provides a simple command line tool (cwrql) to execute simple requests.\n\nRequirements\n------------\n\nclient side:\n\n- requests_ (>= 2.0)\n\nserver side:\n\n- CubicWeb (>= 3.18.3) with the cubes rqlcontroller_ and signedrequest_\n\n\nConfiguration\n-------------\n\n``cwclientlib`` implements a ``cwproxy_for(instance)`` function that\nwill build a ``CWProxy`` for the given instance, reading\nauthentication credentials from a configuration file (can be a ini\nfile, json or yaml). The default configuration file name is\n`~/.config/cwclientlibrc` (using the ini file format), but this can be\nchanged using the ``CWCLCONF`` environment variable. For example:\n\n.. code-block:: bash\n\n david@perseus:~$ cat ~/.config/cwclientlibrc\n [cwo]\n url = https://www.cubicweb.org/\n token-id = my_cwo_token\n secret = <my-secret>\n\n [elo]\n url = https://www.logilab.org\n token-id = my_elo_token\n secret = <my-secret>\n\nmakes it possible to write:\n\n.. code-block:: bash\n\n david@perseus:~$ cwrql cwo \"Any N,S WHERE P eid 1251664, P name N, P summary S\"\n projman a project management tool\n\n david@perseus:~$ cwrql -v ejsonexport -j cwo \"Any P WHERE P eid 1251664\"\n [{\"description\": \"It reads project descriptions [...]\",\n \"modification_date\": \"2015/02/13 18:12:40\",\n \"icon_format\": null,\n \"description_format\": \"text/rest\",\n \"summary\": \"a project management tool\",\n \"downloadurl\": \"http://download.logilab.org/pub/projman\",\n \"cwuri\": \"http://www.logilab.org/873\",\n \"__cwetype__\": \"Project\",\n \"eid\": 1251664,\n \"creation_date\": \"2006/09/28 17:44:38\",\n \"homepage\": null,\n \"debian_source_package\": null,\n \"name\": \"projman\"}]\n\nor:\n\n.. code-block:: python\n\n from cwclientlib import cwproxy_for\n\n client = cwproxy_for('cwo')\n # or client = cwproxy_for('https://www.cubicweb.org/')\n query = 'Any X WHERE X is Ticket, X concerns P, P name \"cwclientlib\"'\n resp = client.rql(query)\n data = resp.json()\n\nNote that the config file may contain credentials, so its permissions\nmust be readable only by the user (checked on posix platforms only).\n\n\nUsing signed requests\n---------------------\n\nOnce the cube signedrequest_ is added, in the WebUI:\n\n#. View a ``CWUser`` and click the action ``add an AuthToken``\n#. Give an identifier to the token and make it enabled\n#. Use the token identifier and the token in your source code\n\n\nConfiguration\n-------------\n\nYou can define url and credentials for commonly used cubicweb\nendpoints in a config file. By default, on Linux, it will be a ini\nfile located at ``$HOME/.config/cwclientlibrc`` but you may define the\n``CWCLCONF`` environmentvariable to specify it. This config file can\nalso be a YAML (file name must end with .yaml) or a JSON file (.json).\n\nThe file will look like:\n\n.. code-block:: ini\n\n [cwo]\n url = https://www.cubicweb.org/\n token-id = my token id\n secret = <my secret>\n\n\nCommand line tools\n------------------\n\ncwclientlib comes with 3 simple command-line tools allowing to easily\nrequest a cubicweb application from a shell:\n\n`cwrql` to make RQL queries:\n\n.. code-block:: bash\n\n david@perseus:~$ cwrql -h\n Usage: cwrql [options] (url|instance_id) rqlquery [rqlquery2] ...\n\n Options:\n -h, --help show this help message and exit\n -j, --json produce JSON data\n -v VID, --vid=VID vid to use (default is jsonexport)\n -S, --no-ssl do NOT verify ssl server certificate; ignored if --ca is\n given\n -c CA, --ca=CA Bundle CA to use to verify server certificate\n -w, --rqlio use rqlio\n david@perseus:~$ cwrql cwo \"Any VN, VS WHERE V version_of P,\n > P name 'cwclientlib', V num VN, V in_state S, S name VS\"\n 0.2.1 published\n 0.3.0 dev\n 0.2.0 published\n 0.1.0 published\n\n`cwget` to make any king of GET request (ie. call a specific cubicweb controller):\n\n.. code-block:: bash\n\n david@perseus:~$ cwget cwo /testconfig/1251730 \\\n vid=apycot.get_configuration environment=4209277\n [{\"pylint_threshold\": \"7\", \"install\": \"python_setup\", \"pycoverage_threshold\": \"70\"}]\n\n`cwshell` to connect to a cubicweb endopint and start an interactive\npython shell with a few additional builtins ``rql`` and\n``client``. This shell also provides RQL auto-completion:\n\n.. code-block:: bash\n\n david@perseus:~$ cwshell cwo\n You are connected to https://www.cubicweb.org\n >>> client.execute('Any X WHERE X is P\n Patch Plan Project ProjectEnvironment\n >>> 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\"')\n [[u'cubicweb-pyramid', u'0.2.0'], [u'cubicweb-simplefacet', u'0.3.2']]\n >>>\n\nAvailable extra builtins:\n\n:client: is the CWProxy instance connected to the cubicweb endpoint.\n\n:rql: shortcut for ``client.execute()``.\n\n\n\nPython examples\n---------------\n\nSimple read only query:\n\n.. code-block:: python\n\n from cwclientlib import cwproxy\n\n client = cwproxy.CWProxy('http://www.cubicweb.org/')\n query = 'Any X WHERE X is Ticket, X concerns P, P name \"cwclientlib\"'\n resp = client.rql(query)\n data = resp.json()\n\nCreating an entity, authenticating with signedrequest_ with\ncredentials read from the config file:\n\n.. code-block:: python\n\n from cwclientlib import cwproxy_for\n\n client = cwproxy_for('cwo')\n queries = [('INSERT CWUser U: U login %(l)s, U upassword %(p)s',\n {'l': 'Babar', 'p': 'cubicweb rulez & 42'}), ]\n resp = client.rqlio(queries)\n data = resp.json()\n\nCreating an entity, authenticating with signedrequest_ building the\nauthentifier by hand:\n\n.. code-block:: python\n\n from cwclientlib import cwproxy\n\n auth = cwproxy.SignedRequestAuth('my token', '6ed44d82172211e49d9777269ec78bae')\n client = cwproxy.CWProxy('https://www.cubicweb.org/', auth)\n queries = [('INSERT CWUser U: U login %(l)s, U upassword %(p)s',\n {'l': 'Babar', 'p': 'cubicweb rulez & 42'}), ]\n resp = client.rqlio(queries)\n data = resp.json()\n\nCreating a file entity, authenticating with signedrequest_:\n\n.. code-block:: python\n\n from io import BytesIO\n from cwclientlib import cwproxy_for\n\n client = cwproxy_for('cwo')\n queries = [('INSERT File F: F data %(content)s, F data_name %(fname)s',\n {'content': BytesIO('some binary data'), 'fname': 'toto.bin'})]\n resp = client.rqlio(queries)\n data = resp.json()\n\n.. _CubicWeb: http://www.cubicweb.org/\n.. _RQL: http://docs.cubicweb.org/annexes/rql/language\n.. _rqlcontroller: http://www.cubicweb.org/project/cubicweb-rqlcontroller/\n.. _signedrequest: http://www.cubicweb.org/project/cubicweb-signedrequest/\n.. _requests: http://docs.python-requests.org/en/latest/\n",
"bugtrack_url": null,
"license": "LGPL",
"summary": "A Python library to easily build CubicWeb clients",
"version": "1.4.3",
"project_urls": {
"Homepage": "https://forge.extranet.logilab.fr/cubicweb/cwclientlib"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1a8d288224d4b5935f509cddc99caad27353f44ce3b35e74442ada4dbc582bf2",
"md5": "071ed8842a4f9c82c34fcf06b2e10afb",
"sha256": "9a0466c17688d7107873e13583ea95f7d151002298ac0664dbdd9ac0bd4b6962"
},
"downloads": -1,
"filename": "cwclientlib-1.4.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "071ed8842a4f9c82c34fcf06b2e10afb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9.2",
"size": 43246,
"upload_time": "2024-11-06T11:22:45",
"upload_time_iso_8601": "2024-11-06T11:22:45.735105Z",
"url": "https://files.pythonhosted.org/packages/1a/8d/288224d4b5935f509cddc99caad27353f44ce3b35e74442ada4dbc582bf2/cwclientlib-1.4.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f48c441419ceff6c914fb1dcb2b887efbebc894e46fd8270477e89d228796612",
"md5": "303165053a2275d704caa8c58cb4c9a7",
"sha256": "6c6a6ff56c3ede39be9ba133217e7db65d431bec5e96145cc3205d4c15ab86b3"
},
"downloads": -1,
"filename": "cwclientlib-1.4.3.tar.gz",
"has_sig": false,
"md5_digest": "303165053a2275d704caa8c58cb4c9a7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9.2",
"size": 38402,
"upload_time": "2024-11-06T11:22:47",
"upload_time_iso_8601": "2024-11-06T11:22:47.707295Z",
"url": "https://files.pythonhosted.org/packages/f4/8c/441419ceff6c914fb1dcb2b887efbebc894e46fd8270477e89d228796612/cwclientlib-1.4.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-06 11:22:47",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "cwclientlib"
}
JSON