Odoo Scripts¶

Odoo vs RPC scripts for administrative tasks¶

There are several Python distributions that wrap the Odoo RPC APIs for easy use within Python code.

Using an RPC script for administrative tasks usually leads to wrap it in a shell script, with the admin password in clear text.

In this author’s experience of applicative maintainance, this always turns to be an easy source of breakage that may look to be trivial at first sight but has actually two nasty properties : it may stay unnoticed for a while, and it lies at the interface between responsibilities.

In case of password change, the persons who can do it in the database and in the system usually differ, and may not communicate on a regular basis. In enterprise hosting environments, you may have to explain stuff to several project managers with different responsabilities, go through crisis management meetings, etc. Who wants to waste hours of their life interacting with people under stress to try and persuade them that it’s only a matter of changing an obscure password ?

Odoo scripts vs Odoo cron jobs¶

Because they are part of addons, Odoo cron jobs also have full unrestricted access to the internal API, and obviously don’t suffer from the password plague.

Some ideas to make a choice:

• who should control, schedule and tune execution (a system administrator or a functional admin)
• which one the script author finds easiest to write for
• reuse and distribution issues : Odoo scripts are in Python distributions, cron jobs are in addons.
• Odoo scripts must implement their own transaction control, whereas cron jobs don’t bother about it but rely on the framework’s decisions.

Perhaps, the best is not to choose : put the bulk of the logic in some technical addon, it’s easy to rewrap it in an Odoo script and as a cron job.

Bare declararations¶

The following configuration:

[openerp-one]
(...)
openerp_scripts = my_script

Produces an executable bin/my_script-openerp-one, that can import Odoo server and addons code, and in which the Odoo configuration related to the appropriate buildout part (here, openerp-one) is loaded in the standard openerp.tools.config, for use in the script. The script has to take care of all database management operations.

Optionally, it’s possible to specify the name of the produced script:

[openerp-one]
(...)
openerp_scripts = my_script=wished_name

That would build the script as bin/wished_name.

This is good enough for scripts that’d take care of many bootstrapping details, but there is a more integrated way that script authors should be aware of: the special session argument.

Arguments and session¶

An arguments parameter, similar to the one of zc.recipe.egg:scripts can be specified:

[openerp-two]
(...)
openerp_scripts = my_script arguments=2,3

This is a raw string that will be used as the string of arguments for the callable specified in the entry point, as in main(2,3) in that example.

There is a special argument: session, which is an object provided by the recipe to expose Odoo API in a convenient manner for script authors. Check anybox.recipe.openerp.runtime.session.Session to learn what can be done with it.

Scripts written for these session objects must be declared as such:

[openerp-two]
(...)
openerp_scripts = my_script arguments=session

Command-line options¶

In some cases, it is useful to do some operations, such as preloading a database, before actual running of the script. This is intended for scripts which have no special knowledge of Odoo but may in turn call some code meant for Odoo, that’d need some preparations to already have been performed.

The main use-case is unit tests launchers.

For these, the command-line-options modifier tells the recipe to produce an executable that will implement some additional command-line options parsing and perform some actions accordingly. On the command-line -- is used as a separator between those additional options and the regular arguments expected by the script.

Example:

[openerp-three]
(...)
openerp_scripts = nosetests command-line-options=-d

This produces a bin/nosetests_openerp-three, which you can use like this:

bin/nosetests_openerp-three -d mydb -- [NOSE REGULAR OPTIONS & ARGUMENTS]

Currently available command-line-options:

Odoo log level¶

This is mostly meant for scripts with the command-line-options=-d modifier.

In some cases, one is not interested in the logs during the Odoo database load. The typical use-case this has been made for is the sphinx-build script, where any warning from Odoo would just make it harder to stop actual documentation warnings, or to limit the output of test launcher before actual testing begins.

The openerp_log_level modifier lets you specify the log level for the openerp logger, at the very start of the script, before any database loading is performed.

In the case of sphinx-build this has the advantage of not affecting the root logger nor the Sphinx dedicated ones.

Of course, the actual script can override that setting once it really starts, in which case the modifier is really only about the loading sequence.

Making the distribution available¶

In order to be used by the recipe, the distribution that holds the script code has to be required with the eggs option. But how can buildout retrieve it ? There’s nothing specific to the Odoo recipe about that, it works in the exact same way as for the standard zc.recipe.eggs recipe.

We list here some possibilities, as a convenience for readers without a more general buildout experience.

• provide it locally and tell buildout to “develop” it:

  [buildout]
  develop = my_script_distribution_path
  

  paths are interpreted relative to the buildout directory, but may be absolute.

• put it on the Python Package Index

• put it in a private index and use the index main buildout option

• prebuild an egg and put it in the eggs directory (can be shared between several buildouts).

• put a source distribution (tarball) or an egg on some HTTP server, and use the find-links global buildout option.

• grab it and develop it from an external VCS, using the gp.vcsdevelop buildout extension.

• use one of the other VCS-oriented buildout extensions (such as mr.developer

Usage for instance creation¶

For projects with a fixed number of modules to install at a given point of code history, upgrade scripts can be used to install a fresh database:

def upgrade(session, logger):
    """Create or upgrade an instance or my_project."""
    if session.is_initialization:
        logger.info("Installing modules on fresh database")
        session.install_modules(['my_module'])
        return

    # now upgrade logic

Not having a command-line argument for modules ot install in the resulting script is a strength. It means that CI robots, deployment tools and the like will be able to install it with zero additional configuration.

The default script produced by the recipe also detects initializations and logs information on how to customize:

2013-10-14 17:16:17,785 WARNING  Usage of upgrade script for initialization detected. You should consider customizing the present upgrade script to add modules install commands. The present script is at : /home/gracinet/openerp/recipe/testing-buildouts/upgrade.py (byte-compiled form)
2013-10-14 17:16:17,786 INFO  Initialization successful. Total time: 22 seconds.

Options of the produced executable upgrade script¶

Command-line parsing is done with argparse. If you have any doubt, use --help with the version you have. Here’s the current state:

$ bin/upgrade_openerp -h
usage: upgrade_openerp [-h] [--log-file LOG_FILE] [--log-level LOG_LEVEL]
                       [--console-log-level CONSOLE_LOG_LEVEL] [-q]
                       [-d DB_NAME]

optional arguments:
  -h, --help            show this help message and exit
  --log-file LOG_FILE   File to log sub-operations to, relative to the current
                        working directory, supports homedir expansion ('~' on
                        POSIX systems). (default: upgrade.log)
  --log-level LOG_LEVEL
                        Main Odoo logging level. Does not affect the
                        logging from the main upgrade script itself. (default:
                        info)
  --console-log-level CONSOLE_LOG_LEVEL
                        Level for the upgrade process console logging. This is
                        for the main upgrade script itself meaning that
                        usually only major steps should be logged (default:
                        info)
  -q, --quiet           Suppress console output from the main upgrade script
                        (lower level stages can still write) (default: False)
  -d DB_NAME, --db-name DB_NAME
                        Database name. If ommitted, the general default values
                        from Odoo config file or libpq will apply.
  --init-load-demo-data
                        Demo data will be loaded with module installations if
                        and only if this modifier is specified (default:
                        False)

Sample output¶

Here’s the output of a run of the default upgrade script:

$ bin/upgrade_openerp -d testrecipe
Starting upgrade, logging details to /home/gracinet/openerp/recipe/testing-buildouts/upgrade.log at level INFO, and major steps to console at level INFO

2013-09-21 18:53:23,471 WARNING  Expected package version file '/home/gracinet/openerp/recipe/testing-buildouts/VERSION.txt' does not exist. version won't be set in database at the end of upgrade. Consider including such a version file in your project *before* version dependent logic is actually needed.
2013-09-21 18:53:23,471 INFO  Database 'testrecipe' loaded. Actual upgrade begins.
2013-09-21 18:53:23,471 INFO  Default upgrade procedure : updating all modules.
2013-09-21 18:53:54,029 INFO  Upgrade successful. Total time: 32 seconds.

The same with a version file:

$ bin/upgrade_openerp -d testrecipe
Starting upgrade, logging details to /home/gracinet/openerp/recipe/testing-buildouts/upgrade.log at level INFO, and major steps to console at level INFO

2013-09-22 19:23:17,908 INFO  Read package version: 6.6.6-final from /home/gracinet/openerp/recipe/testing-buildouts/VERSION.txt
2013-09-22 19:23:17,908 INFO  Database 'testrecipe' loaded. Actual upgrade begins.
2013-09-22 19:23:17,909 INFO  Default upgrade procedure : updating all modules.
2013-09-22 19:23:48,626 INFO  setting version 6.6.6-final in database
2013-09-22 19:23:48,635 INFO  Upgrade successful. Total time: 32 seconds.