cdnupload 1.0.4

源

source是你静态文件的源目录，例如/website/static。使用可选的--include和--exclude参数以及下面描述的其他参数，来控制上传哪些文件。

目标地址和目标参数

destination是要上传到的目标目录，或用于上传到Amazon S3的s3://static-bucket/prefix路径。

你也可以指定目标地址的自定义方案（URL的schema://部分），并且cdnupload将尝试导入名为cdnupload_scheme的模块（该模块必须在PYTHONPATH上），并使用该模块的Destination类以及dest_args来创建目标实例。

例如，如果你为Google Cloud Storage创建了自己的上传器，你可能可以使用前缀gcs://并将模块命名为cdnupload_gcs。然后你可以使用gcs://my/path作为目标地址，并且cdnupload将使用cdnupload_gcs.Destination('gcs://bucket', **dest_args)来实例化目标实例。

有关自定义Destination子类的更多信息，请参阅自定义目标地址部分。

dest_args是传递给Destination类的关键字参数的目标特定参数（例如，对于s3://目标，有用的目标参数可能是max-age=86400或region-name=us-west-2）。请注意，目标参数中的连字符将转换为下划线，因此region-name=us-west-2变为region_name='us-west-2'。

要获取有关目标特定参数的帮助，请使用dest-help操作。例如，要显示S3特定的目标参数

cdnupload source s3:// --action=dest-help

常见参数

-h，--help

显示有关这些命令行选项的帮助并退出。

-a ACTION，--action ACTION

指定要执行的操作（默认为上传）

• upload：从源上传文件到目标（但仅当它们尚未在目标上时）。

• delete：删除目标处的未使用文件（源中不再存在的文件）。删除时要小心，并使用--dry-run先进行测试！

• dest-help: 显示给定目标类的帮助信息和可用目标参数。

-d, --dry-run

显示脚本将上传或删除的内容，而不是实际执行。在运行--action=delete之前，此选项推荐使用，以确保不会删除超出预期的内容。

-e PATTERN, --exclude PATTERN

如果源文件的相对路径与给定的模式匹配（根据Python的fnmatch规则），则排除源文件。例如，使用*.txt排除所有文本文件，或使用__pycache__/*排除pycache目录下的所有内容。此选项可以多次指定以排除多个模式。

排除的优先级高于包含，因此您可以使用--include=*.txt，然后使用--exclude=docs/README.txt排除特定的文本文件。

-f, --force

在上传时，即使目标文件已存在，也强制上传所有文件（例如，在更新Amazon S3上的标题时很有用）。

在删除时，即使目标上的所有文件都将被删除，也允许删除操作发生（默认情况下，会阻止这种情况，以避免rm -rf风格的错误）。

-i PATTERN, --include PATTERN

如果指定，则仅包括相对路径与给定模式匹配的源文件（根据Python的fnmatch规则）。例如，使用*.png包括所有PNG图像，或使用images/*包括images目录下的所有内容。此选项可以多次指定以包括多个模式。

排除的优先级高于包含，因此您可以使用--include=*.txt，然后使用--exclude=docs/README.txt排除特定的文本文件。

-k FILENAME, --key-map FILENAME

将密钥映射写入给定的文件作为JSON（但仅在成功上传或删除后）。此文件可以由您的Web服务器使用，以生成静态文件的完整CDN URL。

JSON对象中的键是原始路径（相对于源根），对象中的值是目标路径（相对于目标根）。例如，JSON可能看起来像这样：{"script.js": "script_0beec7b5ea3f0fdb.js", ...}。

-l LEVEL, --log-level LEVEL

设置日志输出的详细程度。级别必须是以下之一：

• debug：最详细输出。记录脚本会跳过的文件。

• verbose：详细输出。记录脚本开始、结束以及上传和删除发生（或如果进行--dry-run，将发生）时的情况。

• default：默认日志输出级别。仅在脚本实际上传或删除文件时记录（无开始或结束日志）。如果没有要执行的操作，则不记录任何内容。

• error：仅记录错误。

• off：完全关闭所有日志记录。

-v, --version

显示cdnupload的版本号并退出。

较少使用的参数

--continue-on-errors

在发生上传或删除错误后继续。脚本仍将记录错误，并且如果有至少一个错误，它还将返回非零退出代码。默认情况下，在第一个错误时停止。

--dot-names

包括以点（.）开头的源文件和目录。默认情况下，将跳过以点开头的任何文件或目录。

--follow-symlinks

在遍历源树时跟随目录的符号链接。默认情况下，会跳过任何目录的符号链接。

--hash-length N

设置用于目标密钥的内容哈希的十六进制字符数。默认值为16。

--ignore-walk-errors

忽略遍历源树时的错误（例如，目录上的权限错误），除了列出源根目录时的错误。

自定义目标位置

您可能需要扩展 cdnupload 的最常见原因是编写一个自定义的 Destination 子类（如果内置的文件或 Amazon S3 目标不适用于您）。

例如，如果您使用的是连接到名为“我的源”的源服务器的 CDN，您可能需要编写一个自定义子类以上传到您的源。您需要从 cdnupload.Destination 继承并实现初始化器以及 __str__、walk_keys、upload 和 delete 方法。

import cdnupload
import myorigin

class Destination(cdnupload.Destination):
    def __init__(self, url, foo='FOO', bar=None):
        """Initialize destination instance with given "My Origin" URL
        (which should be in form my://server/path).
        """
        self.url = url
        self.conn = myorigin.Connection(url, foo=foo, bar=bar)

    def __str__(self):
        """Return a human-readable string for this destination."""
        return self.url

    def walk_keys(self):
        """Yield keys (files) that are currently on the destination."""
        for file in self.conn.get_files():
            yield file.name

    def upload(self, key, source, rel_path):
        """Upload a single file from source at rel_path to destination
        at given key. Normally this function will use the with statement
        "with source.open(rel_path)" to open the source file object.
        """
        with source.open(rel_path) as source_file:
            self.conn.upload_file_obj(source_file, key)

    def delete(self, key):
        """Delete a single file on destination at given key."""
        self.conn.delete_file(key)

要使用此自定义目标，将您的自定义代码保存到 cdnupload_my.py，并确保该文件位于您的 PYTHONPATH 上的某个位置。然后，如果您以以方案 my:// 开头的目标运行 cdnupload 命令行工具，它将自动导入 cdnupload_my 并查找一个名为 Destination 的类，将 my://server/path URL 和任何其他目标参数传递给初始化器。

请注意，当命令行工具将额外的 dest_args 传递给自定义目标时，它始终将它们作为字符串（如果指定的目标参数重复一次以上，则为字符串列表）传递。因此，如果您需要整数或其他类型，您需要在 __init__ 方法中进行转换。

上传和删除

顶级函数 upload() 和 delete() 推动着 cdnupload。如果您想连接到 cdnupload 的 Python API，可以创建自己的命令行入口点。例如，您可以这样创建一个 myupload.py 脚本：

import cdnupload
import hashlib

source = cdnupload.FileSource('/path/to/my/statics',
                              hash_class=hashlib.md5)
destination = cdnupload.S3Destination('s3://bucket/path')
cdnupload.upload(source, destination)

在这里，我们对 FileSource 的哈希行为进行了轻微的自定义（将其从 SHA-1 更改为 MD5），然后执行上传。

upload() 函数将文件从源上传到目标，但只有当它们在目标中不存在（根据 destination.walk_keys）时才会这样做。

delete() 函数删除目标中的文件，如果它们在源中不再存在（根据 source.build_key_map）。

这两个函数都接受相同的参数集

• source：源对象；可以是 FileSource 实例（或实现相同接口的对象），或字符串，在这种情况下，它通过 FileSource(source) 转换为源

• destination：目标对象；可以是具体 Destination 子类的实例，或字符串，在这种情况下，它通过 FileDestination(destination) 转换为目标

• force=False：如果为 True，则与指定 --force 命令行选项相同

• dry_run=False：如果为 True，则与指定 --dry-run 命令行选项相同

• continue_on_errors=False：如果为 True，则与指定 --continue-on-errors 命令行选项相同

这两个函数都返回一个 Result 命名元组，它有以下属性

• source_key_map：源路径到目标键的映射，与 source.build_key_map() 返回的相同字典

• destination_keys：包含目标键的集合，由destination.walk_keys()返回

• num_scanned：扫描的总文件数（上传时的源文件，或删除时的目标键）

• num_processed：处理的文件数（实际上已上传或删除的文件）

• num_errors：错误数（当continue_on_errors为真时很有用）

自定义源

您还可以自定义文件的源。目前只有一个源类，即FileSource，它从文件系统中读取文件并生成文件哈希。您可以通过传递给FileSource初始化器的选项来控制它包含或排除哪些文件，以及如何对它们的 内容进行哈希以生成基于内容的哈希。

参数dot_names、include、exclude、ignore_walk_errors、follow_symlinks和hash_length对应于命令行选项--dot-names、--include、--exclude、--ignore-walk-errors、--follow-symlinks和--hash-length。

此外，您还可以使用参数hash_chunk_size和hash_class进一步自定义FileSource。在哈希时，文件以hash_chunk_size-字节块读取，hash_class实例化以生成哈希（必须具有hashlib样式签名）。

或者，如果您想自定义高级行为，可以子类化FileSource。例如，您可以覆盖FileSource.hash_file()对文本文件和二进制文件的处理，使所有文件都被视为二进制文件

from cdnupload import FileSource

class BinarySource(FileSource):
    def hash_file(self, rel_path):
        return FileSource.hash_file(self, rel_path, is_text=False)

要使用子类化的FileSource，您需要从Python直接调用实例的upload()和delete()函数。目前无法通过cdnupload命令行脚本使用子类化的源。

日志记录

cdnupload函数使用标准的Python日志记录来记录所有操作。记录器名称为cdnupload，您可以使用Python日志记录函数来控制日志输出格式和详细程度（日志级别）。

例如，要记录所有错误，但只为cdnupload日志打开调试级别记录，可以这样做

import logging

logging.basicConfig(level=logging.ERROR)
logging.getLogger('cdnupload').setLevel(logging.DEBUG)