From: Mike Bayer Date: Wed, 21 May 2025 03:40:33 +0000 (-0400) Subject: more tweaks X-Git-Tag: rel_1_16_0~5 X-Git-Url: http://git.ipfire.org/gitweb/gitweb.cgi?a=commitdiff_plain;h=722e500c339876766c5eed70ef0f5bc2fff8c55c;p=thirdparty%2Fsqlalchemy%2Falembic.git more tweaks this is primarily cleanup of the changelog section which is extensive for this release. Additionally, limited Config.config_file_name and Config.toml_file_name to string only when accessed, making use of _preserving_path_as_str() for these on the parameter side. Change-Id: I9bec7bdc7fcaa79efeccb5e6f584be3f328499f2 --- diff --git a/alembic/config.py b/alembic/config.py index c63f0aed..eb98bcdf 100644 --- a/alembic/config.py +++ b/alembic/config.py @@ -25,6 +25,7 @@ from . import __version__ from . import command from . import util from .util import compat +from .util.pyfiles import _preserving_path_as_str class Config: @@ -113,8 +114,12 @@ 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 @@ -136,10 +141,10 @@ class Config: """ - 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 diff --git a/docs/build/_static/site_custom_css.css b/docs/build/_static/site_custom_css.css index e69de29b..8194030b 100644 --- a/docs/build/_static/site_custom_css.css +++ b/docs/build/_static/site_custom_css.css @@ -0,0 +1,3 @@ +ul.simple p { + margin-bottom: 1.15rem; +} \ No newline at end of file diff --git a/docs/build/conf.py b/docs/build/conf.py index 8b403072..c8c9e763 100644 --- a/docs/build/conf.py +++ b/docs/build/conf.py @@ -57,6 +57,7 @@ changelog_sections = [ "feature", "usecase", "bug", + "refactored", "moved", "removed", ] diff --git a/docs/build/unreleased/1082.rst b/docs/build/unreleased/1082.rst index 8b58c5e8..244f3e8f 100644 --- a/docs/build/unreleased/1082.rst +++ b/docs/build/unreleased/1082.rst @@ -2,18 +2,30 @@ :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:: diff --git a/docs/build/unreleased/1330.rst b/docs/build/unreleased/1330.rst index 736149fd..c426b0fa 100644 --- a/docs/build/unreleased/1330.rst +++ b/docs/build/unreleased/1330.rst @@ -1,28 +1,29 @@ .. 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 diff --git a/docs/build/unreleased/1610.rst b/docs/build/unreleased/1610.rst index b6f37d09..73e0fe16 100644 --- a/docs/build/unreleased/1610.rst +++ b/docs/build/unreleased/1610.rst @@ -1,5 +1,5 @@ .. change:: - :tags: usecase, commands + :tags: feature, commands :tickets: 1610 Added new :meth:`.CommandLine.register_command` method to diff --git a/docs/build/unreleased/1626.rst b/docs/build/unreleased/1626.rst index 664e1958..6bb0e9e2 100644 --- a/docs/build/unreleased/1626.rst +++ b/docs/build/unreleased/1626.rst @@ -1,5 +1,5 @@ .. change:: - :tags: usecase, autogenerate, postgresql + :tags: usecase, operations :tickets: 1626 Added :paramref:`.Operations.add_column.if_not_exists` and @@ -7,5 +7,5 @@ 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 diff --git a/docs/build/unreleased/1637.rst b/docs/build/unreleased/1637.rst index 08ddf60b..059a59a4 100644 --- a/docs/build/unreleased/1637.rst +++ b/docs/build/unreleased/1637.rst @@ -2,7 +2,8 @@ :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. diff --git a/docs/build/unreleased/1650.rst b/docs/build/unreleased/1650.rst index 7e1bc379..29ac2de0 100644 --- a/docs/build/unreleased/1650.rst +++ b/docs/build/unreleased/1650.rst @@ -3,7 +3,7 @@ :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. diff --git a/docs/build/unreleased/1656.rst b/docs/build/unreleased/1656.rst index 3680aa72..040a3848 100644 --- a/docs/build/unreleased/1656.rst +++ b/docs/build/unreleased/1656.rst @@ -1,8 +1,10 @@ .. 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. diff --git a/docs/build/unreleased/pathlib.rst b/docs/build/unreleased/pathlib.rst index 1c547b85..dc29a988 100644 --- a/docs/build/unreleased/pathlib.rst +++ b/docs/build/unreleased/pathlib.rst @@ -1,11 +1,16 @@ .. 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.