| Name | panelstatus JSON |
| Version |
1.1.0
JSON |
| download |
| home_page | None |
| Summary | Dead simple GNOME panel status updates - inspired by ggplot2 |
| upload_time | 2025-10-11 14:11:15 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.7 |
| license | MIT |
| keywords |
gnome
status
panel
notification
gui
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# PanelStatus 📊
**Dead simple GNOME panel status updates** - Inspired by ggplot2's ease of use
Display static text, scrolling messages, and more in your GNOME top panel with just one line of Python!
## Installation
```python
from panelstatus import install_extension, restart_shell
# Install the GNOME extension
install_extension()
# Restart GNOME Shell automatically
restart_shell()
```
Or use the command line:
```bash
pip install panelstatus
python3 -c "from panelstatus import install_extension, restart_shell; install_extension(); restart_shell()"
```
## Features
✨ **Static text** - Show status messages
🎬 **Smooth scrolling** - Perfect for long messages
🎨 **Colors** - Named colors or custom hex codes
⚡ **Fast** - Minimal overhead, smooth 60fps animations
🐍 **Pythonic** - Simple, intuitive API
📦 **Self-installing** - Extension installs with one function call!
🔀 **Multi-process** - Multiple apps can display simultaneously with automatic space allocation
## Quick Start
```python
from panelstatus import status
# Static text
status.set("Processing...", color="blue")
# Scrolling text
status.scroll("This is a long message that scrolls smoothly!")
# Clear
status.clear()
```
## Usage
### Basic Static Status
```python
from panelstatus import status
status.set("Processing...")
status.set("Done!", color="green")
status.clear()
```
### Scrolling Text
```python
# For long messages
status.scroll("This is a long message that scrolls smoothly across your panel! ")
# With color
status.scroll("Welcome to my app!", color="blue")
# Control speed (1.0 = default, 2.0 = 2x faster, 0.5 = slower)
status.scroll("Slow scroll...", speed=0.5)
status.scroll("Fast scroll!", speed=2.0)
# Adjust display width
status.scroll("Custom width", width=200)
```
### Switch Between Modes
```python
import time
status.set("Starting task...", color="yellow")
time.sleep(2)
status.scroll("Processing lots of data... this might take a while...")
time.sleep(5)
status.set("Complete!", color="green")
```
### Colors
**Named colors:**
- `red`, `green`, `blue`
- `yellow`, `orange`, `purple`
- `gray`, `white`
**Custom hex codes:**
```python
status.set("Custom", color="#ff00ff")
```
### Log Feed (Streaming Logs)
```python
# Perfect for continuous log updates!
status.feed("Server started")
status.feed("Connected to database")
status.feed("Ready on port 8080")
# Shows: "Server started | Connected to database | Ready on port 8080" (scrolling)
# Customize separator and buffer size
status.feed("Log line", max_lines=10, separator=" • ")
```
### Progressive Append (Smart Scrolling)
```python
# Accumulates text, stays static until too long, then scrolls to end
status.append("Starting...")
status.append("Step 1 complete")
status.append("Step 2 complete")
status.append("All done!")
# Three scrolling modes:
# 1. INSTANT - Jump immediately to new content (best for alerts)
status.append("Error occurred!", scroll_mode="instant", color="red")
# 2. SMOOTH - Zen-like constant scrolling (default, best for ambience)
status.append("Processing...", scroll_mode="smooth", scroll_speed=0.5)
# 3. ADAPTIVE - Speed up when behind, slow down when caught up
# (best for progress tracking)
status.append("Task complete", scroll_mode="adaptive",
scroll_min=0.5, scroll_max=4.0, color="green")
```
**Choosing the right scroll mode:**
| Mode | Behavior | Best For | Example Use Case |
|------|----------|----------|------------------|
| `instant` | Jumps immediately to new content | Real-time alerts, monitoring | Error notifications, system alerts |
| `smooth` | Constant zen-like scrolling | Ambient displays, background processes | Build progress, server status |
| `adaptive` | Speeds up when behind, slows when caught up | Progress tracking, log streaming | Test results, batch processing |
### Context Manager (Auto-clear)
```python
with status.show("Working...", color="blue"):
# Your code here
do_something()
# Status automatically cleared!
```
### Multi-Process Support
Multiple applications can display status simultaneously with automatic space allocation:
```python
# Process 1: Build system
build_status = Status(id="build")
build_status.set_weight(2.0) # Gets 2x space
build_status.append("Compiling...", color="blue")
# Process 2: Test runner
test_status = Status(id="tests")
test_status.set_weight(1.0) # Default weight
test_status.append("Running tests...", color="green")
# They appear side-by-side: [Compiling...] [Running tests...]
```
**Space Allocation:**
- Extension uses max 40% of panel width by default
- Space divided among processes based on weights
- Automatic cleanup after 30s of inactivity
- Dynamic reallocation when processes start/stop
## API Reference
### `Status(id=None)`
Create a status controller instance.
**Args:**
- `id` (str, optional): Unique process identifier for multi-process support. If None (default), uses singleton mode.
**Example:**
```python
# Single process (default)
from panelstatus import status
status.set("Working...")
# Multi-process
build = Status(id="build")
tests = Status(id="tests")
```
### `set_weight(weight)`
Set space allocation weight for multi-process display.
**Args:**
- `weight` (float): Space allocation multiplier (default 1.0). Higher = more space.
**Example:**
```python
build_status = Status(id="build")
build_status.set_weight(2.0) # Gets 2x space
```
### `install_extension()`
Install the GNOME Shell extension (one-time setup).
```python
from panelstatus import install_extension
install_extension()
```
### `restart_shell()`
Restart GNOME Shell to reload extensions (X11 only).
```python
from panelstatus import restart_shell
restart_shell()
```
### `status.set(text, color=None)`
Display static text in the panel.
**Args:**
- `text` (str): Message to display
- `color` (str, optional): Color name or hex code
### `status.scroll(text, color=None, speed=1.0, width=150)`
Display scrolling text (perfect for long messages).
**Args:**
- `text` (str): Message to scroll
- `color` (str, optional): Color name or hex code
- `speed` (float, optional): Scroll speed multiplier (default 1.0)
- `width` (int, optional): Display width in pixels (default 150)
### `status.feed(text, color=None, max_lines=5, separator=" | ", speed=1.0, width=200)`
Add text to a rolling log feed.
**Args:**
- `text` (str): Log line to add
- `color` (str, optional): Color name or hex code
- `max_lines` (int, optional): Buffer size (default 5)
- `separator` (str, optional): Text between lines (default " | ")
- `speed` (float, optional): Scroll speed multiplier
- `width` (int, optional): Display width in pixels
### `status.append(text, color=None, separator=" ", width=300, scroll_mode="smooth", scroll_speed=1.0, scroll_min=0.3, scroll_max=3.0)`
Append text progressively with configurable scrolling behavior.
Text stays static until it exceeds the panel width, then scrolls to the end and stops. Adding more text resumes scrolling.
**Args:**
- `text` (str): Text to append
- `color` (str, optional): Color name or hex code
- `separator` (str, optional): Text between appends (default " ")
- `width` (int, optional): Display width in pixels (default 300)
- `scroll_mode` (str, optional): Scrolling behavior - "instant", "smooth", or "adaptive" (default "smooth")
- `scroll_speed` (float, optional): Speed multiplier for smooth mode (default 1.0)
- `scroll_min` (float, optional): Minimum speed for adaptive mode (default 0.3)
- `scroll_max` (float, optional): Maximum speed for adaptive mode (default 3.0)
**Scroll Modes:**
- `"instant"`: Jump immediately to show new content (best for real-time alerts)
- `"smooth"`: Constant zen-like scrolling (best for ambient displays)
- `"adaptive"`: Variable speed - accelerates when far behind, slows when caught up (best for progress tracking)
### `status.clear()`
Remove status from panel.
### `status.show(text, color=None)`
Context manager that auto-clears when done.
## Real-World Examples
**Long-running task:**
```python
from panelstatus import status
import requests
status.scroll("Downloading data from API... ")
data = requests.get("https://api.example.com/data").json()
status.set("Processing...", color="yellow")
results = process(data)
status.set("Complete! ✓", color="green")
```
**Build script:**
```python
status.set("Building...", color="blue")
os.system("npm run build")
status.set("Build complete!", color="green")
```
**Training progress:**
```python
for epoch in range(100):
status.scroll(f"Training epoch {epoch}/100... ", color="orange")
train_model(epoch)
status.set("Training complete!", color="green")
```
## Philosophy
Like **ggplot2 made plotting simple**, PanelStatus makes status updates trivial:
- ✅ **Simple API** - Just `status.set()` or `status.scroll()` and go
- ✅ **Sensible defaults** - Works beautifully out of the box
- ✅ **Minimal boilerplate** - No complex setup or configuration
- ✅ **Pythonic** - Feels natural and intuitive
- ✅ **Versatile** - Static text, scrolling, colors, auto-clear
- ✅ **Self-contained** - Extension bundles with the library
## Try the Demo
Run the example to see all features:
```bash
python3 ~/panelstatus-lib/example.py
```
Watch your panel for static messages, smooth scrolling, and color changes!
---
**Enjoy simple status updates!** 🎉
Raw data
{
"_id": null,
"home_page": null,
"name": "panelstatus",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "gnome, status, panel, notification, gui",
"author": null,
"author_email": "Maxime Rivest <mrive052@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/92/17/84a1e8950b71c1575cb843c2c3781e2b81b9f441d46bb86a0d5d730494df/panelstatus-1.1.0.tar.gz",
"platform": null,
"description": "# PanelStatus \ud83d\udcca\n\n**Dead simple GNOME panel status updates** - Inspired by ggplot2's ease of use\n\nDisplay static text, scrolling messages, and more in your GNOME top panel with just one line of Python!\n\n## Installation\n\n```python\nfrom panelstatus import install_extension, restart_shell\n\n# Install the GNOME extension\ninstall_extension()\n\n# Restart GNOME Shell automatically\nrestart_shell()\n```\n\nOr use the command line:\n```bash\npip install panelstatus\npython3 -c \"from panelstatus import install_extension, restart_shell; install_extension(); restart_shell()\"\n```\n\n## Features\n\n\u2728 **Static text** - Show status messages\n\ud83c\udfac **Smooth scrolling** - Perfect for long messages\n\ud83c\udfa8 **Colors** - Named colors or custom hex codes\n\u26a1 **Fast** - Minimal overhead, smooth 60fps animations\n\ud83d\udc0d **Pythonic** - Simple, intuitive API\n\ud83d\udce6 **Self-installing** - Extension installs with one function call!\n\ud83d\udd00 **Multi-process** - Multiple apps can display simultaneously with automatic space allocation\n\n## Quick Start\n\n```python\nfrom panelstatus import status\n\n# Static text\nstatus.set(\"Processing...\", color=\"blue\")\n\n# Scrolling text\nstatus.scroll(\"This is a long message that scrolls smoothly!\")\n\n# Clear\nstatus.clear()\n```\n\n## Usage\n\n### Basic Static Status\n\n```python\nfrom panelstatus import status\n\nstatus.set(\"Processing...\")\nstatus.set(\"Done!\", color=\"green\")\nstatus.clear()\n```\n\n### Scrolling Text\n\n```python\n# For long messages\nstatus.scroll(\"This is a long message that scrolls smoothly across your panel! \")\n\n# With color\nstatus.scroll(\"Welcome to my app!\", color=\"blue\")\n\n# Control speed (1.0 = default, 2.0 = 2x faster, 0.5 = slower)\nstatus.scroll(\"Slow scroll...\", speed=0.5)\nstatus.scroll(\"Fast scroll!\", speed=2.0)\n\n# Adjust display width\nstatus.scroll(\"Custom width\", width=200)\n```\n\n### Switch Between Modes\n\n```python\nimport time\n\nstatus.set(\"Starting task...\", color=\"yellow\")\ntime.sleep(2)\n\nstatus.scroll(\"Processing lots of data... this might take a while...\")\ntime.sleep(5)\n\nstatus.set(\"Complete!\", color=\"green\")\n```\n\n### Colors\n\n**Named colors:**\n- `red`, `green`, `blue`\n- `yellow`, `orange`, `purple`\n- `gray`, `white`\n\n**Custom hex codes:**\n```python\nstatus.set(\"Custom\", color=\"#ff00ff\")\n```\n\n### Log Feed (Streaming Logs)\n\n```python\n# Perfect for continuous log updates!\nstatus.feed(\"Server started\")\nstatus.feed(\"Connected to database\")\nstatus.feed(\"Ready on port 8080\")\n\n# Shows: \"Server started | Connected to database | Ready on port 8080\" (scrolling)\n\n# Customize separator and buffer size\nstatus.feed(\"Log line\", max_lines=10, separator=\" \u2022 \")\n```\n\n### Progressive Append (Smart Scrolling)\n\n```python\n# Accumulates text, stays static until too long, then scrolls to end\nstatus.append(\"Starting...\")\nstatus.append(\"Step 1 complete\")\nstatus.append(\"Step 2 complete\")\nstatus.append(\"All done!\")\n\n# Three scrolling modes:\n\n# 1. INSTANT - Jump immediately to new content (best for alerts)\nstatus.append(\"Error occurred!\", scroll_mode=\"instant\", color=\"red\")\n\n# 2. SMOOTH - Zen-like constant scrolling (default, best for ambience)\nstatus.append(\"Processing...\", scroll_mode=\"smooth\", scroll_speed=0.5)\n\n# 3. ADAPTIVE - Speed up when behind, slow down when caught up\n# (best for progress tracking)\nstatus.append(\"Task complete\", scroll_mode=\"adaptive\",\n scroll_min=0.5, scroll_max=4.0, color=\"green\")\n```\n\n**Choosing the right scroll mode:**\n\n| Mode | Behavior | Best For | Example Use Case |\n|------|----------|----------|------------------|\n| `instant` | Jumps immediately to new content | Real-time alerts, monitoring | Error notifications, system alerts |\n| `smooth` | Constant zen-like scrolling | Ambient displays, background processes | Build progress, server status |\n| `adaptive` | Speeds up when behind, slows when caught up | Progress tracking, log streaming | Test results, batch processing |\n\n### Context Manager (Auto-clear)\n\n```python\nwith status.show(\"Working...\", color=\"blue\"):\n # Your code here\n do_something()\n# Status automatically cleared!\n```\n\n### Multi-Process Support\n\nMultiple applications can display status simultaneously with automatic space allocation:\n\n```python\n# Process 1: Build system\nbuild_status = Status(id=\"build\")\nbuild_status.set_weight(2.0) # Gets 2x space\nbuild_status.append(\"Compiling...\", color=\"blue\")\n\n# Process 2: Test runner\ntest_status = Status(id=\"tests\")\ntest_status.set_weight(1.0) # Default weight\ntest_status.append(\"Running tests...\", color=\"green\")\n\n# They appear side-by-side: [Compiling...] [Running tests...]\n```\n\n**Space Allocation:**\n- Extension uses max 40% of panel width by default\n- Space divided among processes based on weights\n- Automatic cleanup after 30s of inactivity\n- Dynamic reallocation when processes start/stop\n\n## API Reference\n\n### `Status(id=None)`\nCreate a status controller instance.\n\n**Args:**\n- `id` (str, optional): Unique process identifier for multi-process support. If None (default), uses singleton mode.\n\n**Example:**\n```python\n# Single process (default)\nfrom panelstatus import status\nstatus.set(\"Working...\")\n\n# Multi-process\nbuild = Status(id=\"build\")\ntests = Status(id=\"tests\")\n```\n\n### `set_weight(weight)`\nSet space allocation weight for multi-process display.\n\n**Args:**\n- `weight` (float): Space allocation multiplier (default 1.0). Higher = more space.\n\n**Example:**\n```python\nbuild_status = Status(id=\"build\")\nbuild_status.set_weight(2.0) # Gets 2x space\n```\n\n### `install_extension()`\nInstall the GNOME Shell extension (one-time setup).\n\n```python\nfrom panelstatus import install_extension\ninstall_extension()\n```\n\n### `restart_shell()`\nRestart GNOME Shell to reload extensions (X11 only).\n\n```python\nfrom panelstatus import restart_shell\nrestart_shell()\n```\n\n### `status.set(text, color=None)`\nDisplay static text in the panel.\n\n**Args:**\n- `text` (str): Message to display\n- `color` (str, optional): Color name or hex code\n\n### `status.scroll(text, color=None, speed=1.0, width=150)`\nDisplay scrolling text (perfect for long messages).\n\n**Args:**\n- `text` (str): Message to scroll\n- `color` (str, optional): Color name or hex code\n- `speed` (float, optional): Scroll speed multiplier (default 1.0)\n- `width` (int, optional): Display width in pixels (default 150)\n\n### `status.feed(text, color=None, max_lines=5, separator=\" | \", speed=1.0, width=200)`\nAdd text to a rolling log feed.\n\n**Args:**\n- `text` (str): Log line to add\n- `color` (str, optional): Color name or hex code\n- `max_lines` (int, optional): Buffer size (default 5)\n- `separator` (str, optional): Text between lines (default \" | \")\n- `speed` (float, optional): Scroll speed multiplier\n- `width` (int, optional): Display width in pixels\n\n### `status.append(text, color=None, separator=\" \", width=300, scroll_mode=\"smooth\", scroll_speed=1.0, scroll_min=0.3, scroll_max=3.0)`\nAppend text progressively with configurable scrolling behavior.\n\nText stays static until it exceeds the panel width, then scrolls to the end and stops. Adding more text resumes scrolling.\n\n**Args:**\n- `text` (str): Text to append\n- `color` (str, optional): Color name or hex code\n- `separator` (str, optional): Text between appends (default \" \")\n- `width` (int, optional): Display width in pixels (default 300)\n- `scroll_mode` (str, optional): Scrolling behavior - \"instant\", \"smooth\", or \"adaptive\" (default \"smooth\")\n- `scroll_speed` (float, optional): Speed multiplier for smooth mode (default 1.0)\n- `scroll_min` (float, optional): Minimum speed for adaptive mode (default 0.3)\n- `scroll_max` (float, optional): Maximum speed for adaptive mode (default 3.0)\n\n**Scroll Modes:**\n- `\"instant\"`: Jump immediately to show new content (best for real-time alerts)\n- `\"smooth\"`: Constant zen-like scrolling (best for ambient displays)\n- `\"adaptive\"`: Variable speed - accelerates when far behind, slows when caught up (best for progress tracking)\n\n### `status.clear()`\nRemove status from panel.\n\n### `status.show(text, color=None)`\nContext manager that auto-clears when done.\n\n## Real-World Examples\n\n**Long-running task:**\n```python\nfrom panelstatus import status\nimport requests\n\nstatus.scroll(\"Downloading data from API... \")\ndata = requests.get(\"https://api.example.com/data\").json()\n\nstatus.set(\"Processing...\", color=\"yellow\")\nresults = process(data)\n\nstatus.set(\"Complete! \u2713\", color=\"green\")\n```\n\n**Build script:**\n```python\nstatus.set(\"Building...\", color=\"blue\")\nos.system(\"npm run build\")\nstatus.set(\"Build complete!\", color=\"green\")\n```\n\n**Training progress:**\n```python\nfor epoch in range(100):\n status.scroll(f\"Training epoch {epoch}/100... \", color=\"orange\")\n train_model(epoch)\n\nstatus.set(\"Training complete!\", color=\"green\")\n```\n\n## Philosophy\n\nLike **ggplot2 made plotting simple**, PanelStatus makes status updates trivial:\n\n- \u2705 **Simple API** - Just `status.set()` or `status.scroll()` and go\n- \u2705 **Sensible defaults** - Works beautifully out of the box\n- \u2705 **Minimal boilerplate** - No complex setup or configuration\n- \u2705 **Pythonic** - Feels natural and intuitive\n- \u2705 **Versatile** - Static text, scrolling, colors, auto-clear\n- \u2705 **Self-contained** - Extension bundles with the library\n\n## Try the Demo\n\nRun the example to see all features:\n```bash\npython3 ~/panelstatus-lib/example.py\n```\n\nWatch your panel for static messages, smooth scrolling, and color changes!\n\n---\n\n**Enjoy simple status updates!** \ud83c\udf89\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Dead simple GNOME panel status updates - inspired by ggplot2",
"version": "1.1.0",
"project_urls": {
"Homepage": "https://github.com/maximerivest/panelstatus",
"Issues": "https://github.com/maximerivest/panelstatus/issues",
"Repository": "https://github.com/maximerivest/panelstatus"
},
"split_keywords": [
"gnome",
" status",
" panel",
" notification",
" gui"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e96a4d9f774b14874a94371eb5c7a9812ed427c2f6b4a687a1c845083bc1e0be",
"md5": "f05b0f1d234db7f81b252f908ee232b7",
"sha256": "895530a0fcf654d0107ae78f247c9ef9a81bdbeedb0b88e6e6f402d0978ed579"
},
"downloads": -1,
"filename": "panelstatus-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f05b0f1d234db7f81b252f908ee232b7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 13927,
"upload_time": "2025-10-11T14:11:13",
"upload_time_iso_8601": "2025-10-11T14:11:13.447643Z",
"url": "https://files.pythonhosted.org/packages/e9/6a/4d9f774b14874a94371eb5c7a9812ed427c2f6b4a687a1c845083bc1e0be/panelstatus-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "921784a1e8950b71c1575cb843c2c3781e2b81b9f441d46bb86a0d5d730494df",
"md5": "19f907516dbda31f3015bb4314b39816",
"sha256": "397810c4d06a0a31e75804aa62ef291df27d373e277a20a3889bec5c012e975a"
},
"downloads": -1,
"filename": "panelstatus-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "19f907516dbda31f3015bb4314b39816",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 16068,
"upload_time": "2025-10-11T14:11:15",
"upload_time_iso_8601": "2025-10-11T14:11:15.128177Z",
"url": "https://files.pythonhosted.org/packages/92/17/84a1e8950b71c1575cb843c2c3781e2b81b9f441d46bb86a0d5d730494df/panelstatus-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-11 14:11:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "maximerivest",
"github_project": "panelstatus",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "panelstatus"
}
