This guide will lead you through installation and basic configuration of the most recent release of Pygenda on PostmarketOS (a Linux-based operating system for mobile devices such as phones). It is intended for users who want to test Pygenda.
If you want to contribute to or modify Pygenda, then you probably want to get the latest version from GitHub (which is usually a little ahead of the latest release). This guide may be useful to refer to for configuration.
Pygenda is designed for devices with a physical keyboard, for example a Gemini PDA, a Chromebook, or a PinePhone with its keyboard attachment. In theory a Nokia N900 would be great, but I suspect it will be too slow – please let me know if you try.
Unfortunately, I've only been able to test Pygenda on a postmarketOS device without a keyboard. On that device, basic display of entries and navigation worked. However, while entry was possible, it was not very usable. I'm not sure how much this was due to the lack of a keyboard (which meant that a virtual keyboard kept obscuring the UI), how much was due to my choice of UI environment (I chose Phosh, mainly because it was small; a more desktop-like UI might be more appropriate for Pygenda), how much was due to my old phone not being a great platform for pmOS, and how much of it was due to Pygenda.
Because of this, currently Pygenda on postmarketOS should be considered experimental. This guide is to encourage testing (and feedback) on its current state – including on device/UI combinations that I cannot test. Feedback can be sent to [email protected].
This guide has been tested on a Wileyfox Swift ('crackling') device running PostmarketOS 23.06 with Phosh 0.30.0 (pre-built postmarketOS image, id 20230912-0014, with python3-3.11.5-r0 and gtk+3.0-3.24.38-r1). It was revised for PostmarketOS 23.12.
Known issues specific to postmarketOS (observed on Phosh) include:
- Translations are not loaded for strings in .ui files (i.e. most of the UI).
- The menubar behaves badly when using the touchscreen: submenus sometimes do not appear (seems to happen in other GTK3 apps too, but not GTK4?).
- The menubar is even more broken in fullscreen mode, or when app is maximised and the titlebar is hidden.
- The todo bullet in Week/Year view takes up too much vertical space.
- Sometimes the UI stops responding to taps (I'm not sure when this occurs).
- There's no portrait mode.
The following commands install dependencies for Pygenda. Note that you will need to be connected to the Internet, since these download packages.
Enter the following commands in a command prompt (requires password):
sudo apk update
sudo apk add python3
sudo apk add py3-pip
sudo apk add gtk+3.0
sudo apk add py3-gobject3 py3-cairo py3-icalendar py3-dateutil py3-tzlocal py3-num2words
(Note: I'm using the apk versions of the Python3 module dependencies here. This is for better compatibility with other operating system components. If you are already using different versions of these modules, you may want to stick with those versions. Alternatively, you may want to keep the Pygenda module dependencies separate from the OS modules by running Pygenda in a Python virtual environment.)
(Note 2: If you decide to install pycairo via pip, you will need GCC installed, and maybe some other build tools.)
Enter the following command to download and install Pygenda from the PyPI repository:
pip3 install pygenda --user --no-deps --break-system-packages
The --break-system-packages option sounds scary (probably deliberately).
It simply tells pip3 to proceed even though we're in an environment
where packages are managed by apk. In some cases this can cause
problems, but in this case it is safe because there is no Pygenda
package in pmOS that you might interfere with, you are not installing
any other Python modules (the --no-deps option makes sure of this),
and Pygenda is not being installed in the system files.
Test Pygenda runs:
python3 -m pygenda
Pygenda should start. The UI size may not be what you want – it might be smaller than the screen or it might overflow the screen – but this can be changed (see the next section). For now we're just checking that it starts.
Enter the following to edit the Pygenda ini file:
mkdir -p ~/.config/pygenda/
nano ~/.config/pygenda/user.ini
(You can use vi or emacs or a text editor other than nano if you want.)
This should open an empty file. You have some choice about what to enter here, depending on your preferences. Here's a reasonable basic configuration that you can select from or modify as required:
[global]
24hr = True
# The hide_titlebar option_when_maximized seems to break the menu
# under Phosh, but might be useful in other UI environments.
#hide_titlebar_when_maximized = True
# Localisation settings should be picked up from the system.
# If not, language & date order (DMY, MDY, YMD) can be set with:
#language = fr
#date_ord = DMY
[startup]
# Fullscreen UIs are often preferable on handheld devices.
# The fullscreen and maximised are two possible options for this.
# Their behaviour might differ depending on the UI of the device.
# fullscreen = True
maximize = True
[todo_view]
list0_filter = UNCATEGORIZED
list1_title = Shopping list
list1_filter = shopping
# ...and so on for additional todo lists: list2_title, list2_filter etc.
# listN_title gives the todo list name as displayed in the UI.
# listN_filter gives the tag to use internally in the icalendar data.
(Lines starting with a # are comments, so can be changed or omitted.
For other settings, see defaults.ini.)
Save the file and exit. (In nano: ctrl+s, ctrl+x.)
Now you can start Pygenda again, and your options should take effect.
Depending on your device and app scaling settings, you may find the
size of the UI, font sizes or scroll-bar widths are not appropriate.
These can be customised with a ~/.config/pygenda/pygenda.css file.
In particular, if the Pygenda UI is larger than the screen, try adding a CSS file as follows:
nano ~/.config/pygenda/pygenda.css
This should open an empty file, where you can add the following
.view, #view_loading {
min-width:400px;
min-height:200px;
}
/* The following two options reduce the width of the Year View */
.yearview_day_label, .yearview_month_label {
font-size:10.5pt;
}
.yearview_daycell {
font-size:7pt;
}
/* To reduce the width of individual to-do lists */
.todoview_list {
min-width:270px;
}
You may want to adjust the exact values, depending on your taste and device.
Much of the UI can be customised using the user CSS file (colours, fonts, etc.). See the examples gemini.css and cosmo.css for real-world examples of adjusting the UI for specific handheld devices, or darkmode.css for an example "dark mode".
If you have installed Pygenda "locally" (in your user directory), as described above, you can create a soft link to the pygenda.desktop file from the user's ~/.local/share/applications directory:
cd ~/.local/share/applications
ln -s ~/.local/lib/python3.11/site-packages/pygenda/app/pygenda.desktop
The default setting stores calendar data in a file. This is OK for testing and requires no setup. However, for real use you should store the data in a server. An Evolution Data Server (EDS) is the natural choice on PostmarketOS.
Another option: you can store data in a CalDAV server. This is probably not advisable unless you have a specific requirement. If you are using a remote CalDAV server, it would be better to set that up as a backend for EDS.
First, install EDS (it is installed by default, but best to check):
sudo apk add evolution-data-server
Then add the following to your ~/.config/pygenda/user.ini file:
[calendar]
type = evolution
entry_type = event
uid = system-calendar
[calendar1]
type = evolution
entry_type = todo
uid = system-task-list
(The above example uses the default system calendar and task-list. If you use different ones, provide their uids in place of the values used above.)
You can optionally add a display_name = SOME_NAME line to either
calendar if you want to override the name provided by EDS.
For more details/options, see Evolution_Data_Server.md.
I'd be grateful if you emailed me at [email protected] to let me know that you've tried Pygenda. It's a small project without lots of testers, so even feedback to say "it worked for me" is useful to let me know I haven't accidentally broken it. (I also welcome bug reports, feature requests, bug fixes, translations, corrections & additions to the documentation, new features, etc.)
To update to the latest release of Pygenda, enter the following command:
pip3 install --user pygenda --upgrade
You can check the latest available version at https://pypi.org/project/pygenda/
To see which version is currently installed, either check the "About" menu in Pygenda, or run:
pip3 show pygenda
If an update breaks something, please let us know about the problem at [email protected]. Then you can go back to an older version using:
pip3 install --user pygenda==0.2.9
(Change 0.2.9 to your desired version.)