Beautiful, robust CLI for Odoo
click-odoo helps you create and run beautiful and robust command line scripts for Odoo. It is based on the excellent Click library.
Useful community-managed scripts can be found in click-odoo-contrib.
Check Odoo is correctly installed: python -c "import odoo" must work when run from another directory than the Odoo root directory.
pip install click-odoo
Assuming the following script named list-users.py.
#!/usr/bin/env python from __future__ import print_function for u in env['res.users'].search(): print(u.login, u.name)
It can be run with:
python -m click_odoo -d dbname --log-level=error ./list-users.py
click-odoo -d dbname --log-level=error ./list-users.py
./list-users.py -d dbname --log-level=error
The other technique to create scripts looks like this. Assuming the following script named list-users2.py.
#!/usr/bin/env python from __future__ import print_function import click import click_odoo @click.command() @click_odoo.env_options(default_log_level='error') @click.option('--say-hello', is_flag=True) def main(env, say_hello): if say_hello: click.echo("Hello!") for u in env['res.users'].search(): print(u.login, u.name) if __name__ == '__main__': main()
It can be run like this:
$ ./list-users2.py --help Usage: list-users2.py [OPTIONS] Options: -c, --config PATH Specify the Odoo configuration file. Other ways to provide it are with the ODOO_RC or OPENERP_SERVER environment variables, or ~/.odoorc (Odoo >= 10) or ~/.openerp_serverrc. -d, --database TEXT Specify the database name. If present, this parameter takes precedence over the database provided in the Odoo configuration file. --log-level TEXT Specify the logging level. Accepted values depend on the Odoo version, and include debug, info, warn, error, critical. [default: error] --logfile PATH Specify the log file. --rollback Rollback the transaction even if the script does not raise an exception. Note that if the script itself commits, this option has no effect, this is why it is not named dry run. This option is implied when an interactive console is started. --say-hello --help Show this message and exit. $ ./list-users2.py --say-hello -d dbname Hello! admin Administrator ...
Finally, you can start an interactive shell by simply typing python -m click_odoo -d dbname or click-odoo -d dbname. This will launch the python REPL with an Odoo env available as a global variable.
Odoo version 11, 12, 13, 14, 15 and 16 are supported.
An important design goal is to provide a consistent behaviour across Odoo versions.
By default click-odoo commits the transaction for you, unless your script raises an exception. This is so that you don’t need to put explicit commits in your scripts, which are therefore easier to compose in larger transactions (provided they pass around the same env).
There is a --rollback option to force a rollback.
A rollback is always performed after an interactive session. If you need to commit changes made before or during an interactive session, use env.cr.commit().
Logging is controlled by the usual Odoo logging options (--log-level, --logfile) or the Odoo configuration file.
Note the --log-level option applies to the odoo package only.
Usage: click-odoo [OPTIONS] [SCRIPT] [SCRIPT_ARGS]... Execute a python script in an initialized Odoo environment. The script has access to a 'env' global variable which is an odoo.api.Environment initialized for the given database. If no script is provided, the script is read from stdin or an interactive console is started if stdin appears to be a terminal. Options: -c, --config FILE Specify the Odoo configuration file. Other ways to provide it are with the ODOO_RC or OPENERP_SERVER environment variables, or ~/.odoorc (Odoo >= 10) or ~/.openerp_serverrc. --addons-path TEXT Specify the addons path. If present, this parameter takes precedence over the addons path provided in the Odoo configuration file. -d, --database TEXT Specify the database name. If present, this parameter takes precedence over the database provided in the Odoo configuration file. --log-level TEXT Specify the logging level. Accepted values depend on the Odoo version, and include debug, info, warn, error. [default: info] --logfile FILE Specify the log file. --rollback Rollback the transaction even if the script does not raise an exception. Note that if the script itself commits, this option has no effect. This is why it is not named dry run. This option is implied when an interactive console is started. -i, --interactive / --no-interactive Inspect interactively after running the script. --shell-interface TEXT Preferred shell interface for interactive mode. Accepted values are ipython, ptpython, bpython, python. If not provided they are tried in this order. --help Show this message and exit.
Most options above are the same as odoo options and behave identically. Additional Odoo options can be set in the the configuration file. Note however that most server-related options (workers, http interface etc) are ignored because no server is actually started when running a script.
An important feature of click-odoo compared to, say, odoo shell is the capability to pass arguments to scripts.
In order to avoid confusion between click-odoo options and your script options and arguments, it is recommended to separate them with --:
click-odoo -d dbname -- list-users.py -d a b ./list-users.py -d dbname -- -d a b
In both examples above, sys.argv[1:] will contain ['-d', 'a', 'b'] in the script.
@click_odoo.env_options() is a decorator that is used very much like @click.option() and inserts the list of predefined click-odoo options. Instead of passing down these options to the command, it prepares an odoo Environment and passes it as a env parameter.
It is configurable with the following keyword arguments:
The default value for the --log-level option (default: ‘info’).
Controls the presence of the --rollback option (default: True). This is useful for creating commands that commit and leave no possibility for rollback.
Controls the presence of the --database option (default: True). This is useful to create scripts that have access to a pre-loaded Odoo configuration, without any database. In such case, the environment is not set (env is None). If with_database is False, database_required is implied to be False too.
Controls if a database must be provided through the --database option or the Odoo configuration file (default: True).
If this flag is False and the selected database does not exist do not fail and pass env=None instead (default: True).
Controls the presence of the --addons-path option (default: False).
experimental feature A context manager that yields an intialized odoo.api.Environment. It is invoked after Odoo configuration parsing and initialization. It must have the following signature (identical to OdooEnvironment below, plus the click ctx as well as **kwargs for future proofing):
environment_manager(database, rollback, ctx, **kwargs)
click_odoo.env_options is a class that can be extended for customization purposes.
It currently has one method that is intended to be overridden, with the following signature:
def get_odoo_args(self, ctx: click.Context) -> List[str]: ...
It must return a list of Odoo command line arguments computed from the Click context. It will be called after parsing all parameters of the command, and before initializing Odoo and invoking the command function.
As a convenience click_odoo exports the odoo namespace, so from click_odoo import odoo is an alias for import odoo.
This package also provides an experimental OdooEnvironment context manager. It is meant to be used in after properly intializing Odoo (ie parsing the configuration file etc).
from click_odoo import OdooEnvironment with OdooEnvironment(database='dbname') as env: env['res.users'].search()
To run tests, type tox. Tests are made using pytest. To run tests matching a specific keyword for, say, Odoo 12 and python 3.6, use tox -e py36-12.0 -- -k keyword.
This project uses black as code formatting convention, as well as isort and flake8. To make sure local coding convention are respected before you commit, install pre-commit and run pre-commit install after cloning the repository.
Stéphane Bidoul (ACSONE)
Inspiration has been drawn from:
This project is maintained by ACSONE SA/NV.
Add CI tests for Odoo 16 and Python 3.10. (#51)
Deprecations and Removals
Drop support for python < 3.6 and Odoo 8, 9, 10. (#48)
Silenced a noisy warning about Environment.manage() being a no-op in Odoo 15. (#43)
Refined ImportError detection in from click_odoo import odoo, for easier diagnostic of Odoo installation issues. (#36)
Odoo 8 unconditionally registers wsgi handlers, which has the surprising side effect to start a server in some circumstances, for instance when calling env["ir.module.module"].update_list() in click-odoo-initdb. Disable them in click-odoo initialization, since they are useless and other Odoo version do not install them.
Support Odoo saas versions.
revert change to logging made in 1.4.0
add support for launching with python -m click_odoo. Fixes #20.
apply --log-level to the root logger, so it works more intuitively by applying to the script too, and not only to the odoo namespace. This may change the log output of some scripts. In particular, --log-level=debug will now apply debug logging to every python library used, and not only to Odoo. Fine tuning is available through the log_handler configuration item.
support Odoo config files with multiple comma separate databases names in db_name config entry.
pass click ctx to environment_manager
refactor @click_odoo.env_options to allow propagating env to subcommands through the click context. Fixes #16.
do not log click Exit exception, which may be raised by subcommands as a result of –help.
Upgrading: - click-odoo now requires click>=7
add with_addons_path option to @click_odoo.env_options to control the presence of the --addons-path option. Defaults to False. Enabled for the click-odoo CLI.
add environment_manager to @click_odoo.env_options, providing a hook on odoo.api.Environment creation.
add --addons-path option to the CLI.
add database_must_exist option to @click_odoo.env_options so scripts can behave how they please in case the database is absent.
silence deprecation warning
adapt tests for Odoo 12
clarify the behaviour of @env_option with_database and database_required parameters; in particular, when with_database and database_required are both set (the default), the --database option can be omitted as long as a database is declared in the Odoo configuration file.
refactor the OdooEnvironment class: it is much cleaner when it leaves the global Odoo config alone, so we completely move responsibility to initialize the Odoo config to the CLI part.
better error logging and handling: all exceptions occuring in scripts under click_odoo.env_options are logged and converted to ClickException so we are sure they are both in the log file and on the console (handled by click) for the user to see. The OdooEnvironment context manager does not do additional logging, leaving that responsibility to the caller.
close db connections when releasing OdooEnvironment
expose click_odoo.odoo_bin (odoo or openerp-server depending on Odoo series). not documented yet, because it should ideally be a full path corresponding to the installed click_odoo.odoo, and I’m not sure how best to detect it yet.
minor documentation improvements
add the possibility to run script without --database (ie without env, but with a properly initialized Odoo library such as addons path)
be more resilient in case we can’t obtain a context for the user
click_odoo now exports the odoo namespace: from click_odoo import odoo is an alias for import odoo (>9) or import openerp as odoo (<=9)
add a with_rollback option to the env_options decorator, to control the presence of the rollback option
document the env_options decorator
commit in case of success, so users do not need to commit in their scripts, therefore making scripts easier to compose in larger transactions
add a –rollback option
interactive mode forces –rollback
clear cache when starting environment (mostly useful for tests)
simplify and test transaction and exception handling
when leaving the env, log the exception to be sure it is visible when using --logfile
improve transaction management: avoid some rare deadlock
avoid masking original exception in case of error during rollback
make sure scripts launched by click-odoo have __name__ == '__main__'
add --logfile option
Release history Release notifications | RSS feed
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Hashes for click_odoo-1.6.0-py3-none-any.whl