more docs + make bounds inclusive

Author: 3nids

docs/mkdocs.yml

@@ -11,7 +11,14 @@ theme:
     - navigation.tracking
 
 plugins:
-  - mkdocstrings
+  - mkdocstrings:
+      handlers:
+        python:
+          options:
+            show_signature: true
+            show_signature_annotations: true
+            separate_signature: true
+
 
 markdown_extensions:
   - admonition

pum/changelog.py

@@ -27,8 +27,8 @@ def __repr__(self):
 def last_version(
     config: PumConfig,
     dir: str | Path = ".",
-    after_version: str | None = None,
-    before_version: str | None = None,
+    min_version: str | None = None,
+    max_version: str | None = None,
 ) -> str | None:
     """
     Return the last version of the changelogs.
@@ -39,16 +39,19 @@ def last_version(
     Args:
         config (PumConfig): The configuration object.
         dir (str | Path): The directory where the changelogs are located.
-        after_version (str | None): The version to start from.
-        before_version (str | None): The version to end at.
+        min_version (str | None): The version to start from (inclusive).
+        max_version (str | None): The version to end at (inclusive).
+
+    Returns:
+        str | None: The last version of the changelogs. If no changelogs are found, None is returned.
     """
-    changelogs = list_changelogs(config, dir, after_version, before_version)
+    changelogs = list_changelogs(config, dir, min_version, max_version)
     if not changelogs:
         return None
-    if after_version:
-        changelogs = [c for c in changelogs if c.version > parse_version(after_version)]
-    if before_version:
-        changelogs = [c for c in changelogs if c.version < parse_version(before_version)]
+    if min_version:
+        changelogs = [c for c in changelogs if c.version >= parse_version(min_version)]
+    if max_version:
+        changelogs = [c for c in changelogs if c.version <= parse_version(max_version)]
     if not changelogs:
         return None
     return changelogs[-1].version
@@ -57,8 +60,8 @@ def last_version(
 def list_changelogs(
     config: PumConfig,
     dir: str | Path = ".",
-    after_version: str | None = None,
-    before_version: str | None = None,
+    min_version: str | None = None,
+    max_version: str | None = None,
 ) -> list:
     """
     Return a list of changelogs.
@@ -69,8 +72,11 @@ def list_changelogs(
     Args:
         config (PumConfig): The configuration object.
         dir (str | Path): The directory where the changelogs are located.
-        after_version (str | None): The version to start from.
-        before_version (str | None): The version to end at.
+        min_version (str | None): The version to start from (inclusive).
+        max_version (str | None): The version to end at (inclusive).
+
+    Returns:
+        list: A list of changelogs. Each changelog is represented by a Changelog object.
     """
     path = Path(dir)
     if not path.is_dir():
@@ -81,10 +87,10 @@ def list_changelogs(
 
     changelogs = [Changelog(path / d) for d in listdir(path) if isdir(join(path, d))]
 
-    if after_version:
-        changelogs = [c for c in changelogs if c.version > parse_version(after_version)]
-    if before_version:
-        changelogs = [c for c in changelogs if c.version < parse_version(before_version)]
+    if min_version:
+        changelogs = [c for c in changelogs if c.version >= parse_version(min_version)]
+    if max_version:
+        changelogs = [c for c in changelogs if c.version <= parse_version(max_version)]
 
     changelogs.sort(key=lambda c: c.version)
     return changelogs

pum/config.py

@@ -96,6 +96,13 @@ def parameter(self, name) -> MigrationParameterDefintion:
     def from_yaml(cls, file_path):
         """
         Create a PumConfig instance from a YAML file.
+        Args:
+            file_path (str): The path to the YAML file.
+        Returns:
+            PumConfig: An instance of the PumConfig class.
+        Raises:
+            FileNotFoundError: If the file does not exist.
+            yaml.YAMLError: If there is an error parsing the YAML file.
         """
 
         with open(file_path) as file:

test/test_changelog.py

@@ -33,36 +33,36 @@ def test_changelog(self):
         last_version_result = last_version(
             config=cfg,
             dir=str(Path("test") / "data" / "multiple_changelogs"),
-            after_version="1.2.3",
-            before_version="1.3.0",
+            min_version="1.2.4",
+            max_version="1.3.0",
         )
-        self.assertEqual(last_version_result, parse_version("1.2.4"))
+        self.assertEqual(last_version_result, parse_version("1.3.0"))
 
         last_version_result = last_version(
             config=cfg,
             dir=str(Path("test") / "data" / "multiple_changelogs"),
-            before_version="1.3.0",
+            max_version="1.3.0",
         )
-        self.assertEqual(last_version_result, parse_version("1.2.4"))
+        self.assertEqual(last_version_result, parse_version("1.3.0"))
 
         last_version_result = last_version(
             config=cfg,
             dir=str(Path("test") / "data" / "multiple_changelogs"),
-            before_version="1.2.3",
+            max_version="1.0.0",
         )
         self.assertIsNone(last_version_result)
 
         last_version_result = last_version(
             config=cfg,
             dir=str(Path("test") / "data" / "multiple_changelogs"),
-            after_version="1.2.3",
+            min_version="1.2.3",
         )
         self.assertEqual(last_version_result, parse_version("2.0.0"))
 
         last_version_result = last_version(
             config=cfg,
             dir=str(Path("test") / "data" / "multiple_changelogs"),
-            after_version="2.0.0",
+            min_version="2.1.0",
         )
         self.assertIsNone(last_version_result)
 

test/test_upgrader.py

@@ -44,13 +44,15 @@ def setUp(self):
         self.tmp = self.tmpdir.name
 
     def test_install_single_changelog(self):
+        test_dir = Path("test") / "data" / "single_changelog"
+        changelog_file = test_dir / "changelogs" / "1.2.3" / "create_northwind.sql"
         cfg = PumConfig()
         sm = SchemaMigrations(cfg)
         self.assertFalse(sm.exists(self.conn))
         upgrader = Upgrader(
             pg_service=self.pg_service,
             config=cfg,
-            dir=str(Path("test") / "data" / "single_changelog"),
+            dir=test_dir,
         )
         upgrader.install()
         self.assertTrue(sm.exists(self.conn))
@@ -59,24 +61,17 @@ def test_install_single_changelog(self):
         self.assertEqual(sm.migration_details(self.conn)["version"], "1.2.3")
         self.assertEqual(
             sm.migration_details(self.conn)["changelog_files"],
-            [
-                str(
-                    Path("test")
-                    / "data"
-                    / "single_changelog"
-                    / "changelogs"
-                    / "1.2.3"
-                    / "create_northwind.sql"
-                )
-            ],
+            [str(changelog_file)],
         )
 
     @unittest.skipIf(
         os.name == "nt" and os.getenv("CI") == "true",
         "Test not supported on Windows CI (postgis not installed)",
     )
     def test_parameters(self):
-        cfg = PumConfig.from_yaml(str(Path("test") / "data" / "parameters" / ".pum-config.yaml"))
+        test_dir = Path("test") / "data" / "parameters"
+        config_path = test_dir / ".pum-config.yaml"
+        cfg = PumConfig.from_yaml(str(config_path))
         self.assertEqual(
             cfg.parameters()["SRID"],
             MigrationParameterDefintion(
@@ -91,7 +86,7 @@ def test_parameters(self):
         upgrader = Upgrader(
             pg_service=self.pg_service,
             config=cfg,
-            dir=str(Path("test") / "data" / "parameters"),
+            dir=test_dir,
             parameters={"SRID": 2056},
         )
         upgrader.install()
@@ -102,53 +97,57 @@ def test_parameters(self):
         self.assertEqual(srid, 2056)
 
     def test_install_custom_directory(self):
-        cfg = PumConfig.from_yaml(
-            str(Path("test") / "data" / "custom_directory" / ".pum-config.yaml")
-        )
+        test_dir = Path("test") / "data" / "custom_directory"
+        config_path = test_dir / ".pum-config.yaml"
+        cfg = PumConfig.from_yaml(str(config_path))
         sm = SchemaMigrations(cfg)
         self.assertFalse(sm.exists(self.conn))
         upgrader = Upgrader(
             pg_service=self.pg_service,
             config=cfg,
-            dir=str(Path("test") / "data" / "custom_directory"),
+            dir=test_dir,
         )
         upgrader.install()
         self.assertTrue(sm.exists(self.conn))
 
     def test_install_custom_migration_table(self):
-        cfg = PumConfig.from_yaml(
-            str(Path("test") / "data" / "custom_migration_schema" / ".pum-config.yaml")
-        )
+        test_dir = Path("test") / "data" / "custom_migration_schema"
+        config_path = test_dir / ".pum-config.yaml"
+        cfg = PumConfig.from_yaml(str(config_path))
         sm = SchemaMigrations(cfg)
         self.assertFalse(sm.exists(self.conn))
         upgrader = Upgrader(
             pg_service=self.pg_service,
             config=cfg,
-            dir=str(Path("test") / "data" / "custom_migration_schema"),
+            dir=test_dir,
         )
         upgrader.install()
         self.assertTrue(sm.exists(self.conn))
 
     def test_install_complex_files_content(self):
+        complex_dir = Path("test") / "data" / "complex_files_content"
         cfg = PumConfig()
         sm = SchemaMigrations(cfg)
         self.assertFalse(sm.exists(self.conn))
         upgrader = Upgrader(
             pg_service=self.pg_service,
             config=cfg,
-            dir=str(Path("test") / "data" / "complex_files_content"),
+            dir=str(complex_dir),
         )
         upgrader.install()
         self.assertTrue(sm.exists(self.conn))
 
     def test_install_multiple_changelogs(self):
+        test_dir = Path("test") / "data" / "multiple_changelogs"
+        changelog_file_1 = test_dir / "changelogs" / "2.0.0" / "create_second_table.sql"
+        changelog_file_2 = test_dir / "changelogs" / "2.0.0" / "create_third_table.sql"
         cfg = PumConfig()
         sm = SchemaMigrations(cfg)
         self.assertFalse(sm.exists(self.conn))
         upgrader = Upgrader(
             pg_service=self.pg_service,
             config=cfg,
-            dir=str(Path("test") / "data" / "multiple_changelogs"),
+            dir=test_dir,
         )
         upgrader.install()
         self.assertTrue(sm.exists(self.conn))
@@ -160,35 +159,15 @@ def test_install_multiple_changelogs(self):
         self.assertEqual(sm.migration_details(self.conn)["version"], "2.0.0")
         self.assertEqual(
             sm.migration_details(self.conn)["changelog_files"],
-            [
-                str(
-                    Path("test")
-                    / "data"
-                    / "multiple_changelogs"
-                    / "changelogs"
-                    / "2.0.0"
-                    / "create_second_table.sql"
-                ),
-                str(
-                    Path("test")
-                    / "data"
-                    / "multiple_changelogs"
-                    / "changelogs"
-                    / "2.0.0"
-                    / "create_third_table.sql"
-                ),
-            ],
+            [str(changelog_file_1), str(changelog_file_2)],
         )
 
     def test_invalid_changelog(self):
+        test_dir = Path("test") / "data" / "invalid_changelog"
         cfg = PumConfig()
         sm = SchemaMigrations(cfg)
         self.assertFalse(sm.exists(self.conn))
-        upgrader = Upgrader(
-            pg_service=self.pg_service,
-            config=cfg,
-            dir=str(Path("test") / "data" / "invalid_changelog"),
-        )
+        upgrader = Upgrader(pg_service=self.pg_service, config=cfg, dir=test_dir)
         with self.assertRaises(Exception) as context:
             upgrader.install()
         self.assertTrue(