| Name | nightswitch JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | A PyGTK 3 application for managing night mode (dark/light theme switching) in Linux desktop environments |
| upload_time | 2025-07-18 21:04:02 |
| maintainer | None |
| docs_url | None |
| author | Nightswitch Team |
| requires_python | >=3.13 |
| license | MIT |
| keywords |
dark-mode
desktop
flatpak
gtk
linux
theme
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Nightswitch
<div align="center">
**A modern PyGTK 4 application for intelligent theme switching in Linux desktop environments**
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](https://gtk.org/)
[](https://flatpak.org/)
</div>
## Overview
Nightswitch is a sophisticated theme management application that brings intelligent dark/light mode switching to Linux desktop environments. Built with PyGTK 4, it provides seamless integration with your desktop while offering multiple automation modes to match your workflow and preferences.
## ✨ Features
### 🎛️ Multiple Switching Modes
- **Manual Mode**: Instant theme switching via system tray interface
- **Schedule Mode**: Time-based automatic switching with customizable schedules
- **Location Mode**: Sunrise/sunset-based switching using your geographic location
### 🔌 Extensible Plugin System
- **Ubuntu Budgie**: Primary desktop environment support
- **Generic GTK**: Broad compatibility with GTK-based environments
- **Extensible Architecture**: Plugin system for additional desktop environments
### 🖥️ Desktop Integration
- **System Tray**: Minimal footprint with quick access controls
- **Notifications**: Non-intrusive status updates
- **Autostart**: Seamless integration with desktop session management
### 🌐 Smart Location Services
- **IP-based Location**: Automatic location detection for sunrise/sunset calculations
- **Privacy-focused**: Optional location services with user control
- **Offline Fallback**: Manual location configuration when needed
## 🖥️ Supported Desktop Environments
| Desktop Environment | Status | Plugin |
|---------------------|--------|---------|
| Ubuntu Budgie | ✅ Primary Support | Built-in |
| GNOME | 🔄 Planned | Plugin |
| KDE Plasma | 🔄 Planned | Plugin |
| XFCE | 🔄 Planned | Plugin |
| Generic GTK | ✅ Basic Support | Built-in |
## 📋 Requirements
- **Operating System**: Linux (X11/Wayland)
- **Python**: 3.13 or higher
- **Desktop**: GTK-based environment with system tray support
- **Dependencies**: PyGObject (PyGTK 4), requests, python-dateutil
## 📦 Installation
### Flatpak (Recommended)
The easiest way to install Nightswitch is through Flatpak, which provides sandboxed execution and automatic updates.
```bash
# Install from Flathub (when available)
flatpak install flathub org.nightswitch.Nightswitch
# Or build and install locally
flatpak-builder build-dir org.nightswitch.Nightswitch.yml --install --user --force-clean
```
### From Source
For developers or users who prefer traditional installation:
```bash
# Clone the repository
git clone https://github.com/pygillier/nightswitch.git
cd nightswitch
# Install using the installation script (recommended)
./install.sh --user # For user installation
./install.sh --system # For system-wide installation (requires sudo)
# Or install manually with uv
uv pip install -e .
```
### Installation Script Options
The `install.sh` script provides several options:
```bash
# Install for current user (default)
./install.sh --user
# Install system-wide (requires sudo)
./install.sh --system
# Uninstall Nightswitch
./install.sh --uninstall
# Show help
./install.sh --help
```
The installation script will:
- Install required dependencies
- Install Nightswitch package
- Create desktop entry
- Set up autostart via desktop file and systemd service
- Install application icon
## 🚀 Usage
### Starting the Application
```bash
# Launch Nightswitch
nightswitch
# Launch minimized to system tray
nightswitch --minimized
# The application will appear in your system tray
# Look for the theme switcher icon in your system tray area
```
### Autostart Configuration
Nightswitch can be configured to start automatically when you log in:
```bash
# Enable autostart (creates desktop and systemd service entries)
./enable-autostart.sh
# Disable autostart
./enable-autostart.sh --disable
```
The installation script automatically sets up autostart. This separate script is provided for users who want to enable or disable autostart after installation.
### Basic Operations
1. **Manual Switching**: Click the system tray icon and select "Switch to Dark/Light Mode"
2. **Schedule Mode**: Configure automatic switching times in the settings
3. **Location Mode**: Enable location-based switching for sunrise/sunset automation
### Configuration
Nightswitch follows the FreeDesktop.org XDG Base Directory Specification for configuration storage:
- **Configuration**: `~/.config/nightswitch/` (or `$XDG_CONFIG_HOME/nightswitch/`)
- **Application Data**: `~/.local/share/nightswitch/` (or `$XDG_DATA_HOME/nightswitch/`)
- **Cache**: `~/.cache/nightswitch/` (or `$XDG_CACHE_HOME/nightswitch/`)
- **State**: `~/.local/state/nightswitch/` (or `$XDG_STATE_HOME/nightswitch/`)
The main configuration file is stored as `config.json` in the configuration directory.
## 🛠️ Development
### Setting Up Development Environment
```bash
# Clone the repository
git clone https://github.com/pygillier/nightswitch.git
cd nightswitch
# Install development dependencies
uv pip install -e ".[dev]"
# Or with pip
pip install -e ".[dev]"
```
### Development Workflow
**Important**: This project uses `uv` for all Python operations. Never use `pip` or direct `python` commands.
```bash
# Run tests
uv run pytest
# Code formatting
uv run black src tests
uv run isort src tests
# Type checking
uv run mypy src
# Linting
uv run flake8 src tests
# Run all checks
uv run pytest && uv run black --check src tests && uv run isort --check src tests && uv run mypy src && uv run flake8 src tests
```
### Testing
The project includes comprehensive test coverage:
```bash
# Run all tests
uv run pytest
# Run with coverage
uv run pytest --cov=src/nightswitch --cov-report=html
# Run specific test categories
uv run pytest -m unit # Unit tests only
uv run pytest -m integration # Integration tests only
```
## 🏗️ Architecture
Nightswitch follows a modular architecture designed for extensibility and maintainability:
```
src/nightswitch/
├── core/ # Application lifecycle and mode management
│ ├── app.py # Main application controller
│ ├── modes/ # Mode implementations (manual, schedule, location)
│ └── config.py # Configuration management
├── plugins/ # Desktop environment plugins
│ ├── base.py # Plugin interface
│ ├── budgie.py # Ubuntu Budgie support
│ └── gtk.py # Generic GTK support
├── services/ # External service integrations
│ ├── location.py # IP-based location detection
│ ├── schedule.py # Time-based scheduling
│ └── sunrise.py # Astronomical calculations
└── ui/ # GTK 4 user interface
├── tray.py # System tray integration
├── settings.py # Settings dialog
└── notifications.py # User notifications
```
### Key Design Principles
- **Plugin Architecture**: Easy extension for new desktop environments
- **Service-Oriented**: Clean separation of concerns
- **Event-Driven**: Reactive architecture for mode switching
- **Configuration-Driven**: User preferences control behavior
## 🤝 Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
### Development Process
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass (`uv run pytest`)
6. Format code (`uv run black src tests && uv run isort src tests`)
7. Commit changes (`git commit -m 'Add amazing feature'`)
8. Push to branch (`git push origin feature/amazing-feature`)
9. Open a Pull Request
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- **GTK Team**: For the excellent GTK 4 toolkit
- **GNOME Project**: For PyGObject bindings
- **Flatpak Community**: For modern Linux application distribution
- **Ubuntu Budgie Team**: For desktop environment collaboration
## 📞 Support
- **Issues**: [GitHub Issues](https://github.com/pygillier/nightswitch/issues)
- **Discussions**: [GitHub Discussions](https://github.com/pygillier/nightswitch/discussions)
- **Email**: team@nightswitch.org
---
<div align="center">
Made with ❤️ for the Linux desktop community
</div>
Raw data
{
"_id": null,
"home_page": null,
"name": "nightswitch",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.13",
"maintainer_email": null,
"keywords": "dark-mode, desktop, flatpak, gtk, linux, theme",
"author": "Nightswitch Team",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/64/02/f1bea692301d8d8b3beea2b32e4e79b9d2b446f7d56ce3d2c5b33e3be44d/nightswitch-0.1.0.tar.gz",
"platform": null,
"description": "# Nightswitch\n\n<div align=\"center\">\n\n\n\n**A modern PyGTK 4 application for intelligent theme switching in Linux desktop environments**\n\n[](https://opensource.org/licenses/MIT)\n[](https://www.python.org/downloads/)\n[](https://gtk.org/)\n[](https://flatpak.org/)\n\n</div>\n\n## Overview\n\nNightswitch is a sophisticated theme management application that brings intelligent dark/light mode switching to Linux desktop environments. Built with PyGTK 4, it provides seamless integration with your desktop while offering multiple automation modes to match your workflow and preferences.\n\n## \u2728 Features\n\n### \ud83c\udf9b\ufe0f Multiple Switching Modes\n- **Manual Mode**: Instant theme switching via system tray interface\n- **Schedule Mode**: Time-based automatic switching with customizable schedules\n- **Location Mode**: Sunrise/sunset-based switching using your geographic location\n\n### \ud83d\udd0c Extensible Plugin System\n- **Ubuntu Budgie**: Primary desktop environment support\n- **Generic GTK**: Broad compatibility with GTK-based environments\n- **Extensible Architecture**: Plugin system for additional desktop environments\n\n### \ud83d\udda5\ufe0f Desktop Integration\n- **System Tray**: Minimal footprint with quick access controls\n- **Notifications**: Non-intrusive status updates\n- **Autostart**: Seamless integration with desktop session management\n\n### \ud83c\udf10 Smart Location Services\n- **IP-based Location**: Automatic location detection for sunrise/sunset calculations\n- **Privacy-focused**: Optional location services with user control\n- **Offline Fallback**: Manual location configuration when needed\n\n## \ud83d\udda5\ufe0f Supported Desktop Environments\n\n| Desktop Environment | Status | Plugin |\n|---------------------|--------|---------|\n| Ubuntu Budgie | \u2705 Primary Support | Built-in |\n| GNOME | \ud83d\udd04 Planned | Plugin |\n| KDE Plasma | \ud83d\udd04 Planned | Plugin |\n| XFCE | \ud83d\udd04 Planned | Plugin |\n| Generic GTK | \u2705 Basic Support | Built-in |\n\n## \ud83d\udccb Requirements\n\n- **Operating System**: Linux (X11/Wayland)\n- **Python**: 3.13 or higher\n- **Desktop**: GTK-based environment with system tray support\n- **Dependencies**: PyGObject (PyGTK 4), requests, python-dateutil\n\n## \ud83d\udce6 Installation\n\n### Flatpak (Recommended)\n\nThe easiest way to install Nightswitch is through Flatpak, which provides sandboxed execution and automatic updates.\n\n```bash\n# Install from Flathub (when available)\nflatpak install flathub org.nightswitch.Nightswitch\n\n# Or build and install locally\nflatpak-builder build-dir org.nightswitch.Nightswitch.yml --install --user --force-clean\n```\n\n### From Source\n\nFor developers or users who prefer traditional installation:\n\n```bash\n# Clone the repository\ngit clone https://github.com/pygillier/nightswitch.git\ncd nightswitch\n\n# Install using the installation script (recommended)\n./install.sh --user # For user installation\n./install.sh --system # For system-wide installation (requires sudo)\n\n# Or install manually with uv\nuv pip install -e .\n```\n\n### Installation Script Options\n\nThe `install.sh` script provides several options:\n\n```bash\n# Install for current user (default)\n./install.sh --user\n\n# Install system-wide (requires sudo)\n./install.sh --system\n\n# Uninstall Nightswitch\n./install.sh --uninstall\n\n# Show help\n./install.sh --help\n```\n\nThe installation script will:\n- Install required dependencies\n- Install Nightswitch package\n- Create desktop entry\n- Set up autostart via desktop file and systemd service\n- Install application icon\n\n## \ud83d\ude80 Usage\n\n### Starting the Application\n\n```bash\n# Launch Nightswitch\nnightswitch\n\n# Launch minimized to system tray\nnightswitch --minimized\n\n# The application will appear in your system tray\n# Look for the theme switcher icon in your system tray area\n```\n\n### Autostart Configuration\n\nNightswitch can be configured to start automatically when you log in:\n\n```bash\n# Enable autostart (creates desktop and systemd service entries)\n./enable-autostart.sh\n\n# Disable autostart\n./enable-autostart.sh --disable\n```\n\nThe installation script automatically sets up autostart. This separate script is provided for users who want to enable or disable autostart after installation.\n\n### Basic Operations\n\n1. **Manual Switching**: Click the system tray icon and select \"Switch to Dark/Light Mode\"\n2. **Schedule Mode**: Configure automatic switching times in the settings\n3. **Location Mode**: Enable location-based switching for sunrise/sunset automation\n\n### Configuration\n\nNightswitch follows the FreeDesktop.org XDG Base Directory Specification for configuration storage:\n\n- **Configuration**: `~/.config/nightswitch/` (or `$XDG_CONFIG_HOME/nightswitch/`)\n- **Application Data**: `~/.local/share/nightswitch/` (or `$XDG_DATA_HOME/nightswitch/`)\n- **Cache**: `~/.cache/nightswitch/` (or `$XDG_CACHE_HOME/nightswitch/`)\n- **State**: `~/.local/state/nightswitch/` (or `$XDG_STATE_HOME/nightswitch/`)\n\nThe main configuration file is stored as `config.json` in the configuration directory.\n\n## \ud83d\udee0\ufe0f Development\n\n### Setting Up Development Environment\n\n```bash\n# Clone the repository\ngit clone https://github.com/pygillier/nightswitch.git\ncd nightswitch\n\n# Install development dependencies\nuv pip install -e \".[dev]\"\n\n# Or with pip\npip install -e \".[dev]\"\n```\n\n### Development Workflow\n\n**Important**: This project uses `uv` for all Python operations. Never use `pip` or direct `python` commands.\n\n```bash\n# Run tests\nuv run pytest\n\n# Code formatting\nuv run black src tests\nuv run isort src tests\n\n# Type checking\nuv run mypy src\n\n# Linting\nuv run flake8 src tests\n\n# Run all checks\nuv run pytest && uv run black --check src tests && uv run isort --check src tests && uv run mypy src && uv run flake8 src tests\n```\n\n### Testing\n\nThe project includes comprehensive test coverage:\n\n```bash\n# Run all tests\nuv run pytest\n\n# Run with coverage\nuv run pytest --cov=src/nightswitch --cov-report=html\n\n# Run specific test categories\nuv run pytest -m unit # Unit tests only\nuv run pytest -m integration # Integration tests only\n```\n\n## \ud83c\udfd7\ufe0f Architecture\n\nNightswitch follows a modular architecture designed for extensibility and maintainability:\n\n```\nsrc/nightswitch/\n\u251c\u2500\u2500 core/ # Application lifecycle and mode management\n\u2502 \u251c\u2500\u2500 app.py # Main application controller\n\u2502 \u251c\u2500\u2500 modes/ # Mode implementations (manual, schedule, location)\n\u2502 \u2514\u2500\u2500 config.py # Configuration management\n\u251c\u2500\u2500 plugins/ # Desktop environment plugins\n\u2502 \u251c\u2500\u2500 base.py # Plugin interface\n\u2502 \u251c\u2500\u2500 budgie.py # Ubuntu Budgie support\n\u2502 \u2514\u2500\u2500 gtk.py # Generic GTK support\n\u251c\u2500\u2500 services/ # External service integrations\n\u2502 \u251c\u2500\u2500 location.py # IP-based location detection\n\u2502 \u251c\u2500\u2500 schedule.py # Time-based scheduling\n\u2502 \u2514\u2500\u2500 sunrise.py # Astronomical calculations\n\u2514\u2500\u2500 ui/ # GTK 4 user interface\n \u251c\u2500\u2500 tray.py # System tray integration\n \u251c\u2500\u2500 settings.py # Settings dialog\n \u2514\u2500\u2500 notifications.py # User notifications\n```\n\n### Key Design Principles\n\n- **Plugin Architecture**: Easy extension for new desktop environments\n- **Service-Oriented**: Clean separation of concerns\n- **Event-Driven**: Reactive architecture for mode switching\n- **Configuration-Driven**: User preferences control behavior\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n### Development Process\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Add tests for new functionality\n5. Ensure all tests pass (`uv run pytest`)\n6. Format code (`uv run black src tests && uv run isort src tests`)\n7. Commit changes (`git commit -m 'Add amazing feature'`)\n8. Push to branch (`git push origin feature/amazing-feature`)\n9. Open a Pull Request\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83d\ude4f Acknowledgments\n\n- **GTK Team**: For the excellent GTK 4 toolkit\n- **GNOME Project**: For PyGObject bindings\n- **Flatpak Community**: For modern Linux application distribution\n- **Ubuntu Budgie Team**: For desktop environment collaboration\n\n## \ud83d\udcde Support\n\n- **Issues**: [GitHub Issues](https://github.com/pygillier/nightswitch/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/pygillier/nightswitch/discussions)\n- **Email**: team@nightswitch.org\n\n---\n\n<div align=\"center\">\nMade with \u2764\ufe0f for the Linux desktop community\n</div>",
"bugtrack_url": null,
"license": "MIT",
"summary": "A PyGTK 3 application for managing night mode (dark/light theme switching) in Linux desktop environments",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/pygillier/nightswitch",
"Issues": "https://github.com/pygillier/nightswitch/issues",
"Repository": "https://github.com/pygillier/nightswitch"
},
"split_keywords": [
"dark-mode",
" desktop",
" flatpak",
" gtk",
" linux",
" theme"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "311b8421c5c7a68471a47fbf89bbc724511f0e6cf98226627def5c40cab6c295",
"md5": "2a4fe12040582b7f4802baad2cd48e0e",
"sha256": "26c237e2302b13cbc4b03664d2494c61a6e67a8a6bcb8cc7ae6ca4f2f43516f8"
},
"downloads": -1,
"filename": "nightswitch-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2a4fe12040582b7f4802baad2cd48e0e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.13",
"size": 78197,
"upload_time": "2025-07-18T21:04:00",
"upload_time_iso_8601": "2025-07-18T21:04:00.878734Z",
"url": "https://files.pythonhosted.org/packages/31/1b/8421c5c7a68471a47fbf89bbc724511f0e6cf98226627def5c40cab6c295/nightswitch-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "6402f1bea692301d8d8b3beea2b32e4e79b9d2b446f7d56ce3d2c5b33e3be44d",
"md5": "d47d20a7545ecf32a1482ee824fe0b98",
"sha256": "11a514b1ac41fb595fc291f8f120dfc6282821a98563fbf8f20175a08b55933e"
},
"downloads": -1,
"filename": "nightswitch-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "d47d20a7545ecf32a1482ee824fe0b98",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.13",
"size": 105401,
"upload_time": "2025-07-18T21:04:02",
"upload_time_iso_8601": "2025-07-18T21:04:02.728843Z",
"url": "https://files.pythonhosted.org/packages/64/02/f1bea692301d8d8b3beea2b32e4e79b9d2b446f7d56ce3d2c5b33e3be44d/nightswitch-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-18 21:04:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pygillier",
"github_project": "nightswitch",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "nightswitch"
}
