Client Library for Nuxeo API
----------------------------
|Build Status| |Quality| |Coverage|
The Nuxeo Python Client is a Python client library for the Nuxeo
Automation and REST API. It works with Python 3.6+.
This is an ongoing project, supported by Nuxeo.
Getting Started
---------------
The installation is as simple as:
.. code:: shell
python -m pip install -U --user nuxeo
The client can make use of the Amazon S3 provider, to install its requirements:
.. code:: shell
python -m pip install -U --user "nuxeo[s3]"
The client is compatible with OAuth2 mechanism, to install its requirements:
.. code:: shell
python -m pip install -U --user "nuxeo[oauth2]"
And to install several flavors of requirements:
.. code:: shell
python -m pip install -U --user "nuxeo[oauth2, s3]"
Import
------
Then, use the following ``import`` statement to have access to the Nuxeo
API:
.. code:: python
from nuxeo.client import Nuxeo
Documentation
-------------
Check out the `API documentation <https://nuxeo.github.io/nuxeo-python-client/latest/>`__.
Requirements
------------
The Nuxeo Python client works only with:
- the Nuxeo Platform >= LTS 2015
- ``requests`` >= 2.12.2 (for unicode authentication)
- ``setuptools`` >= 30.3.0
Quick Start
-----------
This quick start guide will show how to do basics operations using the
client.
Connect to the Nuxeo Platform
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The easiest way to connect to the Nuxeo Platform with a basic authentication
is passing a tuple containing the ``username`` and the ``password`` to the
client, like so:
.. code:: python
nuxeo = Nuxeo(auth=('Administrator', 'Administrator'))
You can then use the ``nuxeo`` object to interact with the Platform. If you want
to use a specific instance, you can specify the ``base_url`` like so:
.. code:: python
nuxeo = Nuxeo(
host='http://demo.nuxeo.com/nuxeo/',
auth=('Administrator', 'Administrator')
)
Download/Upload Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In the `nuxeo/constants.py <nuxeo/constants.py>`__ file, you have several constants that are
used throughout the client that you can change to fit your needs. Some of them are:
- ``CHECK_PARAMS`` (False by default), to check operation's parameters for each and every HTTP calls.
- ``CHUNK_LIMIT`` (10 MiB by default), the size above which the upload will automatically be chunked.
- ``CHUNK_SIZE`` (8 KiB by default), the size of the chunks when downloading.
- ``MAX_RETRY`` (5 by default), the number of retries for connection error on any HTTP call.
- ``UPLOAD_CHUNK_SIZE`` (20 MiB by default), the size of the chunks when uploading.
Run NXQL Queries
~~~~~~~~~~~~~~~~
You can run queries in NXQL (NXQL is a subset of SQL,
you can check how to use it `in the documentation <https://doc.nuxeo.com/nxdoc/nxql/>`__).
Here, we are first `fetching a workspace <documents.rst>`__, and then using its
``uid`` to build a query which will find all its children that have a ``File``
or ``Picture`` type, and are not deleted.
.. code:: python
# Fetch a workspace
ws = nuxeo.documents.get(path='/default-domain/workspaces/ws')
# Build a query using its UID
nxql = ("SELECT * FROM Document WHERE ecm:ancestorId = '{uid}'"
" AND ecm:primaryType IN ('File', 'Picture')"
" AND ecm:currentLifeCycleState != 'deleted'")
query = nxql.format(uid=ws.uid)
# Make the request
search = nuxeo.client.query(query, params={'properties': '*'})
# Get results
entries = search['entries']
``entries`` will be a ``list`` containing a ``dict`` for each
element returned by the query.
Usage
~~~~~
Now that your client is set up, here are pages to help you with the
main functions available:
- `Available authentication mechanisms <examples/authentication.rst>`__
- `Manage users and groups <examples/users_and_groups.rst>`__
- `Work with documents <examples/documents.rst>`__
- `Work with directories <examples/directories.rst>`__
- `Work with blobs <examples/blobs.rst>`__
- `Work with comments <examples/comments.rst>`__
- `Run requests <examples/requests.rst>`__
- `Helpers <examples/helpers.rst>`__
- `Useful snippets <examples/snippets.rst>`__
- `Script: Find duplicates <examples/find_duplicates.py>`__
- `Script: Create a live proxy <examples/create_proxy.py>`__
You can also check `the API documentation <http://nuxeo.github.io/nuxeo-python-client/latest/>`__
of this Python client for further options.
Contributing
------------
See our `contribution documentation <https://doc.nuxeo.com/x/VIZH>`__.
Setup
~~~~~
.. code:: shell
git clone https://github.com/nuxeo/nuxeo-python-client
cd nuxeo-python-client
python -m pip install -e ".[oauth2, s3]"
Test
~~~~
A Nuxeo Platform instance needs to be running on
``http://localhost:8080/nuxeo`` for the tests to be run, and then:
.. code:: shell
python -m pip install -U --user tox
tox
Sentry
======
We use Sentry to catch unhandled errors from tests.
You can tweak it before running ``tox``.
It can be disabled:
.. code:: shell
export SKIP_SENTRY=1
You can also customize the Sentry DSN for your own team:
.. code:: shell
export SENTRY_DSN="XXX"
And customize the Sentry environment too:
.. code:: shell
# Note that the default value is "testing"
export SENTRY_ENV="testing"
Deploying
~~~~~~~~~
Releases are fully automated, have a look at that `GitHub Action <https://github.com/nuxeo/nuxeo-python-client/actions?query=workflow%3ARelease>`__.
Reporting Issues
~~~~~~~~~~~~~~~~
You can follow the developments in the Nuxeo Python Client project of
our JIRA bug tracker: `NXPY <https://jira.nuxeo.com/browse/NXPY>`__.
You can report issues on
`answers.nuxeo.com <http://answers.nuxeo.com>`__.
License
-------
`Apache License 2.0 <https://www.apache.org/licenses/LICENSE-2.0.txt>`__
Copyright (c) Nuxeo
About Nuxeo
-----------
Nuxeo dramatically improves how content-based applications are built,
managed and deployed, making customers more agile, innovative and
successful. Nuxeo provides a next generation, enterprise ready platform
for building traditional and cutting-edge content oriented applications.
Combining a powerful application development environment with SaaS-based
tools and a modular architecture, the Nuxeo Platform and Products
provide clear business value to some of the most recognizable brands
including Verizon, Electronic Arts, Sharp, FICO, the U.S. Navy, and
Boeing. Nuxeo is headquartered in New York and Paris. More information
is available at `www.nuxeo.com <http://www.nuxeo.com/>`__.
.. |Build Status| image:: https://github.com/nuxeo/nuxeo-python-client/workflows/Unit%20tests/badge.svg
:target: https://github.com/nuxeo/nuxeo-python-client/actions?query=workflow%3A%22Unit+tests%22
.. |Quality| image:: https://github.com/nuxeo/nuxeo-python-client/workflows/Code%20quality/badge.svg
:target: https://github.com/nuxeo/nuxeo-python-client/actions?query=workflow%3A%22Code+quality%22
.. |Coverage| image:: https://codecov.io/gh/nuxeo/nuxeo-python-client/branch/master/graph/badge.svg?token=WuxUo8U8FK
:target: https://codecov.io/gh/nuxeo/nuxeo-python-client
Raw data
{
"_id": null,
"home_page": "https://github.com/nuxeo/nuxeo-python-client",
"name": "nuxeo",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "api, rest, automation, client, nuxeo, ecm",
"author": "Nuxeo",
"author_email": "maintainers-python@nuxeo.com",
"download_url": "https://files.pythonhosted.org/packages/49/ab/cd48c18e5124efa4bad3e953b09f6e7eb50952534e717c419aa1f729bff9/nuxeo-6.1.2.tar.gz",
"platform": null,
"description": "Client Library for Nuxeo API\n----------------------------\n\n|Build Status| |Quality| |Coverage|\n\nThe Nuxeo Python Client is a Python client library for the Nuxeo\nAutomation and REST API. It works with Python 3.6+.\n\nThis is an ongoing project, supported by Nuxeo.\n\nGetting Started\n---------------\n\nThe installation is as simple as:\n\n.. code:: shell\n\n python -m pip install -U --user nuxeo\n\nThe client can make use of the Amazon S3 provider, to install its requirements:\n\n.. code:: shell\n\n python -m pip install -U --user \"nuxeo[s3]\"\n\nThe client is compatible with OAuth2 mechanism, to install its requirements:\n\n.. code:: shell\n\n python -m pip install -U --user \"nuxeo[oauth2]\"\n\nAnd to install several flavors of requirements:\n\n.. code:: shell\n\n python -m pip install -U --user \"nuxeo[oauth2, s3]\"\n\nImport\n------\n\nThen, use the following ``import`` statement to have access to the Nuxeo\nAPI:\n\n.. code:: python\n\n from nuxeo.client import Nuxeo\n\nDocumentation\n-------------\n\nCheck out the `API documentation <https://nuxeo.github.io/nuxeo-python-client/latest/>`__.\n\nRequirements\n------------\n\nThe Nuxeo Python client works only with:\n\n- the Nuxeo Platform >= LTS 2015\n- ``requests`` >= 2.12.2 (for unicode authentication)\n- ``setuptools`` >= 30.3.0\n\nQuick Start\n-----------\n\nThis quick start guide will show how to do basics operations using the\nclient.\n\nConnect to the Nuxeo Platform\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe easiest way to connect to the Nuxeo Platform with a basic authentication\nis passing a tuple containing the ``username`` and the ``password`` to the\nclient, like so:\n\n.. code:: python\n\n nuxeo = Nuxeo(auth=('Administrator', 'Administrator'))\n\n\nYou can then use the ``nuxeo`` object to interact with the Platform. If you want\nto use a specific instance, you can specify the ``base_url`` like so:\n\n.. code:: python\n\n nuxeo = Nuxeo(\n host='http://demo.nuxeo.com/nuxeo/',\n auth=('Administrator', 'Administrator')\n )\n\nDownload/Upload Configuration\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nIn the `nuxeo/constants.py <nuxeo/constants.py>`__ file, you have several constants that are\nused throughout the client that you can change to fit your needs. Some of them are:\n\n- ``CHECK_PARAMS`` (False by default), to check operation's parameters for each and every HTTP calls.\n- ``CHUNK_LIMIT`` (10 MiB by default), the size above which the upload will automatically be chunked.\n- ``CHUNK_SIZE`` (8 KiB by default), the size of the chunks when downloading.\n- ``MAX_RETRY`` (5 by default), the number of retries for connection error on any HTTP call.\n- ``UPLOAD_CHUNK_SIZE`` (20 MiB by default), the size of the chunks when uploading.\n\n\nRun NXQL Queries\n~~~~~~~~~~~~~~~~\n\nYou can run queries in NXQL (NXQL is a subset of SQL,\nyou can check how to use it `in the documentation <https://doc.nuxeo.com/nxdoc/nxql/>`__).\nHere, we are first `fetching a workspace <documents.rst>`__, and then using its\n``uid`` to build a query which will find all its children that have a ``File``\nor ``Picture`` type, and are not deleted.\n\n.. code:: python\n\n # Fetch a workspace\n ws = nuxeo.documents.get(path='/default-domain/workspaces/ws')\n\n # Build a query using its UID\n nxql = (\"SELECT * FROM Document WHERE ecm:ancestorId = '{uid}'\"\n \" AND ecm:primaryType IN ('File', 'Picture')\"\n \" AND ecm:currentLifeCycleState != 'deleted'\")\n query = nxql.format(uid=ws.uid)\n\n # Make the request\n search = nuxeo.client.query(query, params={'properties': '*'})\n\n # Get results\n entries = search['entries']\n\n``entries`` will be a ``list`` containing a ``dict`` for each\nelement returned by the query.\n\nUsage\n~~~~~\n\nNow that your client is set up, here are pages to help you with the\nmain functions available:\n\n- `Available authentication mechanisms <examples/authentication.rst>`__\n- `Manage users and groups <examples/users_and_groups.rst>`__\n- `Work with documents <examples/documents.rst>`__\n- `Work with directories <examples/directories.rst>`__\n- `Work with blobs <examples/blobs.rst>`__\n- `Work with comments <examples/comments.rst>`__\n- `Run requests <examples/requests.rst>`__\n- `Helpers <examples/helpers.rst>`__\n- `Useful snippets <examples/snippets.rst>`__\n- `Script: Find duplicates <examples/find_duplicates.py>`__\n- `Script: Create a live proxy <examples/create_proxy.py>`__\n\nYou can also check `the API documentation <http://nuxeo.github.io/nuxeo-python-client/latest/>`__\nof this Python client for further options.\n\nContributing\n------------\n\nSee our `contribution documentation <https://doc.nuxeo.com/x/VIZH>`__.\n\nSetup\n~~~~~\n\n.. code:: shell\n\n git clone https://github.com/nuxeo/nuxeo-python-client\n cd nuxeo-python-client\n python -m pip install -e \".[oauth2, s3]\"\n\nTest\n~~~~\n\nA Nuxeo Platform instance needs to be running on\n``http://localhost:8080/nuxeo`` for the tests to be run, and then:\n\n.. code:: shell\n\n python -m pip install -U --user tox\n tox\n\nSentry\n======\n\nWe use Sentry to catch unhandled errors from tests.\nYou can tweak it before running ``tox``.\n\nIt can be disabled:\n\n.. code:: shell\n\n export SKIP_SENTRY=1\n\nYou can also customize the Sentry DSN for your own team:\n\n.. code:: shell\n\n export SENTRY_DSN=\"XXX\"\n\nAnd customize the Sentry environment too:\n\n.. code:: shell\n\n # Note that the default value is \"testing\"\n export SENTRY_ENV=\"testing\"\n\nDeploying\n~~~~~~~~~\n\nReleases are fully automated, have a look at that `GitHub Action <https://github.com/nuxeo/nuxeo-python-client/actions?query=workflow%3ARelease>`__.\n\nReporting Issues\n~~~~~~~~~~~~~~~~\n\nYou can follow the developments in the Nuxeo Python Client project of\nour JIRA bug tracker: `NXPY <https://jira.nuxeo.com/browse/NXPY>`__.\n\nYou can report issues on\n`answers.nuxeo.com <http://answers.nuxeo.com>`__.\n\nLicense\n-------\n\n`Apache License 2.0 <https://www.apache.org/licenses/LICENSE-2.0.txt>`__\nCopyright (c) Nuxeo\n\nAbout Nuxeo\n-----------\n\nNuxeo dramatically improves how content-based applications are built,\nmanaged and deployed, making customers more agile, innovative and\nsuccessful. Nuxeo provides a next generation, enterprise ready platform\nfor building traditional and cutting-edge content oriented applications.\nCombining a powerful application development environment with SaaS-based\ntools and a modular architecture, the Nuxeo Platform and Products\nprovide clear business value to some of the most recognizable brands\nincluding Verizon, Electronic Arts, Sharp, FICO, the U.S. Navy, and\nBoeing. Nuxeo is headquartered in New York and Paris. More information\nis available at `www.nuxeo.com <http://www.nuxeo.com/>`__.\n\n.. |Build Status| image:: https://github.com/nuxeo/nuxeo-python-client/workflows/Unit%20tests/badge.svg\n :target: https://github.com/nuxeo/nuxeo-python-client/actions?query=workflow%3A%22Unit+tests%22\n\n.. |Quality| image:: https://github.com/nuxeo/nuxeo-python-client/workflows/Code%20quality/badge.svg\n :target: https://github.com/nuxeo/nuxeo-python-client/actions?query=workflow%3A%22Code+quality%22\n\n.. |Coverage| image:: https://codecov.io/gh/nuxeo/nuxeo-python-client/branch/master/graph/badge.svg?token=WuxUo8U8FK\n :target: https://codecov.io/gh/nuxeo/nuxeo-python-client\n",
"bugtrack_url": null,
"license": "Apache Software",
"summary": "Nuxeo REST API Python client",
"version": "6.1.2",
"project_urls": {
"Homepage": "https://github.com/nuxeo/nuxeo-python-client"
},
"split_keywords": [
"api",
" rest",
" automation",
" client",
" nuxeo",
" ecm"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7908daac1faa5835098c67fb7607e3617f58571d1f5c0e269ac7ef7b5fb13661",
"md5": "37df1167c1d8d232ee195222c3fd1522",
"sha256": "009d7c82f90ef310cb1d21559f989312f985ce338e2bf53495fe8857086b1a1a"
},
"downloads": -1,
"filename": "nuxeo-6.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "37df1167c1d8d232ee195222c3fd1522",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 53714,
"upload_time": "2024-11-08T09:27:26",
"upload_time_iso_8601": "2024-11-08T09:27:26.570603Z",
"url": "https://files.pythonhosted.org/packages/79/08/daac1faa5835098c67fb7607e3617f58571d1f5c0e269ac7ef7b5fb13661/nuxeo-6.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "49abcd48c18e5124efa4bad3e953b09f6e7eb50952534e717c419aa1f729bff9",
"md5": "165556a6a15d33302e339703468b6e2c",
"sha256": "cbc5b2db534dd380154f8800c7ac5881a2fd8aef5f061a8cdb780a1538e66e27"
},
"downloads": -1,
"filename": "nuxeo-6.1.2.tar.gz",
"has_sig": false,
"md5_digest": "165556a6a15d33302e339703468b6e2c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 44375,
"upload_time": "2024-11-08T09:27:28",
"upload_time_iso_8601": "2024-11-08T09:27:28.280220Z",
"url": "https://files.pythonhosted.org/packages/49/ab/cd48c18e5124efa4bad3e953b09f6e7eb50952534e717c419aa1f729bff9/nuxeo-6.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-08 09:27:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "nuxeo",
"github_project": "nuxeo-python-client",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"tox": true,
"lcname": "nuxeo"
}
JSON
