prefpicker 2.17.0__py3-none-any.whl

prefpicker/__init__.py

@@ -0,0 +1,9 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at http://mozilla.org/MPL/2.0/.
+"""prefpicker module"""
+
+from .prefpicker import PrefPicker, SourceDataError
+
+__all__ = ("PrefPicker", "SourceDataError")
+__author__ = "Tyson Smith"

prefpicker/__main__.py

@@ -0,0 +1,10 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at http://mozilla.org/MPL/2.0/.
+"""prefpicker module main"""
+
+import sys
+
+from .main import main
+
+sys.exit(main())

prefpicker/main.py

@@ -0,0 +1,113 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at http://mozilla.org/MPL/2.0/.
+"""prefpicker module main"""
+
+from __future__ import annotations
+
+from argparse import ArgumentParser, Namespace
+from logging import DEBUG, INFO, basicConfig, getLogger
+from os import getenv
+from pathlib import Path
+
+from .prefpicker import PrefPicker, SourceDataError, __version__
+
+__author__ = "Tyson Smith"
+__credits__ = ["Tyson Smith"]
+
+LOG = getLogger(__name__)
+
+
+def parse_args(argv: list[str] | None = None) -> Namespace:
+    """Handle argument parsing.
+
+    Args:
+        argv: Arguments from the user.
+
+    Returns:
+        Parsed and sanitized arguments.
+    """
+    parser = ArgumentParser(
+        description="Manage & generate prefs.js files",
+        prog="prefpicker",
+    )
+    parser.add_argument(
+        "input",
+        type=Path,
+        help="Template containing definitions. This can be the path to a template"
+        " (YAML) file or the name of a built-in template. Built-in templates:"
+        f" {', '.join(x.name for x in PrefPicker.templates())}",
+    )
+    parser.add_argument("output", type=Path, help="Path of prefs.js file to create.")
+    parser.add_argument(
+        "--check", action="store_true", help="Display output of sanity checks."
+    )
+    parser.add_argument("--variant", default="default", help="Specify variant to use.")
+    parser.add_argument(
+        "--version",
+        "-V",
+        action="version",
+        version=f"%(prog)s {__version__}",
+        help="Show version number.",
+    )
+    args = parser.parse_args(argv)
+    # handle using built-in templates
+    builtin_template = PrefPicker.lookup_template(args.input.name)
+    if builtin_template:
+        args.input = builtin_template
+    elif not args.input.is_file():
+        parser.error(f"Cannot find input file '{args.input}'")
+    # sanity check output
+    if args.output.is_dir():
+        parser.error(f"Output '{args.output}' is a directory.")
+    if not args.output.parent.is_dir():
+        parser.error(f"Output '{args.output.parent}' directory does not exist.")
+    return args
+
+
+def main(argv: list[str] | None = None) -> int:
+    """
+    PrefPicker main entry point
+
+    Run with --help for usage
+    """
+    if bool(getenv("DEBUG")):  # pragma: no cover
+        log_fmt = "%(asctime)s %(levelname).1s %(name)s | %(message)s"
+        log_level = DEBUG
+    else:
+        log_fmt = "%(message)s"
+        log_level = INFO
+    basicConfig(format=log_fmt, level=log_level)
+
+    args = parse_args(argv)
+
+    LOG.info("Loading %r...", args.input.name)
+    try:
+        pick = PrefPicker.load_template(args.input)
+    except SourceDataError as exc:
+        LOG.error("Failed to load '%s': %s", args.input, exc)
+        return 1
+    LOG.info("Loaded %d prefs and %d variants", len(pick.prefs), len(pick.variants))
+    if args.check:
+        for combos in pick.check_combinations():
+            LOG.info(
+                "Check: %r variant has %r possible combination(s)", combos[0], combos[1]
+            )
+        for overwrites in pick.check_overwrites():
+            LOG.info(
+                "Check: %r variant %r redefines value %r (may be intentional)",
+                overwrites[0],
+                overwrites[1],
+                overwrites[2],
+            )
+        for dupes in pick.check_duplicates():
+            LOG.info(
+                "Check: %r variant %r contains duplicate values", dupes[0], dupes[1]
+            )
+    if args.variant not in pick.variants:
+        LOG.error("Error: Variant %r does not exist", args.variant)
+        return 1
+    LOG.info("Generating %r using variant %r...", args.output.name, args.variant)
+    pick.create_prefsjs(args.output, args.variant)
+    LOG.info("Done.")
+    return 0

prefpicker/prefpicker.py

@@ -0,0 +1,265 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at http://mozilla.org/MPL/2.0/.
+"""prefpicker module"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from importlib.metadata import PackageNotFoundError, version
+from json import dumps
+from pathlib import Path
+from random import choice
+from typing import TYPE_CHECKING, Any
+
+from yaml import safe_load
+from yaml.parser import ParserError
+from yaml.scanner import ScannerError
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
+
+__author__ = "Tyson Smith"
+__credits__ = ["Tyson Smith"]
+try:
+    __version__ = version("prefpicker")
+except PackageNotFoundError:  # pragma: no cover
+    # package is not installed
+    __version__ = "unknown"
+
+
+class SourceDataError(Exception):
+    """This is raised when issues are found in the source data."""
+
+
+PrefValue = bool | int | str | None
+PrefVariant = dict[str, list[PrefValue]]
+
+
+class PrefPicker:  # pylint: disable=missing-docstring
+    __slots__ = ("prefs", "variants")
+
+    def __init__(self) -> None:
+        self.prefs: dict[str, dict[str, PrefVariant]] = {}
+        self.variants: set[str] = {"default"}
+
+    def check_combinations(self) -> Generator[tuple[str, int]]:
+        """Count the number of combinations for each variation. Only return
+           variants that have more than one combination.
+
+        Args:
+            None
+
+        Yields:
+            Variant and number of potential combinations.
+        """
+        combos = dict.fromkeys(self.variants, 1)
+        for variants in (x["variants"] for x in self.prefs.values()):
+            for variant in combos:
+                # use 'default' if pref does not have a matching variant entry
+                if variant not in variants:
+                    combos[variant] *= len(variants["default"])
+                else:
+                    combos[variant] *= len(variants[variant])
+        for variant, count in sorted(combos.items()):
+            if count > 1:
+                yield (variant, count)
+
+    def check_duplicates(self) -> Generator[tuple[str, str]]:
+        """Look for variants with values that appear more than once per variant.
+
+        Args:
+            None
+
+        Yields:
+            Pref name and the variant.
+        """
+        for pref, keys in sorted(self.prefs.items()):
+            variants = keys["variants"]
+            for variant in variants:
+                if len(variants[variant]) != len(set(variants[variant])):
+                    yield (pref, variant)
+
+    def check_overwrites(self) -> Generator[tuple[str, str, PrefValue]]:
+        """Look for variants that overwrite the default with the same value.
+
+        Args:
+            None
+
+        Yields:
+            Pref, variant and value.
+        """
+        for pref, keys in sorted(self.prefs.items()):
+            variants = keys["variants"]
+            for variant in variants:
+                if variant == "default":
+                    continue
+                for value in variants[variant]:
+                    if value in variants["default"]:
+                        yield (pref, variant, value)
+
+    def create_prefsjs(self, dest: Path, variant: str = "default") -> None:
+        """Write a `prefs.js` file based on the specified variant. The output file
+           will also include comments containing the variant and a timestamp.
+
+        Args:
+            dest: Path of file to create.
+            variant: Used to pick the values to output.
+
+        Returns:
+            None
+        """
+        with dest.open("w") as prefs_fp:
+            prefs_fp.write(f"// Generated with PrefPicker ({__version__}) @ ")
+            prefs_fp.write(datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S %Z"))
+            prefs_fp.write(f"\n// Variant {variant!r}\n")
+            for pref, keys in sorted(self.prefs.items()):
+                variants = keys["variants"]
+                # choose values
+                if variant not in variants or variant == "default":
+                    options = variants["default"]
+                    default_variant = True
+                else:
+                    options = variants[variant]
+                    default_variant = False
+                value = choice(options)
+                if value is None:
+                    if len(options) > 1:
+                        prefs_fp.write(
+                            f"// '{pref}' skipped, options {dumps(options)}\n"
+                        )
+                    # skipping pref
+                    continue
+                if len(options) > 1:
+                    prefs_fp.write(f"// '{pref}' options {dumps(options)}\n")
+                # sanitize value for writing
+                if isinstance(value, bool):
+                    sanitized = "true" if value else "false"
+                elif isinstance(value, int):
+                    sanitized = str(value)
+                elif isinstance(value, str):
+                    sanitized = repr(value)
+                else:
+                    prefs_fp.write(f"// Failed to sanitized {value!r} ({pref})\n")
+                    raise SourceDataError(
+                        f"Unsupported datatype {type(value).__name__!r}"
+                    )
+                # write to prefs.js file
+                if not default_variant:
+                    prefs_fp.write(f"// {pref!r} defined by variant {variant!r}\n")
+                prefs_fp.write(f'user_pref("{pref}", {sanitized});\n')
+
+    @classmethod
+    def lookup_template(cls, name: str) -> Path | None:
+        """Lookup built-in template Path.
+
+        Args:
+            name: Name of template.
+
+        Returns:
+            Template that matches 'name' or None.
+        """
+        path = Path(__file__).parent / "templates" / name
+        if path.is_file():
+            return path
+        return None
+
+    @classmethod
+    def load_template(cls, input_yml: Path) -> PrefPicker:
+        """Load data from a template YAML file.
+
+        Args:
+            input_yml: Input file.
+
+        Returns:
+            PrefPicker object.
+        """
+        try:
+            raw_prefs = safe_load(input_yml.read_bytes())
+        except (ScannerError, ParserError):
+            raise SourceDataError("invalid YAML") from None
+        cls.verify_data(raw_prefs)
+        picker = cls()
+        picker.variants = set(raw_prefs["variant"] + ["default"])
+        # only add relevant parts
+        for pref, parts in raw_prefs["pref"].items():
+            picker.prefs[pref] = {"variants": parts["variants"]}
+        return picker
+
+    @staticmethod
+    def templates() -> Generator[Path]:
+        """Available YAML template files.
+
+        Args:
+            None
+
+        Yields:
+            Template files.
+        """
+        path = Path(__file__).parent.resolve() / "templates"
+        if path.is_dir():
+            for template in path.iterdir():
+                if template.suffix.lower().endswith(".yml"):
+                    yield template
+
+    @staticmethod
+    def verify_data(raw_data: Any) -> None:
+        """Perform strict sanity checks on raw_data. This exists to help prevent
+           the template file from breaking or becoming unmaintainable.
+
+        Args:
+            raw_data: Data to verify.
+
+        Returns:
+            None
+        """
+        if not isinstance(raw_data, dict):
+            raise SourceDataError("invalid template")
+        # check variant list
+        if "variant" not in raw_data:
+            raise SourceDataError("variant list is missing")
+        if not isinstance(raw_data["variant"], list):
+            raise SourceDataError("variant is not a list")
+        # check variant list entries
+        valid_variants = {"default"}
+        for variant in raw_data["variant"]:
+            if not isinstance(variant, str):
+                raise SourceDataError("variant definition must be a string")
+            valid_variants.add(variant)
+        # check prefs dict
+        if "pref" not in raw_data:
+            raise SourceDataError("pref group is missing")
+        if not isinstance(raw_data["pref"], dict):
+            raise SourceDataError("pref is not a dict")
+        # check entries in prefs dict
+        used_variants = set()
+        for pref, keys in raw_data["pref"].items():
+            if not isinstance(keys, dict):
+                raise SourceDataError(f"{pref!r} entry must contain a dict")
+            variants = keys.get("variants")
+            if not isinstance(variants, dict):
+                raise SourceDataError(f"{pref!r} is missing 'variants' dict")
+            if "default" not in variants:
+                raise SourceDataError(f"{pref!r} is missing 'default' variant")
+            # verify variants
+            for variant in variants:
+                if variant not in valid_variants:
+                    raise SourceDataError(
+                        f"{variant!r} in {pref!r} is not a defined variant"
+                    )
+                if not isinstance(variants[variant], list):
+                    raise SourceDataError(
+                        f"variant {variant!r} in {pref!r} is not a list"
+                    )
+                if not variants[variant]:
+                    raise SourceDataError(f"{variant!r} in {pref!r} is empty")
+                for value in variants[variant]:
+                    if value is not None and not isinstance(value, bool | int | str):
+                        raise SourceDataError(
+                            f"unsupported datatype {type(value).__name__!r} ({pref})"
+                        )
+                used_variants.add(variant)
+        if valid_variants - used_variants:
+            raise SourceDataError(
+                f"Unused variants {' '.join(valid_variants - used_variants)!r}"
+            )