from . import command
from . import util
from .util import compat
+from .util.pyfiles import _preserving_path_as_str
class Config:
attributes: Optional[Dict[str, Any]] = None,
) -> None:
"""Construct a new :class:`.Config`"""
- self.config_file_name = file_
- self.toml_file_name = toml_file
+ self.config_file_name = (
+ _preserving_path_as_str(file_) if file_ else None
+ )
+ self.toml_file_name = (
+ _preserving_path_as_str(toml_file) if toml_file else None
+ )
self.config_ini_section = ini_section
self.output_buffer = output_buffer
self.stdout = stdout
"""
- config_file_name: Union[str, os.PathLike[str], None] = None
+ config_file_name: Optional[str] = None
"""Filesystem path to the .ini file in use."""
- toml_file_name: Union[str, os.PathLike[str], None] = None
+ toml_file_name: Optional[str] = None
"""Filesystem path to the pyproject.toml file in use.
.. versionadded:: 1.16.0
+ul.simple p {
+ margin-bottom: 1.15rem;
+}
\ No newline at end of file
"feature",
"usecase",
"bug",
+ "refactored",
"moved",
"removed",
]
:tags: feature, environment
:tickets: 1082
- Added optional :pep:`621` support to Alembic, where a subset of the
- project-centric configuration normally found in the ``alembic.ini`` file
- can now be retrieved from the project-wide ``pyproject.toml`` file. A new
- init template ``pyproject`` is added which illustrates a basic :pep:`621`
- setup. The :pep:`621` feature supports configuration values that are
- relevant to code locations and code production only; it does not
- accommodate database connectivity, configuration, or logging configuration.
- These latter configurational elements remain as elements that can be
- present either in the ``alembic.ini`` file, or retrieved elsewhere within
- the ``env.py`` file. The change also allows the ``alembic.ini`` file to
- be completely optional if the ``pyproject.toml`` file contains a base
- alembic configuration section.
+ Added optional :pep:`621` support to Alembic, allowing all source code
+ related configuration (e.g. local file paths, post write hook
+ configurations, etc) to be configured in the project's ``pyproject.toml``
+ file. A new init template ``pyproject`` is added which illustrates a
+ basic :pep:`621` setup.
+
+ Besides being better integrated with a Python project's existing source
+ code configuration, the TOML format allows for more flexible structures,
+ allowing configuration items like ``version_locations`` and
+ ``prepend_sys_path`` to be configured as lists of path strings without the
+ need for path separator characters used by ``ConfigParser`` format. The
+ feature continues to support the ``%(here)s`` token which can substitute
+ the absolute parent directory of the ``pyproject.toml`` file when
+ consumed.
+
+ The :pep:`621` feature supports configuration values that are relevant to
+ source code organization and generation only; it does not accommodate
+ configuration of database connectivity or logging, which remain under the
+ category of "deployment" configuration and continue to be part of
+ ``alembic.ini``, or whatever configurational method is established by the
+ ``env.py`` file. Using the combination of ``pyproject.toml`` for source
+ code configuration along with a custom database/logging configuration
+ method established in ``env.py`` will allow the ``alembic.ini`` file to be
+ omitted altogether.
.. seealso::
.. change::
- :tags: bug, environment
+ :tags: usecase, environment
:tickets: 1330
- Added new option to the ConfigParser config (typically via ``alembic.ini``)
- ``path_separator``. This new option supersedes the previous similar
- option ``version_path_separator``. The new ``path_separator`` option
- applies to the path splitting mechanism of both the ``version_locations``
- option as well as the ``prepend_sys_path`` option, and in newly
- rendered ``alembic.ini`` files will use the value ``os``, which means to
- use the operating system path separator when splitting these string values
- into a list of paths.
+ Added new option to the ConfigParser (e.g. ``alembic.ini``) configuration
+ ``path_separator``, which supersedes the existing ``version_path_separator``
+ option. ``path_separator`` specifies the path separator character that
+ will be recognized for both the ``version_locations`` option as well
+ as the ``prepend_sys_path`` option, defaulting to ``os`` which indicates
+ that the value of ``os.pathsep`` should be used.
The new attribute applies necessary os-dependent path splitting to the
``prepend_sys_path`` option so that windows paths which contain drive
letters with colons are not inadvertently split, whereas previously
- os-dependent path splitting were only available for the
- ``version_locations`` option.
+ os-dependent path splitting were only available for the ``version_locations`` option.
- Existing installations that do not have ``path_separator`` present
- will continue to make use of ``version_path_separator`` when parsing the
- ``version_locations`` option, or splitting on spaces / commas if
- ``version_path_separator`` is also not present. ``prepend_sys_path`` will
- continue to be split on spaces/commas/colons if ``path_separator`` is
- not present. Under all of these fallback conditions, a deprecation
- warning is now emitted encouraging to set ``path_separator``.
+ Existing installations that don't indicate ``path_separator``
+ will continue to use the older behavior, where ``version_path_separator``
+ may be configured for ``version_locations``, and ``prepend_sys_path``
+ continues to be split on spaces/commas/colons. A deprecation warning
+ is emitted for these fallback scenarios.
+
+ When using the new ``pyproject.toml`` configuration detailed at
+ :ref:`using_pep_621`, the whole issue of "path separators" is sidestepped
+ and parameters like ``path_separator`` are unnecessary, as the TOML based
+ configuration configures version locations and sys path elements as
+ lists.
Pull request courtesy Mike Werezak.
\ No newline at end of file
.. change::
- :tags: usecase, commands
+ :tags: feature, commands
:tickets: 1610
Added new :meth:`.CommandLine.register_command` method to
.. change::
- :tags: usecase, autogenerate, postgresql
+ :tags: usecase, operations
:tickets: 1626
Added :paramref:`.Operations.add_column.if_not_exists` and
for ``ADD COLUMN`` and ``DROP COLUMN`` operations, a feature available on
some database backends such as PostgreSQL, MariaDB, as well as third party
backends. The parameters also support autogenerate rendering allowing them
- to be turned on via a custom :class:`.Rewriter`. Pull request courtesy of
- Louis-Amaury Chaib (@lachaib).
\ No newline at end of file
+ to be added to autogenerate scripts via a custom :class:`.Rewriter`. Pull
+ request courtesy of Louis-Amaury Chaib (@lachaib).
\ No newline at end of file
:tags: bug, general
:tickets: 1637
- The pyproject.toml configuration has been amended to use the updated
- :pep:`639` configuration for license, which eliminates loud deprecation
- warnings when building the package. Note this necessarily bumps
- setuptools build requirement to 77.0.3.
+ The ``pyproject.toml`` file used by the Alembic project itself for its
+ Python package configuration has been amended to use the updated :pep:`639`
+ configuration for license, which eliminates loud deprecation warnings when
+ building the package. Note this necessarily bumps setuptools build
+ requirement to 77.0.3.
:tickets: 1650
Added :paramref:`.Operations.drop_constraint.if_exists` parameter to
- :meth:`.Operations.drop_constraint` which will render "DROP CONSTRAINT IF
- EXISTS". The parameter also supports autogenerate rendering allowing them
- to be turned on via a custom :class:`.Rewriter`. Pull request courtesy
- Aaron Griffin.
+ :meth:`.Operations.drop_constraint` which will render ``DROP CONSTRAINT IF
+ EXISTS``. The parameter also supports autogenerate rendering allowing it to
+ be added to autogenerate scripts via a custom :class:`.Rewriter`. Pull
+ request courtesy Aaron Griffin.
.. change::
- :tags: bug, operations
+ :tags: bug, autogenerate
:tickets: 1656
- The ExecuteSQLOp now takes into account the value configured
- in :paramref:`configure.alembic_module_prefix` instead of always
- defaulting to ``op.``.
- Pull request curtesy of Avery Fischer.
+ The :meth:`.Operations.execute` operation when rendered in autogenerate
+ (which would necessarily be only when using a custom writer that embeds
+ :class:`.ExecuteSQLOp`) now correctly takes into account the value
+ configured in :paramref:`configure.alembic_module_prefix` when rendering
+ the operation with its prefixing namespace; previously this was hardcoded
+ to ``op.``. Pull request courtesy Avery Fischer.
.. change::
- :tags: change, environment
+ :tags: refactored, environment
The command, config and script modules now rely on ``pathlib.Path`` for
- internal path manipulations, instead of ``os.path()`` operations. Public
- API functions that accept string directories and filenames continue to do
- so but also accept ``os.PathLike`` objects. Public API functions and
- accessors that return paths as strings continue to do so. Private API
- functions and accessors, i.e. all those that are prefixed with an
- underscore, may now return a Path object rather than a string to indicate
- file paths.
+ internal path manipulations, instead of ``os.path()`` operations. This
+ has some impact on both public and private (i.e. underscored) API functions:
+
+ * Public API functions that accept parameters indicating file and directory
+ paths as strings will continue to do so, but now will also accept
+ ``os.PathLike`` objects as well.
+ * Public API functions and accessors that return directory paths as strings
+ such as :attr:`.ScriptDirectory.dir`, :attr:`.Config.config_file_name`
+ will continue to do so.
+ * Private API functions and accessors, i.e. all those that are prefixed
+ with an underscore, that previously returned directory paths as
+ strings may now return a Path object instead.
projects / thirdparty / sqlalchemy / alembic.git / commitdiff
