Skip to main content

timeglance

Python tests codecov pre-commit Ruff pip-audit bandit Last commit License PyPI version Downloads sigstore OSSF Scorecard OSSF Best Practice

Config-driven time planning at a glance - one web UI controls two planners:

  • Weekly - your routine sheet with topic layers. Print it or set it as a desktop wallpaper.
  • Year - a wide year-at-a-glance planner, with layers fed by your own calendars, public holidays, and manually added events. Print it or set it as a desktop wallpaper.

One web control panel drives both - preview live, toggle layers, edit the YAML, export, or set the wallpaper:

The weekly routine in the control panel

The year planner in the control panel

...and the rendered output you print or set as a wallpaper:

Weekly routine sheet

Year-at-a-glance planner

Try it instantly (Docker)

The zero-install way to see the control panel and renders - a test drive, not a deployment target. A container can't reach your desktop session, so Docker can never set the wallpaper (the UI auto-hides it, and a scheduled "set wallpaper" renders the file but skips the set). Bridging the host display/DBus into a container isn't something we intend to solve - to actually use timeglance on your desktop, install it locally (next section).

docker compose run --rm timeglance timeglance init   # first run: scaffold year/ + weekly/ config.yaml
docker compose up                                    # then open http://localhost:8753

Config, outputs and scheduler state are bind-mounted under ./year, ./weekly and ./state, so the UI edits files on your host. Outputs are written as your host user — the compose file defaults to 1000:1000 (the usual first Linux user), so it just works for most; if your uid differs, run UID=$(id -u) GID=$(id -g) docker compose up.

Install (Ubuntu/Debian)

The simplest way on a Debian-based desktop. Grab the .deb from the latest release and install it - apt pulls every dependency (the Python libraries, poppler, native Cairo/Pango stack, fonts) from your distro, and the Qt tray as a recommended dependency:

sudo apt install ./timeglance_<version>_all.deb

Then launch timeglance from your applications menu - the tray icon appears and opens the control panel, no terminal needed. Or drive it from the CLI (timeglance is now on your PATH):

timeglance init     # scaffold year/ + weekly/ config.yaml from the templates
timeglance serve    # the control panel at http://localhost:8753

A pure-Python install under /usr/lib/python3/dist-packages run by your system Python, with every dependency satisfied by your distro's own apt packages. CI builds and install-tests the .deb on Ubuntu 24.04, 25.10 and 26.04; other recent releases may work.

Uninstalling. timeglance sets up user-level bits that apt can't remove: a systemd timer for the daily render and, if you enabled it, a tray autostart entry. Run timeglance uninstall first - it stops a running tray, disables the timer, and removes both the unit files and the autostart entry - then sudo apt remove timeglance. Your per-user configs and output (~/.config/timeglance, ~/.local/state/timeglance, ~/.local/share/timeglance) are left untouched either way.

Install (Python/uv)

Needs Python 3.12+ and uv. WeasyPrint and CairoSVG load native libraries (Cairo, Pango, GDK-PixBuf) at runtime, and the wallpaper feature rasterizes the sheet with poppler's pdftocairo; most Linux desktops already have these, but on a minimal or server install add them first (Debian/Ubuntu):

sudo apt-get install libcairo2 libpango-1.0-0 libpangocairo-1.0-0 libgdk-pixbuf-2.0-0 poppler-utils
uv sync
uv run timeglance init      # scaffold year/ + weekly/ config.yaml from the templates
uv run timeglance serve     # the control panel at http://localhost:8753

Config, state and rendered output live under the XDG base directories by default (~/.config/timeglance, ~/.local/state/timeglance, ~/.local/share/timeglance); set TIMEGLANCE_HOME=$PWD to keep it all in the current folder instead.

Headless renders (each flag has a YAML equivalent):

uv run timeglance render year --theme light --layout vertical   # render the year planner
uv run timeglance render weekly --format both                   # render the weekly sheet

Set and forget (systemd timer)

To re-render (and optionally re-wallpaper) on a schedule with nothing running and nothing to start after a reboot:

timeglance install              # write a user service + timer and enable it now
timeglance install --time 06:30 # or pick the time (default: schedule.yaml's)
timeglance uninstall            # remove it

(From a source checkout, prefix these with uv run.) This drops timeglance-render.service (a oneshot that runs timeglance run, honouring your schedule.yaml) and timeglance-render.timer into ~/.config/systemd/user/, then enables the timer. Persistent=true means a run missed while the machine was off happens on the next boot. Change the time by re-running timeglance install --time HH:MM.

Setting the Plasma wallpaper needs an active graphical session, so a render while you're fully logged out writes the files but can't paint - it repaints on your next session. For renders while logged out (no wallpaper), enable lingering: loginctl enable-linger $USER.

Tray controller

A system-tray menu to open the panel and flip the schedule - a launcher and quick toggles, not the scheduler (the timer above keeps running whether or not the tray is open).

The .deb already includes it: after apt install, launch timeglance from your applications menu and the tray icon appears. On a Qt desktop like KDE Plasma the tray needs PySide6, which apt pulls in automatically as a recommended dependency. From a source checkout, add the extra and run it:

uv sync --extra tray
uv run timeglance tray

Ubuntu 24.04 doesn't package PySide6, so the .deb installs there without the tray; install it from PyPI instead (pipx install 'timeglance[tray]'), or add PySide6 yourself (pip install --user PySide6).

The menu opens the control panel (starting the server first if needed), starts/stops it, picks the port, and toggles the schedule: enabled, time, which planners render, and which set the wallpaper. Autostart adds an XDG autostart entry so the tray is there every session (the same thing KDE's System Settings → Autostart manages). Quitting the tray only closes the panel it started - the systemd timer keeps running regardless.

Docs

Metadata

Release files for timeglance 3.11.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for timeglance 3.11.0
File Size Uploaded Provenance Actions
timeglance-3.11.0.tar.gz 1.0 MB With provenance Details for timeglance-3.11.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for timeglance 3.11.0
File Interpreter ABI Platform Actions
timeglance-3.11.0-py3-none-any.whl Python 3 none any Details for timeglance-3.11.0-py3-none-any.whl

Total release size: 1.1 MB

Release files / timeglance-3.11.0.tar.gz

Download URL timeglance-3.11.0.tar.gz
Size 1.0 MB
Tags Source
SHA-256 checksum
How to use checksums
6c4d677fd50ceb8f31b223aa84f51acb357a0f6f23c49bc959ffca720f43031d
BLAKE2b-256 checksum
How to use checksums
3d4adfa7b7b498603c786d9b0619ce0eee5fe45cb3cfed0e3a52c5f8f7beab89
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 21, 2026.

Transparency log

Release files / timeglance-3.11.0-py3-none-any.whl

Download URL timeglance-3.11.0-py3-none-any.whl
Size 97.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5249297980e9b9d6cef447c3d58ad9773f65189ce6d91341a2ac847ebc721c79
BLAKE2b-256 checksum
How to use checksums
115e3ee58c4a717b318e36ead19a88bd898e49fa44792bad0e01226b76a4bd0a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 21, 2026.

Transparency log

Security for timeglance 3.11.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for timeglance-3.11.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 21, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

3.11.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page