跳转到主要内容

该包用于扩展Calmjs框架以支持使用webpack来从Python包提供的JavaScript源代码生成可部署的工件,这些源代码与从npm或其他类似包仓库获取的标准JavaScript或Node.js包相结合。

项目描述

calmjs.webpack

通过webpackCalmjs框架集成到Python环境中,以方便使用Python包中包含的JavaScript源代码,以及从npm或其他类似包仓库获取的Node.js包,以声明和生成预构建JavaScript工件,并允许Python包的依赖项重用和扩展。

https://travis-ci.org/calmjs/calmjs.webpack.svg?branch=1.2.0 https://ci.appveyor.com/api/projects/status/327fghy5uhnhplf5/branch/1.2.0?svg=true https://coveralls.io/repos/github/calmjs/calmjs.webpack/badge.svg?branch=1.2.0

简介

可以使用任何语言创建Web应用程序作为其后端,然而它们提供的交互式前端用户界面最终依赖于某种形式的JavaScript。这尤其适用于从基于Node.js的包管理系统(如npm)获取相关功能的场景。然而,提供自己包管理系统的后端语言通常缺乏与npm的全面集成,或者集成与特定框架紧密耦合,无法以更通用方式重用。

解决此问题的常见方法是强制将包分成两个,或者至少使用完全独立的部署系统,以便JavaScript工具管理面向前端的部分。此外,这些独立的系统不一定相互通信。这导致了软件栈构建困难、部署不稳定且不可重现等问题,整个流程通常紧密耦合到底层源代码库,限制了所有组件的重用性。最终,这使得后端语言的用户无法在包边界内传达前端部署信息,供其依赖项(例如,其他下游包以推广重用性的方式扩展包)重用。

这种自包含的行为也困扰着webpack,其中每个Node.js包提供生成的工件,但不一定是生成它们的方法,这些方法以可重用的形式存在。当然,对于大多数典型用例,只需指定入口点即可解决问题。然而,对于提供动态插件系统的系统,这很快就变成了问题,因为webpack要求在构建时知道所有导入。这使得在不使用充当模块名称可用性和位置的监督者系统的独立系统的情况下,实施任意扩展变得非常困难。

由于Calmjs框架的目的是允许Python包将它们的JavaScript代码作为如果它们是客户端代码中管理的npm模块系统的一部分来暴露,因此这个包,calmjs.webpack,利用这一能力,不仅提供Python包的标准调用方法,而且还允许下游包生成综合webpack工件或仅包含用于与其他现有工件一起使用的特定扩展的独立webpack工件。

功能

calmjs.webpack如何工作

Calmjs框架提供框架,允许Python包声明它们需要的依赖项,针对JavaScript代码所提供的基于npm的包,并使Python包以声明方式暴露它们可能包含的任何JavaScript源文件。

calmjs.webpack中包含的实用程序提供了消耗这些声明的方法,将JavaScript文件视为源和编译目标,并通过webpack包生成最终的可部署工件。

虽然通过 Python 包提供的输入源文件可以写成 webpack 所理解的任何格式,但目前只有标准的 ES5 格式能够被正确处理。这主要是因为 calmjs.parse,这是 calmjs.webpack 用于解析 JavaScript 的解析库,目前仅支持 ES5,并且被用于提取所有导入语句以创建为 webpack 生成动态 Calmjs 导入系统的所有导入语句,同时也用于将 CommonJS 和 AMD(异步模块定义)的 require 语句转换为使用此动态导入系统。

生成的源代码将被放置在构建目录中,包括从 Node.js 包管理器或仓库中获取的所有声明的捆绑源,以及(可选的)生成的导入模块。然后,将生成一个 webpack 配置文件,包含所有选定的相关源,以便生成最终工件文件。这些文件然后可以部署到适当的环境,或者整个上述过程可以通过此包提供的 API 作为现有 Python 后端功能的一部分。

最终,calmjs.webpack 的目标是简化客户端 JavaScript 与服务器端 Python 之间的集成和交互,通过简化在一个共享包和环境中构建、传输和部署这两套源的任务。

最后,为了质量控制,此包与 calmjs.dev 集成,它提供设置测试环境和运行 JavaScript 测试的工具,这些测试是相关 Python 包中 JavaScript 代码的一部分。但是,该包没有直接声明为依赖项,因为并非所有用例都需要该包。请参阅安装部分以获取详细信息。

支持的 webpack 版本

由于 webpack 是一个非常活跃的项目,自从 calmjs.webpack 的初始开发和发布以来,已经发布了多个主要版本。目前,calmjs.webpack 已知支持 webpack-2 的 2.6 或更高版本,webpack-3 和 webpack-4。虽然 webpack@2.7.0 已声明为此版本的 calmjs.webpack,但下游包可能声明更晚的版本,但建议执行完整的 calmjs.webpack 测试套件以验证在给定环境中集成测试通过。有关执行 calmjs.webpack 集成测试的详细说明,请参阅测试安装部分。

安装

建议本地环境至少已经安装了 Node.js 和 npm,以启用 webpack 的安装,如果尚未安装和可用。此外,Python 的版本必须是 2.7 或 3.3+。PyPy 和 PyPy3 都受支持,推荐的版本是 PyPy3-5.2 或更高版本,尽管 PyPy3-2.4 应该可以工作,但由于依赖项的新版本拒绝旧版本的 Python,可能会有困难。

要将 calmjs.webpack 安装到特定的 Python 环境中,可以使用以下命令直接从 PyPI 安装:

$ pip install calmjs.webpack

由于此 Python 包与 Node.js 工具接口,此语言的运行时也应该在系统上可用。请安装 Node.js 网站上列出的受支持的 LTS 版本之一。目前,此包的最低支持 Node.js 版本是 6。

使用 calmjs 安装/使用 webpack

为了在当前工作目录中为支持 webpack 的 Python 包建立开发/构建环境,可以通过 calmjs.webpack 执行以下命令:

$ calmjs npm --install calmjs.webpack

运行 npm install webpack(同时安装 calmjs.webpack 声明并由 npm 需要的其他相关包)将实现相同的效果。请注意,Calmjs 框架使得 npm 依赖关系可以向下传播到依赖包;这意味着如果一个 Python 包将 calmjs.webpack 声明为依赖(无论是通过 install_requires 还是 setup.py 中的 extras_require),可以使用以下命令安装其完整的 npm 依赖关系(假设包名为 example.package):

$ calmjs npm --install example.package

如果将 calmjs.webpack 的依赖声明为名为 webpackextras_require 依赖项,则命令将变为以下内容:

$ calmjs npm --install example.package[webpack]

如果依赖项声明正确,使用上述命令将安装 example.package 所需的 JavaScript/Node.js 代码的所有必需依赖项,并通过 npm 安装到当前目录。请注意,其依赖者也将获得声明的依赖项。

有关此功能的更多详细信息,请参阅 calmjs 的文档。否则,请继续阅读 使用 部分。

其他安装方法(高级用户)

关于 calmjs.webpack 的开发仍在进行中,要获取最新功能和错误修复,可以通过 git 安装开发版本,如下所示:

$ pip install calmjs
$ pip install git+https://github.com/calmjs/calmjs.webpack.git#egg=calmjs.webpack

或者,可以直接克隆 git 仓库,并在源目录的根目录下执行 python setup.py develop

请注意,在执行 calmjs.webpack 源树中的 setup.py 之前,calmjs 必须可用,因为它需要在 calmjs 中使用 package_json 写入功能。如果调用 setup.py 时出现关于 Unknown distribution option: 的任何消息,请执行 python setup.py egg_info

由于 calmjs 被声明为命名空间和包,因此需要在工作 Python 环境中执行某些低级别设置,以确保可以正确地找到所有模块。然而,版本早于 v31.0.0setuptools 在使用与同一命名空间中的 pip install 混合时,使用此开发安装方法安装包时不会创建所需的包命名空间声明。因此,可能会发生任何 calmjs 命名空间下模块的不一致导入失败。例如

>>> import calmjs.webpack
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ImportError: No module named 'calmjs.webpack'
>>> import calmjs.base
>>> import calmjs.webpack
>>>

如果此行为(以及解决方案)不受欢迎,请确保所有 calmjs 相关包的安装方法相同(即,对于所有包,使用 python setup.py develop,或使用通过 pip 获得的 wheel),或者将 setuptools 升级到 31 或更高版本并重新安装所有受影响的包。

测试安装

最后,要验证 calmjs.webpack 的成功安装,可以通过以下命令执行包含的测试:

$ python -m unittest calmjs.webpack.tests.make_suite

然而,如果遵循了将外部 Node.js 依赖项安装到当前目录的步骤,则可以将当前目录指定为 CALMJS_TEST_ENV 环境变量。在 POSIX 兼容的 shell 中,可以从该目录执行以下操作:

$ CALMJS_TEST_ENV=. python -m unittest calmjs.webpack.tests.make_suite

由于这种调用的方式直接使用当前Node.js环境发现的任何内容,因此可以用来测试与当前环境(例如,如果特定包在其工件构建过程中声明了特定较新版本的webpack)兼容性的其他webpack版本。

请注意,如果calmjs.dev包不可用,则与karma集成的多项测试将被跳过。为了避免这种情况,可以手动安装calmjs.dev,或者使用以下方式安装带有其额外依赖声明calmjs.webpack

$ pip install calmjs.webpack[dev]

用法

要从当前环境中已安装的、通过Calmjs模块注册系统公开JavaScript代码的包生成webpack工件,只需执行以下命令

$ calmjs webpack example.package

本文档的以下部分将概述如何通过Calmjs模块注册系统为给定的Python包启用JavaScript模块导出功能,然而关于这个主题的更详细描述可以在calmjs包的README文件中找到,在从Python包导出JavaScript代码部分。

声明Python包的JavaScript导出

Python包内嵌的JavaScript代码可以通过calmjs.module注册表暴露给Calmjs框架。例如,给定由名为example的包定义的以下注册表入口点

[calmjs.module]
example = example

这是适用于与导入位置提供的名称相同的包的最基本声明。

以下是一个具有嵌套子模块(称为example.libexample.app)的包的示例

[calmjs.module]
example.lib = example.lib
example.app = example.app

虽然声明的导入位置看起来就像Python模块(按照Python入口点的规则),但calmjs.module注册表将使用CommonJS/ES6风格的导入路径(即'example/lib''example/app')来展示它们。因此,希望导入这些特定JavaScript模块的用户将需要使用这些字符串作为前缀来require所需的模块。

请还请注意,默认源提取器将提取这些目录中所有的JavaScript文件。最后,由于导入的方式,建议不要使用相对导入。

如果手头的包没有直接声明对calmjs的依赖,可能需要在包的setup函数中明确声明calmjs_module_registry=['calmjs.module'],以确保使用此默认模块注册表获取JavaScript源。

将它们放在一起,setup.py文件应包含以下内容

setup(
    name='example',
    # ... plus other declarations
    # this is recommended
    license='gpl',
    install_requires=[
        'calmjs>=3.0.0,<4',
        'calmjs.webpack>=1.0.0,<2',
        # plus other installation requirements
    ],
    # If the usage of the GPL is impossible for the project, or
    # declaring a direct dependency on calmjs packages is impossible
    # for the project for whatever other reasons (even though the
    # project itself will NOT be required to include/import ANY code
    # from the calmjs namespace), setup_requires may be used instead
    # of install_requires, and the following should also be included
    # as well:
    package_json={
        "devDependencies": {
            "webpack": "~2.6.0",
        }
    },
    calmjs_module_registry=['calmjs.module'],
    # the entry points are required to allow calmjs to pick this up
    entry_points="""
    [calmjs.module]
    example = example
    example.lib = example.lib
    example.app = example.app
    """,
)

对于构建示例包的webpack工件,可以通过calmjs webpack构建工具进行,这将提取所有相关源,创建一个临时构建目录,生成构建清单,并在该文件上调用webpack。示例运行

$ calmjs webpack example
Hash: 1dbcdb61e3afb4d2a383
Version: webpack 2.7.0
Time: 82ms
     Asset     Size  Chunks             Chunk Names
example.js  4.49 kB       0  [emitted]  main
   [1] /tmp/tmp7qvdjb5z/build/example/lib/core.js 51 bytes {0} [built]
       cjs require example/lib/core [2] /tmp/tmp7qvdjb5z/build/__calmjs_loader__.js 6:24-51
       cjs require example/lib/core [4] /tmp/tmp7qvdjb5z/build/example/app/index.js 1:10-37
   [2] /tmp/tmp7qvdjb5z/build/__calmjs_loader__.js 559 bytes {0} [built]
       cjs require __calmjs_loader__ [3] /tmp/tmp7qvdjb5z/build/__calmjs_bootstrap__.js 3:20-48
   [3] /tmp/tmp7qvdjb5z/build/__calmjs_bootstrap__.js 341 bytes {0} [built]
   [4] /tmp/tmp7qvdjb5z/build/example/app/index.js 74 bytes {0} [built]
       cjs require example/app/index [2] /tmp/tmp7qvdjb5z/build/__calmjs_loader__.js 7:25-53
    + 1 hidden modules

由于calmjs.webpack使用的构建过程是在单独的构建目录中执行的,因此所有通过Node.js模块系统进行的导入都必须声明为extras_calmjs,因为将不会提供node_modules。例如,如果example/app/index.js需要使用jqueryunderscore模块,如下所示

var $ = require('jquery'),
    _ = require('underscore');

需要声明目标位置,该位置来自 npm,以及用于依赖项的 package_json 文件,需要在 setup.py 中声明这些信息。

setup(
    # ...
    package_json={
        "dependencies": {
            "jquery": "~3.1.0",
            "underscore": "~1.8.0",
        },
        "devDependencies": {
            # development dependencies from npm
        },
    },
    extras_calmjs = {
        'node_modules': {
            'jquery': 'jquery/dist/jquery.js',
            'underscore': 'underscore/underscore.js',
        },
    },
)

完成这些操作后,重新运行 python setup.py egg_info 命令,将新声明的元数据写入包的 egg-info 目录,以便在环境中使用。现在可以调用 calmjs npm --install example 命令来将 npm 依赖项安装到当前目录;以便允许 calmjs.webpack 查找来自 npm 的所需文件,并将它们放入构建目录中,以便 webpack 可以找到它们。

生成的 calmjs 运行结果可能看起来像这样

$ calmjs webpack example
Hash: fa76455e8abdb96273aa
Version: webpack 2.7.0
Time: 332ms
     Asset    Size  Chunks                    Chunk Names
example.js  326 kB       0  [emitted]  [big]  main
   [1] /tmp/tmposbsof05/build/example/lib/core.js 51 bytes {0} [built]
       cjs require example/lib/core [4] /tmp/tmposbsof05/build/__calmjs_loader__.js 7:24-51
       cjs require example/lib/core [6] /tmp/tmposbsof05/build/example/app/index.js 1:10-37
   [2] /tmp/tmposbsof05/build/jquery.js 268 kB {0} [built]
       cjs require jquery [4] /tmp/tmposbsof05/build/__calmjs_loader__.js 8:14-31
       cjs require jquery [6] /tmp/tmposbsof05/build/example/app/index.js 2:8-25
   [3] /tmp/tmposbsof05/build/underscore.js 52.9 kB {0} [built]
       cjs require underscore [4] /tmp/tmposbsof05/build/__calmjs_loader__.js 9:18-39
       cjs require underscore [6] /tmp/tmposbsof05/build/example/app/index.js 2:31-52
   [4] /tmp/tmposbsof05/build/__calmjs_loader__.js 633 bytes {0} [built]
       cjs require __calmjs_loader__ [5] /tmp/tmposbsof05/build/__calmjs_bootstrap__.js 3:20-48
   [5] /tmp/tmposbsof05/build/__calmjs_bootstrap__.js 341 bytes {0} [built]
   [6] /tmp/tmposbsof05/build/example/app/index.js 128 bytes {0} [built]
       cjs require example/app/index [4] /tmp/tmposbsof05/build/__calmjs_loader__.js 6:25-53
    + 1 hidden modules

在 webpack 构件构建过程中触发测试执行

对于测试,需要向与给定包的模块注册表伴随的模块测试注册表中声明适当的条目,并使用由 calmjs.dev 包提供的 karma 运行时,测试可以作为 webpack 构件构建过程的一部分执行。命令很简单

$ calmjs karma webpack example

请注意,必须安装由 calmjs.devcalmjs.webpack 提供的 devDependencies。这可以通过声明适当的 install_requires 来轻松完成,或者手动安装 calmjs.dev,然后使用 calmjs npm -D --install calmjs.webpack[dev] 命令安装来自 npm 的依赖项。

动态模块导入

虽然 webpack 在某种程度上原生支持此功能,但这种支持仅通过直接文件系统级别的支持来实现。在 Calmjs 的案例中,导入是使用在生成的 webpack.conf.js 配置中显式定义的别名标识符完成的,默认情况下,webpack 无法解析这些别名。

与其尝试使 ContextReplacementPlugin 工作或编写另一个 webpack 插件,不如自动生成一个代理 __calmjs__ 导入模块,并将其包含在每个生成的构件中,这样动态导入就可以按预期工作。使用这种方法作为解决方案的原因只是希望避免对 webpack API 的可能更改,因为此类插件的实现将最终紧密耦合到 webpack 上。

使用代理导入模块,动态导入也可以在通过 calmjs webpack 生成的多个 webpack 构件之间工作,但这是一个高级主题,因此需要更多的文档,因为特定的声明/导入顺序以及各种其他注意事项都会使实际使用复杂化(例如,正确处理循环导入始终是一个复杂的问题)。

对于简单的情况,想象以下 JavaScript 代码

var loader = function(module_name) {
    // the dynamic import
    var module = require(module_name);
    console.log(module + ' was loaded dynamically.');
};

var demo = loader('example/lib/core');

如果 example/lib/core.js 源文件由 example 包导出,并且包含在 webpack 中,那么上面的动态导入默认情况下应该没有任何问题,无需进一步配置。

如果不需要此动态导入模块功能,并且没有任何 JavaScript 代码使用动态导入,则可以通过 --disable-calmjs-compat 标志禁用此功能。

处理 Webpack 加载器

Webpack 提供了加载器的支持,用于处理非 JavaScript 源文件的导入,从而使导入文本文件、JSON 文件等文件可以无缝地使用其导入系统。Python 包可以导出这些资源文件,并通过子加载器注册表 calmjs.module.loader 在 webpack 环境中使它们可用,该注册表将暴露在 calmjs.module 注册表中定义的命名空间的相关资源文件。

至于加载器自身与 Calmjs 工具链系统的集成,必须指定一个单独的加载器插件注册表。对于 webpack 工具链,默认将 calmjs.webpack.loaderplugins 注册表分配为,该注册表将解析一个通用处理器来处理目标资源文件。这个通用处理器支持加载器的链式操作。可以将特定处理程序直接分配给该注册表,例如,如果需要替代 Node.js 包来覆盖默认自动生成的处理器。

如果不希望有这种自动解析行为,可以在 calmjs.webpack.static.loaderplugins 定义一个静态注册表来实现此目的,但是,要在此时刻使用此注册表,需要直接使用工具链 API。

至于指定 Python 包中包含哪些资源文件应使 webpack 环境可用,应使用子模块加载器注册表 calmjs.module.loader

将这些内容组合起来,前面定义的 example 包现在扩展为公开各种类型的资源文件以供使用。

[calmjs.module]
example.lib = example.lib
example.app = example.app

[calmjs.module.loader]
json = json[json]
text = text[txt,json]

这将使 example/libexample/app 命名空间下的相关资源文件在相关加载器下可用,因此如果某些 JavaScript 代码包含以下任一 require 语句

var readme_lib = require('text!example/lib/readme.txt');
var data_txt = require('text!example/lib/data.json');
var data = require('json!example/lib/data.json');

请注意,这将使这些完整名称可用于动态模块导入,因为这些完整名称已经从生成的工件中公开出来。

默认的加载器插件处理器注册表将提供标准处理器,因为没有定义任何处理器,因此具有显式加载器前缀的 require 语句将被正确解析。然而,webpack 已经大量弃用了显式加载器前缀的使用,并更喜欢指定没有前缀的导入语法。这需要不同的处理方法,将在下一节中记录。

处理没有显式 loader! 前缀的 require()

如果忽略了 RequireJS/AMD 工具链的支持(请注意,这将影响任何直接使用此代码的依赖 Python 包,因为它目前不支持此导入方法),则可以使用裸导入语法,例如

var readme_app = require('example/app/readme.txt');
var style = require('example/app/style.css');

跨所有工具链(尤其是加载器)的兼容性难以实现,如果不是不可能实现的原因之一是由于有大量不同的方法被不同的 Node.js 工具链实现。例如,在 webpack 中导入样式表通常是通过将 style-loader 与特定样式表加载器(如 css-loadersass-loader)链式连接来完成的。虽然在 calmjs.module.loader 注册表上可以定义以下入口点

[calmjs.module.loader]
style!css = css[css]

根据上述定义,使用完整语法(即 require('style!css!example/app/style.css');)导入样式表资源将正常工作,但与 require-css 加载器不兼容,因为它不一定支持将 style! 加载器前缀串联起来,因为插件中 RequireJS 版本会在不使用该前缀的情况下立即应用样式(这也是为什么加载器前缀被认为是不可移植的)。

因此,为了更好地支持这种更为中立的用例,webpack 提供了一个 module.rules 部分,该部分定义了如何加载特定的模块,以便实现无前缀加载(即前面的 JavaScript 片段)。为了通过 Calmjs 特殊支持这一点,资源入口点应该定义在 calmjs.module.webpackloader 注册表下,而不是常见的 calmjs.module.loader 注册表下。例如

[calmjs.module]
example.lib = example.lib
example.app = example.app

[calmjs.module.webpackloader]
style-loader!css-loader = stylesheet[css]
text-loader = txt[txt]

请注意,虽然也可以像以下这样定义入口点

[calmjs.module.webpackloader]
style!css = stylesheet[css]

之前这依赖于已被 webpack 删除的旧行为,但它仍然由 calmjscalmjs.webpack 支持,这仅仅是因为对这种格式的通用支持,但鉴于这个注册表是专门为 webpack 定制的,如果解决了以下注意事项,就不应该有问题。

请注意,如果在多个 webpackloaders(注意文本加载器已移除 json 作为文件名扩展)上定义了给定的文件名扩展,则结果行为是未定义的,因为生成的配置无法保证加载器以预期的顺序串联在一起,因为两个加载器都将应用于在未定义的顺序下选择到的文件。

calmjs.module.webpackloader 导出的模块名称在通过默认加载器插件处理程序处理时不会被提供给动态导入模块的收集模块或导入名称,因为存在一些微妙的复杂性,这严重增加了以有意义的方式在 calmjs 系统中使用这些名称的难度。实际上,在构建工件之后将无法进行动态导入。

如果在此处定义的文件名扩展也定义在 calmjs.module.loader 注册表中,如果还生成了动态导入模块,也可能会引起问题。这个问题与上一段中概述的问题相关。

如果需要多个加载器(例如样式表的情况),请使用链式语法,如 style-loader!css-loader 定义,以确保它们被正确应用,就像它们被直接加在导入上为这个特定的 Python 包(即 style!css!)一样。

与标准 calmjs.module.loader 注册表类似,calmjs.module.webpackloader 注册表下声明的任何给定文件名扩展的定义仅限于包本身,因此使用来自上游或下游包的不同加载器集合的定义不会干扰它们的应用。

测试独立的、最终的 webpack 工件

使用标准 calmjs webpack 工具链运行时生成的 Webpack 生成物可以通过 calmjs.dev 包提供的 calmjs karma 运行时进行测试。假设有一个最终版本 example.webpack.js 实现了 example 包提供的功能,可以使用以下命令使用 example 包提供的测试来测试该生成物:

$ calmjs karma run \
    -t calmjs.webpack \
    --artifact=example.webpack.js \
    example

上述命令使用独立的 Karma 运行器,通过 calmjs.webpack 设置测试 example.webpack.js 生成物文件,使用 example 包提供的测试。测试执行类似于开发过程中的测试。

声明 Python 包的预构建 webpack 生成物

最后,为了完成 Python 包部署的故事,该过程应包括自动生成并包含在生成的 Python wheel 中的 JavaScript 生成物。这可以通过在 calmjs.artifacts 注册表中指定一个条目来实现,键是生成物的文件名,值是到构建器的导入位置。在 calmjs.webpack.artifact:complete_webpack 提供的默认构建器函数将启用为 Python 包生成完整的 webpack 生成物。构建器 calmjs.webpack.artifact:optimize_webpack 也会做同样的事情,但启用了优化选项(目前仅支持最小化输出)。

例如,包含两种形式的配置可能如下所示:

[calmjs.artifacts]
example.webpack.js = calmjs.webpack.artifact:complete_webpack
example.webpack.min.js = calmjs.webpack.artifact:optimize_webpack

一旦将这些入口点添加到 setup.py 中,并使用 setup.py egg_info 重新生成包元数据后,运行 calmjs artifact build example.package 将使用 webpack 工具链,并在包元数据目录中的 calmjs_artifacts 目录内构建 example.package 目录内的 example.webpack.js 生成物。或者,对于更集成于 setuptools 的解决方案,setup.py 中的 setup 函数也应启用 build_calmjs_artifacts 标志,这样 setup.py build 也会触发构建过程。这对于在 wheel 构建过程中自动生成和包含生成物很有用。考虑以下 setup.py

setup(
    name='example.package',
    # ... other required fields truncated
    build_calmjs_artifacts=True,
    entry_points="""
    # ... other entry points truncated
    [calmjs.module]
    example.package = example.package

    [calmjs.artifacts]
    example.webpack.js = calmjs.webpack.artifact:complete_webpack
    example.webpack.min.js = calmjs.webpack.artifact:optimize_webpack
    """,
)

使用 setup.py 构建 wheel 可能会导致如下结果。注意,webpack 的执行是过程的一部分,并且元数据(egg-info)目录随后被构建到 wheel 中。

$ python setup.py bdist_wheel
running bdist_wheel
running build
...
running build_calmjs_artifacts
automatically picked registries ['calmjs.module'] for sourcepaths
using loaderplugin registry 'calmjs.webpack.loaderplugins'
using calmjs bootstrap; webpack.output.library set to '__calmjs__'
...
Version: webpack 2.7.0
Time: 240ms
             Asset    Size  Chunks                    Chunk Names
example.webpack.js   10 kB       0  [emitted]  [big]  main
...
running install_egg_info
Copying src/example.package.egg-info to build/.../wheel/example.package...
running install_scripts
creating build/.../wheel/example.package-1.0.dist-info/WHEEL

为了测试包生成物,还应指定 calmjs.artifacts.tests 注册表下的以下入口点,这样运行 calmjs artifact karma example.package 将执行 example.package 声明的 JavaScript 测试,针对 calmjs.artifacts 中声明的生成物。

[calmjs.artifacts.tests]
example.webpack.js = calmjs.webpack.artifact:test_complete_webpack
example.webpack.min.js = calmjs.webpack.artifact:test_complete_webpack

注意,相同的 test_complete_webpack 测试构建器也将能够测试 optimize_webpack 生成物。

故障排除

以下是与该包及其与其他 Python/Node.js 包集成相关的一些已知问题。

CRITICAL calmjs.runtime WebpackRuntimeError:无法定位‘webpack’

这意味着当前的Node.js环境缺少从npm安装的webpack包;可以通过手动安装或通过此包上的calmjs来安装它。如果需要Python包来使用webpack生成包,其package_json应该声明这一点,或者声明对calmjs.webpack的依赖。

CRITICAL calmjs.runtime WebpackExitError: webpack已终止

这可能是由多种原因造成的;可能是由于提供的JavaScript代码中存在无效的语法,或者是配置中不包含足够的信息以供webpack正确执行,或者是因为特定的calmjs webpack标志以与webpack不兼容的方式启用。要提取有关错误的更多信息,可以再次执行相同的calmjs命令,并启用--verbose和/或--debug标志以输出额外的日志信息,这可能会揭示关于错误性质的更多信息,或者完整的堆栈跟踪可能会提供更多信息。必须包含详细信息以便在问题跟踪器上提交错误报告。

UserWarning: 未知分发选项

在开发方法设置和安装过程中,如果显示此警告消息,请确保通过在源目录中运行python setup.py egg_info来正确生成egg元数据,因为在设置脚本最初执行时,calmjs包不可用。

WARNING 无法找到npm包‘???-loader’的‘package.json’

当尝试在没有安装适当的加载模块的工作Node.js环境中使用webpack加载器时,会触发此警告消息。作为快速解决webpack构建问题的临时解决方案,可以尝试执行缺失的包安装命令,但正确的方法是让该包在package_json中将正确的加载器包声明为依赖项。

贡献

变更日志

1.2.0 (2018-08-22)

  • 对webpack 3和4的支持进行了各种更改。[ #6 ]

    • 对webpack配置脚本的生成进行了重大修改,因为它们是通过通过calmjs.parse构建抽象语法树的辅助函数构建的。这样做是为了能够在生成的脚本中将webpack版本特定的不兼容性添加/删除到可执行的Node.js代码中。

    • 默认为karma提供kill插件;如果webpack构建失败,karma进程将停止,因为singleRun: true标志不再适用于webpack。

  • 提供查询仅对其函数作用域变量名进行混淆的工件的能力。[ #8 ]

1.1.1 (2018-08-18)

  • 确保在to_identifier辅助函数中过滤出行续行符,因为自calmjs.parse-1.1.0以来,包含该标记的String节点对象的值。[ #7 ]

1.1.0 (2018-07-25)

  • 通过自定义webpack加载器模块注册表提供对无前缀加载器的支持;这也与calmjs.module注册表协同工作。[ #5 ]

    • 集成了由 calmjs-3.3.0 引入的包资源加载器注册表的支持。

    • 将支持的 calmjs.dev 版本升级到 2.2.0,以便可以自动获取正确的测试加载器注册表。这也使得将测试数据文件声明为 JavaScript 测试的资源变得尽可能直接。

  • 基本加载器插件处理程序还将生成一个以 ./ 为前缀的 modname,试图在特定的 webpack 加载器上下文中提供更自然的包含机制,因为其中许多将隐式通过相对路径解析为裸导入,目标是避免进一步使用专有的 webpack 语法(例如,在加载器上下文中使用 ~ 前缀进行某些 namespace/package 导入/包含)。 [ #4 ]

1.0.2 (2018-05-24)

  • 提供了一个生成器,它将生成启用支持的优化标志的工件。 [ #3 ]

1.0.1 (2018-05-03)

  • 更新了 export_target 和 working_dir 的生产和使用,使其与 calmjs-3.1.0 预期的保持一致。 [ #2 ]

1.0.0 (2018-01-12)

  • 实现了 Calmjs 集成工具的初始版本,该工具可以从包含在 Python 包中的 JavaScript 源生成 webpack 工件,同时也允许通过 Calmjs 框架导入其通过 npm 源的依赖项。

  • 启用了 calmjs webpack 工具入口点。

  • 通过纠正正确的钩子,还提供了与 calmjs.dev 的集成,这样这个包就可以作为一个建议包来使用,通过 calmjs karma webpack 来执行对通过此包生成的工件的测试。 [ #1 ]

  • 通过 calmjs.artifacts 注册表提供对预构建工件的包支持;构建和测试的默认完整生成器都可通过 calmjs.webpack.artifact 模块获得。

  • Webpack 被固定在 ~2.6.0,因为这是目前经过验证可用于构建和测试工件的稳定版本。

项目详细信息


下载文件

下载您平台上的文件。如果您不确定要选择哪一个,请了解更多关于 安装包 的信息。

源分布

calmjs.webpack-1.2.0.zip (148.3 kB 查看散列)

上传时间

构建分布

calmjs.webpack-1.2.0-py2.py3-none-any.whl (116.1 kB 查看散列)

上传时间 Python 2 Python 3

支持者

AWS AWS 云计算和安全赞助商 Datadog Datadog 监控 Fastly Fastly CDN Google Google 下载分析 Microsoft Microsoft PSF 赞助商 Pingdom Pingdom 监控 Sentry Sentry 错误日志 StatusPage StatusPage 状态页面