pylembic 0.2.0__py3-none-any.whl

pylembic/__init__.py

@@ -0,0 +1,4 @@
+"""Package configuration"""
+
+__author__ = "Marco Espinosa"
+__email__ = "marco@marcoespinosa.com"

pylembic/cli.py

@@ -0,0 +1,46 @@
+import typer
+
+from pylembic.migrations import Validator
+
+app = typer.Typer(
+    help="pylembic CLI for validating and visualizing Alembic migrations."
+)
+
+
+@app.command()
+def main(
+    migrations_path: str = typer.Argument(..., help="Path to the migrations folder."),
+    validate: bool = typer.Option(False, "--validate", help="Validate the migrations."),
+    show_graph: bool = typer.Option(
+        False, "--show-graph", help="Visualize the migration dependency graph."
+    ),
+    verbose: bool = typer.Option(
+        False, "--verbose", help="Show migrations validation logs."
+    ),
+):
+    """
+    Main command to validate and/or visualize migrations.
+    """
+    typer.echo(f"Processing migrations in: {migrations_path}")
+    validator = Validator(migrations_path)
+
+    if verbose:
+        typer.echo("Verbose mode enabled.")
+
+    if validate:
+        typer.echo("Validating migrations...")
+        if validator.validate():
+            typer.secho("Migrations validation passed!", fg=typer.colors.GREEN)
+        else:
+            typer.secho("Migrations validation failed!", fg=typer.colors.RED)
+
+    if show_graph:
+        typer.echo("Visualizing migration graph...")
+        validator.show_graph()
+
+    if not validate and not show_graph:
+        typer.echo("No action specified. Use --help for more information.")
+
+
+if __name__ == "__main__":
+    app()

pylembic/exceptions.py

@@ -0,0 +1,8 @@
+class CircularDependencyError(Exception):
+    """Raised when a circular dependency is detected in the migration graph.
+
+    Original exception is CommandError from Alembic util module. This exception
+    is created for readability.
+    """
+
+    pass

pylembic/formatter.py

@@ -0,0 +1,15 @@
+from logging import Formatter
+
+
+class CustomFormatter(Formatter):
+    """Custom formatter that handles missing fields gracefully."""
+
+    params = ["orphans", "dependency", "migration", "heads", "bases"]
+
+    def format(self, record):
+        """Format the log record with default values for missing fields."""
+        for param in self.params:
+            if not hasattr(record, param):
+                setattr(record, param, "")
+
+        return super().format(record)

pylembic/logger.py

@@ -0,0 +1,30 @@
+import logging
+
+from pylembic.formatter import CustomFormatter
+
+
+def configure_logger(verbose: bool = False):
+    """Configure the logger with a custom formatter and verbosity level.
+
+    Args:
+        verbose (bool): Whether to enable verbose logging.
+
+    Returns:
+        logging.Logger: The configured logger.
+    """
+    logger = logging.getLogger()
+
+    if not verbose:
+        logger.setLevel(logging.CRITICAL + 1)
+        return logger
+
+    logger.setLevel(logging.INFO)
+    handler = logging.StreamHandler()
+    formatter = CustomFormatter(
+        "%(levelname)s\t %(asctime)s | %(message)s | %(migration)s"
+        "%(dependency)s%(orphans)s%(heads)s%(bases)s",
+        datefmt="%d %b %Y | %H:%M:%S",
+    )
+    handler.setFormatter(formatter)
+    logger.addHandler(handler)
+    return logger

pylembic/migrations.py

@@ -0,0 +1,152 @@
+import os
+
+import matplotlib.pyplot as plt
+import networkx as nx
+from alembic.config import Config
+from alembic.script import ScriptDirectory
+from alembic.util import CommandError
+
+from pylembic.exceptions import CircularDependencyError
+from pylembic.logger import configure_logger
+
+
+logger = configure_logger()
+
+
+class Validator:
+    """This class provides methods to validate Alembic migrations for linearity,
+    missing nodes, and circular dependencies.
+
+    Here is a summary of the checks performed:
+        - Linearity: Ensures a clean and predictable migration chain.
+        - Circular dependencies: Prevents migration failures due to loops in the
+        dependency chain.
+        - Disconnected roots: Identifies migrations improperly created without linking
+        to the base.
+        - Disconnected leaves: Flags migrations that are improperly disconnected from
+        subsequent migrations.
+        - Multiple roots/heads: Warns about unintentional forks or branching.
+        - Graph visualization: Provides a visual way to catch anomalies and understand
+        migration flow.
+    """
+
+    ALEMBIC_CONFIG_FILE = "alembic.ini"
+
+    def __init__(
+        self, alembic_config_path: str, alembic_config_file: str = None
+    ) -> None:
+        if not os.path.exists(alembic_config_path):
+            raise FileNotFoundError(f"Path '{alembic_config_path}' does not exist!")
+
+        self.alembic_config_path = alembic_config_path
+        self.alembic_config_file = alembic_config_file or self.ALEMBIC_CONFIG_FILE
+        self.graph = nx.DiGraph()
+        self.verbose = False
+        self.script: ScriptDirectory = None
+
+        # Load the Alembic configuration
+        self._load_alembic_config()
+
+        # Build the migration graph
+        self._build_graph()
+
+    def _load_alembic_config(self) -> None:
+        """Loads the Alembic configuration file and initializes the script directory."""
+        alembic_config = Config(
+            os.path.join(self.alembic_config_path, self.alembic_config_file)
+        )
+        alembic_config.set_main_option("script_location", self.alembic_config_path)
+        self.script = ScriptDirectory.from_config(alembic_config)
+
+    def _build_graph(self) -> None:
+        """Builds a directed graph of migrations."""
+        graph = nx.DiGraph()
+        try:
+            for revision in self.script.walk_revisions():
+                graph.add_node(revision.revision)
+                if revision.down_revision:
+                    if isinstance(revision.down_revision, tuple):
+                        # Handle branching migrations
+                        for down_rev in revision.down_revision:
+                            graph.add_edge(revision.revision, down_rev)
+                    else:
+                        graph.add_edge(revision.revision, revision.down_revision)
+        except CommandError as exc:
+            raise CircularDependencyError(str(exc)) from exc
+
+        self.graph = graph
+
+    def _orphans(self) -> bool:
+        """
+        Checks for orphan migrations in the Alembic script directory.
+        As the orphan migrations are not connected to the migration graph, they are
+        considered as a valid base and head.
+
+        Returns:
+            bool: True if orphan migrations are found.
+        """
+        bases = set(self.script.get_bases())
+        heads = set(self.script.get_heads())
+        orphans = bases.intersection(heads)
+        if orphans:
+            logger.warning("Orphan migrations detected.", extra={"orphans": orphans})
+            return True
+
+        logger.info("No orphan migrations detected.")
+        return False
+
+    def _multiple_bases_or_heads(self) -> bool:
+        """
+        Checks if there are multiple bases or heads in the migration graph.
+
+        Returns:
+            bool: True if multiple bases or heads are found.
+        """
+        bases = set(self.script.get_bases())
+        if len(bases) > 1:
+            logger.info("Multiple bases detected", extra={"bases": bases})
+            return True
+
+        heads = set(self.script.get_heads())
+        if len(heads) > 1:
+            logger.info("Multiple heads detected", extra={"heads": heads})
+            return True
+
+        return False
+
+    def validate(self, verbose: bool = False) -> bool:
+        """This method validates the Alembic migrations for linearity and missing nodes.
+
+        Args:
+            verbose (bool): If True, the logger verbosity is increased.
+
+        Returns:
+            bool: True if the migrations are valid.
+        """
+        # Reconfigure the logger verbosity
+        logger = configure_logger(verbose)  # noqa F841
+
+        # Perform validation checks within the graph
+        return not (self._orphans() or self._multiple_bases_or_heads())
+
+    def show_graph(self) -> None:
+        """
+        Visualizes the migration dependency graph.
+        """
+        plt.figure(figsize=(12, 8))
+        pos = nx.spring_layout(self.graph)
+        labels = {node: f"{node[:8]}" for node in self.graph.nodes}  # Short revision ID
+        nx.draw(
+            self.graph,
+            pos,
+            labels=labels,
+            node_size=3000,
+            node_color="lightblue",
+            font_size=10,
+            font_weight="bold",
+            label="Alembic Migration Graph",
+        )
+        # Set the custom window title
+        manager = plt.get_current_fig_manager()
+        manager.set_window_title("Alembic Migration Dependency Graph")
+        plt.show()

pylembic-0.2.0.dist-info/METADATA

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: pylembic
+Version: 0.2.0
+Summary: This package provides validation for Alembic migrations.
+Author-email: Marco Espinosa <marco@marcoespinosa.com>
+License: MIT License
+        
+        Copyright (c) 2024 Marco Espinosa
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: alembic>=1.14.0
+Requires-Dist: matplotlib>=3.10.0
+Requires-Dist: networkx>=3.4.2
+Requires-Dist: typer>=0.15.1
+Description-Content-Type: text/markdown
+
+<!-- Shields -->
+<p align="center">
+<a href="https://github.com/maekind/pylembic"><img src="https://img.shields.io/github/actions/workflow/status/maekind/pylembic/.github%2Fworkflows%2Ftesting.yml?label=tests&color=green" hspace="5"></a>
+<a href="https://codecov.io/gh/maekind/pylembic"><img src="https://codecov.io/gh/maekind/pylembic/graph/badge.svg?token=JcGna50uJL" hspace="5"/>
+ </a>
+<a href="https://github.com/maekind/pylembic/releases"><img src="https://img.shields.io/github/actions/workflow/status/maekind/pylembic/.github%2Fworkflows%2Frelease.yml?label=package&color=green" hspace="5"></a>
+<a href="https://pypi.org/project/pylembic"><img src="https://img.shields.io/github/v/release/maekind/pylembic?color=blue&label=pypi latest" hspace="5"></a>
+<br>
+<a href="https://github.com/maekind/kairo/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-orange.svg" hspace="5"></a>
+<a href="https://github.com/maekind/kairo"><img src="https://img.shields.io/github/repo-size/maekind/pylembic?color=red" hspace="5"></a>
+<a href="https://github.com/maekind/pylembic"><img src="https://img.shields.io/github/last-commit/maekind/pylembic?color=black" hspace="5"></a>
+<a href="https://www.python.org/downloads/"><img src="https://img.shields.io/github/languages/top/maekind/pylembic?color=darkgreen" hspace="5"></a>
+<a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python%20version-%3E3.11-lightblue" hspace="5"></a>
+</p>
+
+# pylembic
+
+## Description
+
+This package provides validation of Alembic migrations for Python projects.
+
+It will check:
+
+- Linearity: Ensures a clean and predictable migration chain.
+- Circular dependencies: Prevents migration failures due to loops in the
+dependency chain.
+- Orphan migrations: Identifies migrations improperly created without linking
+to any other migration.
+- Multiple bases/heads: Identifies multiple bases or heads in the migration graph.
+- Graph visualization: Provides a visual way to catch anomalies and understand the
+migration flow.
+
+## Installation
+
+You can install this package using pip:
+
+```bash
+pip install pylembic
+```
+
+## Usage
+
+### Testing
+
+You can use this module with your preferred testing framework as follows:
+
+```python
+from os import path
+
+from pytest import fixture
+
+from pylembic.migrations import Validator
+
+
+@fixture
+def with_alembic_config_path():
+    # We assume the migrations folder is at the root of the project,
+    # and this test file is in the tests folder, also at the root of the project.
+    # TODO: Feel free to adjust the path to your project's migrations folder.
+    return path.abspath(
+        path.join(path.dirname(path.dirname(__file__)), "migrations")
+    )
+
+
+def test_migrations(with_alembic_config_path):
+    migration_validator = Validator(with_alembic_config_path)
+    assert migration_validator.validate()
+```
+
+### Visualizing the migration graph
+
+You can show the migrations graph by calling the method `show_graph`:
+
+```python
+
+from os import path
+
+from pylembic.migrations import Validator
+
+alembic_config_path = path.abspath(path.join("your path", "migrations"))
+
+migration_validator = Validator(alembic_config_path)
+
+migration_validator.show_graph()
+```
+
+### Command line
+
+You can also use the command line for:
+
+- Validating migrations:
+
+    ```bash
+    pylembic ./path/to/migrations --validate
+    ```
+
+- Visualizing the migration graph:
+
+    ```bash
+    pylembic ./path/to/migrations --show-graph
+    ```
+
+(c) 2024, <a href="mailto:marco@marcoespinosa.com">Marco Espinosa</a>

pylembic-0.2.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+pylembic/__init__.py,sha256=mxZWJyh9P5VqsH8lnghUoFt9VTuP869lvvcujmIGadI,97
+pylembic/cli.py,sha256=Fg4hX7sB9Y8VKRm2zfduO40r5fpVCYfY9nNWzitcZcE,1363
+pylembic/exceptions.py,sha256=-By4dH3X9z4Pyyg-pQCzNBsAvq5piu3KwyoMT2AUQcA,250
+pylembic/formatter.py,sha256=6WJfPrO7UXj3rJTIeLlGRI3sJJFScgh0U_fStS3JY9A,470
+pylembic/logger.py,sha256=x3MIP-mKc7nGSQiVri2ZhoTjw857pHGOd8Fi7vNbItI,803
+pylembic/migrations.py,sha256=_VWBKMxS_5fWn4SDJsiRroE2Z7Vufp6BoLcscQ0wvZs,5471
+pylembic-0.2.0.dist-info/METADATA,sha256=LzcVlqiSK6cKGdPLA73RJ2lJ2EBwv1sETzM5pTlIdqE,5153
+pylembic-0.2.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+pylembic-0.2.0.dist-info/entry_points.txt,sha256=Ta6Ra5zsE9KGAfvAbRMdvceIgqQ09b_FWh6UDhAqF34,46
+pylembic-0.2.0.dist-info/licenses/LICENSE,sha256=tN1cVPGIuSLIoeLQZ3LJFMdEAFQ1BluFCO8kvCGQKlA,1070
+pylembic-0.2.0.dist-info/RECORD,,

pylembic-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pylembic-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pylembic = pylembic.cli:app

pylembic-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Marco Espinosa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.