The library provides few objects to access the OpenObject model and the associated services provided by the Odoo XML-RPC API.

The signature of the methods mimics the standard methods provided by the osv.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.

Client and Services

The Client object provides thin wrappers around XML-RPC services and their methods. Additional helpers are provided to explore the models and list or install Odoo add-ons.

class erppeek.Client(server, db=None, user=None, password=None, transport=None, verbose=False)[source]

Connection to an Odoo instance.

This is the top level object. The server is the URL of the instance, like http://localhost:8069. If server is an openerp module, it is used to connect to the local server (>= 6.1).

The db is the name of the database and the user should exist in the table res.users. If the password is not provided, it will be asked on login.

classmethod Client.from_config(environment, user=None, verbose=False)[source]

Create a connection to a defined environment.

Read the settings from the section [environment] in the erppeek.ini file and return a connected Client. See read_config() for details of the configuration file format.

Client.create_database(passwd, database, demo=False, lang='en_US', user_password='admin')[source]

Create a new database.

The superadmin passwd and the database name are mandatory. By default, demo data are not loaded and lang is en_US. Wait for the thread to finish and login if successful.

Client.login(user, password=None, database=None)[source]

Switch user and (optionally) database.

If the password is not available, it will be asked.


Default context used for all the methods (default None). In interactive mode, this default context contains the language of the shell environment (variable LANG). Do not update the context, either copy it or replace it:

# Set language to German
client.context = {'lang': 'de_DE', 'preferred_color': 'blue'}
# ... do something

# Switch to Italian
client.context = dict(client.context, lang='it_IT')
# ... do something

# and AVOID (because it changes the context of existing records)
client.context['lang'] = 'fr_FR'


In interactive mode, a method Client.connect(env=None) exists, to connect to another environment, and recreate the globals().


In interactive mode, when connected to the local Odoo server, the get_pool(db_name=None) function helps to grab a model registry for the current database. The cursor factory is available on the registry as get_pool().cursor() (Odoo) or get_pool().db.cursor() (OpenERP <= 7).

Objects, domain, offset=0, limit=None, order=None, context=None)[source]

Filter the records in the domain, return the ids.

Client.count(obj, domain, context=None)[source]

Count the records in the domain., domain, fields=None, offset=0, limit=None, order=None, context=None)[source]

Wrapper for client.execute(obj, 'read', [...], ('a', 'b')).

The first argument obj is the model name (example: "res.partner")

The second argument, domain, accepts:
  • [('name', '=', 'mushroom'), ('state', '!=', 'draft')]
  • ['name = mushroom', 'state != draft']
  • []
  • a list of ids [1, 2, 3] or a single id 42
The third argument, fields, accepts:
  • a single field: 'first_name'
  • a tuple of fields: ('street', 'city')
  • a space separated string: 'street city'
  • a format spec: '%(street)s %(city)s'

If fields is omitted, all fields are read.

If domain is a single id, then:
  • return a single value if a single field is requested.
  • return a string if a format spec is passed in the fields argument.
  • else, return a dictionary.

If domain is not a single id, the returned value is a list of items. Each item complies with the rules of the previous paragraph.

The optional keyword arguments offset, limit and order are used to restrict the search. The order is also used to order the results returned. Note: the low-level RPC method read itself does not preserve the order of the results.

Client.perm_read(obj, ids, context=None, details=True)

Lookup metadata about the records in the ids list. Return a list of dictionaries with the following keys:

  • id: object id
  • create_uid: user who created the record
  • create_date: date when the record was created
  • write_uid: last user who changed the record
  • write_date: date of the last change to the record
  • xmlid: XML ID to use to refer to this record (if there is one), in format (not available with OpenERP 5)

If details is True, the create_uid and write_uid contain the name of the user.

Client.write(obj, ids, values, context=None)

Update the record(s) with the content of the values dictionary.

Client.create(obj, values, context=None)

Create a new record for the model. The argument values is a dictionary of values for the new record. Return the object id.

Client.copy(obj, id, default=None, context=None)

Copy a record and return the new id. The optional argument default is a mapping which overrides some values of the new record.

Delete records with the given ids


Return a dictionary of models.

The argument name is a pattern to filter the models returned. If omitted, all models are returned. Keys are camel case names of the models. Values are instances of Model.

The return value can be used to declare the models in the global namespace:

>>> globals().update(client.models('res.'))
Client.model(name, check=True)[source]

Return a Model instance.

The argument name is the name of the model. If the optional argument check is False, no validity check is done.


Wrapper for Model.keys() method.

Client.fields(obj, names=None)[source]

Wrapper for Model.fields() method.

Client.field(obj, name)[source]

Wrapper for Model.field() method.

Client.access(obj, mode='read')[source]

Wrapper for Model.access() method.

Advanced methods

Those methods give more control on the Odoo objects: workflows and reports. Please refer to the Odoo documentation for details.

Client.execute(obj, method, *params, **kwargs)[source]

Wrapper around object.execute RPC method.

Argument method is the name of an osv.osv method or a method available on this obj. Method params are allowed. If needed, keyword arguments are collected in kwargs.

Client.execute_kw(obj, ids, params, kwargs=None)

Wrapper around object.execute_kw RPC method.

Does not exist if server is OpenERP 5.

Client.exec_workflow(obj, signal, obj_id)[source]

Wrapper around object.exec_workflow RPC method.

Argument obj is the name of the model. The signal is sent to the object identified by its integer id obj_id., ids, datas=None, context=None)

Wrapper around RPC method.

Client.render_report(obj, ids, datas=None, context=None)

Wrapper around report.render_report RPC method.

Does not exist if server is OpenERP 5.


Wrapper around report.report_get RPC method.

Client.wizard(name, datas=None, action='init', context=None)[source]

Wrapper around wizard.create and wizard.execute RPC methods.

If only name is provided, a new wizard is created and its id is returned. If action is not "init", then the action is executed. In this case the name is either an id or a string. If the name is a string, the wizard is created before the execution. The optional datas argument provides data for the action. The optional context argument is passed to the RPC method.

Removed in OpenERP 7.

XML-RPC Services

The nake XML-RPC services are exposed too. There are five services. The db and the common services expose few methods which might be helpful for server administration. Use the dir() function to introspect them. The three other services should not be used directly: they are in the private namespace, starting with _ because their methods are wrapped and exposed on the Client object itself. Please refer to the Odoo documentation for more details.


Expose the db Service.

Examples: Client.db.list() or Client.db.server_version() RPC methods.


Expose the common Service.

Example: Client.common.login_message() RPC method.


Expose the object Service.


Expose the report Service.


Expose the wizard Service.

Removed in OpenERP 7.

class erppeek.Service(server, endpoint, methods, transport=None, verbose=False)[source]

A wrapper around XML-RPC endpoints.

The connected endpoints are exposed on the Client instance. The server argument is the URL of the server (scheme+host+port). If server is an openerp module, it is used to connect to the local server. The endpoint argument is the name of the service (examples: "object", "db"). The methods is the list of methods which should be exposed on this endpoint. Use dir(...) on the instance to list them.

Manage addons

These helpers are convenient to list, install or upgrade addons from a Python script or interactively in a Python session.

Client.modules(name='', installed=None)[source]

Return a dictionary of modules.

The optional argument name is a pattern to filter the modules. If the boolean argument installed is True, the modules which are “Not Installed” or “Not Installable” are omitted. If the argument is False, only these modules are returned. If argument installed is omitted, all modules are returned. The return value is a dictionary where module names are grouped in lists according to their state.


Press the button Install.


Press the button Upgrade.


Press the button Uninstall.


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.

Model and Records

In addition to the thin wrapper methods, the Client provides a high level API which encapsulates objects into Active Records.

The Model is instantiated using the Client.model() method or directly through camel case attributes.

Example: both client.model('') and client.ResCompany return the same Model.

class erppeek.Model(client, model_name)[source]

The class for Odoo models.


Return the keys of the model.


Return a dictionary of the fields of the model.

Optional argument names is a sequence of field names or a space separated string of these names. If omitted, all fields are returned.


Return the field properties for field name.


Check if the user has access to this model.

Optional argument mode is the access mode to check. Valid values are read, write, create and unlink. If omitted, the read mode is checked. Return a boolean.

browse(domain, offset=0, limit=None, order=None, context=None)[source]

Return a Record or a RecordList.

The argument domain accepts a single integer id, a list of ids or a search domain. If it is a single integer, the return value is a Record. Otherwise, the return value is a RecordList. Be careful when passing a list of ids, because an empty list will be considered an empty domain and will find all records in the database.

get(domain, context=None)[source]

Return a single Record.

The argument domain accepts a single integer id or a search domain, or an xml_id. The return value is a Record or None. If multiple records are found, a ValueError is raised.

create(values, context=None)[source]

Create a Record.

The argument values is a dictionary of values which are used to create the record. Relationship fields one2many and many2many accept either a list of ids or a RecordList or the extended Odoo syntax. Relationship fields many2one and reference accept either a Record or the Odoo syntax.

The newly created Record is returned.


Retrieve the External IDs of the records.

Return a dictionary with keys being the fully qualified External IDs, and values the Record entries.

class erppeek.RecordList(model, ids)[source]

A sequence of Odoo Record.

It has a similar API as the Record class, but for a list of records. The attributes of the RecordList are read-only, and they return list of attribute values in the same order. The many2one, one2many and many2many attributes are wrapped in RecordList and list of RecordList objects. Use the method RecordList.write to assign a single value to all the selected records.

read(fields=None, context=None)[source]

Wrapper for the method.

Return a RecordList if fields is the name of a single many2one field, else return a list. See for details.


Wrapper for the Record.perm_read() method.

write(values, context=None)[source]

Wrapper for the Record.write() method.

Wrapper for the Record.unlink() method.


Retrieve the External IDs of the RecordList.

Return the list of fully qualified External IDs of the RecordList, with default value False if there’s none. If multiple IDs exist for a record, only one of them is returned.

class erppeek.Record(model, id)[source]

A class for all Odoo records.

It maps any Odoo object. The fields can be accessed through attributes. The changes are immediately sent to the server. The many2one, one2many and many2many attributes are wrapped in Record and RecordList objects. These attributes support writing too. The attributes are evaluated lazily, and they are cached in the record. The Record’s cache is invalidated if any attribute is changed.


Retrieve the External ID of the Record.

Return the fully qualified External ID of the Record, with default value False if there’s none. If multiple IDs exist, only one of them is returned (randomly).


Trigger workflow signal for this Record.

copy(default=None, context=None)[source]

Copy a record and return the new Record.

The optional argument default is a mapping which overrides some values of the new record.


Read the metadata of the Record.

Return a dictionary of values. See Client.perm_read() for details.

read(fields=None, context=None)[source]

Read the fields of the Record.

The argument fields accepts different kinds of values. See for details.


Force refreshing the record’s data.

Delete the current Record from the database.

write(values, context=None)[source]

Write the values in the Record.

values is a dictionary of values. See Model.create() for details.



Convert to lowercase with dots.

>>> lowercase('ResCompany')

Convert to MixedCase.

>>> mixedcase('')

Check if the argument is a search domain.

  • [('name', '=', 'mushroom'), ('state', '!=', 'draft')]
  • ['name = mushroom', 'state != draft']
  • []
erppeek.searchargs(params, kwargs=None, context=None)[source]

Compute the ‘search’ parameters.

erppeek.format_exception(type, value, tb, limit=None, chain=True)[source]

Format a stack trace and the exception information.

This wrapper is a replacement of traceback.format_exception which formats the error and traceback received by XML-RPC. If chain is True, then the original exception is printed too.


Read the environment settings from the configuration file.

The config file erppeek.ini contains a section for each environment. Each section provides parameters for the connection: host, port, database, user and (optional) password. Default values are read from the [DEFAULT] section. If the password is not in the configuration file, it is requested on login. Return a tuple (server, db, user, password or None). Without argument, it returns the list of configured environments.

erppeek.start_odoo_services(options=None, appname=None)[source]

Initialize the Odoo services.

Import the openerp package and load the Odoo services. The argument options receives the command line arguments for openerp. Example:

['-c', '/path/to/openerp-server.conf', '--without-demo', 'all'].

Return the openerp package.