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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quick_ini
-Version: 4.1
+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
@@ -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.1 → quick_ini-4.3}/README.md

@@ -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.1 → quick_ini-4.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "quick_ini"
-version = "4.1"
+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.1 → quick_ini-4.3}/quick_ini/quick_ini.py

@@ -160,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
@@ -171,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:
@@ -266,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"
@@ -282,6 +283,7 @@ class QuickIni:
             "added": added if old_text is not None else [],
             "orphaned": orphaned,
             "backup": backup,
+            "text": new_text,
         }
         return True
 
@@ -292,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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quick_ini
-Version: 4.1
+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
@@ -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.1 → 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.1 → 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):
@@ -853,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()