# odoorpc.ODOO

class `odoorpc.``ODOO`(host='localhost', protocol='jsonrpc', port=8069, timeout=120, version=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='10.0')

  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)

  `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

  `db`

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

  `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)

  `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 10.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': [[1], ['name']]})
        >>> from pprint import pprint
        >>> pprint(data)
        {'id': ...,
         'jsonrpc': '2.0',
         'result': [{'id': 1, 'name': 'Administrator'}]}

    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)

  `port`

    The port used.

  `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

  `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

  `version`

    The version of the server.

        >>> odoo.version
        '10.0'