braveprefs 0.1.0__tar.gz

braveprefs-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+.venv/

braveprefs-0.1.0/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.0
+
+First release.
+
+- `export` reads an allowlist of named settings from a browser profile and writes one JSON file.
+- `diff` compares two exported files.
+- `import` writes the restorable settings back, dry run by default, with a timestamped copy of the
+  original file and a check for a singleton lock.
+- Settings the browser protects with an authenticator are exported read only and never written.
+- No dependencies outside the Python standard library.

braveprefs-0.1.0/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Younes Z.
+
+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.

braveprefs-0.1.0/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.5
+Name: braveprefs
+Version: 0.1.0
+Summary: Export, compare and restore browser profile settings as one small readable JSON file.
+Project-URL: Homepage, https://github.com/Rezarys/braveprefs
+Project-URL: Source, https://github.com/Rezarys/braveprefs
+Author: Younes Z.
+License: MIT
+License-File: LICENSE
+Keywords: backup,browser,chromium,cli,configuration,dotfiles,migration,preferences,profile,restore,settings
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# braveprefs
+
+```
+pip install braveprefs
+```
+
+Put your browser settings in one short JSON file, compare that file between two machines, and write it back on a fresh install. No sync account, no QR code, no network.
+
+This project is not affiliated with Brave Software or with any browser publisher. It reads and writes files on your own disk and nothing else.
+
+## Why
+
+Today the way to move your settings to a new machine is to copy the whole profile directory, several gigabytes of caches and databases, to recover a few kilobytes of choices. The rest of that directory does not restore cleanly anyway. `braveprefs` takes the few kilobytes.
+
+The output is a file you can read, keep in a git repository, and diff.
+
+## Use
+
+Find your profile directory first (see below), then:
+
+```
+braveprefs export "<profile directory>" -o settings.json
+braveprefs diff settings.json other-machine.json
+braveprefs import "<profile directory>" settings.json
+```
+
+`import` is a dry run by default: it prints what it would change and writes nothing. Add `--apply` to write, with the browser closed:
+
+```
+braveprefs import "<profile directory>" settings.json --apply
+```
+
+Before writing, it copies the original `Preferences` file next to itself with a timestamp, so you can always put it back. If a `SingletonLock` file is present, the browser may still be running and the command stops; close the browser, or pass `--force` if you know the lock is stale.
+
+`diff` exits with status 1 when the two files differ and 0 when they match, so it fits in a script.
+
+## What never leaves your profile
+
+The list of settings this tool touches is a list of named keys, written out one by one in `src/braveprefs/keys.py`. It is not a name pattern. A key that is not named there is never read and never written. Concretely, none of this is ever in the exported file:
+
+- passwords, cookies, tokens, session state
+- browsing history, downloads history, visited sites
+- wallet data, payment methods, or any encrypted store
+- your extensions and their data, except the id of your current theme, which is technically an extension in this browser
+- account identifiers and anything the browser uses to sign you in
+
+The exported file is plain text on purpose. Open it and read it.
+
+Two settings in the list are folder paths, the download folder and the save as folder, and a folder path can contain your account name. When either is present the exported file says so in its `notes` field. Read the file before you share it. A folder path that exists on one machine may not exist on another, especially across operating systems; import writes it anyway, so check it still makes sense before you apply it.
+
+## Settings the browser protects, and what this tool does about them
+
+Some settings are not stored like the others. Upstream Chromium splits the profile in two: `Preferences`, and a second file `Secure Preferences` for a fixed set of tracked settings, with a validation authenticator recorded for each of them under `protection.macs`. Two things follow. Writing one of those settings into the plain file has no effect, because the browser reads it from the other file. Writing it into the protected file without a matching authenticator is undone at the next start, on the platforms where upstream turns enforcement on, which are Windows and macOS by default. Either way an outside tool cannot put those values back and make them stay, and it would look like it had worked.
+
+So this tool does not write them. It exports them under a separate `read_only` key in the file, and `export` prints them by name, so you can still read them, compare two machines, and set them yourself in the settings screen. The settings in that group are the home button and home page, what opens on startup, pinned tabs, and the default search engine.
+
+On top of that fixed list, `export` and `import` also look at your actual profile: any covered setting that sits in `Secure Preferences`, or that has an authenticator recorded for it, is treated as read only for that profile even if the fixed list does not mention it. A file edited by hand cannot get around this either, because the list of names is checked again on the way in.
+
+This is the honest shape of the problem rather than a workaround. A tool that says what it cannot do stays useful. A tool whose writes quietly disappear does not.
+
+## Which settings are covered
+
+Roughly sixty named keys, grouped as:
+
+- appearance and layout: bookmarks bar, side panel, toolbar buttons, dark mode, tab behaviour
+- new tab page: clock, stats row, what the page shows
+- fonts and text: font families, default and minimum sizes, caret browsing
+- languages and spelling: accepted languages, dictionaries, translation preferences
+- downloads and printing: download folder, ask where to save, default printer
+- privacy and autofill: do not track, suggestions, preloading, address and payment autofill
+- shields: your own filter rules, filter list subscriptions, embed and language settings
+- startup and search: read only, see the section above
+
+The file `src/braveprefs/keys.py` is the list, with a one line label for each key. Every key in it has its own test.
+
+## Finding your profile directory
+
+Open the browser's version page (`brave://version` in that browser, `chrome://version` in others) and copy the value next to **Profile Path**. That is the directory to pass to `braveprefs`. It is the directory that contains a file named `Preferences`, not the directory above it.
+
+On Windows it sits under `C:\Users\<you>\AppData\Local\BraveSoftware\Brave-Browser`. On other systems the version page is the reliable answer.
+
+## What has not been tested
+
+No real browser profile was read while building this. The key names and the protection mechanism come from the upstream Chromium source, and the test suite runs on example files written for the tests. If you run it on a real profile, whether it works or not, please open an issue and say what happened. That is the one thing I cannot check from here.
+
+## Where this came from
+
+The request thread: https://github.com/brave/brave-browser/issues/46192
+
+There are other tools in this area that apply a hardened set of settings chosen by their author. This one does the opposite: it moves *your* settings, whatever they are, and decides nothing for you.
+
+## Notes
+
+Built with AI assistance, reviewed and tested by me.
+
+Requires Python 3.8 or later. No dependencies outside the standard library.
+
+Run the tests with `python3 -m unittest discover -s tests -t tests` from a checkout, with `src` on `PYTHONPATH`.
+
+MIT licensed. Younes Z.

braveprefs-0.1.0/README.md

@@ -0,0 +1,100 @@
+# braveprefs
+
+```
+pip install braveprefs
+```
+
+Put your browser settings in one short JSON file, compare that file between two machines, and write it back on a fresh install. No sync account, no QR code, no network.
+
+This project is not affiliated with Brave Software or with any browser publisher. It reads and writes files on your own disk and nothing else.
+
+## Why
+
+Today the way to move your settings to a new machine is to copy the whole profile directory, several gigabytes of caches and databases, to recover a few kilobytes of choices. The rest of that directory does not restore cleanly anyway. `braveprefs` takes the few kilobytes.
+
+The output is a file you can read, keep in a git repository, and diff.
+
+## Use
+
+Find your profile directory first (see below), then:
+
+```
+braveprefs export "<profile directory>" -o settings.json
+braveprefs diff settings.json other-machine.json
+braveprefs import "<profile directory>" settings.json
+```
+
+`import` is a dry run by default: it prints what it would change and writes nothing. Add `--apply` to write, with the browser closed:
+
+```
+braveprefs import "<profile directory>" settings.json --apply
+```
+
+Before writing, it copies the original `Preferences` file next to itself with a timestamp, so you can always put it back. If a `SingletonLock` file is present, the browser may still be running and the command stops; close the browser, or pass `--force` if you know the lock is stale.
+
+`diff` exits with status 1 when the two files differ and 0 when they match, so it fits in a script.
+
+## What never leaves your profile
+
+The list of settings this tool touches is a list of named keys, written out one by one in `src/braveprefs/keys.py`. It is not a name pattern. A key that is not named there is never read and never written. Concretely, none of this is ever in the exported file:
+
+- passwords, cookies, tokens, session state
+- browsing history, downloads history, visited sites
+- wallet data, payment methods, or any encrypted store
+- your extensions and their data, except the id of your current theme, which is technically an extension in this browser
+- account identifiers and anything the browser uses to sign you in
+
+The exported file is plain text on purpose. Open it and read it.
+
+Two settings in the list are folder paths, the download folder and the save as folder, and a folder path can contain your account name. When either is present the exported file says so in its `notes` field. Read the file before you share it. A folder path that exists on one machine may not exist on another, especially across operating systems; import writes it anyway, so check it still makes sense before you apply it.
+
+## Settings the browser protects, and what this tool does about them
+
+Some settings are not stored like the others. Upstream Chromium splits the profile in two: `Preferences`, and a second file `Secure Preferences` for a fixed set of tracked settings, with a validation authenticator recorded for each of them under `protection.macs`. Two things follow. Writing one of those settings into the plain file has no effect, because the browser reads it from the other file. Writing it into the protected file without a matching authenticator is undone at the next start, on the platforms where upstream turns enforcement on, which are Windows and macOS by default. Either way an outside tool cannot put those values back and make them stay, and it would look like it had worked.
+
+So this tool does not write them. It exports them under a separate `read_only` key in the file, and `export` prints them by name, so you can still read them, compare two machines, and set them yourself in the settings screen. The settings in that group are the home button and home page, what opens on startup, pinned tabs, and the default search engine.
+
+On top of that fixed list, `export` and `import` also look at your actual profile: any covered setting that sits in `Secure Preferences`, or that has an authenticator recorded for it, is treated as read only for that profile even if the fixed list does not mention it. A file edited by hand cannot get around this either, because the list of names is checked again on the way in.
+
+This is the honest shape of the problem rather than a workaround. A tool that says what it cannot do stays useful. A tool whose writes quietly disappear does not.
+
+## Which settings are covered
+
+Roughly sixty named keys, grouped as:
+
+- appearance and layout: bookmarks bar, side panel, toolbar buttons, dark mode, tab behaviour
+- new tab page: clock, stats row, what the page shows
+- fonts and text: font families, default and minimum sizes, caret browsing
+- languages and spelling: accepted languages, dictionaries, translation preferences
+- downloads and printing: download folder, ask where to save, default printer
+- privacy and autofill: do not track, suggestions, preloading, address and payment autofill
+- shields: your own filter rules, filter list subscriptions, embed and language settings
+- startup and search: read only, see the section above
+
+The file `src/braveprefs/keys.py` is the list, with a one line label for each key. Every key in it has its own test.
+
+## Finding your profile directory
+
+Open the browser's version page (`brave://version` in that browser, `chrome://version` in others) and copy the value next to **Profile Path**. That is the directory to pass to `braveprefs`. It is the directory that contains a file named `Preferences`, not the directory above it.
+
+On Windows it sits under `C:\Users\<you>\AppData\Local\BraveSoftware\Brave-Browser`. On other systems the version page is the reliable answer.
+
+## What has not been tested
+
+No real browser profile was read while building this. The key names and the protection mechanism come from the upstream Chromium source, and the test suite runs on example files written for the tests. If you run it on a real profile, whether it works or not, please open an issue and say what happened. That is the one thing I cannot check from here.
+
+## Where this came from
+
+The request thread: https://github.com/brave/brave-browser/issues/46192
+
+There are other tools in this area that apply a hardened set of settings chosen by their author. This one does the opposite: it moves *your* settings, whatever they are, and decides nothing for you.
+
+## Notes
+
+Built with AI assistance, reviewed and tested by me.
+
+Requires Python 3.8 or later. No dependencies outside the standard library.
+
+Run the tests with `python3 -m unittest discover -s tests -t tests` from a checkout, with `src` on `PYTHONPATH`.
+
+MIT licensed. Younes Z.

braveprefs-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "braveprefs"
+version = "0.1.0"
+description = "Export, compare and restore browser profile settings as one small readable JSON file."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "Younes Z." }]
+keywords = ["browser", "chromium", "preferences", "settings", "backup", "restore", "dotfiles", "configuration", "profile", "migration", "cli"]
+classifiers = ["Development Status :: 4 - Beta", "Environment :: Console", "Intended Audience :: End Users/Desktop", "License :: OSI Approved :: MIT License", "Programming Language :: Python :: 3", "Topic :: Utilities"]
+dependencies = []
+
+[project.scripts]
+braveprefs = "braveprefs.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/Rezarys/braveprefs"
+Source = "https://github.com/Rezarys/braveprefs"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/braveprefs"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "README.md", "LICENSE", "CHANGELOG.md", "pyproject.toml"]

braveprefs-0.1.0/src/braveprefs/__init__.py

@@ -0,0 +1,5 @@
+"""braveprefs: export, compare and restore a named list of browser profile settings."""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

braveprefs-0.1.0/src/braveprefs/cli.py

@@ -0,0 +1,143 @@
+"""Command line for braveprefs: export, diff, import."""
+
+import argparse
+import json
+import sys
+
+from . import core
+from .core import PrefsError
+
+USAGE = "braveprefs {export|diff|import} ..."
+
+
+def _render(value):
+    if isinstance(value, (dict, list)):
+        return json.dumps(value, sort_keys=True, ensure_ascii=False)
+    return json.dumps(value, ensure_ascii=False)
+
+
+def _cmd_export(args, out):
+    bundle = core.export_settings(args.profile)
+    if args.output in (None, "-"):
+        json.dump(bundle, out, indent=2, sort_keys=True, ensure_ascii=False)
+        out.write("\n")
+    else:
+        core.write_bundle(bundle, args.output)
+        out.write("wrote %s\n" % args.output)
+    kept = len(bundle["settings"])
+    locked = len(bundle["read_only"])
+    out.write("%d setting(s) you can restore, %d read only\n" % (kept, locked))
+    if locked:
+        out.write(
+            "read only means the browser signs those values and undoes a change made from "
+            "outside it:\n"
+        )
+        for path in sorted(bundle["read_only"], key=core.group_order):
+            out.write("  %s (%s)\n" % (path, bundle["labels"].get(path, "")))
+    return 0
+
+
+def _cmd_diff(args, out):
+    left = core.read_bundle(args.first)
+    right = core.read_bundle(args.second)
+    rows = core.diff_bundles(left, right)
+    if not rows:
+        out.write("no difference in the settings both files carry\n")
+        return 0
+    out.write("%d difference(s)\n" % len(rows))
+    for path, label, status, value_a, value_b in sorted(rows, key=lambda r: core.group_order(r[0])):
+        out.write("%s (%s)\n  %s\n" % (path, label, status))
+        if value_a is not None or status == "different":
+            out.write("    first:  %s\n" % _render(value_a))
+        if value_b is not None or status == "different":
+            out.write("    second: %s\n" % _render(value_b))
+    return 1
+
+
+def _cmd_import(args, out):
+    bundle = core.read_bundle(args.bundle)
+    if args.apply:
+        rows, backup = core.apply_import(args.profile, bundle, force=args.force)
+    else:
+        rows, backup = core.plan_import(args.profile, bundle), None
+
+    written = 0
+    for path, action, current, new in sorted(rows, key=lambda r: core.group_order(r[0])):
+        if action == core.UNCHANGED:
+            continue
+        out.write("%s\n  %s\n" % (path, action))
+        if action == core.SET:
+            written += 1
+            out.write("    from: %s\n" % _render(current))
+            out.write("    to:   %s\n" % _render(new))
+    unchanged = sum(1 for row in rows if row[1] == core.UNCHANGED)
+    out.write("%d already match\n" % unchanged)
+    if args.apply:
+        out.write("wrote %d setting(s)\n" % written)
+        if backup:
+            out.write("copied the original file to %s\n" % backup)
+        else:
+            out.write("nothing to write, so no copy was made\n")
+    else:
+        out.write(
+            "this was a dry run and nothing was written. Close the browser and add --apply "
+            "to write %d setting(s).\n" % written
+        )
+    return 0
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(
+        prog="braveprefs",
+        description="Export, compare and restore a named list of browser profile settings.",
+    )
+    subparsers = parser.add_subparsers(dest="command")
+
+    exporter = subparsers.add_parser("export", help="read the settings of a profile")
+    exporter.add_argument("profile", help="path of the browser profile directory")
+    exporter.add_argument("-o", "--output", help="file to write, or - for standard output")
+    exporter.set_defaults(handler=_cmd_export)
+
+    differ = subparsers.add_parser("diff", help="compare two exported files")
+    differ.add_argument("first")
+    differ.add_argument("second")
+    differ.set_defaults(handler=_cmd_diff)
+
+    importer = subparsers.add_parser("import", help="write settings back into a profile")
+    importer.add_argument("profile", help="path of the browser profile directory")
+    importer.add_argument("bundle", help="file produced by braveprefs export")
+    importer.add_argument(
+        "--apply", action="store_true",
+        help="actually write; without it the command only says what would change",
+    )
+    importer.add_argument(
+        "--dry-run", action="store_true",
+        help="say what would change and write nothing. This is the default.",
+    )
+    importer.add_argument(
+        "--force", action="store_true",
+        help="write even though a singleton lock file is present",
+    )
+    importer.set_defaults(handler=_cmd_import)
+    return parser
+
+
+def main(argv=None, out=None, err=None):
+    out = out or sys.stdout
+    err = err or sys.stderr
+    parser = build_parser()
+    args = parser.parse_args(list(sys.argv[1:] if argv is None else argv))
+    if getattr(args, "handler", None) is None:
+        parser.print_help(out)
+        return 2
+    if getattr(args, "dry_run", False):
+        args.apply = False
+    try:
+        return args.handler(args, out)
+    except PrefsError as exc:
+        err.write("braveprefs: %s\n" % exc)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())