calmjs 3.4.4

实现

为了实现这一点，Calmjs框架提供了一组扩展，用于辅助跟踪和管理给定Python包的基于JavaScript或Node.js的包（如通过npm）的依赖项。它还提供了一些基类，可用于构建自定义工具链，以实现将所需JavaScript代码和相关资产编译到应用服务器可能使用的部署工件的不同策略，或者生成测试工具，以确保在开发和生产环境下的正确性。这些额外功能将由其他Python包在calmjs命名空间下提供，以实现这种模块化架构。

Calmjs这个名字最初来源于工具链第一迭代中的步骤，这些步骤涉及使用宿主Python包的命名空间将编译、汇编和链接步骤编译成一个JavaScript模块。标志中的“m”是兔子的耳朵。选择这种动物作为项目的吉祥物是因为它们的饮食习惯，这与JavaScript代码通常通过其他工具和框架转换为最少可用级别类似。

替代安装方法（针对开发者，高级用户）

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

$ # standard installation mode
$ pip install git+https://github.com/calmjs/calmjs.git#egg=calmjs
$ # for an editable installation mode; note the upgrade flag
$ pip install -U -e git+https://github.com/calmjs/calmjs.git#egg=calmjs

请注意，可编辑安装的-U标志是为了确保setuptools升级到最新版本，以避免处理开发包命名空间时出现的问题，这些问题在下一段中进行了说明。

或者，可以直接克隆git仓库，并在源目录的根目录下执行python setup.py develop。但是，如果使用版本早于v31的任何版本的setuptools进行此开发安装方法，那么在calmjs命名空间下导入模块时将出现不一致的错误。在本文档的故障排除部分记录了命名空间导入失败的症状。

测试安装

为确保calmjs安装正常工作，可以通过以下方式执行内置测试套件：

$ python -m unittest calmjs.tests.make_suite

如果出现失败，请在问题跟踪器上提交问题，并提供完整的跟踪信息以及安装方法。请记住，还应该包括平台特定信息，例如Python版本、操作系统环境和版本以及与问题相关的其他信息。

为特定的Python包声明一个package.json

如果希望声明对由npm托管的包的依赖关系，则可以在其setup.py中这样做：

from setuptools import setup

package_json = {
    "dependencies": {
        "jquery": "~3.0.0",
        "underscore": "~1.8.0",
    }
}

setup(
    name='example.package',
    # ...
    setup_requires=[
        'calmjs',
        # plus other setup_requires ...
    ],
    package_json=package_json,
    # ...
)

请注意，必须指定calmjs以启用package_json设置关键字，以便在执行python setup.py egg_info（直接或间接）时为给定的包生成package.json元数据文件，即使calmjs尚未安装到当前的Python环境中，它也将从PyPI获取并包含在setuptools设置过程的一部分，而不成为给定包的直接依赖项。如果提供的数据是有效的JSON字符串或字典（不包含不兼容的数据类型），则将生成package.json。例如：

$ python setup.py egg_info
running egg_info
writing package_json to example.package.egg-info/package.json
...
$ cat example.package.egg-info/package.json
{
    "dependencies": {
        "jquery": "~3.0.0",
        "underscore": "~1.8.0"
    }
}

使用 setup_requires 的关键原因是不强迫特定软件包的依赖项将 calmjs 作为它们依赖的一部分，因为通常这仅是开发者的需求，而不是最终用户的需求。这也意味着，对于想要使用 calmjs 和实用工具的开发者，他们必须单独安装（即 pip install calmjs），或者通过使用 extras_require 标志将 calmjs 声明为开发依赖，例如

setup(
    name='example.package',
    # ...
    setup_requires=[
        'calmjs',
        # ...
    ],
    extras_require={
        'dev': [
            'calmjs',
            # ... plus other development dependencies
        ],
    },
    # ...
)

然后完全安装该软件包作为具有 dev 额外功能的可编辑软件包

$ pip install -e .[dev]
Obtaining file://example/package
...
Installing collected packages: ..., calmjs, ...
  Running setup.py develop for example.package
Successfully installed ...

请注意，现在 calmjs 软件包仍然安装在 Python 环境中，它们提供的实用工具现在可以使用，以下章节将涵盖这些内容。

在 Python 软件包依赖项中跨使用 package.json

当将 package.json 文件写入软件包元数据目录后，实用工具如 calmjs 将会利用它。实现这一点的其中一种方法是通过该软件包的 setup.py。通过从该文件调用 setup.py npm --init，将创建一个新的 package.json，并结合给定软件包的 Python 软件包依赖项中声明的所有 dependencies 和 devDependencies，然后将它们写入当前目录。这与运行 npm init 相似，区别在于依赖项也是通过给定 Python 软件包的 Python 软件包依赖树进行解析的。

请注意，这需要给定软件包的 package.json 创建和处理能力（请参考前面的章节了解如何实现这一点），并且所有依赖项都必须正确安装并且可以从当前 Python 环境中导入。

或者，可以使用 calmjs npm 实用工具。在命令行中调用 calmjs npm --init example.package 将实现相同的效果，无论在文件系统的哪个位置，前提是 calmjs 和 example.package 都已安装并通过当前 Python 环境的导入系统可用。有关此实用工具的更多详细信息，请参阅通过 calmjs npm 与 npm 集成部分。

处理具有 Python 软件包依赖项的 npm 依赖项

扁平化优于嵌套。因此，任何上游 Python 软件包声明的所有 dependencies（和 devDependencies）都将自动继承所有其下游软件包，但它们可以选择通过上述机制用任何它们想要的来覆盖它。他们可以设置 JavaScript 或 Node.js 软件包的所需版本，甚至可以将该依赖项完全删除，只需将版本设置为 None。

每当 calmjs 需要实际的 package.json 时，calmjs npm 实用工具将所有 Python 软件包需要的 Node.js 依赖项扁平化到一个文件中，然后将其传递给相应的 JavaScript 软件包管理器进行处理。此过程也是当 calmjs 工具链或实用工具使用这些声明信息生成所需的工件以完成当前任务时进行的。

当然，如果希望包和依赖的嵌套风格与npm相同，没有人会强制使用这种方式，他们可以自由使用任何工具来解释或使用可用的数据文件和依赖项，也可以将包拆分为Python和JavaScript部分，并分别部署和托管在PyPI（用于pip）和npm上，然后想出如何以连贯的方式将它们组合在一起。不要询问（或与）作者关于后一种方式对所有人（开发者、系统集成人员和最终用户）来说更好或更简单。

在node_modules内部声明明确的依赖路径

鉴于对从npm获取的特定版本的包的依赖关系被明确指定，构建工具将再次从对这些包所需文件的确切声明中受益。具体来说，编译后的包可以在JSON字符串的extras_calmjs部分声明，类似于package_json，如下所示

extras_calmjs = {
    'node_modules': {
        'jquery': 'jquery/dist/jquery.js',
        'underscore': 'underscore/underscore.js',
    },
}

setup(
    name='example.package',
    ...
    extras_calmjs=extras_calmjs,
    ...
)

由于node_modules被声明为extras_key，环境内包之间的冲突声明将以与package_json中声明的依赖项冲突相同的方式进行解析和合并。

请注意，必须声明完整的路径名称（注意示例中包括.js文件名后缀）；也可以声明目录。然而，由于这些声明是在Python内部进行的，因此需要显式完整路径，因此下游集成包必须正确处理和/或将这些转换为标准Node.js工具可能期望的约定（即省略.js文件名后缀）。

从Python包导出JavaScript代码

在先前的示例中进一步，如果example.package内部文件和目录布局如下

.
├── example
│   ├── __init__.py
│   └── package
│       ├── __init__.py
│       ├── content.py
│       ├── form.py
│       ├── ui.js
│       ├── ui.py
│       └── widget.js
└── setup.py

为了通过calmjs将./example/package内的JavaScript源文件声明为JavaScript模块，可以在setup.py文件中声明如下入口点

setup(
    ...
    entry_points="""
    ...
    [calmjs.module]
    example.package = example.package
    """,
    ...
)

请注意，入口点的名称无关紧要；该入口点名称被忽略，因为默认模块注册表的目的是提供一个模块名称，该名称直接映射到与源Python模块相同的导入命名空间，但使用ES5命名空间分隔符/，而不是Python中的.字符。如果需要显式映射，可以定义一个新的模块注册表类，该类使用提供的名称作为JavaScript代码中的CommonJS导入名称。

默认方法将公开以下名称的两个源文件

- 'example/package/ui'
- 'example/package/widget'

对于某些项目，可能不希望允许此自动化方法从给定的Python模块中提取所有可用的JavaScript源文件。

为了解决这个问题，可以通过Calmjs框架声明新的模块注册表。只要正确设置了ModuleRegistry子类以从给定的包生成所需的模块，只需像这样声明为calmjs.registry入口点

setup(
    ...
    entry_points="""
    ...
    [calmjs.registry]
    example.module = example.package.registry:ExampleModuleRegistry
    """,
    ...
)

请注意，尽管对入口点名称的允许范围相当不受限制，但这些注册表名称应采用标准点分隔命名空间格式，以确保最大程度的工具兼容性，因为这些可以通过使用此系统的工具在命令行中指定。

一旦声明了注册表，只需将calmjs.module替换为该名称，并添加一个具有calmjs_module_registry属性的example.module注册表，该属性声明此注册表是该包的默认注册表。

setup(
    ...
    calmjs_module_registry=['example.package'],
    entry_points="""
    ...
    [example.module]
    example.package = example.package
    """,
    ...
)

在Calmjs框架中，可以明确指定工具来捕获框架注册的所有或任何模块注册表中的模块。还定义了另一个注册表。如果入口点是这样声明的

setup(
    ...
    entry_points="""
    ...
    [calmjs.py.module]
    example.package = example.package
    """,
    ...
)

命名空间和模块的分隔符将使用.字符而不是/字符。然而，由于.字符是JavaScript模块的有效名称，这种用法可能与其他JavaScript工具产生问题。虽然基于AMD的模块系统通常可以无问题地处理导入中的.字符，允许在JavaScript环境中使用点命名进行类似Python的导入，但这可能会导致与其他JavaScript库不兼容，因此不建议使用这种命名方案。

默认情况下，还声明了另一个具有.tests后缀的注册表，作为之前引入的注册表的补充，这些注册表可以供软件包使用来声明与已声明的模块一起提供的JavaScript测试代码。例如

setup(
    ...
    entry_points="""
    ...
    [calmjs.module]
    example.package = example.package

    [calmjs.module.tests]
    example.package.tests = example.package.tests
    """,
    ...
)

与第一个例子类似，这声明了example.package作为一个导出JavaScript代码的Python命名空间模块，后续的声明部分是包含与第一个模块一起提供的测试的模块。

向加载器提供伴随的资源文件

某些Node.js构建工具和框架支持通过相同的导入/导入系统为JavaScript模块之外的资源文件提供“加载器”的概念。为了为包创建者提供最基本的支持，以减轻将其他资源文件公开给Node.js工具导入系统所需的努力，可以声明并使用一个子加载器注册表，与父模块注册表一起使用。在先前的例子中，如果定义以下入口点

[calmjs.module]
example.package = example.package

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

calmjs.module.loader注册表将引用其父注册表calmjs.module以获取已公开的特定模块，因此它将根据声明的文件扩展名收集所有相关的文件名到一个特定的加载器中。与基本模块注册表不同，模块加载器注册表将忽略Python模块名称部分，而名称（在左侧）是所需的加载器，额外的（在[ ]内用逗号分隔的标记）是要从包中获取的文件扩展名。因此，使用之前为example.package定义的条目，以下require语句应该可以解析，如果目标资源文件对包存在的话

// resolved through "json = ...[json]"
var manifest_obj = require('json!example/package/manifest.json');
// resolved through "text = ...[txt,json]"
var manifest_txt = require('text!example/package/manifest.json');
var index_txt = require('text!example/package/index.txt');

由于注册表生成的值遵循标准工具链规范编译入口语法，这应该满足最基本的使用案例，可以直接作为包的calmjs_module_registry包含。然而，在提供的JavaScript代码与实际集成的工具链包一起使用时，可能存在需要特殊处理（例如，包含/排除针对最终产品生成的部分，或如何将源代码别名或提供给系统，或是否注册本身需要手动集成）的交互；请参阅特定集成包的文档，以了解此特定注册表类型。

最后一点：由于Python入口点系统的限制，假设文件扩展名都是小写。

通过calmjs npm与npm集成

如前所述，可以在setuptools之外使用package.json生成功能。用户可以通过内置的calmjs npm工具轻松完成同样的操作。

$ calmjs npm --help
usage: calmjs npm [-h] [-d] [-q] [-v] [-V] [--view] [--init] [--install]
                  [-i] [-m] [-w] [-E] [-P] [-D]
                  <package> [<package> ...]

npm support for the calmjs framework

positional arguments:
  <package>          python packages to be used for the generation of
                     'package.json'

optional arguments:
  -D, --development  explicitly specify development mode for npm install
  -E, --explicit     explicit mode disables resolution for dependencies;
                     only the specified Python package(s) will be used.
  -h, --help         show this help message and exit
  -i, --interactive  enable interactive prompt; if an action requires an
                     explicit response but none were specified through
                     flags (i.e. overwrite), prompt for response;
                     disabled by default
  -m, --merge        merge generated 'package.json' with the one in
                     current directory; if interactive mode is not
                     enabled, implies overwrite, else the difference will
                     be displayed
  -P, --production   explicitly specify production mode for npm install
  -w, --overwrite    automatically overwrite any file changes to current
                     directory without prompting

当然，上面展示的与 setuptools 框架一起的相同 --init 功能是可用的，但是可以提供包名称，从文件系统的任何位置生成目标 package.json 文件，前提是 Python 环境已经安装了所有必需的包。例如，如果需要安装 example.package 的 Node.js 包，可以调用此命令以查看将要生成的 package.json 文件。

$ calmjs -v npm --view example.package
2016-09-01 16:37:18,398 INFO calmjs.cli generating a flattened
'package.json' for 'example.package'
{
    "dependencies": {
        "jquery": "~3.0.0",
        "underscore": "~1.8.0",
    },
    "devDependencies": {},
    "name": "example.package"
}

如果当前目录中已存在 package.json 文件，使用 -i 标志与 --init 或 --install 将显示生成的版本和现有版本之间可能存在的差异，并提示执行操作。

工具链

如何扩展工具链类以支持用例的文档目前尚不完整。这通常与 calmjs.runtime.DriverRuntime 结合使用，以挂钩到 calmjs 运行时。

遗憾的是，目前还没有完成如何创建完整实现的详细指南（然而，类内的文档是有的）。有关如何实现此功能的示例，请参阅 calmjs.rjs 或 calmjs.webpack 提供的实现。

工具链建议

对于需要向工具链执行提供额外指令的包开发者（例如，为了在 RequireJS 和 webpack 之间实现特定用例的兼容性），工具链系统也将使用建议系统，以便为依赖项创建和注册额外的指令以供使用和重用。与工具链类似，这个功能目前的文档也只限于测试用例。

通过 setuptools 预定义工件生成

可以为特定包定义要生成的工件以及生成它们的规则。只需定义一个函数，它返回一个与所需工具集成的 calmjs.toolchain.Toolchain 子类实例，以及一个包含所需规则的 calmjs.toolchain.Spec 对象。这些特定函数通常由提供它们的包提供，请参阅上一节中列出的工具链包及其链接，以了解如何使用这些函数的更多详细信息。

因为这些也是通过注册系统实现的，所以入口点通常如下所示

setup(
    ...
    build_calmjs_artifacts=True,
    entry_points="""
    ...
    [calmjs.artifacts]
    complete.bundle.js = example.toolchain:builder
    """,
    ...
)

在示例中，模块 example.toolchain 中的 builder 函数用于生成 complete.bundle.js 文件。生成的工件文件将位于包元数据目录（以 .dist-info 或 .egg-info 结尾）中的 calmjs_artifacts 目录内。还将生成一个伴随的 calmjs_artifacts.json 文件，列出在构建该工件时涉及的各个 Python 包的版本以及用于任务的二进制版本。

当将 build_calmjs_artifacts 设置为 True 时，将通过 setup.py build 步骤自动生成这些工件的自定义钩子将被启用。这对于与发行版（如 Python 轮子）自动捆绑工件文件非常有用（例如，运行 setup.py bdist_wheel 也将构建声明的工件。否则，可以使用 setup.py build_calmjs_artifacts 或通过 calmjs artifact build 工具手动调用此步骤。

CRITICAL calmjs.runtime 因严重错误而终止

如果 calmjs 遇到任何意外情况，它可能会像这样中止

$ calmjs npm --install calmjs.dev
CRITICAL calmjs.runtime terminating due to a critical error

如果之前没有列出有用的 ERROR 信息，请尝试使用调试标志（无论是 -d 还是 --debug）再次运行。

$ calmjs -d npm --install calmjs.dev
CRITICAL calmjs.runtime terminating due to exception
Traceback (most recent call last):
...

指定调试标志两次将启用 post_mortem 模式，其中将在失败点启动调试器。实现向 calmjs 命令提供子命令的运行时类的包的作者可能会在他们的开发周期中发现这很有用。请注意，默认调试器只有在顶层运行时类启用使用（这是实现 calmjs 命令的运行时类所做的）并且失败发生在调用运行时类期间时才会被触发。在 calmjs 运行的设置阶段发生的任何其他错误或异常将仅以较低优先级记录（例如，要使设置阶段生成的警告可见，必须提供附加的详细标志）。

ERROR bad ‘calmjs.runtime’ entry point

ImportError

这通常是由于不当地删除了已注册入口点的本地安装的包、指向错误导入位置的 calmjs 的附加包注册的入口点，或使用了与文档中安装部分所述的当前环境冲突的安装方法所导致的。重新使用环境的正确安装方法安装损坏的包，或完全卸载或删除触发不希望的错误消息的包或源文件。

bad entry point

这是由于定义了格式不正确的入口点。触发此错误的包的名称将在日志中注明；可以将错误报告给其开发者。

尝试从 calmjs 命名空间导入时出现随机 ImportError

由于 calmjs 同时被声明为命名空间和包，因此在工作 Python 环境中必须进行某些低级设置，以确保可以正确定位所有模块。然而，早于 v31.0.0 的 setuptools 版本在将包使用 开发安装方法（例如，使用 python setup.py develop）安装到 Python 环境中，并且与在同一命名空间内通过 pip 安装的另一个包一起安装时，不会创建所需的包命名空间声明。失败可能表现为 calmjs 命名空间下任何模块的不一致导入失败。例如

>>> from calmjs import tests
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ImportError: cannot import name tests
>>> from calmjs import parse  # calmjs.parse was installed via pip
>>> from calmjs import tests
>>> # no failure, but it was failing just earlier?

它也可能以不同的方式表现出来，例如 AttributeError，这可能是通过执行 calmjs 的 unittest 触发的

$ coverage run --include=src/* -m unittest calmjs.tests.make_suite
Traceback (most recent call last):
  ...
    parent, obj = obj, getattr(obj, part)
AttributeError: 'module' object has no attribute 'tests'
$ python -m calmjs.tests.make_suite
/usr/bin/python: No module named 'calmjs.tests'

为了解决这个问题，请确保将setuptools升级到v31或更高版本，可以通过以下方式通过pip安装/升级：

$ pip install --upgrade setuptools

然后重新安装所有在calmjs命名空间下的所需包，以解决这个导入问题。

环境变量被忽略/未传递给底层工具

一般来说，Calmjs框架默认过滤掉所有环境变量，除了最基本的变量外，并且只将有限的环境变量传递给底层工具。这些变量是PATH和NODE_PATH变量，以及平台特定的变量，以启用脚本和二进制文件的执行。

运行时报告在声明的参数上显示‘未识别的参数：’

对于 calmjs>=3.1.0，此问题应该已完全解决。

在ArgumentParser的默认行为中，对于由其子解析器引起的任何未识别的参数，都会无用地责备根解析器。在calmjs-3.1.0之前的原始解决方案中，由于子解析器解析器实现不完整，失败如下所述。这两种误导行为都会阻碍最终用户快速定位错误的参数标志。

例如，如果像这样执行calmjs命令，则错误消息可能如下所示

$ calmjs subcmd1 subcmd2 --flag item
usage: calmjs subcmd1 ... [--flag FLAG]
calmjs subcmd1: error: unrecognized arguments: --flag

这意味着--flag在第二个子命令（即calmjs subcmd1 subcmd2命令）中未被识别，因为该标志放在了subcmd2之后，但subcmd1的子解析器将其标记为错误。不幸的是，argparse模块中存在一些问题，使得完全解决这个问题变得困难，因此请确保在正确的子命令级别提供标志（在此例中，calmjs subcmd1 --flag item subcmd2），否则通过在每个有效子命令后附加-h来在正确的级别上查阅帮助。

模块注册未定位到命名空间包中的文件

Python中的命名空间包存在许多边缘情况，尤其是如果它们通过不同的方法提供到系统上（即zip egg、wheel和开发包的混合）。尽管提供了处理给定包的命名空间模块的解决方案，但存在一些限制。其中一个原因是处理zip egg的复杂性；如果这是一个问题，请确保受影响的包将zip_safe声明为false，或者另外生成一个Python wheel然后安装该wheel，如果目标Python环境将此作为标准安装格式。

UserWarning：未知发行选项：'package_json'

这也适用于其他相关选项，因为它是由在calmjs对setuptools不可用的情况下执行setup.py引起的，因此这些关键词的处理方法仍然是未定义的。可以通过在setup_requires部分提供calmjs来纠正此问题。有关此问题的更多信息，请参阅本文件的使用package_json部分。