Use the Webclient API by default for Odoo >= 9.0

Author: florentx

.github/workflows/python-package.yml

@@ -5,9 +5,9 @@ name: Odooly
 
 on:
   push:
-    branches: [ "master" ]
+    branches: [ "master", "dev" ]
   pull_request:
-    branches: [ "master" ]
+    branches: [ "master", "dev" ]
 
 jobs:
   build:

CHANGES.rst

@@ -5,8 +5,20 @@ Changelog
 2.x.x (unreleased)
 ~~~~~~~~~~~~~~~~~~
 
-* Use a Web session for JSON-RPC requests
-  when Requests is installed.
+* Support webclient :class:`WebAPI` protocol as an alternative:
+  ``/web/dataset/*``, ``/web/database/*``, ...
+  Webclient API is stable since Odoo 9.0
+
+* Authenticate with ``/web/session/authenticate`` by default
+  and retrieve :attr:`Env.session_info`, with Odoo >= 9.0.
+
+* Use Webclient API by default when ``protocol`` is not set.
+  It is same as setting ``protocol = web``
+
+* New function :meth:`Client.drop_database`.
+
+* New functions to create/destroy a session:
+  :meth:`Env.session_authenticate` and :meth:`Env.session_destroy`.
 
 * Drop support for Python 3.5
 

README.rst

@@ -10,13 +10,13 @@ Download and install the latest release::
    :local:
    :backlinks: top
 
-Documentation and tutorial: http://odooly.readthedocs.org
+Documentation and tutorial: https://odooly.readthedocs.io/
 
 
 Overview
 --------
 
-Odooly carries three completing uses:
+Odooly carries three modes of use:
 
 (1) with command line arguments
 (2) as an interactive shell
@@ -25,14 +25,15 @@ Odooly carries three completing uses:
 
 Key features:
 
-- provides an API very close to the Odoo API, through JSON-RPC and XML-RPC
+- provides an API similar to Odoo Model, through Webclient API
 - compatible with OpenERP 6.1 through Odoo 19.0
-- single executable ``odooly.py``, no external dependency
+- supports external APIs JSON-RPC and XML-RPC as alternative
+- single file ``odooly.py``, no external dependency
 - helpers for ``search``, for data model introspection, etc...
 - simplified syntax for search ``domain`` and ``fields``
 - full API accessible on the ``Client.env`` environment
 - the module can be imported and used as a library: ``from odooly import Client``
-- supports Python 3.6 and above
+- supports Python 3.6 and more recent
 
 
 
@@ -59,7 +60,7 @@ Although it is quite limited::
       -c CONFIG, --config=CONFIG
                             specify alternate config file (default: 'odooly.ini')
       --server=SERVER       full URL of the server (default:
-                            http://localhost:8069/xmlrpc)
+                            http://localhost:8069/web)
       -d DB, --db=DB        database
       -u USER, --user=USER  username
       -p PASSWORD, --password=PASSWORD
@@ -113,7 +114,7 @@ Edit ``odooly.ini`` and declare the environment(s)::
     [demo]
     username = demo
     password = demo
-    protocol = xmlrpc
+    protocol = web
 
     [demo_jsonrpc]
     username = demo
@@ -164,6 +165,6 @@ This is a sample session::
 
 .. note::
 
-   To preserve the history of commands when closing the session, first
+   To preserve the commands' history when closing the session, first
    create an empty file in your home directory:
    ``touch ~/.odooly_history``

docs/api.rst

@@ -8,7 +8,7 @@ The library provides few objects to access the Odoo model and the
 associated services of `the Odoo API`_.
 
 The signature of the methods mimics the standard methods provided by the
-:class:`osv.Model` Odoo class.  This is intended to help the developer when
+:class:`odoo.models.Model` Odoo class.  This is intended to help the developer when
 developping addons.  What is experimented at the interactive prompt should
 be portable in the application with little effort.
 
@@ -21,9 +21,9 @@ be portable in the application with little effort.
 Client and Services
 -------------------
 
-The :class:`Client` object provides thin wrappers around Odoo RPC services
-and their methods.  Additional helpers are provided to explore the models and
-list or install Odoo add-ons.
+The :class:`Client` object provides thin wrappers around Odoo Webclient API
+and RPC services and their methods.  Additional helpers are provided to explore
+the models and to list or to install Odoo add-ons.
 
 
 .. autoclass:: Client
@@ -34,6 +34,8 @@ list or install Odoo add-ons.
 
 .. automethod:: Client.clone_database
 
+.. automethod:: Client.drop_database
+
 .. automethod:: Client.login
 
 
@@ -50,9 +52,44 @@ list or install Odoo add-ons.
    ``ODOOLY_SSL_UNVERIFIED=1``.
 
 
+Odoo Webclient API
+~~~~~~~~~~~~~~~~~~
+
+These HTTP routes were developed for the Odoo Web application.  They are now
+used by Odooly to provide high level methods on :class:`Env`
+and :class:`Model`.
+
+.. attribute:: Client.database
+
+   Expose the ``database`` :class:`WebAPI`.
+
+   Example: :meth:`Client.database.list` method.
+
+.. attribute:: Client.web
+
+   Expose the root ``/web`` :class:`WebAPI`.
+
+.. attribute:: Client.web_dataset
+
+   Expose the ``/web/dataset`` :class:`WebAPI`.
+
+.. attribute:: Client.web_session
+
+   Expose the ``/web/session`` :class:`WebAPI`.
+
+.. attribute:: Client.web_webclient
+
+   Expose the ``/web/webclient`` :class:`WebAPI`.
+
+
 Odoo RPC Services
 ~~~~~~~~~~~~~~~~~
 
+.. note::
+
+   These RPC services are deprecated in Odoo 19.0.  They are
+   scheduled for removal in Odoo 20.0 in 2026.
+
 The naked Odoo RPC services are exposed too.
 The :attr:`~Client.db` and the :attr:`~Client.common` services expose few
 methods which might be helpful for server administration.  Use the
@@ -70,16 +107,22 @@ Please refer to `the Odoo documentation`_ for more details.
    Examples: :meth:`Client.db.list` or :meth:`Client.db.server_version`
    RPC methods.
 
+   Removed in Odoo 20.
+
 .. attribute:: Client.common
 
    Expose the ``common`` :class:`Service`.
 
    Example: :meth:`Client.common.login_message` RPC method.
 
+   Removed in Odoo 20.
+
 .. data:: Client._object
 
    Expose the ``object`` :class:`Service`.
 
+   Removed in Odoo 20.
+
 .. attribute:: Client._report
 
    Expose the ``report`` :class:`Service`.
@@ -92,12 +135,16 @@ Please refer to `the Odoo documentation`_ for more details.
 
    Removed in OpenERP 7.
 
+.. autoclass:: WebAPI
+   :members:
+   :undoc-members:
+
 .. autoclass:: Service
    :members:
    :undoc-members:
 
 .. _the Odoo documentation:
-.. _the Odoo API: http://doc.odoo.com/v6.1/developer/12_api.html#api
+.. _the Odoo API: https://www.odoo.com/documentation/19.0/developer/reference/external_rpc_api.html
 
 
 Environment
@@ -131,6 +178,16 @@ Environment
 
       Cursor on the current database.
 
+   .. automethod:: session_authenticate
+
+   .. automethod:: session_destroy
+
+   .. attribute:: session_info
+
+      Dictionary returned when a Webclient session is authenticated.
+      It contains ``uid`` and ``user_context`` among other user's preferences
+      and server parameters.
+
    .. automethod:: sudo(user=SUPERUSER_ID)
 
 
@@ -151,6 +208,12 @@ Please refer to `the Odoo documentation`_ for details.
 
 .. automethod:: Env.execute(obj, method, *params, **kwargs)
 
+.. automethod:: Env._call_kw(obj, method, *params, **kwargs)
+
+.. attribute:: Env._web(obj, method, *params, **kwargs)
+
+   Expose the root of the ``/web`` API.
+
 .. method:: Env.exec_workflow(obj, signal, obj_id)
 
    Wrapper around ``object.exec_workflow`` RPC method.
@@ -212,7 +275,7 @@ Python script or interactively in a Python session.
    It is not recommended to install or upgrade modules in offline mode when
    any web server is still running: the operation will not be signaled to
    other processes.  This restriction does not apply when connected through
-   XML-RPC or JSON-RPC.
+   Webclient API or other RPC API.
 
 
 .. _model-and-records:
@@ -222,7 +285,7 @@ Model and Records
 
 The :class:`Env` provides a high level API similar to the Odoo API, which
 encapsulates objects into `Active Records
-<http://www.martinfowler.com/eaaCatalog/activeRecord.html>`_.
+<https://www.martinfowler.com/eaaCatalog/activeRecord.html>`_.
 
 The :class:`Model` is instantiated using the ``client.env[...]`` syntax.
 

docs/developer.rst

@@ -22,12 +22,13 @@ complex tasks.
 For example:
 
 * write unit tests using the standard `unittest
-  <http://docs.python.org/library/unittest.html>`_ framework.
-* write BDD tests using the `Gherkin language <http://packages.python.org/
-  behave/gherkin.html#gherkin-feature-testing-language>`_, and a library
-  like `Behave <http://packages.python.org/behave/>`_.
+  <https://docs.python.org/library/unittest.html>`_ framework.
+* write BDD tests using the `Gherkin language <https://behave.readthedocs.io/
+  en/latest/gherkin/#gherkin-feature-testing-language>`_, and a library
+  like `Behave <https://behave.readthedocs.io/>`_.
 * build an interface for Odoo, using a framework like
-  `Flask <http://flask.pocoo.org/>`_ (HTML, JSON, SOAP, ...).
+  `Flask <https://flask.palletsprojects.com/>`_ (HTML, JSON, SOAP, ...).
+
 
 
 Changes

docs/index.rst

@@ -10,7 +10,7 @@ Odooly's documentation
 *A versatile tool for browsing Odoo / OpenERP data*
 
 The Odooly library communicates with any `Odoo / OpenERP server`_ (>= 6.1)
-using `the standard XML-RPC interface`_ or the new JSON-RPC interface.
+using the Webclient API or `the deprecated external RPC interface`_ (JSON-RPC or XML-RPC).
 
 It provides both a :ref:`fully featured low-level API <client-and-services>`,
 and an encapsulation of the methods on :ref:`Active Record objects
@@ -35,11 +35,11 @@ Contents:
    tutorial
    developer
 
-* Online documentation: http://odooly.readthedocs.org/
+* Online documentation: https://odooly.readthedocs.io/
 * Source code and issue tracker: https://github.com/tinyerp/odooly
 
-.. _Odoo / OpenERP server: http://doc.odoo.com/
-.. _the standard XML-RPC interface: http://doc.odoo.com/v6.1/developer/12_api.html#api
+.. _Odoo / OpenERP server: https://www.odoo.com/documentation/
+.. _the deprecated external RPC interface: https://www.odoo.com/documentation/19.0/developer/reference/external_rpc_api.html
 
 
 Indices and tables

docs/intro.rst

@@ -10,7 +10,7 @@ Installation
 ------------
 
 Download and install the `latest release
-<http://pypi.python.org/pypi/Odooly>`__ from PyPI::
+<https://pypi.org/project/Odooly>`__ from PyPI::
 
     pip install -U odooly
 

docs/tutorial.rst

@@ -6,7 +6,7 @@ Tutorial
 
 This tutorial demonstrates some features of Odooly in the interactive shell.
 
-It assumes an Odoo or OpenERP server is installed.
+It assumes an Odoo server is installed.
 The shell is a true Python shell.  We have access to all the features and
 modules of the Python interpreter.
 
@@ -32,12 +32,17 @@ If our configuration is different, then we use arguments, like::
 
     $ odooly --server http://192.168.0.42:8069
 
-It connects using the XML-RPC protocol. If you want to use the JSON-RPC
-protocol instead, then pass the full URL with ``/jsonrpc`` path::
+It connects using the Webclient API. If you want to use the JSON-RPC
+external API instead, then pass the full URL with ``/jsonrpc`` path::
 
     $ odooly --server http://127.0.0.1:8069/jsonrpc
 
 
+.. note::
+
+    These protocols JSON-RPC and XML-RPC are deprecated in Odoo 19.0 and will
+    be removed in Odoo 20.0.
+
 On login, it prints few lines about the commands available.
 
 .. sourcecode:: pycon
@@ -64,6 +69,7 @@ On login, it prints few lines about the commands available.
         env.install(module1, module2, ...)
         env.upgrade(module1, module2, ...)
                                         # Install or upgrade the modules
+        env.upgrade_cancel()            # Reset failed upgrade/install
 
 And it confirms that the default database is not available::
 
@@ -73,9 +79,9 @@ And it confirms that the default database is not available::
 Though, we have a connected client, ready to use::
 
     >>> client
-    <Client 'http://localhost:8069/xmlrpc#()'>
+    <Client 'http://localhost:8069/web#()'>
     >>> client.server_version
-    '6.1'
+    '18.0'
     >>> #
 
 
@@ -96,8 +102,8 @@ Default password is ``"admin"``.
     >>> client.create_database('super_password', 'demo')
     Logged in as 'admin'
     >>> client
-    <Client 'http://localhost:8069/xmlrpc#demo'>
-    >>> client.db.list()
+    <Client 'http://localhost:8069/web#demo'>
+    >>> client.database.list()
     ['demo']
     >>> env
     <Env 'admin@demo'>
@@ -137,8 +143,8 @@ database name and the superadmin password.
     >>> client.clone_database('super_password', 'demo_test')
     Logged in as 'admin'
     >>> client
-    <Client 'http://localhost:8069/xmlrpc#demo_test'>
-    >>> client.db.list()
+    <Client 'http://localhost:8069/web#demo_test'>
+    >>> client.database.list()
     ['demo', 'demo_test']
     >>> env
     <Env 'admin@demo'>
@@ -160,7 +166,7 @@ Where is the table for the users?
 .. sourcecode:: pycon
 
     >>> client
-    <Client 'http://localhost:8069/xmlrpc#demo'>
+    <Client 'http://localhost:8069/web#demo'>
     >>> env.models('user')
     ['res.users', 'res.users.log']