Metadata-Version: 2.4
Name: py-bg-changer
Version: 1.2.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

[![PyPI](https://img.shields.io/pypi/v/py-bg-changer)](https://pypi.org/project/py-bg-changer/)
[![Python Versions](https://img.shields.io/pypi/pyversions/py-bg-changer)](https://pypi.org/project/py-bg-changer/)
![GitHub repo size](https://img.shields.io/github/repo-size/Mr-MRF-Dev/Py-Bg-Changer)
[![Tests](https://github.com/Mr-MRF-Dev/Py-Bg-Changer/actions/workflows/test.yml/badge.svg)](https://github.com/Mr-MRF-Dev/Py-Bg-Changer/actions/workflows/test.yml)
[![GitHub License](https://img.shields.io/github/license/Mr-MRF-Dev/Py-Bg-Changer)](/LICENSE)
[![Code Style: Black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)

<!-- ![Screenshot](/images/screenshot.gif) -->

Simple cross-platform wallpaper changer made with Python. Change your desktop wallpaper from the terminal, Win+R or any launcher. Works on Windows, macOS and Linux, with no dependencies.

The command is `py-bg-changer`, and `pbc` is the short alias for it.

> [!NOTE]
> This project is written and published **just for fun**. The goal is to try out publishing a Python package, for testing, experience and fun.

## 📥 Installation

you can install the latest version from [PyPI](https://pypi.org/project/py-bg-changer/) 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.10+.

## 📖 Usage

```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 add night img.jpg --default      # ...or make it the default right away
pbc alias night moon                 # add more aliases later
pbc rename night midnight            # rename a wallpaper or an alias
pbc default night                    # choose what a plain "pbc" sets
pbc remove night                     # forget a name (or just an alias)
pbc set night                        # set it by name (or any alias: pbc set n)
pbc night                            # set it by name (or any alias: pbc n)
pbc random                           # set a random saved wallpaper
pbc current                          # show which wallpaper is set now
pbc back                             # go back to the previous wallpaper
pbc doctor                           # check your setup if a wallpaper does not change
pbc list                             # see what you saved (* marks the default); `pbc ls` works too
pbc                                  # set the default wallpaper
```

> If a saved name clashes with a command (say, one called `list`, `ls`, `default` or `back`), use `pbc set list`.

## 🛠 Getting Started

follow the instruction to install Py Bg Changer from source (to try the latest code or to work on it):

1. Clone Code

   use [Git](https://git-scm.com/) on your system

   ```bash
   git clone https://github.com/Mr-MRF-Dev/Py-Bg-Changer.git
   ```

   or use [GitHub CLI](https://cli.github.com/)

   ```bash
   gh repo clone Mr-MRF-Dev/Py-Bg-Changer
   ```

2. Change your directory.

   ```bash
   cd Py-Bg-Changer
   ```

3. Install it with [uv](https://docs.astral.sh/uv/)

   ```bash
   uv tool install --editable .
   ```

   `--editable` means any change you make to the code is used right away. Leave it out for a normal install, or use `pip install .` if you prefer pip.

4. Check that it works

   ```bash
   pbc --version
   ```

Done :)

> to remove it later: `uv tool uninstall py-bg-changer` (your saved wallpapers and config stay where they are).

## 🏷️ Versioning

this project follows [Semantic Versioning](https://semver.org/) (`MAJOR.MINOR.PATCH`):

- **patch** (`1.0.0` → `1.0.1`): bug fixes, or small changes you want on the PyPI page
- **minor** (`1.0.0` → `1.1.0`): new features that do not break anything
- **major** (`1.0.0` → `2.0.0`): changes that break the old behavior

### 🔄 Updating the app

check which version you have:

```bash
pbc --version
```

then update with the same tool you used to install it:

| Installed with             | Update with                                                             |
| -------------------------- | ----------------------------------------------------------------------- |
| `uv tool install`          | `uv tool upgrade py-bg-changer`                                         |
| `pipx`                     | `pipx upgrade py-bg-changer`                                            |
| `pip`                      | `pip install --upgrade py-bg-changer`                                   |
| `uvx` (no install)         | `uvx --from py-bg-changer@latest pbc` (`@latest` skips the cached copy) |
| from source (`--editable`) | `git pull`, then `uv tool install --editable --reinstall .`             |

> your saved wallpapers, aliases and config are never touched by an update. Run `pbc --version` again to make sure it worked.

## 💡 Tips

- 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
  ```

  it prints nothing on success, so use `pbc` in a terminal for `list`, `default` and the like.

- `pbc random` sets one of your saved wallpapers at random. It skips images whose file is missing, and (when you have more than one) it never picks the image that is set right now, so you always get a change. To know that, the last image set is remembered in the config file under `current`. It works from Win+R too: `pbcw random`.

- On Linux with a bare X11 window manager (i3, bspwm, ...) install `feh` (`sudo pacman -S feh` on Arch). feh remembers the last wallpaper in `~/.fehbg`, so add `~/.fehbg &` to your window manager's startup to get it back after a restart.

- `pbc current` and `pbc back` only know about images that py-bg-changer set itself. The 5 previous images are kept in the config file under `history`, like a stack (the image that is set now is stored under `current`, not in `history`). `pbc back` takes the newest one (skipping images whose file is gone), and it works from Win+R too: `pbcw back`.

- If a wallpaper does not change, run `pbc doctor`. It shows your OS, desktop and session type, the config and image folder, and whether the tools that your desktop needs are installed. Please include its output when you open an issue.

- 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`). Removing an alias leaves the wallpaper alone; removing a wallpaper also removes its aliases. Renaming a wallpaper keeps its aliases, its image and its place as the default.

- 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.

- 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, or 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"
  }
  ```

## 🖥️ 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 (X11 only; other Wayland desktops are not supported yet). |

## 👨‍💻 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
```

## 🤝 Contributing

we welcome any contributions you may have. If you're interested in helping out, fork the repository and create an [Issue](https://github.com/Mr-MRF-Dev/Py-Bg-Changer/issues) and [PR](https://github.com/Mr-MRF-Dev/Py-Bg-Changer/pulls).

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](/LICENSE) file for details.
