calmjs.sassy 1.0.2

替代安装方法（高级用户）

calmjs.sassy 的开发仍在进行中；可以通过以下方式通过 git 安装开发版本

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

或者，可以直接克隆 git 存储库，并在源目录的根目录中执行 pip install -e .

较新的 pip 和 setuptools 版本可能省略 calmjs 包的初始手动安装。

如果在 calmjs.sassy 源树中使用 setup.py，请记住，在执行之前，calmjs 必须可用，以便正确生成所有必需的包元数据。或者，如果调用 setup.py 时出现关于 Unknown distribution option: 的任何消息，请执行 python setup.py egg_info。

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

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

如果这种行为（和解决方案）不理想，请确保所有与 calmjs 相关的包的安装方式相同（即，对于所有包，要么使用 python setup.py develop，要么使用通过 pip 获取的 wheel），或者将 setuptools 升级到 31 或更高版本并重新安装所有受影响的包。

安装测试

最后，为了验证 calmjs.sassy 的成功安装，可以执行以下命令来运行包含的测试

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

声明用于给定 Python 包导出的 SCSS 文件

Python 包内部的 SCSS 文件可以被暴露到由本包提供的 calmjs.scss 注册表中。例如，给定以下由名为 example 的包定义的注册表的入口点

[calmjs.scss]
example = example

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

以下是具有嵌套子模块（称为 example.lib 和 example.app）的包的示例

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

虽然声明的导入位置看起来与 Python 模块（按照 Python 入口点的规则）完全相同，但 calmjs.scss 注册表将使用 CommonJS/ES6 风格的导入路径（即 'example/lib' 和 'example/app'）来展示它们，因此需要那些样式规则的用户需要确保他们 导入 这些字符串。

请注意，默认的源提取器将提取那些目录内所有的 *.scss 文件。

将第二个示例组合起来，setup.py 文件应包含以下内容

setup(
    name='example',
    setup_requires=[
        'calmjs.scss',
        # plus other setup level requirements
    ],
    # the entry points are required to allow calmjs to pick this up
    entry_points="""
    [calmjs.scss]
    example.lib = example.lib
    example.app = example.app
    """,
)

确保 SCSS 以支持的重用方式进行结构化

为了正确生成结果 .css 文件，以及管理 .scss 的使用和导出，当使用默认设置时，默认的 libsass-python 工具链会施加一些固定的限制。主要的限制是必须声明一个特定的入口点文件，用于获取生成样式表工件所需指定包的样式规则。此参数通常默认为 index.scss，但可以根据需要指定为不同的值，例如用于与不同的应用端点一起使用。

本质上，这允许包创建一个仅包含显式导入和定义在其中的样式规则的工件，并将它定义的规则分块导出到依赖项中，以便它们可以使用类似的包命名空间和模块名称导入。这使导出和这些样式规则的复用成为可能，而不需要依赖项多次显式声明它们所需的样式（即在样式表中只需要 @import 语句，无需针对包外的东西声明显式的入口）。

例如，在 example.package 内可能有以下布局

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

导出 example 包内 .scss 文件的入口点声明将是这样的

[calmjs.scss]
example.package = example.package

注意，该包的默认入口点 index.scss 可能包含以下内容

@import "example/package/colors";
@import "example/package/form";
@import "example/package/ui";

这些只是导入包本身提供的所有 .scss 模块。对于依赖于 example.package 并导出其自己的样式规则的 example.dependant 包，它需要在 setup.py 中的 install_requires 关键字中声明其依赖，并声明以下入口点以导出定义的样式

[calmjs.scss]
example.dependant = example.dependant

将所有这些放在一起

setup(
    name='example.dependant',
    install_requires=[
        'example.package',
        # ... plus other dependencies
    ],
    entry_points="""
    [calmjs.scss]
    example.dependant = example.dependant
    """,
    # ... plus other declarations
)

注意，特定于其依赖项 example.package 的入口点已由该包声明。对于 example.dependant 的主入口点 index.scss，它可能包含以下内容

@import "example/dependant/colors";
@import "example/dependant/full_ui";
@import "example/package/form";

在这个例子中，仅包含了 example.package 导出的 form.scss 样式，省略了 colors.scss 和 ui.scss，因为这些可能与依赖包中其他样式（例如 colors 和 full_ui）所需和实现的定义冲突。其他依赖此 example.dependant 包的依赖项可以按照其所有者的偏好声明使用任何这些导出的样式。这是提供可扩展样式的一种方法，这些样式可以通过依赖项分块地重复使用。

当然，如果需要，可以为特定包指定除了 index.scss 之外的入口点参数（例如，可能需要导出多个样式表以用于给定包提供的不同工作流程）。

在 Node.js 包仓库中包含 .scss 文件

由于与 Node.js 的集成是 Calmjs 框架的目标，因此可以声明与包含 .scss 文件的 Node.js 包（例如 npm）的链接。实际使用方式与通过 Calmjs 的典型集成非常相似，区别在于要指定的关键字。

例如，一个 setup.py 可能包含以下内容

setup(
    name="example.package"
    package_json={
        "dependencies": {
            "bootstrap": "~4.0.0",
        },
    },
    extras_calmjs_scss={
        'node_modules': {
            'bootstrap': 'bootstrap/scss',
        }
    },
)

上面的声明简单地暴露了来自 npm 的 bootstrap 包内的所有 .scss 文件，因为目录已被声明为用于构建过程。从这个依赖项导入所需的模块很简单

@import "bootstrap/nav";
@import "bootstrap/navbar";

将无缝工作，就像JavaScript代码的使用一样。

也可以显式指定来自npm的完整工件以在特定标识符下导出。

声明Python包的标准CSS包

最后，为了完成Python包部署的故事，过程应包括自动生成和包含结果Python轮中的样式表工件。这可以通过在calmjs.artifacts注册表中指定一个条目来实现，键是工件文件的名称，值是到构建器的导入位置。在calmjs.sassy.artifact:complete_css提供的默认构建器函数将允许基于默认工具链和设置生成完整的样式表，而calmjs.sassy.artifact:complete_compressed_css提供了一种将生成压缩样式输出的规范。请注意，这两个构建器都使用了libsass-python工具链。

一个示例入口点配置，仅生成完整的CSS工件（不进行压缩）

[calmjs.artifacts]
example.bundle.css = calmjs.sassy.artifact:complete_css

一旦安装了这些入口点，运行calmjs artifact build example.package将使用SCSS工具链并构建位于元数据目录中的calmjs_artifacts目录内的example.bundle.css工件。作为替代，对于与setuptools更紧密结合的解决方案，setup.py中的setup函数也应启用build_calmjs_artifacts标志，这样setup.py build也将触发构建过程。这有助于在构建轮的过程中自动生成和包含工件。

一个更完整的定义，可以生成两种类型的工件，如下所示setup.py

setup(
    name='example.package',
    # to enable calmjs artifact generation integration w/ setuptools
    build_calmjs_artifacts=True,
    entry_points="""
    # ... other entry points truncated
    [calmjs.module]
    example.package = example.package

    [calmjs.artifacts]
    example.bundle.css = calmjs.sassy.artifact:complete_css
    example.bundle.min.css = calmjs.sassy.artifact:complete_compressed_css
    """,
    # ... other required fields truncated
)

使用setup.py构建轮可能会得到如下结果。

$ python setup.py bdist_wheel
automatically picked registries ['calmjs.scss'] for sourcepaths
...
invoking 'sass.compile' on entry point module at '/tmp/tmpwb5bhmd0/build/__calmjs_sassy__/index.scss'
wrote export css file at '/home/user/example.package/src/example.package.egg-info/calmjs_artifacts/example.bundle.css'
installing to build/bdist.linux-x86_64/wheel
...

在生成的Python轮的包元数据目录中的calmjs_artifacts子目录下，既有example.bundle.css也有example.bundle.min.css可用。

此外，默认构建器指定index作为默认入口点。如果需要提供其他入口点或需要其他选项，只需创建一个新的构建器函数，该函数返回一个带有所需值的Spec对象。

最终结果是，该包的最终用户将能够使用提供的功能，而无需进行单独的构建步骤，同时保留仅通过安装构建依赖项即可重新生成所有必需的工件的能力，无需进一步获取原始配置文件（甚至源文件），因为这些工件作为包的一部分提供（前提是原始源也打包到轮中）。

使用注册的.scss与其他Calmjs Node.js/JavaScript工具链

虽然注册系统旨在尽可能地扩展和重用，但这些特定的底层工具可能期望不同的完整模块名称，因为它们可能需要在样式表前添加特定的加载器字符串。这个主题需要更多的探索以实现更好的整体集成，尽管实现这一目标的基础/通用形式已经可用。

用户警告：未知分布选项

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

CalmjsSassyRuntimeError：缺少所需的包 'libsass'。

请安装 libsass-python 包；这可以通过运行

$ pip install libsass

CalmjsSassyRuntimeError：使用 libsass 编译失败。

这可能是由于样式规则中的语法错误导致的，这些错误应作为输出的一部分报告。使用内置的 calmjs scss 运行时生成可能会通过相关标志返回更详细的调试信息，如 --help 标志所述。

内部错误：使用空源字符串创建数据上下文。

在使用 libsass 接口运行时或工具链（例如默认的 calmjs scss 运行时）时，如果提供的包不包含（导出）指定入口点名称（默认为 index，因此包必须在 calmjs.scss 注册表中注册的位置导出 index.scss 文件），则不会导入任何内容，源字符串将为空，导致 libsass 中断执行。