| Name | pwr-tray JSON |
| Version |
0.9
JSON |
| download |
| home_page | None |
| Summary | A GTK tray applet for power management for i3/sway/KDE |
| upload_time | 2024-06-16 19:49:32 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | MIT |
| keywords |
power
energy
gtk
applet
tray
kde
i3wm
sway
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# pwr-tray
A GTK Tray Applet for Power/Energy Saving and System/DE Controls.
Currently supported/tested DEs are:
* i3wm
* KDE on X11
In the plans are:
* Support for these DEs:
* swaywm
* KDE on Wayland
* Gnome on X11
* Gnome on Wayland
* And, imaginably, an AppImage that bundles all the system requirements since pip/pipx
does not deal with those.
---
### Install
* Basically: `pipx install pwr-tray` (exactly how depends on your installation and its state)
* Plus, various system modules and executables.
* Manually run as `pwr-tray -o`:
* Creates config (in `~/.config/pwr-tray/config.ini`).
* Shows missing, required system-level imports (DE dependent).
* See "Installing Needed System Python Modules" (immediately below).
* Shows missing system-level commands (DE dependent). Install per distro instructions.
`systemctl` and `playerctl` are always required.
* When running manually, see the "Per-Distro Specific Notes" below for its configuration.
* Finally, see the "Using pwr-tray" for everyday use after install.
#### Installing Needed System Python Modules
* On Debian, use `sudo apt install ...` of:
* python3-gi python3-gi-cairo gir1.2-gtk-3.0
* gir1.2-appindicator3-0.1 libappindicator3-1
* On Debian 12 and others?, if the above is not working, try:
* python3-gi python3-gi-cairo gir1.2-gtk-3.0
* gir1.2-notify-0.7 gir1.2-ayatanaappindicator3-0.1 ayatanalibappindicator3-1
* On Arch, use `pacman -Syy ...` of:
* libappindicator-gtk3 python-gobject python-cairo
* On other distros, use the hints above to resolve any missing "imports".
---
## Using pwr-tray
### Manual Launch of the Applet
- For foreground in terminal, run `pwr-tray -o` ("-o" logs to stdout).
- In the background, run `setsid pwr-tray &` (logs to `~/.config/pwr-tray/debug.log`).
### Other Forms of pwr-tray
- `pwr-tray -e` edits the config file (`~/.config/pwr-ini/config.ini`)
- `pwr-tray -f` tails the log file (`~/.config/pwr-ini/debug.log`)
### Tests
- Running `pwr-tray --quick` reduces the lock and sleep timeout to 1 minute
(although you can 'click' the current value to try others),
and `--quick` runs double-time (so 1 minute timers expire in 30s per the wall clock).
- You can run in various modes, but the default, SleepAfterLock, runs thru almost every action.
- Then ensure closing the lid, hitting the power button, etc., has the desired effects.
---
# Configuration Basics
- When the program is started w/o a `config.ini`, then it is created with defaults.
- It has three sections:
* **Settings**: The settings for when plugged in. Missing/invalid settings are inherited from the defaults. Here are the defaults:
* **HiBattery**: The settings for when on battery on and not a low battery condition. Missing/invalid settings are inherited from 'Settings'.
* **LoBattery**: The settings for when on battery in a low battery condition. Missing/invalid settings are inherited from 'Settings'.
Here are the current 'Settings' defaults with explanation.
```
[Settings]
i3lock_args = -t -i ./lockpaper.png # arguments when running i3lock
debug_mode = False # more frequent and elaborate logging
power_down = False # power down (rather than Suspend)
turn_off_monitors = False # turn off monitors after locking screen
lock_min_list = [15, 30] # lock minutes choices
sleep_min_list = [5, 30] # sleep minutes choices (after lock)
lo_battery_pct = 10 # define "low battery" state
```
NOTE: I've had problems with turning off the monitors, and if you do so, then
it is harder to know the system state. If you have issues with the monitors
failing to sleep or the system cannot wake with the monitors off, then
avoid those that "feature".
### Tray Menu
Notes:
* `pwr-tray` changes directory to `~/.config/pwr-tray`.
* If .ini file is missing, it is created and `lockpaper.png` is copied there too.
* Your picks of mode and times are saved to disk when changed, and restored on the next start.
* Items may be absent depending on the mode and battery state.
* Icons change based on state:
* **Full Sun**: Presentation Mode
* **Setting Sun**: SleepAfterLock Mode ("normal")
- **Setting Sun + Moon** : SleepAfterLock Mode and Locking Screen Soon
* **Open Lock**: LockOnly Mode
- **Open Lock + Moon** : LockOnly Mode and Locking Screen Soon
* **Red Downward Triangle**: LowBattery State
* **Musical Notes**: Inhibited when playing media or by other inhibitors.
First, you may see:
- **🗲 Plugged In** (or HiBattery or LoBattery). If you click this when you don't have a battery, then it switches to the next state. This allows you to test battery state handly faily well and/or repurpose the battery config sections.
- **♺ Chg Screen Idle: 15m->30m** - change the time to start the screen saver; each time clicked, it changes to the next one.
- **♺ Chg System Idle: 5m->30m** - change the time to take the system down; clicking selects the next value.
Next, choose from three *major power modes* (to control the effects of timeouts):
- **⮀ PRESENTATION Mode** - Keeps the screen unlocked/on and system up.
- **⮀ LockOnly Mode** - Keeps the system up, but the screens may lock.
- **⮀ SleepAfterLock Mode** - Allows screen locking and system to go down (the "normal" mode).
- **NOTE**: when in LoBattery, SleepAfterLock is in effect.
The icon will change per your selection and the battery state.
Next, you may choose from various locking/blanking/DE operations:
- **â–· Lock Screen** - lock screen.
- **â–· Blank Monitors** - Blanks the screen after locking the screen.
- **â–· Reload i3** - various DE-dependent actions.
- **â–· Log Off** - terminate your user session.
Or choose a new *system state*:
- **â–¼ Suspend System** - suspends the system immediately.
- **â–¼ Reboot System** - reboots the system immediately.
- **â–¼ Poweroff System** - power down the system immediately.
Or act on the applet itself:
- **☓ Quit this Applet** - exit applet.
- **↺ Restart this Applet** - restart applet.
---
## Per-Distro Specific Notes
### i3wm Specific Notes
* Uninstall or disable all competing energy saving programs (e.g., `xscreensaver`, `xfce4-power-manager`, etc.) when running `i3` whether started by `systemd` or `i3/config` or whatever; don't forget the X11 defaults that can be defeated many ways such as in in `~/.config/i3/config`:
```
exec --no-startup-id xset s off ; xset s noblank ; xset -dpms
```
* Edit `/etc/system/logind.conf` and uncomment `HandlePowerKey=`, `HandlePowerKey=`, `HandlePowerKey=`, and `HandlePowerKey=`, and set the action to `suspend` (reboot or restart `systemd-logind`). That enables `xss-lock` to handle those keys similar to `pwr-tray`.
* In `~/.config/i3/config`, configure `xss-lock` something like:
```
set $screenlock i3lock -t -i ./lockpaper.png --ignore-empty-password --show-failed-attempts
exec --no-startup-id xss-lock --transfer-sleep-lock -- $screenlock --nofork
```
* Finally, start your pwr-tray somehow. Below is a simplest case, but it may depend on your status bar:
```
bar {
status_command i3status
tray_output primary
}
exec_always --no-startup-id ~/.local/bin/pwr-tray
```
* If you use `polybar` for status, then it may be best to run `pwr-tray` from polybar's 'launch' script, and I had to run it as `env DISPLAY=:0 pwr-tray` and delay to ensure the tray is ready.
### sway Specific Notes
* Uninstall or disable all competing energy saving programs (e.g., `swayidle`, `xfce4-power-manager`, etc.) when running `sway` whether started by `systemd` or `sway/config` or whatever.
* NOTE: on `sway`, `pwr-tray` cannot read the title time and do its usual micromanagement of
the system; instead, it runs a `swayidle` whose arguments may change with you change `pwr-tray`
settings either in the .ini file or by clicking tray items.
* Edit `/etc/system/logind.conf` and uncomment `HandlePowerKey=`, `HandlePowerKey=`,
`HandlePowerKey=`, and `HandlePowerKey=`, and set the action to `suspend`
(reboot or restart `systemd-logind`). That enables the ever-running `sway-idle` to handle
the suspend / resume events.
### KDE (X11) Specific Notes
* In Settings/Energy Saving, disable "Screen Energy Saving", "Suspend session", etc., except keep the "Button events handling" and make it as you wish (e.g., "When power button pressed", "Sleep").
* In Settings/AutoStart, add the full path of `~/.local/bin/pwr-tray`.
Raw data
{
"_id": null,
"home_page": null,
"name": "pwr-tray",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "power, energy, GTK, applet, tray, kde, i3wm, sway",
"author": null,
"author_email": "Joe Defen <joedef@google.com>",
"download_url": "https://files.pythonhosted.org/packages/d9/db/a2fa2df16940b7413137d6e84b4af2adfef2e882193315d8d0eefc1a4735/pwr_tray-0.9.tar.gz",
"platform": null,
"description": "# pwr-tray\nA GTK Tray Applet for Power/Energy Saving and System/DE Controls.\n\nCurrently supported/tested DEs are:\n* i3wm\n* KDE on X11\n\nIn the plans are:\n* Support for these DEs:\n * swaywm\n * KDE on Wayland\n * Gnome on X11\n * Gnome on Wayland\n* And, imaginably, an AppImage that bundles all the system requirements since pip/pipx\ndoes not deal with those.\n\n---\n\n### Install\n* Basically: `pipx install pwr-tray` (exactly how depends on your installation and its state)\n* Plus, various system modules and executables.\n* Manually run as `pwr-tray -o`:\n * Creates config (in `~/.config/pwr-tray/config.ini`).\n * Shows missing, required system-level imports (DE dependent).\n * See \"Installing Needed System Python Modules\" (immediately below).\n * Shows missing system-level commands (DE dependent). Install per distro instructions.\n `systemctl` and `playerctl` are always required.\n* When running manually, see the \"Per-Distro Specific Notes\" below for its configuration.\n* Finally, see the \"Using pwr-tray\" for everyday use after install.\n\n#### Installing Needed System Python Modules\n* On Debian, use `sudo apt install ...` of:\n * python3-gi python3-gi-cairo gir1.2-gtk-3.0\n * gir1.2-appindicator3-0.1 libappindicator3-1\n* On Debian 12 and others?, if the above is not working, try:\n * python3-gi python3-gi-cairo gir1.2-gtk-3.0\n * gir1.2-notify-0.7 gir1.2-ayatanaappindicator3-0.1 ayatanalibappindicator3-1\n* On Arch, use `pacman -Syy ...` of:\n * libappindicator-gtk3 python-gobject python-cairo\n* On other distros, use the hints above to resolve any missing \"imports\".\n\n---\n\n## Using pwr-tray\n\n### Manual Launch of the Applet\n- For foreground in terminal, run `pwr-tray -o` (\"-o\" logs to stdout).\n- In the background, run `setsid pwr-tray &` (logs to `~/.config/pwr-tray/debug.log`).\n### Other Forms of pwr-tray\n- `pwr-tray -e` edits the config file (`~/.config/pwr-ini/config.ini`)\n- `pwr-tray -f` tails the log file (`~/.config/pwr-ini/debug.log`)\n\n### Tests\n- Running `pwr-tray --quick` reduces the lock and sleep timeout to 1 minute\n (although you can 'click' the current value to try others),\n and `--quick` runs double-time (so 1 minute timers expire in 30s per the wall clock).\n- You can run in various modes, but the default, SleepAfterLock, runs thru almost every action.\n- Then ensure closing the lid, hitting the power button, etc., has the desired effects.\n\n---\n\n# Configuration Basics\n- When the program is started w/o a `config.ini`, then it is created with defaults.\n- It has three sections:\n * **Settings**: The settings for when plugged in. Missing/invalid settings are inherited from the defaults. Here are the defaults:\n * **HiBattery**: The settings for when on battery on and not a low battery condition. Missing/invalid settings are inherited from 'Settings'.\n * **LoBattery**: The settings for when on battery in a low battery condition. Missing/invalid settings are inherited from 'Settings'.\n\nHere are the current 'Settings' defaults with explanation.\n```\n[Settings]\ni3lock_args = -t -i ./lockpaper.png # arguments when running i3lock\ndebug_mode = False # more frequent and elaborate logging\npower_down = False # power down (rather than Suspend)\nturn_off_monitors = False # turn off monitors after locking screen\nlock_min_list = [15, 30] # lock minutes choices\nsleep_min_list = [5, 30] # sleep minutes choices (after lock)\nlo_battery_pct = 10 # define \"low battery\" state\n```\nNOTE: I've had problems with turning off the monitors, and if you do so, then\nit is harder to know the system state. If you have issues with the monitors\nfailing to sleep or the system cannot wake with the monitors off, then\navoid those that \"feature\".\n\n### Tray Menu \nNotes:\n* `pwr-tray` changes directory to `~/.config/pwr-tray`.\n* If .ini file is missing, it is created and `lockpaper.png` is copied there too.\n* Your picks of mode and times are saved to disk when changed, and restored on the next start.\n* Items may be absent depending on the mode and battery state.\n* Icons change based on state:\n * **Full Sun**: Presentation Mode\n * **Setting Sun**: SleepAfterLock Mode (\"normal\")\n - **Setting Sun + Moon** : SleepAfterLock Mode and Locking Screen Soon\n * **Open Lock**: LockOnly Mode\n - **Open Lock + Moon** : LockOnly Mode and Locking Screen Soon\n * **Red Downward Triangle**: LowBattery State\n * **Musical Notes**: Inhibited when playing media or by other inhibitors.\n\nFirst, you may see:\n- **\ud83d\uddf2 Plugged In** (or HiBattery or LoBattery). If you click this when you don't have a battery, then it switches to the next state. This allows you to test battery state handly faily well and/or repurpose the battery config sections.\n- **\u267a Chg Screen Idle: 15m->30m** - change the time to start the screen saver; each time clicked, it changes to the next one.\n- **\u267a Chg System Idle: 5m->30m** - change the time to take the system down; clicking selects the next value.\n\nNext, choose from three *major power modes* (to control the effects of timeouts):\n- **\u2b80 PRESENTATION Mode** - Keeps the screen unlocked/on and system up.\n- **\u2b80 LockOnly Mode** - Keeps the system up, but the screens may lock.\n- **\u2b80 SleepAfterLock Mode** - Allows screen locking and system to go down (the \"normal\" mode).\n- **NOTE**: when in LoBattery, SleepAfterLock is in effect.\n The icon will change per your selection and the battery state.\n\n\nNext, you may choose from various locking/blanking/DE operations:\n- **\u25b7 Lock Screen** - lock screen.\n- **\u25b7 Blank Monitors** - Blanks the screen after locking the screen.\n- **\u25b7 Reload i3** - various DE-dependent actions.\n- **\u25b7 Log Off** - terminate your user session.\n\nOr choose a new *system state*:\n- **\u25bc Suspend System** - suspends the system immediately.\n- **\u25bc Reboot System** - reboots the system immediately.\n- **\u25bc Poweroff System** - power down the system immediately.\n\nOr act on the applet itself:\n- **\u2613 Quit this Applet** - exit applet.\n- **\u21ba Restart this Applet** - restart applet.\n\n---\n\n## Per-Distro Specific Notes\n\n### i3wm Specific Notes\n* Uninstall or disable all competing energy saving programs (e.g., `xscreensaver`, `xfce4-power-manager`, etc.) when running `i3` whether started by `systemd` or `i3/config` or whatever; don't forget the X11 defaults that can be defeated many ways such as in in `~/.config/i3/config`:\n```\n exec --no-startup-id xset s off ; xset s noblank ; xset -dpms\n```\n* Edit `/etc/system/logind.conf` and uncomment `HandlePowerKey=`, `HandlePowerKey=`, `HandlePowerKey=`, and `HandlePowerKey=`, and set the action to `suspend` (reboot or restart `systemd-logind`). That enables `xss-lock` to handle those keys similar to `pwr-tray`.\n* In `~/.config/i3/config`, configure `xss-lock` something like:\n```\n set $screenlock i3lock -t -i ./lockpaper.png --ignore-empty-password --show-failed-attempts\n exec --no-startup-id xss-lock --transfer-sleep-lock -- $screenlock --nofork\n```\n* Finally, start your pwr-tray somehow. Below is a simplest case, but it may depend on your status bar:\n```\n bar { \n status_command i3status\n tray_output primary\n }\n exec_always --no-startup-id ~/.local/bin/pwr-tray\n```\n* If you use `polybar` for status, then it may be best to run `pwr-tray` from polybar's 'launch' script, and I had to run it as `env DISPLAY=:0 pwr-tray` and delay to ensure the tray is ready.\n\n### sway Specific Notes\n* Uninstall or disable all competing energy saving programs (e.g., `swayidle`, `xfce4-power-manager`, etc.) when running `sway` whether started by `systemd` or `sway/config` or whatever.\n* NOTE: on `sway`, `pwr-tray` cannot read the title time and do its usual micromanagement of\n the system; instead, it runs a `swayidle` whose arguments may change with you change `pwr-tray`\n settings either in the .ini file or by clicking tray items.\n* Edit `/etc/system/logind.conf` and uncomment `HandlePowerKey=`, `HandlePowerKey=`,\n `HandlePowerKey=`, and `HandlePowerKey=`, and set the action to `suspend`\n (reboot or restart `systemd-logind`). That enables the ever-running `sway-idle` to handle\n the suspend / resume events.\n\n### KDE (X11) Specific Notes\n* In Settings/Energy Saving, disable \"Screen Energy Saving\", \"Suspend session\", etc., except keep the \"Button events handling\" and make it as you wish (e.g., \"When power button pressed\", \"Sleep\").\n* In Settings/AutoStart, add the full path of `~/.local/bin/pwr-tray`.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A GTK tray applet for power management for i3/sway/KDE",
"version": "0.9",
"project_urls": {
"Bug Tracker": "https://github.com/joedefen/pwr-tray/issues",
"Homepage": "https://github.com/joedefen/pwr-tray"
},
"split_keywords": [
"power",
" energy",
" gtk",
" applet",
" tray",
" kde",
" i3wm",
" sway"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d59b86723dc1c62e7d5617ba7a9d5a47a48d17fd09f585fe51815e1c19c11210",
"md5": "fad5c8045af955b01c3fc78182c94ead",
"sha256": "3affbaedcee626bc270e2a145b6f48b700a2698196b5b38d2b9b6aa89720b17e"
},
"downloads": -1,
"filename": "pwr_tray-0.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fad5c8045af955b01c3fc78182c94ead",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 46077,
"upload_time": "2024-06-16T19:49:30",
"upload_time_iso_8601": "2024-06-16T19:49:30.696158Z",
"url": "https://files.pythonhosted.org/packages/d5/9b/86723dc1c62e7d5617ba7a9d5a47a48d17fd09f585fe51815e1c19c11210/pwr_tray-0.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d9dba2fa2df16940b7413137d6e84b4af2adfef2e882193315d8d0eefc1a4735",
"md5": "531f72fe4aee0cb134061b6e45a9a752",
"sha256": "12e32ccde696c9a2dd5ca5f8208e80f7d23d4866c9dac7b8f9c2f967bbe3bc60"
},
"downloads": -1,
"filename": "pwr_tray-0.9.tar.gz",
"has_sig": false,
"md5_digest": "531f72fe4aee0cb134061b6e45a9a752",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 44680,
"upload_time": "2024-06-16T19:49:32",
"upload_time_iso_8601": "2024-06-16T19:49:32.624408Z",
"url": "https://files.pythonhosted.org/packages/d9/db/a2fa2df16940b7413137d6e84b4af2adfef2e882193315d8d0eefc1a4735/pwr_tray-0.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-16 19:49:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "joedefen",
"github_project": "pwr-tray",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pwr-tray"
}
