py-bg-changer 0.1.0__tar.gz

py_bg_changer-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mr MRF
+
+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.

py_bg_changer-0.1.0/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: py-bg-changer
+Version: 0.1.0
+Summary: A simple cross-platform wallpaper changer made with Python
+Keywords: wallpaper,background,desktop,cli,cross-platform
+Author: Mr MRF Dev
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Environment :: Console
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/Mr-MRF-Dev/Py-Bg-Changer
+Project-URL: Issues, https://github.com/Mr-MRF-Dev/Py-Bg-Changer/issues
+Description-Content-Type: text/markdown
+
+# 🖼️ Py Bg Changer
+
+Change your desktop wallpaper from the terminal, Win+R or any launcher.
+Works on Windows, macOS and Linux. No dependencies.
+
+The command is `py-bg-changer`, and `pbc` is the short alias for it.
+
+## Install
+
+With [uv](https://docs.astral.sh/uv/) (recommended):
+
+```bash
+uv tool install py-bg-changer
+```
+
+Or try it without installing:
+
+```bash
+uvx --from py-bg-changer pbc --help
+```
+
+Prefer pip? `pipx install py-bg-changer` or `pip install py-bg-changer` work too. Needs Python 3.9+.
+
+## Use
+
+```bash
+pbc add night ~/Pictures/night.jpg   # save an image under a name
+pbc add night img.jpg -a n -a dark   # ...and give it extra names (aliases)
+pbc alias night moon                 # add more aliases later
+pbc rename night midnight            # rename a wallpaper or an alias
+pbc night                            # set it by name (or any alias: pbc n)
+pbc ~/Pictures/any.png               # or set any image directly
+pbc list                             # see what you saved (* marks the default); `pbc ls` works too
+pbc default night                    # choose what a plain "pbc" sets
+pbc remove night                     # forget a name (or just an alias)
+pbc                                  # set the default wallpaper
+```
+
+If a saved name clashes with a command (say, one called `list`, `ls` or `default`), use `pbc set list`.
+
+### Win+R and launchers (no console window)
+
+Running `pbc` from Win+R opens a terminal that closes right away. Use `pbcw` (or
+`py-bg-changer-w`) instead: it takes the same arguments, opens no window, and shows a
+small message box only if something goes wrong.
+
+```bash
+pbcw night                           # from Win+R: set it silently
+```
+
+It prints nothing on success, so use `pbc` in a terminal for `list`, `default` and
+the like.
+
+### Aliases
+
+A wallpaper can have as many aliases as you like, and every alias works anywhere a name
+does (`pbc n`, `pbc default n`, `pbc alias n moon`). Add them while saving with
+`-a` (repeat it for more) or later with `pbc alias NAME ALIAS...`. `pbc list` shows
+them in brackets after the name.
+
+Removing an alias leaves the wallpaper alone; removing a wallpaper also removes its
+aliases. If you replace the image saved under a name, its aliases follow the new image.
+
+Rename either one with `pbc rename OLD NEW`. Renaming a wallpaper keeps its aliases, its
+image and its place as the default.
+
+### Default wallpaper
+
+Run `pbc` with no arguments and it sets your default wallpaper. Pick the default with
+`pbc default NAME`, or do it while saving an image with `pbc add NAME IMAGE --default`.
+`pbc default` on its own shows the current choice.
+
+### Your images are copied
+
+When you save an image, `py-bg-changer` keeps its own copy next to the config file and
+gives that copy to the system. If you later move or delete the original, the wallpaper
+still works. The copy is removed when you remove the name (or replace its image), and
+your original file is never touched.
+
+## Supported desktops
+
+| OS      | Notes                                                                                                                                                        |
+| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Windows | Built in, nothing extra needed                                                                                                                               |
+| macOS   | Built in (uses `osascript`)                                                                                                                                  |
+| Linux   | GNOME, Budgie, Cinnamon, MATE, KDE Plasma, XFCE and Sway work out of the box. Anything else (i3, bspwm, ...) falls back to `feh` or `nitrogen` if installed. |
+
+## Config
+
+Saved names live in a small JSON file, and the copied images in a `wallpapers` folder
+next to it. Run `pbc path` to see where. Set `PBC_CONFIG` to use a different file.
+
+```json
+{
+  "wallpapers": {
+    "night": "/home/me/.config/py-bg-changer/wallpapers/3e23e8160039594a.png"
+  },
+  "aliases": { "n": "night", "dark": "night" },
+  "default": "night"
+}
+```
+
+## Development
+
+The project is managed with [uv](https://docs.astral.sh/uv/).
+
+```bash
+uv sync              # create the virtualenv and install everything
+uv run pytest        # run the tests
+uv run pbc --help    # run the CLI from source
+```
+
+### Releasing
+
+```bash
+uv build             # builds the sdist and wheel into dist/
+uv publish           # uploads them to PyPI
+```
+
+Bump `version` in `pyproject.toml` before each release.
+
+## License
+
+MIT

py_bg_changer-0.1.0/README.md

@@ -0,0 +1,124 @@
+# 🖼️ Py Bg Changer
+
+Change your desktop wallpaper from the terminal, Win+R or any launcher.
+Works on Windows, macOS and Linux. No dependencies.
+
+The command is `py-bg-changer`, and `pbc` is the short alias for it.
+
+## Install
+
+With [uv](https://docs.astral.sh/uv/) (recommended):
+
+```bash
+uv tool install py-bg-changer
+```
+
+Or try it without installing:
+
+```bash
+uvx --from py-bg-changer pbc --help
+```
+
+Prefer pip? `pipx install py-bg-changer` or `pip install py-bg-changer` work too. Needs Python 3.9+.
+
+## Use
+
+```bash
+pbc add night ~/Pictures/night.jpg   # save an image under a name
+pbc add night img.jpg -a n -a dark   # ...and give it extra names (aliases)
+pbc alias night moon                 # add more aliases later
+pbc rename night midnight            # rename a wallpaper or an alias
+pbc night                            # set it by name (or any alias: pbc n)
+pbc ~/Pictures/any.png               # or set any image directly
+pbc list                             # see what you saved (* marks the default); `pbc ls` works too
+pbc default night                    # choose what a plain "pbc" sets
+pbc remove night                     # forget a name (or just an alias)
+pbc                                  # set the default wallpaper
+```
+
+If a saved name clashes with a command (say, one called `list`, `ls` or `default`), use `pbc set list`.
+
+### Win+R and launchers (no console window)
+
+Running `pbc` from Win+R opens a terminal that closes right away. Use `pbcw` (or
+`py-bg-changer-w`) instead: it takes the same arguments, opens no window, and shows a
+small message box only if something goes wrong.
+
+```bash
+pbcw night                           # from Win+R: set it silently
+```
+
+It prints nothing on success, so use `pbc` in a terminal for `list`, `default` and
+the like.
+
+### Aliases
+
+A wallpaper can have as many aliases as you like, and every alias works anywhere a name
+does (`pbc n`, `pbc default n`, `pbc alias n moon`). Add them while saving with
+`-a` (repeat it for more) or later with `pbc alias NAME ALIAS...`. `pbc list` shows
+them in brackets after the name.
+
+Removing an alias leaves the wallpaper alone; removing a wallpaper also removes its
+aliases. If you replace the image saved under a name, its aliases follow the new image.
+
+Rename either one with `pbc rename OLD NEW`. Renaming a wallpaper keeps its aliases, its
+image and its place as the default.
+
+### Default wallpaper
+
+Run `pbc` with no arguments and it sets your default wallpaper. Pick the default with
+`pbc default NAME`, or do it while saving an image with `pbc add NAME IMAGE --default`.
+`pbc default` on its own shows the current choice.
+
+### Your images are copied
+
+When you save an image, `py-bg-changer` keeps its own copy next to the config file and
+gives that copy to the system. If you later move or delete the original, the wallpaper
+still works. The copy is removed when you remove the name (or replace its image), and
+your original file is never touched.
+
+## Supported desktops
+
+| OS      | Notes                                                                                                                                                        |
+| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Windows | Built in, nothing extra needed                                                                                                                               |
+| macOS   | Built in (uses `osascript`)                                                                                                                                  |
+| Linux   | GNOME, Budgie, Cinnamon, MATE, KDE Plasma, XFCE and Sway work out of the box. Anything else (i3, bspwm, ...) falls back to `feh` or `nitrogen` if installed. |
+
+## Config
+
+Saved names live in a small JSON file, and the copied images in a `wallpapers` folder
+next to it. Run `pbc path` to see where. Set `PBC_CONFIG` to use a different file.
+
+```json
+{
+  "wallpapers": {
+    "night": "/home/me/.config/py-bg-changer/wallpapers/3e23e8160039594a.png"
+  },
+  "aliases": { "n": "night", "dark": "night" },
+  "default": "night"
+}
+```
+
+## Development
+
+The project is managed with [uv](https://docs.astral.sh/uv/).
+
+```bash
+uv sync              # create the virtualenv and install everything
+uv run pytest        # run the tests
+uv run pbc --help    # run the CLI from source
+```
+
+### Releasing
+
+```bash
+uv build             # builds the sdist and wheel into dist/
+uv publish           # uploads them to PyPI
+```
+
+Bump `version` in `pyproject.toml` before each release.
+
+## License
+
+MIT

py_bg_changer-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[project]
+name = "py-bg-changer"
+version = "0.1.0"
+description = "A simple cross-platform wallpaper changer made with Python"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "wallpaper",
+    "background",
+    "desktop",
+    "cli",
+    "cross-platform",
+]
+dependencies = []
+classifiers = [
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Environment :: Console",
+]
+
+[[project.authors]]
+name = "Mr MRF Dev"
+
+[project.urls]
+Homepage = "https://github.com/Mr-MRF-Dev/Py-Bg-Changer"
+Issues = "https://github.com/Mr-MRF-Dev/Py-Bg-Changer/issues"
+
+[project.scripts]
+py-bg-changer = "py_bg_changer.cli:main"
+pbc = "py_bg_changer.cli:main"
+
+[project.gui-scripts]
+py-bg-changer-w = "py_bg_changer.gui:main"
+pbcw = "py_bg_changer.gui:main"
+
+[dependency-groups]
+dev = ["pytest>=9.0.3"]
+
+[build-system]
+requires = ["uv_build>=0.13"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

py_bg_changer-0.1.0/pyproject.toml.orig

@@ -0,0 +1,39 @@
+[project]
+name = "py-bg-changer"
+version = "0.1.0"
+description = "A simple cross-platform wallpaper changer made with Python"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Mr MRF Dev" }]
+keywords = ["wallpaper", "background", "desktop", "cli", "cross-platform"]
+dependencies = []
+classifiers = [
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Environment :: Console",
+]
+
+[project.urls]
+Homepage = "https://github.com/Mr-MRF-Dev/Py-Bg-Changer"
+Issues = "https://github.com/Mr-MRF-Dev/Py-Bg-Changer/issues"
+
+[project.scripts]
+py-bg-changer = "py_bg_changer.cli:main"
+pbc = "py_bg_changer.cli:main"
+
+# Same commands without a console window.
+[project.gui-scripts]
+py-bg-changer-w = "py_bg_changer.gui:main"
+pbcw = "py_bg_changer.gui:main"
+
+[dependency-groups]
+dev = ["pytest>=9.0.3"]
+
+[build-system]
+requires = ["uv_build>=0.13"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

py_bg_changer-0.1.0/src/py_bg_changer/__init__.py

@@ -0,0 +1,6 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("py-bg-changer")
+except PackageNotFoundError:
+    __version__ = "unknown"

py_bg_changer-0.1.0/src/py_bg_changer/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

py_bg_changer-0.1.0/src/py_bg_changer/cache.py

@@ -0,0 +1,48 @@
+"""Our own copy of every saved wallpaper.
+
+When an image is added we copy it next to the config file and hand that copy to
+the operating system, so the wallpaper keeps working even if the original file
+is moved or deleted.
+
+Copies are named after a hash of their content: adding the same image under two
+names stores it once, and the copy is deleted when no saved name uses it.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import shutil
+from pathlib import Path
+
+from . import config
+
+
+def cache_dir() -> Path:
+    return config.config_path().expanduser().resolve().parent / "wallpapers"
+
+
+def store(source: Path) -> Path:
+    """Copy `source` into the cache (if it isn't there yet) and return the copy."""
+    digest = hashlib.sha256()
+    with source.open("rb") as f:
+        for chunk in iter(lambda: f.read(1 << 20), b""):
+            digest.update(chunk)
+    dest = cache_dir() / f"{digest.hexdigest()[:16]}{source.suffix.lower()}"
+    if not dest.exists():
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        tmp = dest.with_name(dest.name + ".tmp")
+        shutil.copyfile(source, tmp)
+        tmp.replace(dest)
+    return dest
+
+
+def release(path: str, wallpapers: dict[str, str]) -> None:
+    """Delete a cached copy once no saved name points to it any more."""
+    if path in wallpapers.values():
+        return
+    try:
+        target = Path(path).expanduser().resolve()
+        if target.parent == cache_dir():
+            target.unlink()
+    except OSError:
+        pass

py_bg_changer-0.1.0/src/py_bg_changer/cli.py

@@ -0,0 +1,400 @@
+"""Command line interface."""
+
+from __future__ import annotations
+
+import argparse
+import difflib
+import sys
+from pathlib import Path
+
+from . import __version__, cache, config
+from .wallpaper import WallpaperError, set_wallpaper
+
+COMMANDS = {
+    "set",
+    "list",
+    "ls",
+    "add",
+    "alias",
+    "rename",
+    "remove",
+    "rm",
+    "default",
+    "path",
+}
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="py-bg-changer",
+        description="Change your desktop wallpaper from the command line.",
+        epilog=(
+            "'pbc' is a short alias for 'py-bg-changer'.\n\n"
+            "examples:\n"
+            "  pbc add night ~/Pictures/night.jpg   save an image under a name\n"
+            "  pbc add night img.jpg -a n -a dark   ...with extra names (aliases)\n"
+            "  pbc alias night moon                 add more aliases later\n"
+            "  pbc rename night midnight            rename a wallpaper or an alias\n"
+            "  pbc night                            set it by name or alias\n"
+            "  pbc ~/Pictures/any.png               set any image directly\n"
+            "  pbc default night                    choose what a plain 'pbc' sets\n"
+            "  pbc                                  set the default wallpaper"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"%(prog)s {__version__}"
+    )
+    sub = parser.add_subparsers(dest="command", metavar="<command>")
+
+    p = sub.add_parser("set", help="set the wallpaper (this is the default command)")
+    p.add_argument(
+        "target",
+        nargs="?",
+        help="a saved name, an alias or a path to an image (omit it to use the default)",
+    )
+
+    sub.add_parser(
+        "list", aliases=["ls"], help="show saved wallpapers (* marks the default)"
+    )
+
+    p = sub.add_parser("add", help="save an image under a name")
+    p.add_argument("name")
+    p.add_argument("path")
+    p.add_argument(
+        "-a",
+        "--alias",
+        action="append",
+        dest="aliases",
+        metavar="ALIAS",
+        help="another name for the same image (repeat it for more)",
+    )
+    p.add_argument(
+        "-d",
+        "--default",
+        action="store_true",
+        dest="make_default",
+        help="also make it the default wallpaper",
+    )
+
+    p = sub.add_parser("alias", help="give a saved wallpaper extra names")
+    p.add_argument("name", help="a saved name (or one of its aliases)")
+    p.add_argument("aliases", nargs="+", metavar="ALIAS")
+
+    p = sub.add_parser("rename", help="rename a saved wallpaper or an alias")
+    p.add_argument("old", help="a saved name or an alias")
+    p.add_argument("new")
+
+    p = sub.add_parser("default", help="choose the wallpaper that a plain 'pbc' sets")
+    p.add_argument(
+        "name", nargs="?", help="a saved name or alias (omit it to show the default)"
+    )
+
+    p = sub.add_parser("remove", aliases=["rm"], help="forget a saved name or alias")
+    p.add_argument("name")
+
+    sub.add_parser("path", help="print where the config file lives")
+    return parser
+
+
+def _error(message: str) -> int:
+    print(message, file=sys.stderr)
+    return 1
+
+
+def _dedupe(items: list[str]) -> list[str]:
+    return list(dict.fromkeys(items))
+
+
+def _resolve(
+    name: str, wallpapers: dict[str, str], aliases: dict[str, str]
+) -> str | None:
+    """The saved wallpaper a name or alias stands for, or None."""
+    if name in wallpapers:
+        return name
+    target = aliases.get(name)
+    return target if target in wallpapers else None
+
+
+def _aliases_of(name: str, aliases: dict[str, str]) -> list[str]:
+    return [alias for alias, target in aliases.items() if target == name]
+
+
+def _label(name: str, aliases: dict[str, str]) -> str:
+    extra = _aliases_of(name, aliases)
+    return f"{name} ({', '.join(extra)})" if extra else name
+
+
+def _check_aliases(
+    owner: str,
+    requested: list[str],
+    wallpapers: dict[str, str],
+    aliases: dict[str, str],
+) -> str | None:
+    """An error message if one of the aliases can't be used for `owner`."""
+    for alias in requested:
+        if alias == owner:
+            return f"'{alias}' is already the name of this wallpaper."
+        if alias in wallpapers:
+            return f"'{alias}' is already a saved wallpaper name."
+        if alias in aliases and aliases[alias] != owner:
+            return f"'{alias}' is already an alias of '{aliases[alias]}'."
+    return None
+
+
+def _unknown(target: str, wallpapers: dict[str, str], aliases: dict[str, str]) -> int:
+    message = f"Unknown wallpaper: '{target}'"
+    close = difflib.get_close_matches(target, [*wallpapers, *aliases], n=1)
+    if close:
+        message += f"\nDid you mean '{close[0]}'?"
+    if wallpapers:
+        labels = ", ".join(_label(name, aliases) for name in wallpapers)
+        message += f"\nAvailable: {labels}"
+    else:
+        message += "\nNothing is saved yet. Save one with:  pbc add NAME IMAGE"
+    return _error(message)
+
+
+def _default_name(wallpapers: dict[str, str], aliases: dict[str, str]) -> str | None:
+    chosen = config.get_default()
+    if chosen:
+        resolved = _resolve(chosen, wallpapers, aliases)
+        if resolved:
+            return resolved
+    # Configs from the original bg.py use a wallpaper literally named "default".
+    if "default" in wallpapers:
+        return "default"
+    return None
+
+
+def cmd_set(target: str | None) -> int:
+    wallpapers = config.load()
+    aliases = config.load_aliases()
+
+    if target is None:
+        target = _default_name(wallpapers, aliases)
+        if target is None:
+            if not wallpapers:
+                return _error(
+                    "Nothing is saved yet. Save one with:  pbc add NAME IMAGE --default"
+                )
+            labels = ", ".join(_label(name, aliases) for name in wallpapers)
+            return _error(
+                "No default wallpaper is set. Choose one with:  pbc default NAME\n"
+                f"Available: {labels}"
+            )
+
+    saved = _resolve(target, wallpapers, aliases)
+    if saved is not None:
+        image = Path(wallpapers[saved]).expanduser()
+        label = f"'{saved}'"
+    elif Path(target).expanduser().is_file():
+        image = Path(target).expanduser()
+        label = str(image)
+    else:
+        return _unknown(target, wallpapers, aliases)
+
+    if not image.is_file():
+        message = f"File not found: {image}"
+        if saved is not None:
+            message += f"\nAdd it again with:  pbc add {saved} IMAGE"
+        return _error(message)
+
+    set_wallpaper(image)
+    print(f"Wallpaper set to {label}")
+    return 0
+
+
+def cmd_list() -> int:
+    wallpapers = config.load()
+    aliases = config.load_aliases()
+    if not wallpapers:
+        print("Nothing saved yet. Save one with:  pbc add NAME IMAGE")
+        return 0
+    default = _default_name(wallpapers, aliases)
+    labels = {name: _label(name, aliases) for name in wallpapers}
+    width = max(len(label) for label in labels.values())
+    for name, path in wallpapers.items():
+        mark = "*" if name == default else " "
+        note = "" if Path(path).expanduser().is_file() else "  (missing)"
+        print(f"{mark} {labels[name]:<{width}}  {path}{note}")
+    return 0
+
+
+def cmd_add(
+    name: str, path: str, make_default: bool, alias_names: list[str] | None
+) -> int:
+    source = Path(path).expanduser().resolve()
+    if not source.is_file():
+        return _error(f"File not found: {source}")
+
+    wallpapers = config.load()
+    aliases = config.load_aliases()
+    if name in aliases:
+        return _error(
+            f"'{name}' is already an alias of '{aliases[name]}'.\n"
+            f"Remove the alias first with:  pbc remove {name}"
+        )
+    requested = _dedupe(alias_names or [])
+    problem = _check_aliases(name, requested, wallpapers, aliases)
+    if problem:
+        return _error(problem)
+
+    try:
+        stored = cache.store(source)
+    except OSError as exc:
+        return _error(f"Could not copy {source}: {exc}")
+
+    previous = wallpapers.get(name)
+    wallpapers[name] = str(stored)
+    for alias in requested:
+        aliases[alias] = name
+    config.save(wallpapers, aliases)
+    if previous is not None:
+        cache.release(previous, wallpapers)
+
+    print(f"Saved '{name}' -> {stored}")
+    if requested:
+        print(f"Aliases: {', '.join(requested)}")
+    if make_default:
+        config.set_default(name)
+        print(f"'{name}' is now the default wallpaper")
+    return 0
+
+
+def cmd_alias(name: str, new_aliases: list[str]) -> int:
+    wallpapers = config.load()
+    aliases = config.load_aliases()
+    real = _resolve(name, wallpapers, aliases)
+    if real is None:
+        return _unknown(name, wallpapers, aliases)
+
+    requested = _dedupe(new_aliases)
+    problem = _check_aliases(real, requested, wallpapers, aliases)
+    if problem:
+        return _error(problem)
+
+    added = [alias for alias in requested if alias not in aliases]
+    if not added:
+        print(f"'{real}' already has those aliases")
+        return 0
+    for alias in added:
+        aliases[alias] = real
+    config.save(wallpapers, aliases)
+    print(f"'{real}' is now also called: {', '.join(added)}")
+    return 0
+
+
+def cmd_rename(old: str, new: str) -> int:
+    wallpapers = config.load()
+    aliases = config.load_aliases()
+    if old not in wallpapers and old not in aliases:
+        return _unknown(old, wallpapers, aliases)
+    if new == old:
+        print(f"'{old}' is already called that")
+        return 0
+    if new in wallpapers:
+        return _error(f"'{new}' is already a saved wallpaper name.")
+    if new in aliases:
+        return _error(f"'{new}' is already an alias of '{aliases[new]}'.")
+
+    # Rebuild the dicts so the renamed entry keeps its place in the list.
+    if old in wallpapers:
+        wallpapers = {
+            (new if name == old else name): path for name, path in wallpapers.items()
+        }
+        aliases = {
+            alias: (new if target == old else target)
+            for alias, target in aliases.items()
+        }
+        what = f"'{old}'"
+    else:
+        aliases = {
+            (new if alias == old else alias): target
+            for alias, target in aliases.items()
+        }
+        what = f"alias '{old}'"
+    config.save(wallpapers, aliases)
+    if config.get_default() == old:
+        config.set_default(new)
+    print(f"Renamed {what} to '{new}'")
+    return 0
+
+
+def cmd_default(name: str | None) -> int:
+    wallpapers = config.load()
+    aliases = config.load_aliases()
+    if name is None:
+        current = config.get_default()
+        resolved = _resolve(current, wallpapers, aliases) if current else None
+        if resolved:
+            print(resolved)
+        else:
+            print("No default set. Choose one with:  pbc default NAME")
+        return 0
+    resolved = _resolve(name, wallpapers, aliases)
+    if resolved is None:
+        return _unknown(name, wallpapers, aliases)
+    config.set_default(resolved)
+    print(f"'{resolved}' is now the default wallpaper")
+    return 0
+
+
+def cmd_remove(name: str) -> int:
+    wallpapers = config.load()
+    aliases = config.load_aliases()
+
+    if name in wallpapers:
+        removed = wallpapers.pop(name)
+        gone = _aliases_of(name, aliases)
+        for alias in gone:
+            del aliases[alias]
+        config.save(wallpapers, aliases)
+        if config.get_default() == name:
+            config.set_default(None)
+        cache.release(removed, wallpapers)
+        message = f"Removed '{name}'"
+        if gone:
+            message += f" (and its aliases: {', '.join(gone)})"
+        print(message)
+        return 0
+
+    if name in aliases:
+        target = aliases.pop(name)
+        config.save(wallpapers, aliases)
+        print(f"Removed alias '{name}' (the wallpaper '{target}' is still saved)")
+        return 0
+
+    return _error(f"Unknown wallpaper: '{name}'")
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+
+    # "pbc night" is shorthand for "pbc set night".
+    if not argv or (argv[0] not in COMMANDS and not argv[0].startswith("-")):
+        argv.insert(0, "set")
+
+    args = build_parser().parse_args(argv)
+
+    try:
+        if args.command == "set":
+            return cmd_set(args.target)
+        if args.command in ("list", "ls"):
+            return cmd_list()
+        if args.command == "add":
+            return cmd_add(args.name, args.path, args.make_default, args.aliases)
+        if args.command == "alias":
+            return cmd_alias(args.name, args.aliases)
+        if args.command == "rename":
+            return cmd_rename(args.old, args.new)
+        if args.command == "default":
+            return cmd_default(args.name)
+        if args.command in ("remove", "rm"):
+            return cmd_remove(args.name)
+        if args.command == "path":
+            print(config.config_path())
+            return 0
+    except (config.ConfigError, WallpaperError) as exc:
+        return _error(str(exc))
+    return 0

py_bg_changer-0.1.0/src/py_bg_changer/config.py

@@ -0,0 +1,117 @@
+"""Reading and writing the saved wallpapers and the chosen default.
+
+The file format is the same as the original bg.py, plus an optional default and
+optional aliases (extra names for a saved wallpaper):
+
+    {
+      "wallpapers": {"night": "/path/to/image.jpg"},
+      "aliases": {"n": "night", "dark": "night"},
+      "default": "night"
+    }
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import platform
+from pathlib import Path
+
+APP_NAME = "py-bg-changer"
+
+
+class ConfigError(Exception):
+    """The config file exists but cannot be used."""
+
+
+def config_dir() -> Path:
+    system = platform.system()
+    if system == "Windows":
+        base = Path(os.environ.get("APPDATA") or Path.home() / "AppData" / "Roaming")
+    elif system == "Darwin":
+        base = Path.home() / "Library" / "Application Support"
+    else:
+        base = Path(os.environ.get("XDG_CONFIG_HOME") or Path.home() / ".config")
+    return base / APP_NAME
+
+
+def config_path() -> Path:
+    """Default location, or whatever PBC_CONFIG points to."""
+    override = os.environ.get("PBC_CONFIG")
+    if override:
+        return Path(override).expanduser()
+    return config_dir() / "config.json"
+
+
+def _read_raw() -> dict:
+    path = config_path()
+    if not path.exists():
+        return {}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise ConfigError(f"Could not read {path}: {exc}") from exc
+    if not isinstance(data, dict):
+        raise ConfigError(f"{path} has an unexpected format (expected a JSON object).")
+    return data
+
+
+def _write(data: dict) -> None:
+    path = config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_name(path.name + ".tmp")
+    tmp.write_text(
+        json.dumps(data, indent=2, ensure_ascii=False) + "\n", encoding="utf-8"
+    )
+    tmp.replace(path)
+
+
+def load() -> dict[str, str]:
+    """Return the saved wallpapers as {name: path}. Empty if nothing is saved yet."""
+    wallpapers = _read_raw().get("wallpapers", {})
+    if not isinstance(wallpapers, dict):
+        raise ConfigError(
+            f"{config_path()}: 'wallpapers' must be an object of name -> path."
+        )
+    return {str(name): str(path) for name, path in wallpapers.items()}
+
+
+def load_aliases() -> dict[str, str]:
+    """Return the aliases as {alias: wallpaper name}. Empty if there are none."""
+    aliases = _read_raw().get("aliases", {})
+    if not isinstance(aliases, dict):
+        raise ConfigError(
+            f"{config_path()}: 'aliases' must be an object of alias -> name."
+        )
+    return {str(alias): str(name) for alias, name in aliases.items()}
+
+
+def save(wallpapers: dict[str, str], aliases: dict[str, str] | None = None) -> None:
+    """Write the wallpapers back, keeping any other keys already in the file.
+
+    The aliases are only touched when they are passed in.
+    """
+    data = _read_raw()
+    data["wallpapers"] = wallpapers
+    if aliases is not None:
+        if aliases:
+            data["aliases"] = aliases
+        else:
+            data.pop("aliases", None)
+    _write(data)
+
+
+def get_default() -> str | None:
+    """Name of the wallpaper that a plain `pbc` sets, if one was chosen."""
+    value = _read_raw().get("default")
+    return value if isinstance(value, str) and value else None
+
+
+def set_default(name: str | None) -> None:
+    """Choose the default wallpaper, or pass None to clear the choice."""
+    data = _read_raw()
+    if name is None:
+        data.pop("default", None)
+    else:
+        data["default"] = name
+    _write(data)

py_bg_changer-0.1.0/src/py_bg_changer/gui.py

@@ -0,0 +1,46 @@
+"""Entry point without a console window, for Win+R and other launchers.
+
+It runs the same commands as `pbc`, but stays silent when everything works and
+shows a small message box when something goes wrong (there is no console to
+print errors to).
+"""
+
+from __future__ import annotations
+
+import contextlib
+import io
+import sys
+
+from .cli import main as cli_main
+
+TITLE = "py-bg-changer"
+
+
+def _show_error(message: str) -> None:
+    if sys.platform == "win32":
+        import ctypes
+
+        MB_ICONERROR = 0x10
+        MB_TOPMOST = 0x40000
+        ctypes.windll.user32.MessageBoxW(
+            None, message, TITLE, MB_ICONERROR | MB_TOPMOST
+        )
+    else:
+        print(message, file=sys.stderr)
+
+
+def main(argv: list[str] | None = None) -> int:
+    out, err = io.StringIO(), io.StringIO()
+    code = 0
+    with contextlib.redirect_stdout(out), contextlib.redirect_stderr(err):
+        try:
+            code = cli_main(argv)
+        except SystemExit as exc:  # argparse exits on bad arguments, --help, --version
+            code = exc.code if isinstance(exc.code, int) else int(exc.code is not None)
+        except Exception as exc:  # never let a traceback vanish into a missing console
+            code = 1
+            err.write(f"Unexpected error: {exc}")
+    if code != 0:
+        message = err.getvalue().strip() or out.getvalue().strip()
+        _show_error(message or f"Something went wrong (exit code {code}).")
+    return code

py_bg_changer-0.1.0/src/py_bg_changer/wallpaper.py

@@ -0,0 +1,128 @@
+"""Set the desktop wallpaper on Windows, macOS and Linux."""
+
+from __future__ import annotations
+
+import os
+import platform
+import shutil
+import subprocess
+from pathlib import Path
+
+
+class WallpaperError(Exception):
+    """The wallpaper could not be applied."""
+
+
+def set_wallpaper(path: Path) -> None:
+    path = Path(path).expanduser().resolve()
+    system = platform.system()
+    if system == "Windows":
+        _windows(path)
+    elif system == "Darwin":
+        _macos(path)
+    elif system == "Linux":
+        _linux(path)
+    else:
+        raise WallpaperError(f"Unsupported operating system: {system}")
+
+
+def _run(cmd: list[str], *, check: bool = True) -> subprocess.CompletedProcess:
+    if shutil.which(cmd[0]) is None:
+        raise WallpaperError(f"'{cmd[0]}' was not found on this system.")
+    result = subprocess.run(cmd, capture_output=True, text=True)
+    if check and result.returncode != 0:
+        detail = result.stderr.strip() or f"exit code {result.returncode}"
+        raise WallpaperError(f"{cmd[0]} failed: {detail}")
+    return result
+
+
+# --- Windows ---------------------------------------------------------------
+
+
+def _windows(path: Path) -> None:
+    import ctypes
+
+    SPI_SETDESKWALLPAPER = 0x0014
+    SPIF_UPDATEINIFILE = 0x01
+    SPIF_SENDCHANGE = 0x02
+    ok = ctypes.windll.user32.SystemParametersInfoW(
+        SPI_SETDESKWALLPAPER, 0, str(path), SPIF_UPDATEINIFILE | SPIF_SENDCHANGE
+    )
+    if not ok:
+        raise WallpaperError("Windows refused to change the wallpaper.")
+
+
+# --- macOS -----------------------------------------------------------------
+
+
+def _macos(path: Path) -> None:
+    escaped = str(path).replace("\\", "\\\\").replace('"', '\\"')
+    script = (
+        'tell application "System Events" to tell every desktop '
+        f'to set picture to "{escaped}"'
+    )
+    _run(["osascript", "-e", script])
+
+
+# --- Linux -----------------------------------------------------------------
+
+
+def _linux(path: Path) -> None:
+    desktop = ":".join(
+        filter(
+            None,
+            [os.environ.get("XDG_CURRENT_DESKTOP"), os.environ.get("DESKTOP_SESSION")],
+        )
+    ).lower()
+    uri = path.as_uri()
+
+    if "cinnamon" in desktop:
+        _run(
+            ["gsettings", "set", "org.cinnamon.desktop.background", "picture-uri", uri]
+        )
+    elif "mate" in desktop:
+        _run(["gsettings", "set", "org.mate.background", "picture-filename", str(path)])
+    elif any(name in desktop for name in ("gnome", "budgie", "unity", "pantheon")):
+        _run(["gsettings", "set", "org.gnome.desktop.background", "picture-uri", uri])
+        # Newer GNOME has a separate key for dark mode; older versions don't.
+        _run(
+            [
+                "gsettings",
+                "set",
+                "org.gnome.desktop.background",
+                "picture-uri-dark",
+                uri,
+            ],
+            check=False,
+        )
+    elif "kde" in desktop or "plasma" in desktop:
+        _run(["plasma-apply-wallpaperimage", str(path)])
+    elif "xfce" in desktop:
+        _xfce(path)
+    elif "sway" in desktop:
+        _run(["swaymsg", "output", "*", "bg", str(path), "fill"])
+    else:
+        _linux_fallback(path)
+
+
+def _xfce(path: Path) -> None:
+    props = _run(["xfconf-query", "-c", "xfce4-desktop", "-l"]).stdout.splitlines()
+    targets = [p for p in props if p.endswith("/last-image")]
+    if not targets:
+        raise WallpaperError("Could not find the XFCE wallpaper settings.")
+    for prop in targets:
+        _run(["xfconf-query", "-c", "xfce4-desktop", "-p", prop, "-s", str(path)])
+
+
+def _linux_fallback(path: Path) -> None:
+    for cmd in (
+        ["feh", "--bg-fill", str(path)],
+        ["nitrogen", "--set-zoom-fill", "--save", str(path)],
+    ):
+        if shutil.which(cmd[0]):
+            _run(cmd)
+            return
+    raise WallpaperError(
+        "Could not detect your desktop environment. "
+        "Install 'feh' (or 'nitrogen') and try again."
+    )