pomoglorbo 2024.11.22

Terminal Pomodoro timer

Links: PyPI Codeberg

Pomoglorbo

A Pomodoro Technique timer for your terminal! Runs over SSH! A bell rings when your Pomodoro is over!

muuuuuust haaaaaaaveeeeee

But what are Pomodoros? And why would I run this in my terminal? Read my blog post about Pomoglorbo for more info.

Installation

Recommended: Install using pipx:

pipx install pomoglorbo

Then run using

pomoglorbo

You can also install using pip, if you don't mind clobbering packages:

pip3 install --user pomoglorbo

With Nix

For NixOS or Home Manager users, you can also use and install Pomoglorbo as a Nix Flake.

The easiest way is to use nix run with this Codeberg repository:

nix run git+https://codeberg.org/justusw/Pomoglorbo.git

If you want to pass additional arguments, append a -- argument separator first, and you are good to go:

nix run git+https://codeberg.org/justusw/Pomoglorbo.git -- --audio-check

It's almost a bit too magical. Reproducible builds? Poetry packages? Builds on many different systems? whooooosh Nix is the cave allegory of build systems.

This is how you can add it to your Home Manager configuration, if you use Nix Flakes with Home Manager:

{
  description = "My awesome nix home manager configuration";

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-23.11";
    pomoglorbo = {
      url = "git+https://codeberg.org/justusw/Pomoglorbo.git";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };

  outputs = { self, nixpkgs, pomoglorbo }: {
    # do what you must here
  };
}

How to evaluate package size:

nix run github:utdemir/nix-tree -- --derivation .#pomoglorbo

Do you want to know more about Nix Flakes? I recommend these posts by Xe Iaso:

• Nix Flakes: an Introduction
• Building Go programs with Nix Flakes

Usage

See pomoglorbo --help for a complete overview of available options. At the time of writing, these are all available flags:

-h, --help            show this help message and exit
--no-sound            Mute alarm
--audio-check         Play alarm and exit
-v, --version         Display version and exit
--audio-file path     Custom audio file for alarm
--config-file path    Use a different config file. Overrides POMOGLORBO_CONFIG_FILE environment variable. Default is "$XDG_CONFIG_HOME/pomoglorbo/config.ini".
--work-state-cmd-suffix suffix [suffix ...]
                      Append these arguments to external command invocation when starting the next Pomodoro

Configure Pomoglorbo

A configuration file is automatically created in $XDG_CONFIG_HOME/pomoglorbo/config.ini when you launch Pomoglorbo. You can customize how Pomoglorbo behaves. The default configuration can be found in src/pomoglorbo/core/config.py under DEFAULT_CONFIG.

Use a different audio file

Set the following in your config.ini file:

[General]
audio_file = path/to/your/audio/file.ogg

or run Pomoglorbo with the following flag:

pomoglorbo --audio-file path/to/your/audio/file.ogg

If you want to just check whether the sound plays correctly, add the --audio-check flag as well.

pomoglorbo --audio-file path/to/your/audio/file.ogg --audio-check

Change Pomodoro intervals

The duration of work and break times can be set using the following variables in your configuration file:

[Time]
# How many tomatoes need to elapse to get to a long break
tomatoes_per_set = 4
# Duration of a single pomodoro in minutes
work_minutes = 25
# Duration of a short break between Pomodoros in minutes
small_break_minutes = 5
# Duration of a long break after a set, in minutes
long_break_minutes = 15

Change key bindings

The default key bindings are:

• Focus previous: shift-tab, up, left, h, or k
• Focus next: tab, right, down, l, or j
• Exit: q
• Start: s
• Pause: p
• Reset: r
• Reset all: a
• Help: ? or f1

While Pomoglorbo is running, you can always review the current keybindings by opening the help menu. You can open the help menu by pressing ? or F1

You can customize Pomoglorbo TUI key bindings using the following configuration variables, illustrated with some examples values:

[KeyBindings]
# Focus on previous button in TUI
focus_previous = s-tab
# Focus on next button in TUI
focus_next = tab
# Quit Pomoglorbo
exit_clicked = q
# Start the next Pomodoro or break
start = s
# Pause the current Pomodoro or break
pause = p
# Reset elapsed time of current Pomodoro or break
reset = r
# Reset elapsed time, go back to 0 elapsed Pomodoros (see tomatoes_per_set)
reset_all = a
# Show current key bindings
help = ?

You can find more documentation on keybindings on prompt_toolkits documentation site here.

Run a command when something happens (Triggers)

You can configure Pomoglorbo to execute a command for you automatically when one of the following things happens:

• A new Pomodoro is started
• A Pomodoro is paused
• A Pomodoro is resumed
• A long break is started
• A short break is started
• A break is over
• Pomoglorbo exits

The commands can be given as string array-like string in the configuration file section Trigger. A good use case for this is automatically starting time tracking in time tracking software like Timewarrior. Here are some ideas on what you can put in each command.

[Trigger]
work_state_cmd = ["curl", "https://example.com"]
work_paused_state_cmd = ["timew", "stop"]
work_resumed_state_cmd = ["timew", "start"]
long_break_state_cmd = ["i3lock"]
small_break_state_cmd = ["timew", "start", "break"]
break_over_cmd = ["timew", "stop"]
exit_cmd = ["espeak", "bye"]

Note from Justus: But that's not all! Here's something I do a lot. When I start Pomoglorbo, I want it to start Timewarrior with a specific tag. The work state command is timew start, which would start time tracking without any tags. I can then add --work-state-cmd-suffix when calling Pomoglorbo like so:

pomoglorbo --work-state-cmd-suffix development pomoglorbo

Pomoglorbo will call timew for me when the next Pomodoro starts like so:

timew start development pomoglorbo

This could be extended to the other commands as well, if required. Patches are very welcome here.

Development

To start developing Pomoglorbo this, clone this repository from Codeberg:

git clone https://codeberg.org/justusw/Pomoglorbo.git

Use poetry to install all dependencies:

# This will install packages used for testing as well
poetry install --all-extras

Run Pomoglorbo inside the poetry virtual environment using the following command:

poetry run src/pomoglorbo/cli/__init__.py

You can additionally specify a config file to be used like so:

poetry run src/pomoglorbo/cli/__init__.py --config-file test/config.ini

Testing

Run all tests and formatters using

poetry run bin/test.sh

Format code using

poetry run bin/format.sh

Translations

Provided you have the development requirements from the Poetry file installed, you can translate strings like so:

Mark a string for translation: If you want to mark a string for translation, you have to mark it using gettext. For example, if you want to print the string "Hello, World!" and automatically translate it, write the following:

# Assuming this file is called source_file.py
from pomoglorbo.cli.util import gettext_lazy as _
print(_("Hello, World!))

We use our own gettext_lazy here (similar to Django), to make sure that strings are not translated at module import time.

Extract strings: Run

bin/pybabel-update.sh

This will populate all message catalogs for the languages in src/pomoglorbo/messages/. You will see a new string added to each .po file and the .pot file. Edit the new message and translate it. Here, we translate it into German.

#: source_file.py
msgid "Hello, World!"
msgstr "Hallo, Welt!"

Compile message catalogs: Now, you have to compile the translations into MO files.

bin/pybabel-compile.sh

And you are done.

The translation uses GNU Gettext, the Python gettext module and Babel. Refer to Babel's Command-Line Interface help to learn more about how the bin/pybabel-*.sh commands work.

Contributing

Would you like to make a contribution? Your ideas are very welcome as this is an open source project welcoming all contributors! Please read the CONTRIBUTING.md file for more info. Please also refer to the Code of Conduct.

Credits

Pomoglorbo is a fork of the original pydoro.

• pydoro - by Bhathiya Perera
• Pomodoro - Invented by Francesco Cirillo
• prompt-toolkit - Awesome TUI library
• b15.wav - Dana robinson designs, CC0 from freesound

See the CONTRIBUTORS file in the root directory for a list of contributors to the original pydoro project.

Copyright

See the LICENSES folder for more information.