一键安装程序/嵌入代码

xlwings PRO 提供了一种简单的方法，可以将您的 xlwings 工具部署给最终用户，而无需通常在安装和配置 Python 和 xlwings 时涉及的麻烦。最终用户不需要了解任何关于 Python 的知识，因为他们只需要：

  • 运行安装程序（一个安装程序可以支持多个不同的 Excel 工作簿）

  • 将 Excel 工作簿像普通的宏启用工作簿一样使用

优势：

  • 零配置：最终用户在整个过程中不需要进行任何配置。

  • 无需加载项：无需安装 xlwings 加载项。

  • 易于更新：如果您想部署 Python 代码的新版本，通常分发工作簿的新版本就足够了。

  • 无冲突：安装程序不会修改任何环境变量或注册表项，因此不会与现有的 Python 安装产生冲突。

  • 部署密钥：发布命令会将部署密钥作为您的 LICENSE_KEY 添加。部署密钥不会过期，并且最终用户不需要付费订阅。

作为开发人员，您需要创建一键安装程序并在工作簿上运行xlwings release命令。让我们详细介绍一下这两个步骤！

视频教程位于：https://www.youtube.com/watch?v=yw36VT_n1qg

第一步：一键安装程序

作为我们之一的订阅者付费计划，您将获得访问私人 GitHub 仓库的权限，在那里您可以构建自己的一键安装程序：

  1. 使用您的依赖项更新requirements.txt文件：在您的仓库中，首先点击requirements.txt文件。这将打开以下屏幕，您可以在其中点击铅笔图标以编辑文件（如果您熟悉 Git，也可以克隆仓库并使用本地提交/推送工作流）：

../_images/gh_edit_requirements.png

编辑完成后，点击绿色的Commit changes按钮配合使用的工作簿。

注意

如果您不确定依赖项，最好在虚拟或 Conda 环境中本地工作。在虚拟/Conda 环境中，只安装您需要的包，然后运行：pip list --format=freeze.

  1. 在登录页面的右侧，点击Releases:

../_images/gh_releases.png

在下一个屏幕上，点击Draft a new release（注意，第一次时，您会看到一个名为Create a new release的绿色按钮）：

../_images/gh_create_release.png

这将弹出以下屏幕，您只需填写Tag version（例如，1.0.0），然后点击绿色按钮Publish release:

../_images/gh_publish_release.png

约 3-5 分钟后（您可以通过Actions标签页跟踪进度），您将在“发布”下找到准备下载的安装程序（忽略zip和tar.gz文件）：

../_images/gh_installer_download.png

注意

一键安装程序是一个正常的 Python 安装程序，可以与多个 Excel 工作簿一起使用。因此，只要所有工作簿都使用由requirements.txt文件。

第二步：发布命令（CLI）

发布命令是 xlwings CLI（命令行客户端）的一部分，它将准备您的 Excel 文件，以便与上一步生成的一键安装程序配合使用。在此之前：

  • 确保您已启用Trust access to the VBA project object model在File > Options > Trust Center > Trust Center Settings > Macro Settings。您只需执行一次此操作，由于这是一个开发者设置，最终用户无需担心。此设置是为了让 xlwings 能够用正确的 VBA 代码版本更新 Excel 文件。

  • 运行上一步中的安装程序。这不会干扰您现有的 Python 安装，因为它不会修改您的环境变量或注册表。相反，它只会写入以下文件夹：%LOCALAPPDATA%\<installer-name>.

  • 确保您本地的 xlwings 版本与安装程序中的 xlwings 版本对应。最简单的检查方法是在命令提示符或 Anaconda 提示符中运行requirements.txt from the installer. The easiest way to double-check this is to run pip freeze。如果您的本地 xlwings 版本不同，请通过以下方式安装与安装程序相同的版本：pip install xlwings==<version from installer>.

要与发布命令一起工作，您应该将工作簿放在xlsm格式中，与您的 Python 代码相邻：

myworkbook.xlsm
mymodule_one.py
mypackage/
  mymodule_two.py
...

确保您的 Excel 工作簿是活动工作簿，然后在命令/Anaconda 提示符下运行以下命令：

xlwings release

如果这是您第一次运行此命令，系统会询问您一些问题。如果显示[Y/n]，您可以按 Enter 键接受默认值，如大写字母所示：

  • Name of your one-click installer? 输入您的一键安装程序的名称。如果您想使用不同的 Python 发行版（例如，Anaconda），可以留空（但需要在发布命令运行后更新 xlwings.conf 表格中的 Conda 设置）。

  • Embed your Python code? [Y/n] 这将把 Python 代码复制到 Excel 文件的工作表中。

  • Hide the config sheet? [Y/n] 这将隐藏 xlwings.conf 表格。

  • Hide the sheets with the embedded Python code? [Y/n] 如果您嵌入 Python 代码，这将隐藏所有以 .py 结尾的工作表。

  • Allow your tool to run without the xlwings add-in? [Y/n] 这将删除对 xlwings 的 VBA 引用，并复制 xlwings VBA 模块，因此最终用户无需安装 xlwings 加载项。请注意，在这种情况下，您需要将 RunPython 调用绑定到按钮上，因为您不能再使用功能区的主运行按钮。

无论您选择什么答案，都可以通过编辑xlwings.conf表格或删除xlwings.conf表格并重新运行xlwings release命令来随时更改它们。如果选择默认值，您只需向最终用户提供一键安装程序和 Excel 工作簿，无需外部 Python 文件。

更新发布版本

若要编辑Python代码，最简单的方法是使用外部Python文件而不是嵌入式代码。要停止xlwings使用嵌入式代码，只需删除所有以.py结尾的工作表，工作簿将再次使用外部Python模块。完成文件编辑后，只需再次运行xlwings release命令，这将嵌入更新后的代码。如果您没有对依赖项进行任何更改（即，没有升级包或引入新包），则只需要重新部署您的Excel工作簿，最终用户即可获得更新。

如果您确实对requirements.txt进行了更改并发布了一个新的单击安装程序，则需要用户先安装新版本的安装程序。

注意

每当您在requirements.txt的一键安装程序中更改xlwings版本时，请确保将本地xlwings安装升级到相同版本并运行xlwings release再次运行！

嵌入式代码说明

当您运行xlwings release命令时，您的代码将被自动嵌入（除非您关闭此行为）。但是，您也可以直接嵌入代码：在命令行中，运行以下命令：

xlwings code embed

这将从当前目录导入所有Python文件，并将它们粘贴到当前活动工作簿的Excel工作表中。现在，您可以像平常一样使用RunPython as usual: RunPython "import mymodule;mymodule.myfunction()".

请注意，您可以拥有多个Excel工作表并将它们像普通Python文件一样导入。考虑这个例子：

../_images/embedded_code1.png
../_images/embedded_code2.png

您可以从VBA这样调用main函数：

Sub RandomNumbers()
    RunPython "import random_numbers;random_numbers.main()"
End Sub

注意

  • 使用嵌入式代码时，UDF模块不必显式添加到UDF Modules中。但是，与外部文件的工作方式不同，目前在更改函数时需要重新导入它们。

  • 虽然您可以隐藏包含代码的工作表，但它们将以明文形式写入临时目录。