webresource 1.2

特性

• 通过Python声明Web资源。

• 管理资源之间的依赖关系。

• 资源分组。

• 条件交付资源。

• 开发和生产模式。

详细文档

详细的 webresource 文档可在 此处 查找。

源代码

源代码位于GIT DVCS中，其主要分支位于 github。

版权

• 版权（c）2021-2022 Cone贡献者

贡献者

• Robert Niederreiter（作者）

声明资源

Web资源提供了3种类型的资源。 ScriptResource 用于注册JavaScript，StyleResource 用于CSS文件，LinkResource 可用于注册各种资源链接。

声明一个脚本

import webresource as wr

my_js = wr.ScriptResource(
    name='my_js',
    directory='/path/to/scripts',
    resource='my.js',
    compressed='my.min.js',
    path='js'
)

name 是资源的唯一标识符。directory 定义资源在文件系统中的位置。resource 是与此声明对应的默认资源文件。compressed 是资源的压缩版本，如果Webresource在生产模式下使用，则会被考虑。path 定义资源发布的URL路径的路径部分。

资源之间的依赖关系通过传递 depends 参数来定义，它可以是单个依赖项或元组或列表中的多个依赖项。

other_js = wr.ScriptResource(
    name='other_js',
    depends='my_js',
    ...
)

可以将回调函数作为 include 参数传递。它可以用来计算是否应该包含资源。

def include_conditional_js():
    # Compute whether to include resource here.
    return True

conditional_js = wr.ScriptResource(
    name='conditional_js',
    include=include_conditional_js,
    ...
)

include 属性也可以设置为布尔值，这可能会在排除已注册的资源时很有用。

conditional_js.include = False

资源URL可以渲染包括资源文件的唯一键。这在缓存能力强的环境中很有用，以确保更改的资源能够正确地重新加载。当与唯一的资源URL一起工作时，唯一键在路径和文件名之间渲染，因此集成商需要实现自定义URL重写/分发/遍历来正确交付资源。

cached_js = wr.ScriptResource(
    name='cached_js',
    unique=True,
    unique_prefix='++webresource++',
    ...
)

如果要声明外部资源，请传递 url 参数。在这种情况下，忽略 path、resource 和 compressed。

external_js = wr.ScriptResource(
    name='external_js',
    url='https://example.org/resource.js'
    ...
)

可以通过将额外的关键字参数传递给构造函数来在资源标签上渲染额外的属性。当与Web编译器（如Diazo）一起工作时，这可能很有用。

custom_attr_js = wr.ScriptResource(
    name='custom_attr_js',
    **{'data-bundle': 'bundle-name'}
)

此示例使用 ScriptResource，但上述描述的行为适用于所有提供的资源类型。

资源组

可以通过将资源添加到 ResourceGroup 对象中来对资源进行分组。

scripts = wr.ResourceGroup(name='scripts')

如果事先知道组，则可以在实例化时将资源添加到组中。

script = wr.ScriptResource(
    name='script',
    group=scripts
    ...
)

或者可以将已声明的资源添加到组中

scripts.add(script)

组可以嵌套

scripts = wr.ResourceGroup(name='scripts')
base_scripts = wr.ResourceGroup(
    name='base_scripts',
    group=scripts
)
addon_scripts = wr.ResourceGroup(
    name='addon_scripts',
    group=scripts
)

组可以为其成员定义默认的 path。如果包含的组成员定义了自己的路径，则取默认路径。

scripts = wr.ResourceGroup(name='scripts', path='js')

对于资源的 directory 也适用。如果定义在资源组上，则取默认值，除非包含的成员覆盖它。

scripts = wr.ResourceGroup(name='scripts', directory='/path/to/scripts')

要控制是否应该包含整个组，请定义一个 include 回调函数或标志。

def include_group():
    # Compute whether to include resource group here.
    return True

group = wr.ResourceGroup(
    name='group',
    include=include_group,
    ...
)

交付资源

Web资源不提供任何机制来发布声明的资源。用户需要将定义目录中的资源在定义的路径下提供给浏览器。

但它提供了一个用于渲染结果资源HTML标签的渲染器。

首先需要创建一个 ResourceResolver，该渲染器了解要交付的资源。members 可以是资源或资源组的实例或列表。

然后使用 ResourceRenderer 创建标记。

GracefulResourceRenderer 创建标记，但如果一个资源无效，则不会失败。它会记录一个错误，并用关于失败情况的注释代替HTML标签。

完整示例

import webresource as wr

icon = wr.LinkResource(
    name='icon',
    resource='icon.png',
    rel='icon',
    type_='image/png'
)

css = wr.StyleResource(name='css', resource='styles.css')

ext_css = wr.StyleResource(
    name='ext_css',
    url='https://ext.org/styles.css'
)

script = wr.ScriptResource(
    name='script',
    resource='script.js',
    compressed='script.min.js'
)

resources = wr.ResourceGroup(name='resources', path='res')
resources.add(icon)
resources.add(css)
resources.add(ext_css)
resources.add(script)

resolver = wr.ResourceResolver(resources)
renderer = wr.ResourceRenderer(resolver, base_url='https://tld.org')

rendered = renderer.render()

rendered 结果是

<link href="https://tld.org/res/icon.png"
      rel="icon" type="image/png" />
<link href="https://tld.org/res/styles.css" media="all"
      rel="stylesheet" type="text/css" />
<link href="https://ext.org/styles.css" media="all"
      rel="stylesheet" type="text/css" />
<script src="https://tld.org/res/script.min.js"></script>

调试

为防止Web资源生成指向已声明资源压缩版本的链接，需要设置配置单例的development标志。

wr.config.development = True

1.2 (2022-12-21)

• 在资源中接受额外的关键字参数。它们将被渲染为资源标签上的附加属性。[rnix, aormazabal]

1.1 (2022-07-01)

• 移除相对目录解析。[rnix]

• 向ResourceMixin添加remove函数。[rnix]

• 向ResourceMixin添加copy函数。[rnix]

• 向ResourceGroup添加scripts、styles和links属性。[rnix]

• 在ResourceMixin上引入parent属性。在ResourceGroup.add方法中设置，以提供层次信息。[rnix]

• 移除资源魔术路径解析行为。路径现在不再在解析器中被覆盖。如果没有在资源或资源组上设置，则从父路径获取。[rnix]

• LinkResource和StyleResource现在有共同的父类LinkMixin。StyleResource不再从LinkResource继承。这样，通过isinstance可以区分链接和样式资源的相应子类。[rnix]

• 从StyleResource构造函数中移除sizes关键字参数。[rnix]

• ResourceGroup可以为包含的资源定义一个目录。[rnix]

• Resource.directory现在默认不再设置为包路径，而是保持为None。[rnix]

• 资源可以定义多个依赖项。[rnix]

1.0 (2022-03-24)

• 添加Tox、Github actions并使其在Windows上运行。现代化设置。[py|cfg]。[jensens]

• 添加了GracefulResourceRenderer。修复了#1。[jensens]

1.0b8 (2021-09-23)

• 将资源中的hash_关键字参数重命名为unique。

• 在资源上引入unique_prefix关键字参数。

• 更改唯一URL生成的行为。唯一键现在在URL路径和文件名之间渲染。这样我们就能与缓存服务器很好地配合，但这也意味着在处理唯一资源URL时需要自定义URL分发/重写/遍历。[rnix]

1.0b7 (2021-08-16)

• 在ScriptResource上添加自动完整性哈希计算。[rnix]

• 向Resource、ScriptResource、LinkResource和FileResource添加hash_和hash_algorithm关键字参数。[rnix]

• 添加Resource.file_hash属性。[rnix]

• 添加Resource.file_data属性。[rnix]

1.0b6 (2021-08-10)

• 显式引发ResourceError而不是通用ValueError。[rnix]

1.0b5 (2021-08-09)

• 使Resource.directory成为可读写属性。[rnix]

1.0b4 (2021-08-08)

• 更改路径级联行为。在ResourceGroup上设置的路径始终优先于其成员路径。[rnix]

• Resource和ResourceGroup的include属性可以外部设置。[rnix]

1.0b3 (2021-08-06)

• 向发布中添加剩余缺失的rst文件。[rnix]

1.0b2 (2021-08-06)

• 向发布中添加缺失的docs/source/overview.rst。[rnix]

1.0b1 (2021-08-06)

• 初始发布。[rnix]