A basic educational Python timer used to learn python and software testing libraries

minutaria

minutaria is a basic educational Python timer.

The project is educational, it aims to teach myself programming, python programming, python's stdlib, tools (pdb, venv, mypy...) and ecosystem, development best pratices, git and some software testing libraries or frameworks.

The project is separed in 3 parts:

a module as a library
a CLI utility
a simple ncurses GUI using parts of the module, also usable with CLI
a GTK GUI using the full module and so also usable with CLI

Done

Use OOP approach
Use datetime module
Display time ISO 8601 format like as hh:mm:ss.n
Use argparse module to build the CLI utility
Manage presets and use json module to store them
ncurses interface via curses Python standard module with basic start/relaunch/quit command also usable with the lib's CLI
Gradually introduce type hints
Some fixes with Flake8 and PyLint
Minimal documentation
Minimal log system
Unit tests with unittest and pytest without test run
packaging
Usable with a GTK GUI and so:
- reset the timer
- pause/continue the timer
- add/use/manage presets
- play a sound at 00:00:00.0
- manage alarm volum
- display an "About" window.

Dependencies

Nothing except Python 3 and modules from the standard library for the lib and the ncurses TUI, currently :

datetime, argparse, logging and json for the lib
curses, datetime, logging and os for the ncurses interface.

The GTK GUI naturally use GTK and also use cheofusi's just-playback library for playing sound, licensed under the MIT License.

For the GTK GUI, please follow the guide to install it.

For me, in short, on Debian :

Create virtual environment if not already done:python3 -m venv venv
Enter it:source venv/bin/activate
Execute the following command to install the build dependencies and GTK:sudo apt install libgirepository1.0-dev gcc libcairo2-dev pkg-config python3-dev gir1.2-gtk-3.0
Execute:pip3 install pycairo
Executepip3 install PyGObject
For just-playback:pip3 install just_playback

A requirement.txt is inclued in this repository for the three last steps, you can use it with:pip3 install -r requirements.txt

Use

libminutaria.py is a library module which provides everything to create the timer application. It is testable by beeing launched in a terminal emulator which executes a default 5 seconds timer.

minutaria-cli.py contains a fully usable command line interface to libminutaria. It executes a default timer if launched without argument. Presets created by this way are stored in a JSON file. Use -h/--help arguments for more information.

minutaria-curses.py contains the basic ncurses interface and so shall be launched via command line. It offers a start/pause/continue/relaunch/quit functionality and is fully usable with CLI arguments identically to minutaria-cli.py. This user interface shall only be use on Unix system as the Windows version isn't included in the standard library, the script contains a WINDOWS_CHECK parameter for this purpose. Nervertheless it should be usable with WSL (not tested).

minutaria-gtk.py contains the GTK interface (see the picture) to libminutaria. It offers the same functionalities plus alarm sound (sound configurable) at time up :

To add a preset, enter a name and select a duration before pressing the button "Add".
To delete a preset, select it from the list of existing preset before pressing the "Delete" button.
To rename a preset, select it from the list and enter a new name before pressing the "Rename" button.
To set a new duration to a preset, select it from the list and select a duration before pressing the "Set timing" button.
To launch a timer, select a duration with the spin button or select an existing preset from the list then press "Start/Pause".
To pause, press "Start/Pause" again.
"Reset/Stop" is used to stop the alarm, stop the timer and reset it.
The volume of the alarm can be managed by the volume button (scale).
An "About" dialog is available from the option/menu button.

To use any interface to libminutaria, libminutaria shall be installed. As it is an educational project, do it in a virtual environment :

Create virtual environment if not already done:python3 -m venv venv
Enter it:source venv/bin/activate
Install/update PyPA’s build:python3 -m pip install --upgrade build
Build from the source:python3 -m build
Install the .whl file found in dist/:python3 -m pip install dist/libminutaria-1.0-py3-none-any.whl