setuptools-odoo 3.3

需求

以下为必备条件

• 支持Odoo版本8, 9, 10, 11, 12, 13, 14, 15和16（有关实现差异的说明，请参阅文档中的注释）。

• 要安装此工具打包的插件，任何支持wheel包格式的pip版本都应适用（即pip >= 1.4）。

• 对于任何高级用途，如从源安装、从git安装、打包wheel等，您需要pip的较新版本（>= 9.0.1）。

• 最后，如果您使用的是Odoo 8、9或10，您需要安装odoo-autodiscover（pip install odoo-autodiscover）以提供自动扩展插件路径（以及解决setuptools > 31和Odoo 10的bug）。对于Odoo >= 11，odoo-autodiscover不是必需的。

打包单个插件

要与此库打包，插件源代码必须具有以下结构（假设插件名为<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>/...

其中odoo/__init__.py、odoo/addons/__init__.py和odoo_addons/__init__.py是标准的Python命名空间包声明__init__.py（注意Odoo >= 11时不存在__init__.py）

__import__('pkg_resources').declare_namespace(__name__)

而setup.py的内容如下

import setuptools

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

通常的setup()关键字参数会自动从Odoo清单文件（__manifest__.py或__openerp__.py）计算得出，并包含以下内容

• name：包名，odoo<series>-addon-<addon_name>

• version：清单中的version键

• description：如果存在，则为清单中的summary键，否则为清单中的name键

• long_description：如果存在，则为README.rst文件的内容，否则为清单中的description键

• url：清单中的website键

• license：清单中的license键

• packages：自动检测的包

• namespace_packages：['odoo', 'odoo.addons']（Odoo 10）或['odoo_addons']（Odoo 8、9），Odoo 11不存在

• zip_safe：False

• include_package_data：True

• install_requires：对Odoo、其他插件（除Odoo社区版和企业版插件外，它们由Odoo依赖引入）和Python库的依赖关系。

• python_requires

然后，可以使用通常的pip命令部署和打包插件，例如

pip install odoo<8|9|10|11|12|13|14>-addon-<addon name>
pip install "git+https://github.com/OCA/<repo>#subdirectory=setup/<addon name>"
pip install "git+https://github.com/OCA/<repo>@<branch or reference>#subdirectory=setup/<addon name>"
pip install -e .
pip wheel .
python -m build

当然，强烈建议在虚拟环境中运行。

打包多个插件

打算被其他插件重用或依赖的插件必须单独打包。在为特定客户准备项目时，通常准备一系列插件集合，这些插件不打算被项目之外的插件依赖。setuptools-odoo 提供了帮助您完成此操作的工具。

要与此库一起打包，您的项目必须根据以下结构进行组织

# 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>/...

其中 setup.py 包含以下内容

import setuptools

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

以下 setup() 关键字参数自动从 Odoo 清单文件（__manifest__.py 或 __openerp__.py）计算得出，并包含以下内容

• packages：自动检测的包

• namespace_packages： ['odoo', 'odoo.addons']（Odoo 10）或 ['odoo_addons']（Odoo 8、9），Python 3 中不存在（Odoo 11 及以后版本）

• zip_safe：False

• include_package_data：True

• install_requires：对 Odoo、不在插件目录中找到的任何依赖插件以及外部 Python 依赖的依赖。

• python_requires

安装Odoo CE和EE插件

setuptools-odoo 内置了对 Odoo 社区和企业版本中包含的插件的了解。对这些插件的依赖被视为由 odoo 分发满足。

这意味着 Odoo 必须在您的 Python 环境中 安装。

从 Odoo 8 到 16，安装 Odoo 的一个好方法是在虚拟环境中进行。有多种可能性，但以下 bash 命令应该能让您入门

$ python3 -m venv ./venv
$ source ./venv/bin/activate
(venv) $ python3 -m pip install --upgrade pip wheel
(venv) $ python3 -m pip install -r ./odoo/requirements.txt
(venv) $ python3 -m pip install -e ./odoo

之后，./venv/bin/pip list 将显示 odoo 作为已安装项目的一部分，运行 ./venv/bin/odoo 将使用适当的插件路径启动 Odoo。

如果您需要添加 Odoo 企业插件，可以使用 --addons-path Odoo 选项使它们对 Odoo 可见，或者将它们打包在多插件项目中，然后按照上述方法使用 pip 安装。

控制setuptools-odoo行为

可以使用字典代替 True 为 odoo_addon 和 odoo_addons 关键字，以控制其行为。

支持以下键

• depends_override，用于精确控制 Odoo 插件依赖。其值必须是将插件名称映射到包要求字符串的字典。

• external_dependencies_override，用于精确控制 Python 外部依赖。其值必须是包含一个 python 键的字典，该键具有将 Python 外部依赖映射到 Python 包要求指定符或指定符列表的字典值。

• odoo_version_override，用于指定要使用哪个 Odoo 系列（8.0、9.0、10.0、11.0、……），如果插件版本不以 Odoo 系列数字开头。仅在无法在插件的清单中更正插件版本的情况下，作为最后的手段使用。

• post_version_strategy_override，用于指定如何使用 git 提交来修改清单中找到的版本（见下面的 版本控制 部分）。

例如，如果您的模块需要至少版本 10.0.3.2.0 的连接器插件，以及至少版本 0.5.5 的 py-Asterisk，则您的 setup.py 将如下所示

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',
                'somepkg': [
                  'somepkg<3 ; python_version < "3"',
                  'somepkg>=3 ; python_version > "3"',
                ]
            },
        },
    },
)

setuptools-odoo-make-default辅助脚本

由于可重用插件通常不是使用命名空间结构化，而是收集在目录中，每个子目录包含一个插件，因此此包提供 setuptools-odoo-make-default 脚本，该脚本根据以下结构为每个插件创建默认的 setup.py

# 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>/...

可用选项

usage: setuptools-odoo-make-default [-h] --addons-dir ADDONS_DIR [--force]
                                    [--odoo-version-override ODOO_VERSION_OVERRIDE]
                                    [--metapackage METAPACKAGE] [--clean]
                                    [--commit]

Generate default setup.py for all addons in an Odoo addons directory

optional arguments:
  -h, --help            show this help message and exit
  --addons-dir ADDONS_DIR, -d ADDONS_DIR
  --force, -f
  --odoo-version-override ODOO_VERSION_OVERRIDE
                        Force Odoo version for situations where some addons
                        versions do not start with the odoo version.
  --metapackage METAPACKAGE, -m METAPACKAGE
                        Create a metapackage using the given name. This
                        package depends on all installable addons in
                        ADDONS_DIR.
  --clean, -c           Clean the setup directory: remove setups of
                        uninstallable addons, remove files corresponding to
                        other Odoo versions, remove metapackage setup if there
                        are no installable addons.
  --commit              Git commit changes, if any.

setuptools-odoo-make-default 还可以作为 pre-commit 插件使用。要使用它，您可以在您的 .pre-commit-config.yaml 中添加以下条目

repos:
  - repo: https://github.com/acsone/setuptools-odoo
    rev: 2.5.2
    hooks:
      - id: setuptools-odoo-make-default

setuptools-odoo-get-requirements辅助脚本

由于在 Odoo 世界中，通常在仓库根目录下有一个名为 requirements.txt 的文件，因此此脚本有助于从 add-ons 清单中声明的外部依赖项生成它。

usage: setuptools-odoo-get-requirements [-h] [--addons-dir ADDONS_DIR] [--output OUTPUT]

Print external python dependencies for all addons in an Odoo addons directory.
If dependencies overrides are declared in setup/{addon}/setup.py, they are
honored in the output.

optional arguments:
  -h, --help            show this help message and exit
  --addons-dir ADDONS_DIR, -d ADDONS_DIR
                        addons directory (default: .)
  --output OUTPUT, -o OUTPUT
                        output file (default: stdout)
  --header HEADER       output file header
  --include-addons      Include addons and odoo requirements in addition to
                        python external dependencies (default: false).

版本控制

默认情况下，setuptools-odoo 会尽力检测 add-on 是否与清单中指示的版本有所不同。为此，它探索 add-on 子树的 git 日志。

如果 add-on 的最后更改与清单中的版本号相对应，则将其直接用作 Python 包版本。否则，对于每个提交，计数器都会递增，并且生成的版本号包含该计数器。

默认策略取决于 Odoo 系列。其形式如下，N 表示自版本更改以来的 git 提交数。

• 策略 .99.devN 是 8 到 12 系列的默认策略，产生 [8|9|10|11|12].0.x.y.z.99.devN。

• 策略 +1.devN 是 13 和 14 系列的默认策略，产生 [13|14].0.x.y.z+1.devN。

• 策略 .N 是 15 系列及以后的默认策略，添加一个数字，通常产生 [series].0.x.y.z.N。

• 策略 none 默认不使用，并禁用后版本化机制，产生在清单中找到的版本。

这些方案符合在 PEP 440 中记录的接受 Python 版本控制方案。

可以使用 post_version_strategy_override 关键字或 SETUPTOOLS_ODOO_POST_VERSION_STRATEGY_OVERRIDE 环境变量来覆盖默认策略。如果设置且不为空，则环境变量比 setup.py 关键字具有优先级。

公共API

setuptools_odoo 软件包公开了临时公共 API。

• get_addon_metadata(addon_dir, ...) 返回一个符合 Python 核心元数据规范 的 email.message.Message。

有用的链接

• PyPI 页面： https://pypi.python.org/pypi/setuptools-odoo

• 文档： https://setuptools-odoo.readthedocs.io

• 代码仓库： https://github.com/acsone/setuptools-odoo

• 在： https://github.com/acsone/setuptools-odoo/issues 报告问题

• 另请参阅 odoo-autodiscover: https://pypi.python.org/pypi/odoo-autodiscover

鸣谢

作者

• Stéphane Bidoul (ACSONE)

贡献者

• Benjamin Willig

• Matteo Bilotta

感谢 Daniel Reis 清晰的路径，以及 Laurent Mignon，他使我确信可以使用标准 Python 打包工具完成它，并提出了 odoo_addons 命名空间包的想法。

变更