配置

配置#

注意

本节讨论了 Alembic 的内部 API，涉及内部配置结构。本节仅对希望扩展 Alembic 功能的开发者有用。有关 Alembic 环境配置的文档，请参阅 教程。

对象 Config 表示传递给 Alembic 环境的配置。从 API 使用角度来看，它对于以下用例是必需的

  • 创建 ScriptDirectory，它允许你在迁移环境中使用实际脚本文件

  • 创建 EnvironmentContext，它允许你在迁移环境中实际运行 env.py 模块

  • 以编程方式运行 Commands 模块中的任何命令。

对于这些情况，不需要 Config

class alembic.config.Config(file_: str | ~os.PathLike[str] | None = None, ini_section: str = 'alembic', output_buffer: ~typing.TextIO | None = None, stdout: ~typing.TextIO = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, cmd_opts: ~argparse.Namespace | None = None, config_args: ~typing.Mapping[str, ~typing.Any] = {}, attributes: ~typing.Dict[str, ~typing.Any] | None = None)#

表示 Alembic 配置。

在 env.py 脚本中，可以通过 EnvironmentContext.config 属性进行访问，该属性又可以在 alembic.context 中进行访问

from alembic import context

some_param = context.config.get_main_option("my option")

以编程方式调用 Alembic 时，可以通过将 .ini 文件的名称传递给构造函数来创建新的 Config

from alembic.config import Config
alembic_cfg = Config("/path/to/yourapp/alembic.ini")

使用 Config 对象，然后可以使用 alembic.command 中的指令以编程方式运行 Alembic 命令。

还可以不使用文件名构造 Config 对象。可以以编程方式设置值，并且将根据需要创建新部分

from alembic.config import Config
alembic_cfg = Config()
alembic_cfg.set_main_option("script_location", "myapp:migrations")
alembic_cfg.set_main_option("sqlalchemy.url", "postgresql://foo/bar")
alembic_cfg.set_section_option("mysection", "foo", "bar")

警告

使用编程配置时，请确保所使用的 env.py 文件与目标配置兼容；包括如果编程配置实际上不包含日志记录指令，则省略对 Python logging.fileConfig() 的调用。

要将非字符串值传递到环境（例如连接和引擎），请使用 Config.attributes 字典

with engine.begin() as connection:
    alembic_cfg.attributes['connection'] = connection
    command.upgrade(alembic_cfg, "head")
参数:

  • file_ – 要打开的 .ini 文件的名称。

  • ini_section – .ini 文件中 Alembic 主部分的名称

  • output_buffer – 可选的文件输入缓冲区，该缓冲区将传递给 MigrationContext - 用于在以编程方式使用 Alembic 时重定向“离线生成”的输出。

  • stdout – 缓冲区，其中将发送命令的“print”输出。默认为 sys.stdout。

  • config_args – 将用于在 alembic 配置文件中进行替换的键值字典。给定的字典复制到一个新字典，作为属性 .config_args 本地存储。当 Config.file_config 属性首次调用时，替换变量 here 将添加到此字典中，然后将字典传递给 ConfigParser() 以解析 .ini 文件。

  • attributes –

    可选的任意 Python 键/值字典，它将填充到 Config.attributes 字典中。

    另请参阅

    在一条或多条编程迁移命令之间共享连接

构建一个新的 Config

attributes#

用于存储附加状态的 Python 字典。

这是一个实用程序字典，其中不仅可以包含字符串，还可以包含引擎、连接、架构对象或其他任何内容。使用它将对象传递到 env.py 脚本中，例如在从 alembic.command 以编程方式调用命令时传递 sqlalchemy.engine.base.Connection。

另请参阅

在一条或多条编程迁移命令之间共享连接

Config.attributes

cmd_opts: Namespace | None = None#

传递给 alembic 脚本的命令行选项。

在 env.py 脚本中，可以通过 EnvironmentContext.config 属性访问它。

另请参阅

EnvironmentContext.get_x_argument()

config_file_name: str | PathLike[str] | None = None#

正在使用的 .ini 文件的文件系统路径。

config_ini_section: str = None#

读取基本配置的配置文件部分的名称。默认为 alembic，即 .ini 文件的 [alembic] 部分。此值使用 -n/--name 选项修改为 Alembic 运行器。

file_config#

返回底层的 ConfigParser 对象。

此处可直接访问 .ini 文件，不过 Config.get_section() 和 Config.get_main_option() 方法提供了一个更简单的界面。

get_main_option(name: str, default: str) → str#
get_main_option(name: str, default: str | None = None) → str | None

返回 .ini 文件“main”部分中的选项。

除非使用 -n/--name 标志指示不同的部分，否则默认为 [alembic] 部分中的键。

get_section(name: str, default: None = None) → Dict[str, str] | None#
get_section(name: str, default: Dict[str, str]) → Dict[str, str]
get_section(name: str, default: Mapping[str, str]) → Dict[str, str] | Mapping[str, str]

从给定的 .ini 文件部分中以字典形式返回所有配置选项。

如果给定的部分不存在，则返回 default 的值，该值应为字典或其他映射。

get_section_option(section: str, name: str, default: str | None = None) → str | None#

从 .ini 文件的给定部分返回一个选项。

get_template_directory() → str#

返回找到 Alembic 设置模板的目录。

此方法由 alembic init 和 list_templates 命令使用。

messaging_opts#

消息选项。

print_stdout(text: str, *arg: Any) → None#

将消息呈现到标准输出。

当 Config.print_stdout() 使用附加参数调用时，这些参数将根据提供的文本进行格式化，否则，我们仅逐字输出提供的文本。

当启用``quiet``消息选项时，这是一个无操作。

例如。

>>> config.print_stdout('Some text %s', 'arg')
Some Text arg
set_main_option(name: str, value: str) → None#

在“main”部分以编程方式设置一个选项。

这将覆盖 .ini 文件中的任何内容。

参数:

  • name – 值的名称

  • value – 值。请注意，此值传递给 ConfigParser.set，它支持使用 pyformat（例如 %(some_value)s）进行变量插值。因此，不属于插值符号一部分的原始百分号必须进行转义，例如 %%。给定的值可以使用插值格式引用文件中已有的另一个值。

set_section_option(section: str, name: str, value: str) → None#

在给定部分中以编程方式设置选项。

如果部分不存在，则创建该部分。此处的值将覆盖 .ini 文件中的任何值。

参数:

  • section – 部分名称

  • name – 值的名称

  • value – 值。请注意，此值将传递给 ConfigParser.set，它支持使用 pyformat（例如 %(some_value)s）进行变量插值。因此，不属于插值符号一部分的原始百分号必须进行转义，例如 %%。给定值可以使用插值格式引用文件中已有的另一个值。

class alembic.config.MessagingOptions#
alembic.config.main(argv: Sequence[str] | None = None, prog: str | None = None, **kwargs: Any) → None#

Alembic 的控制台运行器函数。

目录