# odoorpc.ODOO

class odoorpc.ODOO(host='localhost', protocol='jsonrpc', port=8069, timeout=120, version=None, opener=None)

  Return a new instance of the `ODOO` class. JSON-RPC protocol is used to make requests, and the respective values for the protocol parameter are `jsonrpc` (default) and `jsonrpc+ssl`.

      >>> import odoorpc
      >>> odoo = odoorpc.ODOO('localhost', protocol='jsonrpc', port=8069)

  OdooRPC will try by default to detect the server version in order to adapt its requests if necessary. However, it is possible to force the version to use with the version parameter:

      >>> odoo = odoorpc.ODOO('localhost', version='12.0')

  You can also define a custom URL opener to handle HTTP requests. A use case is to manage a basic HTTP authentication in front of Odoo:

      >>> import urllib.request
      >>> import odoorpc
      >>> pwd_mgr = urllib.request.HTTPPasswordMgrWithDefaultRealm()
      >>> pwd_mgr.add_password(None, "http://example.net", "userName", "passWord")
      >>> auth_handler = urllib.request.HTTPBasicAuthHandler(pwd_mgr)
      >>> opener = urllib.request.build_opener(auth_handler)
      >>> odoo = odoorpc.ODOO('example.net', port=80, opener=opener)

  Python 2:

  Raise

    `odoorpc.error.InternalError`

  Raise

    ValueError (wrong protocol, port value, timeout value)

  Raise

    urllib2.URLError (connection error)

  Python 3:

  Raise

    `odoorpc.error.InternalError`

  Raise

    ValueError (wrong protocol, port value, timeout value)

  Raise

    urllib.error.URLError (connection error)

  property config

    Dictionary of available configuration options.

        >>> odoo.config
        {'auto_commit': True, 'auto_context': True, 'timeout': 120}

    - `auto_commit`: if set to True (default), each time a value is set on a record field a RPC request is sent to the server to update the record (see `odoorpc.env.Environment.commit()`).

    - `auto_context`: if set to True (default), the user context will be sent automatically to every call of a `model` method (default: True):

        >>> odoo.env.context['lang'] = 'fr_FR'
        >>> Product = odoo.env['product.product']
        >>> Product.name_get([2])   # Context sent by default ('lang': 'fr_FR' here)
        [[2, 'Surveillance sur site']]
        >>> odoo.config['auto_context'] = False
        >>> Product.name_get([2])   # No context sent, 'en_US' used
        [[2, 'On Site Monitoring']]

    - `timeout`: set the maximum timeout in seconds for a RPC request (default: 120):

          >>> odoo.config['timeout'] = 300

  property db

    The database management service. See the `odoorpc.db.DB` class.

  property env

    The environment which wraps data to manage records such as the user context and the registry to access data model proxies.

        >>> Partner = odoo.env['res.partner']
        >>> Partner
        Model('res.partner')

    See the `odoorpc.env.Environment` class.

  exec_workflow(model, record_id, signal)

    Execute the workflow signal on the instance having the ID record_id of model.

    Python 2:

    Raise

      `odoorpc.error.RPCError`

    Raise

      `odoorpc.error.InternalError` (if not logged)

    Raise

      urllib2.URLError (connection error)

    Python 3:

    Raise

      `odoorpc.error.RPCError`

    Raise

      `odoorpc.error.InternalError` (if not logged)

    Raise

      urllib.error.URLError (connection error)

  execute(model, method, *args)

    Execute the method of model. *args parameters varies according to the method used.

        >>> odoo.execute('res.partner', 'read', [1], ['name'])
        [{'id': 1, 'name': 'YourCompany'}]

    Python 2:

    Returns

      the result returned by the method called

    Raise

      `odoorpc.error.RPCError`

    Raise

      `odoorpc.error.InternalError` (if not logged)

    Raise

      urllib2.URLError (connection error)

    Python 3:

    Returns

      the result returned by the method called

    Raise

      `odoorpc.error.RPCError`

    Raise

      `odoorpc.error.InternalError` (if not logged)

    Raise

      urllib.error.URLError (connection error)

  execute_kw(model, method, args=None, kwargs=None)

    Execute the method of model. args is a list of parameters (in the right order), and kwargs a dictionary (named parameters). Both varies according to the method used.

        >>> odoo.execute_kw('res.partner', 'read', [[1]], {'fields': ['name']})
        [{'id': 1, 'name': 'YourCompany'}]

    Python 2:

    Returns

      the result returned by the method called

    Raise

      `odoorpc.error.RPCError`

    Raise

      `odoorpc.error.InternalError` (if not logged)

    Raise

      urllib2.URLError (connection error)

    Python 3:

    Returns

      the result returned by the method called

    Raise

      `odoorpc.error.RPCError`

    Raise

      `odoorpc.error.InternalError` (if not logged)

    Raise

      urllib.error.URLError (connection error)

  property host

    Hostname of IP address of the the server.

  http(url, data=None, headers=None)

    Low level method to execute raw HTTP queries.

    Note

    For low level JSON-RPC queries, see the more convenient `odoorpc.ODOO.json()` method instead.

    You have to know the names of each POST parameter required by the URL, and set them in the data string/buffer. The data argument must be built by yourself, following the expected URL parameters (with `urllib.urlencode()` function for simple parameters, or multipart/form-data structure to handle file upload).

    E.g., the HTTP raw query to get the company logo on Odoo 12.0:

        >>> response = odoo.http('web/binary/company_logo')
        >>> binary_data = response.read()

    Python 2:

    Returns

      urllib.addinfourl

    Raise

      urllib2.HTTPError

    Raise

      urllib2.URLError (connection error)

    Python 3:

    Returns

      http.client.HTTPResponse

    Raise

      urllib.error.HTTPError

    Raise

      urllib.error.URLError (connection error)

  json(url, params)

    Low level method to execute JSON queries. It basically performs a request and raises an `odoorpc.error.RPCError` exception if the response contains an error.

    You have to know the names of each parameter required by the function called, and set them in the params dictionary.

    Here an authentication request:

        >>> data = odoo.json(
        ...     '/web/session/authenticate',
        ...     {'db': 'db_name', 'login': 'admin', 'password': 'admin'})
        >>> from pprint import pprint
        >>> pprint(data)
        {'id': 645674382,
         'jsonrpc': '2.0',
         'result': {'db': 'db_name',
                    'session_id': 'fa740abcb91784b8f4750c5c5b14da3fcc782d11',
                    'uid': 1,
                    'user_context': {'lang': 'en_US',
                                     'tz': 'Europe/Brussels',
                                     'uid': 1},
                    'username': 'admin'}}

    And a call to the `read` method of the `res.users` model:

        >>> data = odoo.json(
        ...     '/web/dataset/call',
        ...     {'model': 'res.users', 'method': 'read',
        ...      'args': [[2], ['name']]})
        >>> from pprint import pprint
        >>> pprint(data)
        {'id': ...,
         'jsonrpc': '2.0',
         'result': [{'id': 2, 'name': 'Mitchell Admin'}]}

    Python 2:

    Returns

      a dictionary (JSON response)

    Raise

      `odoorpc.error.RPCError`

    Raise

      urllib2.HTTPError (if params is not a dictionary)

    Raise

      urllib2.URLError (connection error)

    Python 3:

    Returns

      a dictionary (JSON response)

    Raise

      `odoorpc.error.RPCError`

    Raise

      urllib.error.HTTPError (if params is not a dictionary)

    Raise

      urllib.error.URLError (connection error)

  classmethod list(rc_file='~/.odoorpcrc')

    Return a list of all stored sessions available in the rc_file file:

        >>> import odoorpc
        >>> odoorpc.ODOO.list()
        ['foo', 'bar']

    Use the `save` and `load` methods to manage such sessions.

    Python 2:

    Raise

      IOError

    Python 3:

    Raise

      PermissionError

    Raise

      FileNotFoundError

  classmethod load(name, rc_file='~/.odoorpcrc')

    Return a connected `ODOO` session identified by name:

        >>> import odoorpc
        >>> odoo = odoorpc.ODOO.load('foo')

    Such sessions are stored with the `save` method.

    Python 2:

    Raise

      `odoorpc.error.RPCError`

    Raise

      urllib2.URLError (connection error)

    Python 3:

    Raise

      `odoorpc.error.RPCError`

    Raise

      urllib.error.URLError (connection error)

  login(db, login='admin', password='admin')

    Log in as the given user with the password passwd on the database db.

        >>> odoo.login('db_name', 'admin', 'admin')
        >>> odoo.env.user.name
        'Administrator'

    Python 2:

    Raise

      `odoorpc.error.RPCError`

    Raise

      urllib2.URLError (connection error)

    Python 3:

    Raise

      `odoorpc.error.RPCError`

    Raise

      urllib.error.URLError (connection error)

  logout()

    Log out the user.

        >>> odoo.logout()
        True

    Python 2:

    Returns

      True if the operation succeed, False if no user was logged

    Raise

      `odoorpc.error.RPCError`

    Raise

      urllib2.URLError (connection error)

    Python 3:

    Returns

      True if the operation succeed, False if no user was logged

    Raise

      `odoorpc.error.RPCError`

    Raise

      urllib.error.URLError (connection error)

  property port

    The port used.

  property protocol

    The protocol used.

  classmethod remove(name, rc_file='~/.odoorpcrc')

    Remove the session identified by name from the rc_file file:

        >>> import odoorpc
        >>> odoorpc.ODOO.remove('foo')
        True

    Python 2:

    Raise

      ValueError (if the session does not exist)

    Raise

      IOError

    Python 3:

    Raise

      ValueError (if the session does not exist)

    Raise

      PermissionError

    Raise

      FileNotFoundError

  property report

    The report management service. See the `odoorpc.report.Report` class.

  save(name, rc_file='~/.odoorpcrc')

    Save the current `ODOO` instance (a session) inside rc_file (`~/.odoorpcrc` by default). This session will be identified by name:

        >>> import odoorpc
        >>> odoo = odoorpc.ODOO('localhost', port=8069)
        >>> odoo.login('db_name', 'admin', 'admin')
        >>> odoo.save('foo')

    Use the `list` class method to list all stored sessions, and the `load` class method to retrieve an already-connected `ODOO` instance.

    Python 2:

    Raise

      `odoorpc.error.InternalError` (if not logged)

    Raise

      IOError

    Python 3:

    Raise

      `odoorpc.error.InternalError` (if not logged)

    Raise

      PermissionError

    Raise

      FileNotFoundError

  property version

    The version of the server.

        >>> odoo.version
        '12.0'