脚本目录

脚本目录#

ScriptDirectory 对象提供对文件系统中存在的 Alembic 版本文件的编程访问。

类 alembic.script.Script(module: ModuleType, rev_id: str, path: str)#

表示 versions/ 目录中的单个修订文件。

Script 实例由方法返回，例如 ScriptDirectory.iterate_revisions()。

属性 doc: str#

返回脚本中给出的文档字符串。

属性 长文档: str#

返回脚本中给出的文档字符串。

模块: ModuleType#

表示实际脚本本身的 Python 模块。

路径: str#

脚本的文件系统路径。

class alembic.script.ScriptDirectory(dir: str, file_template: str = '%(rev)s_%(slug)s', truncate_slug_length: int | None = 40, version_locations: List[str] | None = None, sourceless: bool = False, output_encoding: str = 'utf-8', timezone: str | None = None, hook_config: Mapping[str, str] | None = None, recursive_version_locations: bool = False, messaging_opts: MessagingOptions = {})#

提供对 Alembic 脚本目录的操作。

此对象可用于获取有关当前版本的的信息，最值得注意的是能够获取“头”版本，对于想要测试数据库中的当前版本是否是最新版本的方案来说。

from alembic.script import ScriptDirectory
from alembic.config import Config
config = Config()
config.set_main_option("script_location", "myapp:migrations")
script = ScriptDirectory.from_config(config)

head_revision = script.get_current_head()
作为版本号(id_: str | None) → str | Tuple[str, ...] | None#

将符号修订（即“head”或“base”）转换为实际修订号。

classmethod from_config(config: Config) → ScriptDirectory#

给定 Config 实例，生成新的 ScriptDirectory。

Config 只需要有 script_location 键。

generate_revision(revid: str, message: str | None, head: _RevIdType | None = None, splice: bool | None = False, branch_labels: _RevIdType | None = None, version_path: str | None = None, depends_on: _RevIdType | None = None, **kw: Any) → Script | None#

生成新的修订文件。

这将运行 script.py.mako 模板（给定模板参数），并创建一个新文件。

参数:

  • revid – 字符串修订 ID。通常来自 alembic.util.rev_id()。

  • message – 修订消息，即 revision 命令的 -m 参数传递的消息。

  • head – 要针对其生成的头部修订。如果没有分支，则默认为当前“头部”；否则，引发异常。

  • splice – 如果为 True，则允许“头部”版本不是实际头部；否则，选定的头部必须是头部（例如端点）修订。

get_base() → str | None#

将“基本”修订作为字符串返回。

这是脚本的修订号，其 down_revision 为 None。

如果脚本目录有多个基础，则会引发错误；应优先使用 ScriptDirectory.get_bases()。

get_bases() → List[str]#

将所有“基础”修订版本作为字符串返回。

这是所有 down_revision 为 None 的脚本的修订号。

get_current_head() → str | None#

返回当前头修订版本。

如果脚本目录由于分支而有多个头，则会引发错误；应优先使用 ScriptDirectory.get_heads()。

返回:

字符串修订号。

另请参阅

脚本目录.get_heads()

get_heads() → List[str]#

以字符串形式返回所有“版本化头”修订。

这通常是一个长度为一的列表，除非存在分支。当脚本目录只有一个头时，通常可以使用 ScriptDirectory.get_current_head() 方法。

返回:

一个字符串修订号元组。

get_revision(id_: str) → Script#

返回具有给定修订 ID 的 Script 实例。

另请参阅

脚本目录.get_revisions()

get_revisions(id_: _GetRevArg) → Tuple[Script, ...]#

返回具有给定修订标识符、符号名称或标识符序列的 Script 实例。

iterate_revisions(upper: str | Tuple[str, ...] | None, lower: str | Tuple[str, ...] | None, **kw: Any) → Iterator[Script]#

从给定的上修订标识符开始，到下修订标识符结束，遍历脚本修订。

遍历严格使用每个迁移脚本中的 down_revision 标记，因此 upper >= lower 是一个要求，否则你将一无所获。

迭代器生成 Script 对象。

另请参阅

RevisionMap.iterate_revisions()

run_env() → None#

运行脚本环境。

这基本上运行迁移环境中存在的 env.py 脚本。它由 alembic.command 中的命令函数独占调用。

walk_revisions(base: str = 'base', head: str = 'heads') → Iterator[Script]#

遍历所有修订版本。

参数:

  • base – 基本修订版本，或从空修订版本开始的“base”。

  • head – 头部修订版本；默认为“heads”，表示所有头部修订版本。也可以是“head”，表示单个头部修订版本。

修订版本#

RevisionMap 对象充当修订版本管理的基础，由 ScriptDirectory 独占使用。

异常 alembic.script.revision.CycleDetected(revisions: 序列[str])#
异常 alembic.script.revision.DependencyCycleDetected(revisions: 序列[str])#
异常 alembic.script.revision.DependencyLoopDetected(revision: 序列[str])#
异常 alembic.script.revision.LoopDetected(revision: str)#
异常 alembic.script.revision.MultipleHeads(heads: Sequence[str], argument: str | None)#
异常 alembic.script.revision.RangeNotAncestorError(lower: str | Tuple[str, ...] | None, upper: str | Tuple[str, ...] | None)#
异常 alembic.script.revision.ResolutionError(message: str, argument: str)#
class alembic.script.revision.Revision(revision: str, down_revision: str | Tuple[str, ...] | None, dependencies: str | Tuple[str, ...] | None = None, branch_labels: str | Tuple[str, ...] | None = None)#

修订对象的基本类。

Revision 类是面向公众的 Script 对象的基础，它表示一个迁移脚本。修订管理和遍历的机制封装在 Revision 中，而 Script 将此逻辑应用于版本目录中的 Python 文件。

branch_labels: Set[str] = None#

应用于此修订分支的可选字符串/符号名称元组

dependencies: str | List[str] | Tuple[str, ...] | None = None#

此修订所依赖的其他修订。

从迁移角度来看，这些依赖项被添加到 down_revision 中以形成完整迭代。但是，将 down_revision 与“依赖项”分开是为了帮助浏览包含许多分支（通常是多根场景）的历史记录。

down_revision: str | List[str] | Tuple[str, ...] | None = None#

迁移脚本中的 down_revision 标识符。

请注意，“向下”修订的总集合是 down_revision + 依赖项。

property is_base: bool#

如果此 Revision 是“基本”修订，则返回 True。

property is_branch_point: bool#

如果此 Script 是分支点，则返回 True。

分支点定义为一个 Script，它被多个后续 Script 引用，即多个 Script 具有指向此处的 down_revision 标识符。

property is_head: bool#

如果此 Revision 是“头部”修订版，则返回 True。

这取决于 ScriptDirectory 中的任何其他 Script 是否引用此 Script。可以存在多个头部。

property is_merge_point: bool#

如果此 Script 是合并点，则返回 True。

nextrev: FrozenSet[str] = frozenset({})#

仅基于 down_revision 的后续修订版。

revision: str = None#

字符串修订版本号。

exception alembic.script.revision.RevisionError#
class alembic.script.revision.RevisionMap(generator: Callable[[], Iterable[Revision]])#

维护Revision对象的映射。

RevisionMap由ScriptDirectory用来维护和遍历Script对象集合，它们本身是Revision的实例。

构造一个新的RevisionMap。

参数:

generator – 一个零参数可调用对象，它将生成一个可迭代的Revision实例，供使用。在常规的 Alembic 使用中，这些通常是Script子类。

add_revision(revision: Revision, _replace: bool = False) → None#

将单个修订版添加到现有映射中。

此方法适用于单修订版用例，不适用于完全填充整个修订版映射。

bases#

所有“基本”修订版（作为字符串）。

这些修订版具有 down_revision 为 None 或空元组。

返回:

一个字符串修订号元组。

get_current_head(branch_label: str | None = None) → str | None#

返回当前头修订版本。

如果脚本目录由于分支而有多个头，则会引发错误；应优先使用 ScriptDirectory.get_heads()。

参数:

branch_label – 可选分支名称，它将限制所考虑的头，仅考虑包含该 branch_label 的头。

返回:

字符串修订号。

另请参阅

脚本目录.get_heads()

get_revision(id_: str | None) → Revision | None#

返回具有给定修订 ID 的 Revision 实例。

如果给出了符号名称（如“head”或“base”），则将标识符解析为当前头或基本修订。如果符号名称引用多个，则会引发 MultipleHeads。

支持部分标识符，其中给定的标识符与以给定字符开头的所有标识符匹配；如果完全匹配，则确定完整修订。

get_revisions(id_: _GetRevArg | None) → Tuple[_RevisionOrBase | None, ...]#

返回具有给定修订 ID 或标识符的 Revision 实例。

可以给出一个标识符、一系列标识符或特殊符号“head”或“base”。结果是一个或多个标识符的元组，或在“base”的情况下为空元组。

在请求“head”、“heads”且修订映射为空的情况下，返回一个空元组。

支持部分标识符，其中给定的标识符与以给定字符开头的所有标识符匹配；如果完全匹配，则确定完整修订。

heads#

所有“head”修订作为字符串。

这通常是一个长度为 1 的元组，除非存在未合并的分支。

返回:

一个字符串修订号元组。

iterate_revisions(upper: str | Tuple[str, ...] | None, lower: str | Tuple[str, ...] | None, implicit_base: bool = False, inclusive: bool = False, assert_relative_length: bool = True, select_for_downgrade: bool = False) → Iterator[Revision]#

从给定的上修订标识符开始，到下修订标识符结束，遍历脚本修订。

遍历严格使用每个迁移脚本中的 down_revision 标记，因此 upper >= lower 是一个要求，否则你将一无所获。

迭代器生成 Revision 对象。

写入挂钩#

alembic.script.write_hooks.register(name: str) → Callable#

一个函数装饰器，它将该函数注册为写入挂钩。

有关示例，请参阅下面链接的文档。

另请参阅

将自定义挂钩编写为 Python 函数

目录