# [kshift](https://github.com/justjokiing/kshift): A KDE Plasma Theme Switcher
## Overview
kshift is a dynamic theme manager for KDE Plasma that automatically changes your system's theme (color scheme, icon theme, desktop theme, and wallpaper) based on predefined schedules, times of day, or solar events (e.g., sunrise and sunset). It supports advanced configurations using `systemd` timers, making it a highly customizable solution for KDE Plasma users who want seamless transitions between themes.
## Demo
https://github.com/user-attachments/assets/c18332df-b3b7-4bda-9254-e061a7fa0367
## Why Use kshift?
**Effortless and Dynamic Theme Automation**: Save time by automating theme changes for morning, evening, or specific events without manual adjustments. Coordinate your system's appearance with colorschemes, wallpapers, cursorthemes, icon themes, and desktop themes that match the time of day or occasion.
**Customizable and Reliable Schedules**: Define unique schedules for themes using flexible time settings or solar events like sunrise and sunset. With systemd integration, theme changes are guaranteed to occur on time, even after system reboots.
**Simple and Lightweight**: kshift is built around a straightforward CLI interface and a single YAML configuration file. This design keeps it lightweight and efficient, with no background processes required. By leveraging systemd for scheduling, kshift ensures seamless theme transitions with minimal system resource usage.
## Installation
### Prerequisites
Ensure you have the following installed:
- KDE Plasma
- systemd
- Python 3.7+
- Pip
### Install via `pip`
```bash
pip install kshift
```
### Setup
Run the following command to install kshift's systemd services and timers:
```bash
kshift install
```
This creates necessary configuration and systemd files in your user directory.
## Configuration
kshift uses a YAML configuration file, created during `install` and located at `~/.config/kshift/kshift.yml`. Below is a guide to setting up and customizing your configuration.
Use the command `kshift conf` to open the configuration file in your default editor. Load and confirm this configuration by running `kshift`
### Default Configuration
```yaml
latitude: 39
longitude: -77
sunrise: '08:00'
sunset: '18:00'
rise_delay: 0
set_delay: 0
webdata: true
net_timeout: 10
themes:
day:
colorscheme: BreezeLight
time: sunrise
night:
colorscheme: BreezeDark
time: sunset
```
### Key Configuration Parameters
#### Global Settings
All global parameters are optional; if not provided, they will use the default values as shown in the Default Configuration section above.
| Parameter | Description |
| ------------- | ------------------------------------------------------- |
| `latitude` | Latitude coordinate for solar data |
| `longitude` | Longitude coordinate for solar data |
| `sunrise` | Default sunrise time in `HH:MM` format |
| `sunset` | Default sunset time in `HH:MM` format |
| `rise_delay` | Delay sunrise by the specified hours (negative allowed) |
| `set_delay` | Delay sunset by the specified hours (negative allowed) |
| `webdata` | Enable or disable fetching solar data from the web |
| `net_timeout` | Timeout for fetching solar data in seconds |
#### Themes
All parameters are optional, but to enable automatic theme switching, a `time` variable must be specified.
| Parameter | Description | Example Value |
| -------------- | --------------------------------------------------- | --------------------------------- |
| `colorscheme` | Name of the Plasma color scheme | `BreezeLight` |
| `cursortheme` | Name of the Plasma cursor theme | `HighContrast` |
| `desktoptheme` | Name of the Plasma desktop theme | `Breeze` |
| `icontheme` | Name of the icon theme | `Papirus-Dark` |
| `wallpaper` | Path to the wallpaper image | `~/Pictures/morning.jpg` |
| `command` | Custom command to execute when the theme is applied | `echo 'Theme applied'` |
| `time` | Schedule for theme activation | `sunset`, `HH:MM`, `weekly` |
The `time` variable must either be a sun position (sunrise/sunset), a simple 24HR time (HH:MM), or a string that is a valid `systemd OnCalendar` time.
If you use a sun position, this will be converted to a 24HR time using the coordinate variables of the configuration.
`OnCalendar` uses a cron-like expression that can represent one or more times in a single expression. More information on this format [here](https://www.freedesktop.org/software/systemd/man/latest/systemd.time.html#Calendar%20Events)
## Usage
### Command-Line Options
Run `kshift` with various options:
- `theme [THEME_NAME]`: Apply a specific theme by name. If no name is provided, kshift determines the appropriate theme to apply based on time and configuration.
- Positional argument `[THEME_NAME]`: Optional. Specify the theme to apply.
- `-c, --colorscheme <scheme>`: Apply a specific colorscheme (overrides the theme configuration).
- `-csr, --cursortheme <theme>`: Apply a specific cursor theme (overrides the theme configuration).
- `-dk, --desktop_theme <theme>`: Apply a specific desktop theme (overrides the theme configuration).
- `-i, --icontheme <theme>`: Apply a specific icon theme (overrides the theme configuration).
- `-w, --wallpaper <path>`: Apply a specific wallpaper (overrides the theme configuration).
- `install`: Install systemd services and timers for kshift.
- `remove`: Remove systemd services and timers for kshift.
- `status`: Display the current status of kshift and active timers.
- `config`: Open the kshift configuration file in the default editor for editing.
- `logs`: View the most recent entries from the kshift log file.
- `list`: List possible themes or attributes
### Examples
| **Command** | **Description** |
|--------------------------------------------|------------------------------------------------------------------|
| `kshift theme night` | Apply a theme by name. |
| `kshift` | Have kshift determine the current theme and apply it. |
| `kshift status` | Check current status. |
| `kshift theme night -c BreezeLight -w ~/cat.png` | Apply a theme with modifications. |
| `kshift theme -w ~/cat.png` | Apply a theme attribute with no theme. |
| `kshift list themes` | List available kshift themes |
| `kshift list colorschemes` | List available colorschemes |
## Systemd Integration
kshift leverages `systemd` timers to provide robust and reliable automation of theme changes. This integration ensures that:
1. **Timely Theme Switching**: Each theme is tied to a `systemd` timer, which allows precise scheduling of theme changes based on time or solar events.
2. **Automatic Startup**: A dedicated startup timer ensures that kshift applies the correct theme when your system boots up.
3. **Flexibility with OnCalendar**: `systemd`'s `OnCalendar` expressions provide flexibility for advanced scheduling. For example, you can schedule themes to activate at exact times, specific days of the week, or even recurring intervals.
### How It Works
- When you install kshift (`kshift install`), it creates a `systemd` service and timer for each theme defined in your configuration.
- The templates used for the services and timers are located in your configuration directory, where if you edit them, their changes will be reflected in the next write.
- The timers are then activated, and `systemd` ensures that the correct theme is applied at the scheduled time.
- The startup timer runs shortly after the system boots, ensuring that kshift applies the most relevant theme based on the current time.
## Uninstallation
To remove kshift, run:
1. `kshift remove`
This disables and removes all related systemd timers and services.
2. `pip uninstall kshift`
Removes the `kshift` package from your computer
Raw data
{
"_id": null,
"home_page": null,
"name": "kshift",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "KDE, KDE Plasma, Linux, Plasma, automation, color scheme, cron replacement, desktop customization, desktop environment, icon theme, script, sunrise sunset, systemd, theme, theme switching, timers, wallpaper",
"author": null,
"author_email": "Seth Mackert <seth.mackert@fastsycamore.com>",
"download_url": "https://files.pythonhosted.org/packages/8a/e9/90235057fa2ce03e7860f23bd01ce5c6e20973d9d525d0d5bd7956e95442/kshift-1.2.0.tar.gz",
"platform": null,
"description": "# [kshift](https://github.com/justjokiing/kshift): A KDE Plasma Theme Switcher\n\n## Overview\n\nkshift is a dynamic theme manager for KDE Plasma that automatically changes your system's theme (color scheme, icon theme, desktop theme, and wallpaper) based on predefined schedules, times of day, or solar events (e.g., sunrise and sunset). It supports advanced configurations using `systemd` timers, making it a highly customizable solution for KDE Plasma users who want seamless transitions between themes.\n\n## Demo\n\nhttps://github.com/user-attachments/assets/c18332df-b3b7-4bda-9254-e061a7fa0367\n\n## Why Use kshift?\n\n**Effortless and Dynamic Theme Automation**: Save time by automating theme changes for morning, evening, or specific events without manual adjustments. Coordinate your system's appearance with colorschemes, wallpapers, cursorthemes, icon themes, and desktop themes that match the time of day or occasion.\n\n**Customizable and Reliable Schedules**: Define unique schedules for themes using flexible time settings or solar events like sunrise and sunset. With systemd integration, theme changes are guaranteed to occur on time, even after system reboots.\n\n**Simple and Lightweight**: kshift is built around a straightforward CLI interface and a single YAML configuration file. This design keeps it lightweight and efficient, with no background processes required. By leveraging systemd for scheduling, kshift ensures seamless theme transitions with minimal system resource usage.\n\n\n## Installation\n\n### Prerequisites\n\nEnsure you have the following installed:\n\n- KDE Plasma\n- systemd\n- Python 3.7+\n- Pip\n\n### Install via `pip`\n\n```bash\npip install kshift\n```\n\n### Setup\n\nRun the following command to install kshift's systemd services and timers:\n\n```bash\nkshift install\n```\n\nThis creates necessary configuration and systemd files in your user directory.\n\n## Configuration\n\nkshift uses a YAML configuration file, created during `install` and located at `~/.config/kshift/kshift.yml`. Below is a guide to setting up and customizing your configuration.\n\nUse the command `kshift conf` to open the configuration file in your default editor. Load and confirm this configuration by running `kshift`\n\n### Default Configuration\n\n```yaml\nlatitude: 39\nlongitude: -77\nsunrise: '08:00'\nsunset: '18:00'\nrise_delay: 0\nset_delay: 0\nwebdata: true\nnet_timeout: 10\nthemes:\n day:\n colorscheme: BreezeLight\n time: sunrise\n night:\n colorscheme: BreezeDark\n time: sunset\n```\n\n### Key Configuration Parameters\n\n#### Global Settings\n\nAll global parameters are optional; if not provided, they will use the default values as shown in the Default Configuration section above.\n\n| Parameter | Description |\n| ------------- | ------------------------------------------------------- |\n| `latitude` | Latitude coordinate for solar data |\n| `longitude` | Longitude coordinate for solar data |\n| `sunrise` | Default sunrise time in `HH:MM` format |\n| `sunset` | Default sunset time in `HH:MM` format |\n| `rise_delay` | Delay sunrise by the specified hours (negative allowed) |\n| `set_delay` | Delay sunset by the specified hours (negative allowed) |\n| `webdata` | Enable or disable fetching solar data from the web |\n| `net_timeout` | Timeout for fetching solar data in seconds |\n\n#### Themes\n\nAll parameters are optional, but to enable automatic theme switching, a `time` variable must be specified.\n\n| Parameter | Description | Example Value |\n| -------------- | --------------------------------------------------- | --------------------------------- |\n| `colorscheme` | Name of the Plasma color scheme | `BreezeLight` |\n| `cursortheme` | Name of the Plasma cursor theme | `HighContrast` |\n| `desktoptheme` | Name of the Plasma desktop theme | `Breeze` |\n| `icontheme` | Name of the icon theme | `Papirus-Dark` |\n| `wallpaper` | Path to the wallpaper image | `~/Pictures/morning.jpg` |\n| `command` | Custom command to execute when the theme is applied | `echo 'Theme applied'` |\n| `time` | Schedule for theme activation | `sunset`, `HH:MM`, `weekly` |\n\nThe `time` variable must either be a sun position (sunrise/sunset), a simple 24HR time (HH:MM), or a string that is a valid `systemd OnCalendar` time. \n\nIf you use a sun position, this will be converted to a 24HR time using the coordinate variables of the configuration.\n\n`OnCalendar` uses a cron-like expression that can represent one or more times in a single expression. More information on this format [here](https://www.freedesktop.org/software/systemd/man/latest/systemd.time.html#Calendar%20Events)\n\n## Usage\n\n### Command-Line Options\n\nRun `kshift` with various options:\n\n- `theme [THEME_NAME]`: Apply a specific theme by name. If no name is provided, kshift determines the appropriate theme to apply based on time and configuration.\n - Positional argument `[THEME_NAME]`: Optional. Specify the theme to apply.\n - `-c, --colorscheme <scheme>`: Apply a specific colorscheme (overrides the theme configuration).\n - `-csr, --cursortheme <theme>`: Apply a specific cursor theme (overrides the theme configuration).\n - `-dk, --desktop_theme <theme>`: Apply a specific desktop theme (overrides the theme configuration).\n - `-i, --icontheme <theme>`: Apply a specific icon theme (overrides the theme configuration).\n - `-w, --wallpaper <path>`: Apply a specific wallpaper (overrides the theme configuration).\n- `install`: Install systemd services and timers for kshift.\n- `remove`: Remove systemd services and timers for kshift.\n- `status`: Display the current status of kshift and active timers.\n- `config`: Open the kshift configuration file in the default editor for editing.\n- `logs`: View the most recent entries from the kshift log file.\n- `list`: List possible themes or attributes\n\n### Examples\n| **Command** | **Description** |\n|--------------------------------------------|------------------------------------------------------------------|\n| `kshift theme night` | Apply a theme by name. |\n| `kshift` | Have kshift determine the current theme and apply it. |\n| `kshift status` | Check current status. |\n| `kshift theme night -c BreezeLight -w ~/cat.png` | Apply a theme with modifications. |\n| `kshift theme -w ~/cat.png` | Apply a theme attribute with no theme. |\n| `kshift list themes` | List available kshift themes |\n| `kshift list colorschemes` | List available colorschemes |\n\n\n## Systemd Integration\n\nkshift leverages `systemd` timers to provide robust and reliable automation of theme changes. This integration ensures that:\n\n1. **Timely Theme Switching**: Each theme is tied to a `systemd` timer, which allows precise scheduling of theme changes based on time or solar events.\n2. **Automatic Startup**: A dedicated startup timer ensures that kshift applies the correct theme when your system boots up.\n3. **Flexibility with OnCalendar**: `systemd`'s `OnCalendar` expressions provide flexibility for advanced scheduling. For example, you can schedule themes to activate at exact times, specific days of the week, or even recurring intervals.\n\n### How It Works\n\n- When you install kshift (`kshift install`), it creates a `systemd` service and timer for each theme defined in your configuration.\n- The templates used for the services and timers are located in your configuration directory, where if you edit them, their changes will be reflected in the next write.\n- The timers are then activated, and `systemd` ensures that the correct theme is applied at the scheduled time.\n- The startup timer runs shortly after the system boots, ensuring that kshift applies the most relevant theme based on the current time.\n\n## Uninstallation\n\nTo remove kshift, run:\n\n1. `kshift remove` \n\n This disables and removes all related systemd timers and services.\n\n2. `pip uninstall kshift`\n\n Removes the `kshift` package from your computer\n",
"bugtrack_url": null,
"license": "GPL-3.0-or-later",
"summary": "KDE Theme Shift",
"version": "1.2.0",
"project_urls": {
"Homepage": "https://github.com/justjokiing/kshift"
},
"split_keywords": [
"kde",
" kde plasma",
" linux",
" plasma",
" automation",
" color scheme",
" cron replacement",
" desktop customization",
" desktop environment",
" icon theme",
" script",
" sunrise sunset",
" systemd",
" theme",
" theme switching",
" timers",
" wallpaper"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ea8b4053fcd9ac3e82a0623beccbf97c903a5160c0a37d5d5bc666eb19ebc8bb",
"md5": "4e6dd49cb70b8d39e594145d7dd8b8f2",
"sha256": "286d3094c52adacf89d9e96dbace6f5d252ceb99ccb3ce9e2e7d2cb8cdafe2f8"
},
"downloads": -1,
"filename": "kshift-1.2.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "4e6dd49cb70b8d39e594145d7dd8b8f2",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 28539,
"upload_time": "2025-01-17T17:41:59",
"upload_time_iso_8601": "2025-01-17T17:41:59.764494Z",
"url": "https://files.pythonhosted.org/packages/ea/8b/4053fcd9ac3e82a0623beccbf97c903a5160c0a37d5d5bc666eb19ebc8bb/kshift-1.2.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8ae990235057fa2ce03e7860f23bd01ce5c6e20973d9d525d0d5bd7956e95442",
"md5": "ada1a18c838ec3774b9e53a94fd5ddd4",
"sha256": "93ca66f96e2902b30719c7b3385c757554275ff491d08e656efbb3ffad146bab"
},
"downloads": -1,
"filename": "kshift-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "ada1a18c838ec3774b9e53a94fd5ddd4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 29240,
"upload_time": "2025-01-17T17:42:02",
"upload_time_iso_8601": "2025-01-17T17:42:02.584600Z",
"url": "https://files.pythonhosted.org/packages/8a/e9/90235057fa2ce03e7860f23bd01ce5c6e20973d9d525d0d5bd7956e95442/kshift-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-17 17:42:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "justjokiing",
"github_project": "kshift",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "click",
"specs": []
},
{
"name": "colorama",
"specs": []
},
{
"name": "pydantic",
"specs": []
},
{
"name": "pytest",
"specs": []
},
{
"name": "pytest-mock",
"specs": []
},
{
"name": "PyYAML",
"specs": []
},
{
"name": "Requests",
"specs": []
}
],
"lcname": "kshift"
}
JSON
