quick-ini 4.0__tar.gz → 4.3__tar.gz

{quick_ini-4.0/quick_ini.egg-info → quick_ini-4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quick_ini
-Version: 4.0
+Version: 4.3
 Summary: A library for reading from and writing to .ini formatted files
 Author-email: OllieZ-Mods <socksinthewash@gmail.com>
 License-Expression: MIT
@@ -38,7 +38,7 @@ pip install quick_ini
 ```python
 from quick_ini import QuickIni
 
-# Load from file
+# Load from file, before any get_value() or get_all() (those raise RuntimeError otherwise)
 QuickIni.load_file("config.ini")
 
 # Load from URL
@@ -82,7 +82,19 @@ if report and report["added"]:
     print("New settings added to config.ini:", ", ".join(report["added"]))
 ```
 
-The report also has `created`, `changed`, `orphaned` (settings kept that aren't in the template) and `backup`. Use `QuickIni.sync_template("config.ini")` to sync without loading.
+The report also has `created`, `changed`, `orphaned` (settings kept that aren't in the template), `backup` and `text` (the synced file). Use `QuickIni.sync_template("config.ini")` to sync without loading, and `dry_run=True` to work out the changes without writing anything.
+
+### From the command line
+
+Installing QuickINI adds a `quick-ini` command (or run `python -m quick_ini`), so you can sync without starting your program:
+
+```bash
+quick-ini sync                     # config.ini with config.ini.template
+quick-ini sync --dry-run           # show what would change as a diff, write nothing (--diff works too)
+quick-ini sync --config app.ini --template defaults.ini
+```
+
+`--config` defaults to `config.ini` and `--template` to `<config>.template`. Unlike `template=True`, a missing template is an error here. It prints the settings added and kept, and exits with 1 on any error.
 
 ## File Format
 

{quick_ini-4.0 → quick_ini-4.3}/README.md

@@ -13,7 +13,7 @@ pip install quick_ini
 ```python
 from quick_ini import QuickIni
 
-# Load from file
+# Load from file, before any get_value() or get_all() (those raise RuntimeError otherwise)
 QuickIni.load_file("config.ini")
 
 # Load from URL
@@ -57,7 +57,19 @@ if report and report["added"]:
     print("New settings added to config.ini:", ", ".join(report["added"]))
 ```
 
-The report also has `created`, `changed`, `orphaned` (settings kept that aren't in the template) and `backup`. Use `QuickIni.sync_template("config.ini")` to sync without loading.
+The report also has `created`, `changed`, `orphaned` (settings kept that aren't in the template), `backup` and `text` (the synced file). Use `QuickIni.sync_template("config.ini")` to sync without loading, and `dry_run=True` to work out the changes without writing anything.
+
+### From the command line
+
+Installing QuickINI adds a `quick-ini` command (or run `python -m quick_ini`), so you can sync without starting your program:
+
+```bash
+quick-ini sync                     # config.ini with config.ini.template
+quick-ini sync --dry-run           # show what would change as a diff, write nothing (--diff works too)
+quick-ini sync --config app.ini --template defaults.ini
+```
+
+`--config` defaults to `config.ini` and `--template` to `<config>.template`. Unlike `template=True`, a missing template is an error here. It prints the settings added and kept, and exits with 1 on any error.
 
 ## File Format
 

{quick_ini-4.0 → quick_ini-4.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "quick_ini"
-version = "4.0"
+version = "4.3"
 description = "A library for reading from and writing to .ini formatted files"
 readme = "README.md"
 license = "MIT"
@@ -25,6 +25,9 @@ classifiers = [
     "Typing :: Typed",
 ]
 
+[project.scripts]
+quick-ini = "quick_ini.__main__:main"
+
 [project.urls]
 Homepage = "https://github.com/olliez-mods/Quick-Ini"
 "Bug Reports" = "https://github.com/olliez-mods/Quick-Ini/issues"

quick_ini-4.3/quick_ini/__main__.py

@@ -0,0 +1,67 @@
+"""
+Command line: quick-ini sync [--config config.ini] [--template <config>.template] [--dry-run | --diff]
+\nAlso runs as "python -m quick_ini". Brings a config file up to date with its template, see QuickIni.sync_template().
+"""
+from .quick_ini import QuickIni
+import argparse
+import difflib
+import sys
+
+def sync(config:str, template:str | None, dry_run:bool) -> int:
+    # Unlike load_file(template=True), a missing template is an error here: on the command line it's a typo
+    template = template or f"{config}.template"
+    try:
+        with open(config, 'r', encoding='utf-8') as file:
+            old_text = file.read()
+    except FileNotFoundError:
+        old_text = ""
+    except IOError as e:
+        print(f"Error reading file: '{e}'", file=sys.stderr)
+        return 1
+
+    if(not QuickIni.sync_template(config, template, dry_run=dry_run)):
+        print(QuickIni.get_last_error(), file=sys.stderr)
+        return 1
+    report = QuickIni.get_sync_report()
+
+    if(dry_run and report["changed"]):
+        diff = difflib.unified_diff(old_text.splitlines(keepends=True), report["text"].splitlines(keepends=True),
+                                    config, f"{config} (synced)")
+        sys.stdout.writelines(diff)
+        print()
+
+    if(report["added"]):
+        print("Added from template:", ", ".join(report["added"]))
+    if(report["orphaned"]):
+        print("Kept at the end (not in template):", ", ".join(report["orphaned"]))
+
+    if(not report["changed"]):
+        print("Already in sync")
+    elif(dry_run):
+        print(f"Would create {config} from {template}" if report["created"] else "Dry run: nothing written")
+    elif(report["created"]):
+        print(f"Created {config} from {template}")
+    else:
+        print(f"Synced {config} (previous version: {report['backup']})")
+    return 0
+
+def main(argv:list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="quick-ini", description="Tools for .ini config files.")
+    commands = parser.add_subparsers(dest="command")
+    sync_parser = commands.add_parser("sync", help="bring a config file up to date with its template",
+                                      description="Bring a config file up to date with its template. Your values are "
+                                      "kept, new keys get the template's value, keys the template doesn't have are kept "
+                                      "at the end of their section. The previous version is saved as <config>.bak.")
+    sync_parser.add_argument("--config", default="config.ini", help="the config file (default: config.ini)")
+    sync_parser.add_argument("--template", help="the template (default: <config>.template)")
+    sync_parser.add_argument("--dry-run", "--diff", dest="dry_run", action="store_true",
+                             help="show the changes as a diff, write nothing")
+
+    args = parser.parse_args(argv)
+    if(args.command == "sync"):
+        return sync(args.config, args.template, args.dry_run)
+    parser.print_help()
+    return 1
+
+if __name__ == "__main__":
+    sys.exit(main())

{quick_ini-4.0 → quick_ini-4.3}/quick_ini/quick_ini.py

@@ -17,6 +17,7 @@ class QuickIni:
     error_message: str = ""
     web_file: str | None = None
     sync_report: dict[str, Any] | None = None
+    load_called: bool = False
 
     @staticmethod
     def grab_from_url(url:str, timeout:float = 10) -> bool:
@@ -159,7 +160,7 @@ class QuickIni:
             raise
 
     @staticmethod
-    def sync_template(file_location:str, template:bool | str = True) -> bool:
+    def sync_template(file_location:str, template:bool | str = True, dry_run:bool = False) -> bool:
         """
         Brings a config file up to date with its template, keeping the values already set in the config.
         \nThe template decides which keys exist, their order, sections and comments. Keys the config doesn't have yet get
@@ -170,6 +171,7 @@ class QuickIni:
             file_location (str): The path of the config file.
             template (bool | str): True to use "<config>.template", skipped quietly if it doesn't exist.
                 Or the path of the template file, which must exist.
+            dry_run (bool): Work out the synced file without writing it (or a backup). The report has it as "text".
         Returns:
             bool: True if successfull, False otherwise
         Example:
@@ -265,7 +267,7 @@ class QuickIni:
         changed = new_text != old_text
         backup = None
 
-        if(changed):
+        if(changed and not dry_run):
             try:
                 if(old_text is not None):
                     backup = f"{path}.bak"
@@ -281,6 +283,7 @@ class QuickIni:
             "added": added if old_text is not None else [],
             "orphaned": orphaned,
             "backup": backup,
+            "text": new_text,
         }
         return True
 
@@ -291,12 +294,12 @@ class QuickIni:
         Return:
             dict[str, Any]: "created" (bool) the config was made from the template, "changed" (bool) the config was rewritten,
                 "added" (list) keys taken from the template, "orphaned" (list) keys kept that aren't in the template,
-                "backup" (str | None) the path of the backup of the previous config
+                "backup" (str | None) the path of the backup of the previous config, "text" (str) the synced file
         Example:
             >>> load_file("config.ini", template=True)
                 True
             >>> get_sync_report()
-                {'created': False, 'changed': True, 'added': ['database.timeout'], 'orphaned': [], 'backup': '/app/config.ini.bak'}
+                {'created': False, 'changed': True, 'added': ['database.timeout'], 'orphaned': [], 'backup': '/app/config.ini.bak', 'text': '...'}
         """
         if(QuickIni.sync_report is None):
             return None
@@ -323,6 +326,8 @@ class QuickIni:
         """
         QuickIni.parsed_ini = {}
         QuickIni.auto_type_convert_g = auto_type_convert
+        # Set even if loading fails, the caller gets False and reading falls back to defaults
+        QuickIni.load_called = True
 
         if(not QuickIni.sync_template(file_location, template)):
             # sync_template sets the error message
@@ -411,6 +416,15 @@ class QuickIni:
         QuickIni.loaded_file_path=file_location
         return True
 
+    @staticmethod
+    def check_loaded(call:str) -> None:
+        """
+        Raises a RuntimeError if load_file() was never called, so settings aren't silently read as defaults.
+        """
+        if(not QuickIni.load_called):
+            QuickIni.error_message = f"QuickIni.{call} was called before QuickIni.load_file()"
+            raise(RuntimeError(QuickIni.error_message))
+
     @staticmethod
     def get_value(name:str, default:Any = None, expected_type:type | None = None, section:str | None = None) -> Any:
         """
@@ -423,6 +437,8 @@ class QuickIni:
             section (str): The [section] the setting is in, None for keys above any section
         Return:
             Any: The value associated with the name
+        Raises:
+            RuntimeError: If load_file() was never called
         Example:
             >>> get_value("do_debug_logs", False)
             True
@@ -431,6 +447,7 @@ class QuickIni:
         """
         if(section):
             name = f"{section}.{name}"
+        QuickIni.check_loaded(f"get_value({name!r})")
         value:Any = QuickIni.parsed_ini.get(name, default)
         if(expected_type != None):
             if(not isinstance(value, expected_type)):
@@ -446,10 +463,13 @@ class QuickIni:
             section (str): Only return the settings in this [section], with the section prefix removed
         Return:
             dict[str, Any]: The settings, keys in a section are given as "section.key" when no section is passed
+        Raises:
+            RuntimeError: If load_file() was never called
         Example:
             >>> get_all("database")
             {'host': 'localhost', 'port': 5432}
         """
+        QuickIni.check_loaded(f"get_all({section!r})" if section else "get_all()")
         if(not section):
             return dict(QuickIni.parsed_ini)
         prefix = f"{section}."

{quick_ini-4.0 → quick_ini-4.3/quick_ini.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quick_ini
-Version: 4.0
+Version: 4.3
 Summary: A library for reading from and writing to .ini formatted files
 Author-email: OllieZ-Mods <socksinthewash@gmail.com>
 License-Expression: MIT
@@ -38,7 +38,7 @@ pip install quick_ini
 ```python
 from quick_ini import QuickIni
 
-# Load from file
+# Load from file, before any get_value() or get_all() (those raise RuntimeError otherwise)
 QuickIni.load_file("config.ini")
 
 # Load from URL
@@ -82,7 +82,19 @@ if report and report["added"]:
     print("New settings added to config.ini:", ", ".join(report["added"]))
 ```
 
-The report also has `created`, `changed`, `orphaned` (settings kept that aren't in the template) and `backup`. Use `QuickIni.sync_template("config.ini")` to sync without loading.
+The report also has `created`, `changed`, `orphaned` (settings kept that aren't in the template), `backup` and `text` (the synced file). Use `QuickIni.sync_template("config.ini")` to sync without loading, and `dry_run=True` to work out the changes without writing anything.
+
+### From the command line
+
+Installing QuickINI adds a `quick-ini` command (or run `python -m quick_ini`), so you can sync without starting your program:
+
+```bash
+quick-ini sync                     # config.ini with config.ini.template
+quick-ini sync --dry-run           # show what would change as a diff, write nothing (--diff works too)
+quick-ini sync --config app.ini --template defaults.ini
+```
+
+`--config` defaults to `config.ini` and `--template` to `<config>.template`. Unlike `template=True`, a missing template is an error here. It prints the settings added and kept, and exits with 1 on any error.
 
 ## File Format
 

{quick_ini-4.0 → quick_ini-4.3}/quick_ini.egg-info/SOURCES.txt

@@ -2,10 +2,12 @@ LICENSE
 README.md
 pyproject.toml
 quick_ini/__init__.py
+quick_ini/__main__.py
 quick_ini/py.typed
 quick_ini/quick_ini.py
 quick_ini.egg-info/PKG-INFO
 quick_ini.egg-info/SOURCES.txt
 quick_ini.egg-info/dependency_links.txt
+quick_ini.egg-info/entry_points.txt
 quick_ini.egg-info/top_level.txt
 tests/test_quickini.py

quick_ini-4.3/quick_ini.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+quick-ini = quick_ini.__main__:main

{quick_ini-4.0 → quick_ini-4.3}/tests/test_quickini.py

@@ -8,6 +8,9 @@ import tempfile
 import os
 from unittest.mock import patch, mock_open
 from quick_ini import QuickIni
+from quick_ini import __main__ as cli
+from contextlib import redirect_stdout, redirect_stderr
+import io
 
 
 class TestQuickIni(unittest.TestCase):
@@ -16,6 +19,7 @@ class TestQuickIni(unittest.TestCase):
         """Set up test fixtures before each test method."""
         # Clear any previous state
         QuickIni.parsed_ini = {}
+        QuickIni.load_called = False
         QuickIni.loaded_file_path = None
         QuickIni.auto_type_convert_g = True
         QuickIni.error_message = ""
@@ -473,6 +477,7 @@ class TestQuickIniFormats(unittest.TestCase):
 
     def setUp(self):
         QuickIni.parsed_ini = {}
+        QuickIni.load_called = False
         QuickIni.loaded_file_path = None
         QuickIni.auto_type_convert_g = True
         QuickIni.error_message = ""
@@ -496,6 +501,30 @@ class TestQuickIniFormats(unittest.TestCase):
         with open(path, encoding='utf-8') as f:
             return f.read()
 
+    # ===== LOADING FIRST =====
+
+    def test_get_value_before_load_raises(self):
+        with self.assertRaises(RuntimeError):
+            QuickIni.get_value("port", 8080)
+        self.assertEqual(QuickIni.get_last_error(), "QuickIni.get_value('port') was called before QuickIni.load_file()")
+
+    def test_get_value_section_before_load_names_key(self):
+        with self.assertRaises(RuntimeError):
+            QuickIni.get_value("port", section="database")
+        self.assertIn("'database.port'", QuickIni.get_last_error())
+
+    def test_get_all_before_load_raises(self):
+        with self.assertRaises(RuntimeError):
+            QuickIni.get_all()
+        with self.assertRaises(RuntimeError):
+            QuickIni.get_all("database")
+        self.assertIn("get_all('database')", QuickIni.get_last_error())
+
+    def test_failed_load_falls_back_to_defaults(self):
+        self.assertFalse(QuickIni.load_file("/no/such/config.ini"))
+        self.assertEqual(QuickIni.get_value("port", 8080), 8080)
+        self.assertEqual(QuickIni.get_all(), {})
+
     # ===== PARSING =====
 
     def test_spaces_around_equals(self):
@@ -667,6 +696,7 @@ port = 5432
 
     def setUp(self):
         QuickIni.parsed_ini = {}
+        QuickIni.load_called = False
         QuickIni.loaded_file_path = None
         QuickIni.auto_type_convert_g = True
         QuickIni.error_message = ""
@@ -826,5 +856,102 @@ port = 6000
         self.assertFalse(any(name.endswith(".tmp") for name in os.listdir(self.dir.name)))
 
 
+
+class TestQuickIniCommandLine(unittest.TestCase):
+    """Tests for "quick-ini sync" (quick_ini/__main__.py), run from inside a temp folder for the default paths."""
+
+    # The template tests' setup and helpers, without running those tests again
+    TEMPLATE = TestQuickIniTemplate.TEMPLATE
+    write = TestQuickIniTemplate.write
+    read = TestQuickIniTemplate.read
+
+    def setUp(self):
+        TestQuickIniTemplate.setUp(self)
+        self.cwd = os.getcwd()
+        os.chdir(self.dir.name)
+
+    def tearDown(self):
+        os.chdir(self.cwd)
+        TestQuickIniTemplate.tearDown(self)
+
+    def run_cli(self, *args):
+        out, err = io.StringIO(), io.StringIO()
+        with redirect_stdout(out), redirect_stderr(err):
+            code = cli.main(list(args))
+        return code, out.getvalue(), err.getvalue()
+
+    def test_default_config_and_template(self):
+        self.write("config.ini.template", self.TEMPLATE)
+        self.write("config.ini", "debug = true\nold = 1\n")
+        code, out, _ = self.run_cli("sync")
+        self.assertEqual(code, 0)
+        self.assertIn("debug = true", self.read(self.config))
+        self.assertIn("name = MyApp", self.read(self.config))
+        self.assertIn("Added from template: name, parts, database.host, database.port", out)
+        self.assertIn("Kept at the end (not in template): old", out)
+        self.assertIn("previous version:", out)
+        self.assertEqual(self.read(self.config + ".bak"), "debug = true\nold = 1\n")
+
+    def test_config_and_template_given(self):
+        self.write("defaults.ini", self.TEMPLATE)
+        self.write("app.ini", "debug = true\n")
+        code, _, _ = self.run_cli("sync", "--config", "app.ini", "--template", "defaults.ini")
+        self.assertEqual(code, 0)
+        self.assertIn("name = MyApp", self.read(os.path.join(self.dir.name, "app.ini")))
+
+    def test_template_defaults_to_given_config(self):
+        self.write("app.ini.template", self.TEMPLATE)
+        self.write("app.ini", "debug = true\n")
+        code, _, _ = self.run_cli("sync", "--config", "app.ini")
+        self.assertEqual(code, 0)
+        self.assertIn("name = MyApp", self.read(os.path.join(self.dir.name, "app.ini")))
+
+    def test_dry_run_shows_diff_and_writes_nothing(self):
+        for flag in ("--dry-run", "--diff"):
+            self.write("config.ini.template", self.TEMPLATE)
+            self.write("config.ini", "debug = true\n")
+            code, out, _ = self.run_cli("sync", flag)
+            self.assertEqual(code, 0)
+            self.assertEqual(self.read(self.config), "debug = true\n")
+            self.assertFalse(os.path.exists(self.config + ".bak"))
+            self.assertIn("+++ config.ini (synced)", out)
+            self.assertIn("+name = MyApp", out)
+            self.assertIn("Dry run: nothing written", out)
+
+    def test_dry_run_does_not_create_config(self):
+        self.write("config.ini.template", self.TEMPLATE)
+        code, out, _ = self.run_cli("sync", "--dry-run")
+        self.assertEqual(code, 0)
+        self.assertFalse(os.path.exists(self.config))
+        self.assertIn("Would create config.ini from config.ini.template", out)
+
+    def test_missing_config_is_created(self):
+        self.write("config.ini.template", self.TEMPLATE)
+        code, out, _ = self.run_cli("sync")
+        self.assertEqual(code, 0)
+        self.assertEqual(self.read(self.config), self.TEMPLATE)
+        self.assertIn("Created config.ini from config.ini.template", out)
+
+    def test_already_in_sync(self):
+        self.write("config.ini.template", self.TEMPLATE)
+        self.write("config.ini", self.TEMPLATE)
+        code, out, _ = self.run_cli("sync", "--dry-run")
+        self.assertEqual(code, 0)
+        self.assertEqual(out.strip(), "Already in sync")
+
+    def test_missing_template_is_an_error(self):
+        self.write("config.ini", "debug = true\n")
+        code, out, err = self.run_cli("sync")
+        self.assertEqual(code, 1)
+        self.assertIn("Could not find template", err)
+        self.assertEqual(out, "")
+        self.assertEqual(self.read(self.config), "debug = true\n")
+
+    def test_no_command_prints_help(self):
+        code, out, _ = self.run_cli()
+        self.assertEqual(code, 1)
+        self.assertIn("sync", out)
+
+
 if __name__ == '__main__':
     unittest.main()