setuptools-odoo 2.0.1

A library to help package Odoo addons with setuptools

setuptools-odoo is a library to help packaging Odoo addons with setuptools. It mainly populates the usual setup.py keywords from the Odoo manifest files.

It enables the packaging and distribution of Odoo addons using standard python infrastructure (ie setuptools, pip, wheel, and pypi).

Contents

• Requirements

• Packaging a single addon

• Packaging multiple addons

• Controlling setuptools-odoo behaviour

• setuptools-odoo-make-default helper script

• Versioning

• Helper API

• Useful links

• Credits

• Changes

  • 2.0.0 (2017-09-19)

  • 1.0.1 (2017-04-08)

  • 1.0.0 (2017-04-07)

  • 1.0.0rc4 (2017-02-21)

  • 1.0.0rc3 (2017-01-14)

  • 1.0.0rc2 (2016-10-07)

  • 1.0.0rc1 (2016-10-03)

  • 1.0.0b7 (2016-09-22)

  • 1.0.0b6 (2016-08-23)

  • 1.0.0b5 (2016-05-03)

  • 1.0.0b4 (2016-04-06)

  • 1.0.0b3 (2016-02-10)

  • 1.0.0b2 (2016-01-26)

  • 1.0.0b1 (2015-12-29)

  • 0.9.0 (2015-12-13)

Requirements

The following prerequisites apply:

• Odoo version 8, 9, 10 and 11 are supported (see notes in the documentation for implementation differences).

• To install addons packaged with this tool, any pip version that supports the wheel package format should work (ie pip >= 1.4).

• For any advanced use such as installing from source, installing from git, packaging wheels etc, you need a recent version of pip (>= 9.0.1).

• Finally, you need to install odoo-autodiscover (pip install odoo-autodiscover) to provide automatic extension of the addons path (and workaround a bug with setuptools > 31 and Odoo 10).

Packaging a single addon

To be packaged with this library, the addon source code must have the following structure (assuming the addon is named <addon_name>):

# Odoo 11
setup.py
odoo/
odoo/addons/
odoo/addons/<addon_name>/
odoo/addons/<addon_name>/__manifest__.py
odoo/addons/<addon_name>/...

# Odoo 10
setup.py
odoo/
odoo/__init__.py
odoo/addons/
odoo/addons/__init__.py
odoo/addons/<addon_name>/
odoo/addons/<addon_name>/__manifest__.py
odoo/addons/<addon_name>/...

# Odoo 8, 9
setup.py
odoo_addons/
odoo_addons/__init__.py
odoo_addons/<addon_name>/
odoo_addons/<addon_name>/__openerp__.py
odoo_addons/<addon_name>/...

where odoo/__init__.py, odoo/addons/__init__.py, and odoo_addons/__init__.py are standard python namespace package declaration __init__.py (note absent __init__.py for Odoo 11):

__import__('pkg_resources').declare_namespace(__name__)

and where setup.py has the following content:

import setuptools

setuptools.setup(
    setup_requires=['setuptools-odoo'],
    odoo_addon=True,
)

The usual setup() keyword arguments are computed automatically from the Odoo manifest file (__manifest__.py or __openerp__.py) and contain:

• name: the package name, odoo<series>-addon-<addon_name>

• version: the version key from the manifest

• description: the summary key from the manifest if it exists otherwise the name key from the manifest

• long_description: the content of the README.rst file if it exists, otherwise the description key from the manifest

• url: the website key from the manifest

• license: the license key from the manifest

• packages: autodetected packages

• namespace_packages: ['odoo', 'odoo.addons'] (Odoo 10) or ['odoo_addons'] (Odoo 8, 9), absent for Odoo 11

• zip_safe: False

• include_package_data: True

• install_requires: dependencies to Odoo, other addons (except official odoo community and enterprise addons, which are brought by the Odoo dependency) and python libraries.

• python_requires

Then, the addon can be deployed and packaged with usual setup.py or pip commands such as:

python setup.py install
python setup.py develop
python setup.py bdist_wheel
pip install odoo<8|9|10|11>-addon-<addon name>
pip install -e .
pip install -e git+https://github.com/OCA/<repo>/<addon>#egg=odoo<8|9|10|11>-addon-<addon name>\&subdirectory=setup/<addon name>

Note

When using pip to install from source, the -e option is important because of pip issue #3500. The -e option has the huge advantage of letting pip freeze produce meaningful output.

When odoo-server-autodiscover is installed, The addons-path is automatically populated with all places providing odoo addons installed with this method.

It is of course highly recommanded to run in a virtualenv.

Note

Odoo 8, 9 namespace.

Although the addons are packaged in the odoo_addons namespace, the code can still import them using import odoo.addons..... odoo_addons must never appear in the code, it is just a packaging peculiarity for Odoo 8 and 9 only, and does not require any change to the addons source code.

Packaging multiple addons

Addons that are intended to be reused or depended upon by other addons MUST be packaged individually. When preparing a project for a specific customer, it is common to prepare a collection of addons that are not intended to be depended upon by addons outside of the project. setuptools-odoo provides tools to help you do that.

To be packaged with this library, your project must be structured according to the following structure:

# Odoo 11
setup.py
odoo/
odoo/addons/
odoo/addons/<addon1_name>/
odoo/addons/<addon1_name>/__manifest__.py
odoo/addons/<addon1_name>/...
odoo/addons/<addon2_name>/
odoo/addons/<addon2_name>/__manifest__.py
odoo/addons/<addon2_name>/...

# Odoo 10
setup.py
odoo/
odoo/__init__.py
odoo/addons/
odoo/addons/__init__.py
odoo/addons/<addon1_name>/
odoo/addons/<addon1_name>/__manifest__.py
odoo/addons/<addon1_name>/...
odoo/addons/<addon2_name>/
odoo/addons/<addon2_name>/__manifest__.py
odoo/addons/<addon2_name>/...

# Odoo 8, 9
setup.py
odoo_addons/
odoo_addons/__init__.py
odoo_addons/<addon1_name>/
odoo_addons/<addon1_name>/__openerp__.py
odoo_addons/<addon1_name>/...
odoo_addons/<addon2_name>/
odoo_addons/<addon2_name>/__openerp__.py
odoo_addons/<addon2_name>/...

where setup.py has the following content:

import setuptools

setuptools.setup(
    name='<your project package name>',
    version='<your version>',
    # ...any other setup() keyword
    setup_requires=['setuptools-odoo'],
    odoo_addons=True,
)

The following setup() keyword arguments are computed automatically from the Odoo manifest files (__manifest__.py or __openerp__.py) and contain:

• packages: autodetected packages

• namespace_packages: ['odoo', 'odoo.addons'] (Odoo 10) or ['odoo_addons'] (Odoo 8, 9), absent for Odoo 11

• zip_safe: False

• include_package_data: True

• install_requires: dependencies on Odoo, any depending addon not found in the addons directory, and external python dependencies.

• python_requires

Controlling setuptools-odoo behaviour

It is possible to use a dictionary instead of True for the odoo_addon and odoo_addons keywords, in order to control their behaviour.

The following keys are supported:

• depends_override, used to precisely control odoo addons dependencies. Its value must be a dictionary mapping addon names to a package requirement string.

• external_dependencies_override, used to precisely control python external dependencies. Its value must be a dictionary with one python key, with value a dictionary mapping python external dependencies to python package requirement strings.

• odoo_version_override, used to specify which Odoo series to use (8.0, 9.0, 10.0, 11.0) in case an addon version does not start with the Odoo series number. Use this only as a last resort, if you have no way to correct the addon version in its manifest.

For instance, if your module requires at least version 10.0.3.2.0 of the connector addon, as well as at least version 0.5.5 of py-Asterisk, your setup.py would look like this:

import setuptools

setuptools.setup(
    setup_requires=['setuptools-odoo'],
    odoo_addon={
        'depends_override': {
            'connector': 'odoo10-addon-connector>=10.0.3.2.0',
        },
        'external_dependencies_override': {
            'python': {
                'Asterisk': 'py-Asterisk>=0.5.5',
            },
        },
    },
)

setuptools-odoo-make-default helper script

Since reusable addons are generally not structured using the namespace package but instead collected in a directory with each subdirectory containing an addon, this package provides the setuptools-odoo-make-default script which creates a default setup.py for each addon according to the following structure:

# Odoo 11
setup/
setup/addon1/
setup/addon1/setup.py
setup/addon1/odoo/
setup/addon1/odoo/addons/
setup/addon1/odoo/addons/<addon1_name> -> ../../../../<addon1_name>
setup/addon2/setup.py
setup/addon1/odoo/
setup/addon2/odoo/addons/
setup/addon2/odoo/addons/<addon2_name> -> ../../../../<addon2_name>
<addon1_name>/
<addon1_name>/__manifest__.py
<addon1_name>/...
<addon2_name>/
<addon2_name>/__manifest__.py
<addon2_name>/...

# Odoo 10
setup/
setup/addon1/
setup/addon1/setup.py
setup/addon1/odoo/
setup/addon1/odoo/__init__.py
setup/addon1/odoo/addons/
setup/addon1/odoo/addons/__init__.py
setup/addon1/odoo/addons/<addon1_name> -> ../../../../<addon1_name>
setup/addon2/setup.py
setup/addon1/odoo/
setup/addon1/odoo/__init__.py
setup/addon2/odoo/addons/
setup/addon2/odoo/addons/__init__.py
setup/addon2/odoo/addons/<addon2_name> -> ../../../../<addon2_name>
<addon1_name>/
<addon1_name>/__manifest__.py
<addon1_name>/...
<addon2_name>/
<addon2_name>/__manifest__.py
<addon2_name>/...

# Odoo 8, 9
setup/
setup/addon1/
setup/addon1/setup.py
setup/addon1/odoo_addons/
setup/addon1/odoo_addons/__init__.py
setup/addon1/odoo_addons/<addon1_name> -> ../../../<addon1_name>
setup/addon2/setup.py
setup/addon2/odoo_addons/
setup/addon2/odoo_addons/__init__.py
setup/addon2/odoo_addons/<addon2_name> -> ../../../<addon2_name>
<addon1_name>/
<addon1_name>/__openerp__.py
<addon1_name>/...
<addon2_name>/
<addon2_name>/__openerp__.py
<addon2_name>/...

Versioning

setuptools-odoo does its best to detect if an addon has changed compared to the version indicated in it’s manifest. To this end it explores the git log of the addon subtree.

If the last change to the addon corresponds to the version number in the manifest, it is used as is for the python package version. Otherwise a counter is incremented for each commit and the resulting version number has the following form: [8|9|10|11].0.x.y.z.99.devN, N being the number of git commits since the version change.

This scheme is compliant with the accepted python versioning scheme documented in PEP 440.

The 99 suffix is there to make sure it is considered as posterior to x.y.z. (.postN is ignored by pip, as specified in PEP 440, and x.y.z.devN is considered anterior to x.y.z.).

Note

for pip to install a developmental version, it must be invoked with the –pre option.

Helper API

Note

TODO

Should you have a use case for using the setuptools-odoo internals, get in touch so we can review your needs and expose a clean API.

Useful links

• pypi page: https://pypi.python.org/pypi/setuptools-odoo

• documentation: https://setuptools-odoo.readthedocs.io

• code repository: https://github.com/acsone/setuptools-odoo

• report issues at: https://github.com/acsone/setuptools-odoo/issues

• see also odoo-autodiscover: https://pypi.python.org/pypi/odoo-autodiscover

Credits

Author:

• Stéphane Bidoul (ACSONE)

Many thanks to Daniel Reis who cleared the path, and Laurent Mignon who convinced me it was possible to do it using standard Python setup tools and had the idea of the odoo_addons namespace package.

Changes

2.0.0 (2017-09-19)

• [IMP] update base addons list for Odoo 10.0

• [IMP] when setuptools extends a list-type keyword, prevent duplicate items

• [IMP] make tests pass with python 3

• [ADD] preliminary Odoo 11 support

• [IMP] BREAKING: remove LEGACY_MODE support

• [IMP] python_requires is now part of the generated keywords

• [CHG] In the classifiers, use Python instead of Python :: 2.7 since we now have python_requires that is more precise

1.0.1 (2017-04-08)

• [ADD] add license classifier for the licenses commonly used in OCA

1.0.0 (2017-04-07)

• [ADD] support the brand new Framework :: Odoo classifier

1.0.0rc4 (2017-02-21)

• [FIX] avoid setuptools-git version 1.2 as it is broken for our use case

1.0.0rc3 (2017-01-14)

• [FIX] git based automatic postversioning was not working in situations where the manifest was renamed (eg when renaming __openerp__.py to __manifest__.py)

• [IMP] support author email: since the Odoo manifest has no such concept this is currently just a special case when OCA is in the authors

1.0.0rc2 (2016-10-07)

• [IMP] 10.0 addons now depend on the specific Odoo version again (>=10.0, <10.1dev)

1.0.0rc1 (2016-10-03)

• [IMP] Odoo 10.0 support with addons in the odoo.addons namespace.

• [IMP] update base addons list for Odoo 9.0 and 10.0rc1

1.0.0b7 (2016-09-22)

• [IMP] add __manifest__.py support for Odoo 10, drop __odoo__.py support which has never been supported by Odoo.

• [IMP] BREAKING: package names are now constructed along the following scheme: odoo{series}-addon-{addon_name} where series is 8, 9 or 10.

1.0.0b6 (2016-08-23)

• [IMP] the odoo_addon and odoo_addons keyword now extend list keywords such as install_requires if they are present in setup.py (previously, it left them alone); this is useful to create a package that contains odoo addons in addition to other python packages

• [IMP] allow None as value for depends_override to disable the addition of an addon present in __openerp__.py ‘depends’ key to setup.py ‘install_requires’

• [IMP] check if Odoo version is supported also in presence of odoo_version_override

• [ADD] preliminary OpenErp 7.0 support

• [ADD] –odoo-version-override to setuptools-odoo-make-default to use when there is no practical way to normalize addons versions

• [FIX] when using odoo_version_override, make sure the package version starts with the Odoo version, otherwise dependencies from other packages do not work

• [UPD] refresh base addons list for odoo 9c with new modules added over the last months

1.0.0b5 (2016-05-03)

• [FIX] fix bug of previous release that prevented the packaging of a single auto_install addon

1.0.0b4 (2016-04-06)

• [UPD] pycrypto in external dependencies map

• [ADD] setuptools-odoo-make-default now ignores addons listed in .setuptools-odoo-make-default-ignore; this is useful when some addons are manually included in another package (such as autoinstallable glue modules)

• [ADD] setuptools-odoo-make-default now generates README and .setuptools-odoo-make-default-ignore files at the root of the setup directory

• [IMP] the odoo_addon setup keyword now accepts several addons in the odoo_addons namespace, provided exactly one is installable and not auto installable. This is meant to package an addon together with one or more auto_installable glue modules.

1.0.0b3 (2016-02-10)

• [ADD] mechanism to specify which Odoo version to use in dependencies (8.0, 9.0) in case some addons to be packaged have non-standard version numbers

• [ADD] support for addons without version number in their manifest (unfortunately there are some in the wild…)

1.0.0b2 (2016-01-26)

• [ADD] mechanism to override dependencies, to allow addon authors to require minimal versions of dependent odoo addons, and to control external python dependencies

1.0.0b1 (2015-12-29)

• [FIX] fix postversioning when running outside git directory

• [IMP] additional mappings for python external dependencies

• [ADD] make_pkg_name public api to convert an addon name to a python package name

• [ADD] make_pkg_requirement public api to obtain a valid package requirement for a given addon (same as make_pkg_name but includes requirement for the correct Odoo series)

• [FIX] crash in case a previous commit had a bad __openerp__.py

0.9.0 (2015-12-13)

• first beta