Home

Welcome to the pydoro 🍅 wiki!

Installation

• Refer README and Problems with sound section if you cannot get audio to work.

Usage

• Simply run pydoro and it will start with the TUI (Text User Interface).

Keyboard Shortcuts

• Focus Next: Tab | -> | l | k
• Focus Previous: Shift + Tab | <- | h | j
• Exit: q
• Start: s
• Pause: p
• Reset: r
• Reset All: a

Configuration

• If PYDORO_CONFIG_FILE is set configuration is loaded from that location.
• Default location is ~/.pydoro.ini (Windows: C:\Users\<User>\.pydoro.ini)
• Configuration with default values will be created if file doesn't exist.
• This file must be writable from pydoro.
• There are no validations yet! 💀

Config INI

[General]
; Set this to True to disable clock animation
no_clock = False
; Set this to True to disable sounds
no_sound = False
; Set this to True to enable emoji tomatoes
emoji = False
; Set a file here to play this instead of default bell sound (Optional)
audio_file = path/file.wav

[Time]
; Tomatoes in a set usually this is a 4
tomatoes_per_set = 4
; Work time in minutes
work_minutes = 25
; Small break time in minutes
small_break_minutes = 5
; Long break time in minutes
long_break_minutes = 15
; How long does alarm goes on (if sound is enabled)
alarm_seconds = 20

[KeyBindings]
; Remove any of the lines below - to not have a binding for respective function
; Navigate to previous button
focus_previous = s-tab,left,h,j
; Navigate to next button
focus_next = tab,right,l,k
exit_clicked = q
start = s
pause = p
reset = r
reset_all = a

[Trigger]
; Custom trigger commands
; Similar to *args in https://docs.python.org/3/library/subprocess.html#subprocess.run
; Example: work_state_cmd = ["say", "Working"] 
work_state_cmd = []
work_paused_state_cmd = []
work_resumed_state_cmd = []
long_break_state_cmd = []
small_break_state_cmd = []
exit_cmd = []

Key Bindings

• Custom keys allow aliases to be defined. Simply separate them from space
• Refer Keybinding documentation
• Limitation: Alt/Meta + x - not supported.
• Limitation: Key sequences are not supported.

CLI Arguments

usage: pydoro [-h] [-e] [--focus] [--no-clock] [--no-sound] [--audio-check] [--version] [--audio-file path]

Terminal Pomodoro Timer

optional arguments:
  -h, --help         show this help message and exit
  -e, --emoji        If set, use tomato emoji instead of the ASCII art
  --focus            focus mode: hides clock and mutes sounds (equivalent to --no-clock and --no-sound)
  --no-clock         hides clock
  --no-sound         mutes all sounds
  --audio-check      play audio and exit
  --version          display version and exit
  --audio-file path  custom audio file

Developer Guide

You can find the developer guide here.

Problems with sound

Sound can be checked in 2 ways. Run pydoro --audio-check or pydoro and press start.

• If you are on Linux
  • Method 1: Install pygame in same virtual environment you install pydoro if you are using pip or pipx.
  • Method 2: Install using snapcraft if you are using snapcraft (audio does not work for PopOS). (Snap package is currently maintained by James Tigert)
• If you are on Windows - pip install pydoro or .exe file should work.
• If you are on MacOS - Install as pip install "pydoro[audio]"
• Any other operating systems - See if pygame works for you and send a PR.

If you still cannot get sound working - Consider using a trigger command to run a program that can notify you. This results in a non-shell subprocess run. (https://docs.python.org/3/library/subprocess.html#subprocess.run).

How to run TUI as a python module

Windows if you are using py

py -m pydoro.pydoro_tui

Windows and other operating systems if virtual environment is activated

python -m pydoro.pydoro_tui

License

The MIT License (MIT)

Copyright (c) 2021 - 2023 Bhathiya Perera

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.