| Name | pomodorable JSON |
| Version |
0.1.dev28
JSON |
| download |
| home_page | None |
| Summary | A pomodoro timer implemented as a Textual app |
| upload_time | 2024-05-11 19:16:16 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | None |
| keywords |
textual
pomodoro
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# pomodorable
A **pomodoro timer** built using Textual.
> Development work in progress.
<!--  -->
<p align="center">
<a href="https://github.com/wmelvin/pomodorable/raw/main/readme_images/pomororo-timer-200.jpg">
<img src="https://github.com/wmelvin/pomodorable/raw/main/readme_images/pomororo-timer-200.jpg"
alt="Picture of a Pomodoro Timer"/></a></p>
## Screenshots
<!--  -->
<p align="center">
<a href="https://github.com/wmelvin/pomodorable/raw/main/readme_images/app-1.gif">
<img src="https://github.com/wmelvin/pomodorable/raw/main/readme_images/app-1.gif"
alt="Screenshot animation"/></a></p>
## Using the Application
### Modes
1. **Ready**
- Initial mode when the application starts.
- Returned to when a session is *finished* or *stopped*.
2. **Running**
- Entered when the *Start* button is pressed.
- Returned to when *Extend* or *Resume* is chosen in *paused* mode.
3. **Paused**
- Entered when the *Pause* button is pressed.
- Ended by pressing *Extend*, *Resume* or *Stop*.
### Display and Inputs
#### Times Display
- **Countdown** display: Shows the time remaining in the current session.
- **Start Time** display: Shows the Start time of the current session. When a session is not *running* it shows the current time.
- **End Time** display: Shows the End time of the current session. When a session is not *running* it shows the current time plus the session length.
#### Settings Panel
- **Reset** button: Resets the *Countdown* to the configured session length (default setting is 25 minutes).
- **+5**, **+1**, **-1**, **-5** buttons: Increment or decrement the *Countdown* by minutes.
- **?** (About) button: Open the *About* screen.
- **Settings** button: Open the *Settings* screen.
#### Task Panel
- **Task description** input box: A brief description of the task at hand (optional). Press the **down arrow** key to open a list of recently used descriptions to pick from.
- **Start** button: Starts the session. Countdown begins. Time displays show Start and End times for the running session.
#### Pause Panel - Running
- **Pause** button: Pause the running session.
- **Reason description** input box: Disabled when *running*.
#### Pause Panel - Paused
- **Pause** button: Disabled when *paused*.
- **Reason description** input box: Enter the reason for pausing (optional). Press the **down arrow** key to open a list of recently used descriptions to pick from.
- **Extend** button: Return to *running*. Add the paused duration to the end-time to complete the full session length time-on-task.
- **Resume** button: Return to *running*. Resume the session from the current time. The pause duration is subtracted from the countdown, reducing the session's time-on-task.
- **Stop** button: Finish the session now. Return to *ready* mode.
#### Timer Bar
- Mimics the markings on a classic pomodoro (tomato-shaped) kitchen timer.
- Shows the current countdown minute at the pointer.
#### Log Panel
- Shows messages from the application with a timestamp.
### About Screen
The *About* screen is a dialog box showing some information about the application.
- **Version** number of the application.
- **GitHub** button: Open the web browser and go to the source GitHub page.
- File locations:
- **Data path** shows the directory where the application's data is stored. Output files are written to different locations as configured in the *Settings* screen.
- **Configuration** shows the full path to the application's configuration file.
- **Close** button: Closes the dialog.
### Settings Screen
The *Settings* screen is where you configure the application. It has the following settings:
- **Session Minutes**: Initial *Countdown* setting on startup, finish, stop, or reset.
- **Running CSV Folder**: Folder to which the file is written. The folder must already exist.
- **Running CSV File Name**: Name to use for the output file (default is `pomodorable-sessions.csv`).
- **Daily CSV Folder**: Folder to which the file is written. The folder must already exist.
- **Filter CSV Output**: Exclude selected actions from the CSV output files (see *Filters* below).
- **Daily Markdown Folder**: Folder to which the file is written. The folder must already exist.
- **Daily Markdown Heading**: The Markdown [heading](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#headings) to insert before the individual sessions. The heading can be any heading level (`# Heading-text` or `### Heading-text` for example).
- **Daily Markdown Append-only**: When enabled, the file must already exist. This is for the case where the file is initially created by another application (such as a Daily Note file created by Obsidian).
- **Filter Markdown Output**: Exclude selected actions from the Markdown output files (see *Filters* below).
- **Log Retention Days**: Number of daily log files to keep. This applies to the application's operational logs, not the session data.
**Filters** for CSV and Markdown output:
| Settings screen | CLI: `--filters=` | Description |
| --- | --- | --- |
| Finish | F | Exclude *Finish* actions. |
| Pause (all) | P | Exclude all *Pause* actions. |
| Pause (w/o Reason) | R | Exclude *Pause* actions with no *reason* noted. |
| Stop | X | Exclude *Stop* actions. |
## Outputs
### Daily and Running CSV
The **Daily CSV** output is for a single day. The folder it is written to can be configured in the *Settings* screen. The name of the file is the current date as *yyyy*-*mm*-*dd*.csv (`2024-04-30.csv`, for example).
The **Running CSV** output spans multiple days (*running* vs *daily*). Both the folder, and file name, are configured in the *Settings* screen.
The following columns are in the CSV output files:
- **date**: Date of the action.
- **act**: Action code (see below). When exported via the `--export-csv` CLI option, *Start* actions will instead have the *session number* (daily sequence).
- **time**: Time of the action.
- **task**: Description of the task for *Start* actions, otherwise empty.
- **message**: Message associated with the action. Varies depending on the action.
- **notes**: Note associated with the action. Varies depending on the action.
Action codes:
- **S** - Start
- **E** - Extend (after Pause)
- **R** - Resume (after Pause)
- **F** - Finished session
- **X** - Stopped session
Note: The format of the CSV output files is based on the layout of a spreadsheet the author uses to track *pomodoro sessions* (among other things). It is designed for easy copy and paste into that spreadsheet. It's likely not the layout someone else would choose.
### Daily Markdown
The *Daily Markdown* output is designed to insert *pomodoro sessions* into a [Daily Notes](https://help.obsidian.md/Plugins/Daily+notes) file in [Obisdian](https://obsidian.md/).
If the *Daily Markdown Append-only* setting is enabled, the Daily Note file (expects `YYYY-MM-DD.md`) must already exist. This is for the case where a [template](https://help.obsidian.md/Plugins/Templates) is used for Daily Note files and you want that template to always be used to create the file. If sessions are completed before the file is created they will be included the first time a session finishes and the Daily Note file exists.
## Data
### Configuration File
The configuration file is `pomodorable-config.toml` and is stored in a folder named `pomodorable` under the *user config* folder for the operating system. Configuration settings are managed in the *Settings* screen. You should not need to directly edit this file.
### Data File
The main data file is `pomodorable-data.csv` and is stored in a folder named `pomodorable` under the *user data* folder for the operating system.
Each **action** (or *event*) recorded by the application is written to this file.
The columns in the CSV file are:
- **version**: The version of the CSV format.
- **date**: The date of the action.
- **time**: The time of the action.
- **action**: The *name* of the action.
- **message**: A message associated with the action.
- **duration**: The duration of the action.
- **notes**: Any notes associated with the action.
This file is not intended to be used directly (though being CSV format, that is easy to do). There are several output files that provide a log of pomodoro sessions for the user.
### Log Files
Log files are also written to the `pomodorable` folder under the system's *user data* folder.
Each log file is named with the current date.
The number of files to keep is configured in the *Settings* screen.
---
## Command-Line Usage
``` console
Usage: pomodorable [OPTIONS]
Handle command-line options or run the Textual User Interface.
Options:
--version Show the version and exit.
--csv-date TEXT Export a Daily CSV file for a given date (provide the
date as YYYY-MM-DD or YY-MM-DD). If a 'Daily CSV Folder'
is not configured, then you must provide the --export-
path option as well. Existing files are not overwritten.
Exits when finished.
--md-date TEXT Export a Daily Markdown file for a given date (provide
the date as YYYY-MM-DD or YY-MM-DD). If a 'Daily
Markdown Folder' is not configured, then you must
provide the --export-path option as well. Existing files
are not overwritten. Exits when finished.
--end-date TEXT Export a range of sessions from the start date to the
end date (provide the dates as YYYY-MM-DD or YY-MM-DD).
This option is only valid with the --csv-date or --md-
date option.
--export-path TEXT Path to export a Daily CSV or Markdown file. This option
is required if a 'Daily CSV Folder' or 'Daily Markdown
Folder' is not configured, or you want the files written
to a different location.
--filters TEXT Filter specified actions from exported CSV data. The
filter is specified as a string with no spaces, where
each character represents a type of action to exclude.
The characters are: F (Finish), P (Pause - all), R
(pause w/o Reason), and X (Stop).
-h, --help Show this message and exit.
```
---
## Reference
- [Pomodoro Technique - Wikipedia](https://en.wikipedia.org/wiki/Pomodoro_Technique)
### Packages used
- [Textual](https://textual.textualize.io/) - Textual User Interface framework
- [Click](https://palletsprojects.com/p/click/) - command-line options
- [platformdirs](https://github.com/platformdirs/platformdirs#readme) - common directories on different platforms
- [plyer](https://pypi.org/project/plyer/) - system notifications
- [python-dotenv](https://pypi.org/project/python-dotenv/) - override default settings during development
- [tomlkit](https://pypi.org/project/tomlkit/) - store configuration as TOML
### Project tools
- [Hatch](https://hatch.pypa.io/latest/) - Python project manager (environments, packaging, and more)
- [Ruff](https://docs.astral.sh/ruff/) - linter and code formatter (integrated with Hatch)
- [pytest](https://docs.pytest.org/en/stable/) - testing framework
- [Just](https://github.com/casey/just#readme) - command runner
#### Textual Development Tools
- Textual [Devtools](https://textual.textualize.io/guide/devtools/)
- [tcss-vscode-extension](https://github.com/Textualize/tcss-vscode-extension#readme): VS Code extension that enables syntax highlighting for Textual CSS files.
- [pytest-textual-snapshot](https://github.com/Textualize/pytest-textual-snapshot#readme): Snapshot testing for Textual applications
Raw data
{
"_id": null,
"home_page": null,
"name": "pomodorable",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "Textual, pomodoro",
"author": null,
"author_email": "Bill Melvin <bill@billmelvin.com>",
"download_url": "https://files.pythonhosted.org/packages/1b/8f/db67e870ab63d64b8c66374436f20655898e4afd5c15b877836a382e2ff0/pomodorable-0.1.dev28.tar.gz",
"platform": null,
"description": "# pomodorable\n\nA **pomodoro timer** built using Textual.\n\n> Development work in progress.\n\n<!--  -->\n<p align=\"center\">\n<a href=\"https://github.com/wmelvin/pomodorable/raw/main/readme_images/pomororo-timer-200.jpg\">\n<img src=\"https://github.com/wmelvin/pomodorable/raw/main/readme_images/pomororo-timer-200.jpg\"\nalt=\"Picture of a Pomodoro Timer\"/></a></p>\n\n## Screenshots\n\n<!--  -->\n<p align=\"center\">\n<a href=\"https://github.com/wmelvin/pomodorable/raw/main/readme_images/app-1.gif\">\n<img src=\"https://github.com/wmelvin/pomodorable/raw/main/readme_images/app-1.gif\"\nalt=\"Screenshot animation\"/></a></p>\n\n## Using the Application\n\n### Modes\n\n1. **Ready**\n - Initial mode when the application starts.\n - Returned to when a session is *finished* or *stopped*.\n2. **Running**\n - Entered when the *Start* button is pressed.\n - Returned to when *Extend* or *Resume* is chosen in *paused* mode.\n3. **Paused**\n - Entered when the *Pause* button is pressed.\n - Ended by pressing *Extend*, *Resume* or *Stop*.\n\n### Display and Inputs\n\n#### Times Display\n\n- **Countdown** display: Shows the time remaining in the current session.\n- **Start Time** display: Shows the Start time of the current session. When a session is not *running* it shows the current time.\n- **End Time** display: Shows the End time of the current session. When a session is not *running* it shows the current time plus the session length.\n\n#### Settings Panel\n\n- **Reset** button: Resets the *Countdown* to the configured session length (default setting is 25 minutes).\n- **+5**, **+1**, **-1**, **-5** buttons: Increment or decrement the *Countdown* by minutes.\n- **?** (About) button: Open the *About* screen.\n- **Settings** button: Open the *Settings* screen.\n\n#### Task Panel\n\n- **Task description** input box: A brief description of the task at hand (optional). Press the **down arrow** key to open a list of recently used descriptions to pick from.\n- **Start** button: Starts the session. Countdown begins. Time displays show Start and End times for the running session.\n\n#### Pause Panel - Running\n\n- **Pause** button: Pause the running session.\n- **Reason description** input box: Disabled when *running*.\n\n#### Pause Panel - Paused\n\n- **Pause** button: Disabled when *paused*.\n- **Reason description** input box: Enter the reason for pausing (optional). Press the **down arrow** key to open a list of recently used descriptions to pick from.\n- **Extend** button: Return to *running*. Add the paused duration to the end-time to complete the full session length time-on-task.\n- **Resume** button: Return to *running*. Resume the session from the current time. The pause duration is subtracted from the countdown, reducing the session's time-on-task.\n- **Stop** button: Finish the session now. Return to *ready* mode.\n\n#### Timer Bar\n\n- Mimics the markings on a classic pomodoro (tomato-shaped) kitchen timer.\n- Shows the current countdown minute at the pointer.\n\n#### Log Panel\n\n- Shows messages from the application with a timestamp.\n\n### About Screen\n\nThe *About* screen is a dialog box showing some information about the application.\n\n- **Version** number of the application.\n- **GitHub** button: Open the web browser and go to the source GitHub page.\n- File locations:\n - **Data path** shows the directory where the application's data is stored. Output files are written to different locations as configured in the *Settings* screen.\n - **Configuration** shows the full path to the application's configuration file.\n- **Close** button: Closes the dialog.\n\n### Settings Screen\n\nThe *Settings* screen is where you configure the application. It has the following settings:\n\n- **Session Minutes**: Initial *Countdown* setting on startup, finish, stop, or reset.\n- **Running CSV Folder**: Folder to which the file is written. The folder must already exist.\n- **Running CSV File Name**: Name to use for the output file (default is `pomodorable-sessions.csv`).\n- **Daily CSV Folder**: Folder to which the file is written. The folder must already exist.\n- **Filter CSV Output**: Exclude selected actions from the CSV output files (see *Filters* below).\n- **Daily Markdown Folder**: Folder to which the file is written. The folder must already exist.\n- **Daily Markdown Heading**: The Markdown [heading](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#headings) to insert before the individual sessions. The heading can be any heading level (`# Heading-text` or `### Heading-text` for example).\n- **Daily Markdown Append-only**: When enabled, the file must already exist. This is for the case where the file is initially created by another application (such as a Daily Note file created by Obsidian).\n- **Filter Markdown Output**: Exclude selected actions from the Markdown output files (see *Filters* below).\n- **Log Retention Days**: Number of daily log files to keep. This applies to the application's operational logs, not the session data.\n\n**Filters** for CSV and Markdown output:\n\n| Settings screen | CLI: `--filters=` | Description |\n| --- | --- | --- |\n| Finish | F | Exclude *Finish* actions. |\n| Pause (all) | P | Exclude all *Pause* actions. |\n| Pause (w/o Reason) | R | Exclude *Pause* actions with no *reason* noted. |\n| Stop | X | Exclude *Stop* actions. |\n\n## Outputs\n\n### Daily and Running CSV\n\nThe **Daily CSV** output is for a single day. The folder it is written to can be configured in the *Settings* screen. The name of the file is the current date as *yyyy*-*mm*-*dd*.csv (`2024-04-30.csv`, for example).\n\nThe **Running CSV** output spans multiple days (*running* vs *daily*). Both the folder, and file name, are configured in the *Settings* screen.\n\nThe following columns are in the CSV output files:\n\n- **date**: Date of the action.\n- **act**: Action code (see below). When exported via the `--export-csv` CLI option, *Start* actions will instead have the *session number* (daily sequence).\n- **time**: Time of the action.\n- **task**: Description of the task for *Start* actions, otherwise empty.\n- **message**: Message associated with the action. Varies depending on the action.\n- **notes**: Note associated with the action. Varies depending on the action.\n\nAction codes:\n\n- **S** - Start\n- **E** - Extend (after Pause)\n- **R** - Resume (after Pause)\n- **F** - Finished session\n- **X** - Stopped session\n\nNote: The format of the CSV output files is based on the layout of a spreadsheet the author uses to track *pomodoro sessions* (among other things). It is designed for easy copy and paste into that spreadsheet. It's likely not the layout someone else would choose.\n\n### Daily Markdown\n\nThe *Daily Markdown* output is designed to insert *pomodoro sessions* into a [Daily Notes](https://help.obsidian.md/Plugins/Daily+notes) file in [Obisdian](https://obsidian.md/).\n\nIf the *Daily Markdown Append-only* setting is enabled, the Daily Note file (expects `YYYY-MM-DD.md`) must already exist. This is for the case where a [template](https://help.obsidian.md/Plugins/Templates) is used for Daily Note files and you want that template to always be used to create the file. If sessions are completed before the file is created they will be included the first time a session finishes and the Daily Note file exists.\n\n## Data\n\n### Configuration File\n\nThe configuration file is `pomodorable-config.toml` and is stored in a folder named `pomodorable` under the *user config* folder for the operating system. Configuration settings are managed in the *Settings* screen. You should not need to directly edit this file.\n\n### Data File\n\nThe main data file is `pomodorable-data.csv` and is stored in a folder named `pomodorable` under the *user data* folder for the operating system.\n\nEach **action** (or *event*) recorded by the application is written to this file.\n\nThe columns in the CSV file are:\n\n- **version**: The version of the CSV format.\n- **date**: The date of the action.\n- **time**: The time of the action.\n- **action**: The *name* of the action.\n- **message**: A message associated with the action.\n- **duration**: The duration of the action.\n- **notes**: Any notes associated with the action.\n\nThis file is not intended to be used directly (though being CSV format, that is easy to do). There are several output files that provide a log of pomodoro sessions for the user.\n\n### Log Files\n\nLog files are also written to the `pomodorable` folder under the system's *user data* folder.\nEach log file is named with the current date.\nThe number of files to keep is configured in the *Settings* screen.\n\n---\n\n## Command-Line Usage\n\n``` console\n\nUsage: pomodorable [OPTIONS]\n\n Handle command-line options or run the Textual User Interface.\n\nOptions:\n --version Show the version and exit.\n --csv-date TEXT Export a Daily CSV file for a given date (provide the\n date as YYYY-MM-DD or YY-MM-DD). If a 'Daily CSV Folder'\n is not configured, then you must provide the --export-\n path option as well. Existing files are not overwritten.\n Exits when finished.\n --md-date TEXT Export a Daily Markdown file for a given date (provide\n the date as YYYY-MM-DD or YY-MM-DD). If a 'Daily\n Markdown Folder' is not configured, then you must\n provide the --export-path option as well. Existing files\n are not overwritten. Exits when finished.\n --end-date TEXT Export a range of sessions from the start date to the\n end date (provide the dates as YYYY-MM-DD or YY-MM-DD).\n This option is only valid with the --csv-date or --md-\n date option.\n --export-path TEXT Path to export a Daily CSV or Markdown file. This option\n is required if a 'Daily CSV Folder' or 'Daily Markdown\n Folder' is not configured, or you want the files written\n to a different location.\n --filters TEXT Filter specified actions from exported CSV data. The\n filter is specified as a string with no spaces, where\n each character represents a type of action to exclude.\n The characters are: F (Finish), P (Pause - all), R\n (pause w/o Reason), and X (Stop).\n -h, --help Show this message and exit.\n```\n\n---\n\n## Reference\n\n- [Pomodoro Technique - Wikipedia](https://en.wikipedia.org/wiki/Pomodoro_Technique)\n\n### Packages used\n\n- [Textual](https://textual.textualize.io/) - Textual User Interface framework\n- [Click](https://palletsprojects.com/p/click/) - command-line options\n- [platformdirs](https://github.com/platformdirs/platformdirs#readme) - common directories on different platforms\n- [plyer](https://pypi.org/project/plyer/) - system notifications\n- [python-dotenv](https://pypi.org/project/python-dotenv/) - override default settings during development\n- [tomlkit](https://pypi.org/project/tomlkit/) - store configuration as TOML\n\n### Project tools\n\n- [Hatch](https://hatch.pypa.io/latest/) - Python project manager (environments, packaging, and more)\n- [Ruff](https://docs.astral.sh/ruff/) - linter and code formatter (integrated with Hatch)\n- [pytest](https://docs.pytest.org/en/stable/) - testing framework\n- [Just](https://github.com/casey/just#readme) - command runner\n\n#### Textual Development Tools\n\n- Textual [Devtools](https://textual.textualize.io/guide/devtools/)\n- [tcss-vscode-extension](https://github.com/Textualize/tcss-vscode-extension#readme): VS Code extension that enables syntax highlighting for Textual CSS files.\n- [pytest-textual-snapshot](https://github.com/Textualize/pytest-textual-snapshot#readme): Snapshot testing for Textual applications\n",
"bugtrack_url": null,
"license": null,
"summary": "A pomodoro timer implemented as a Textual app",
"version": "0.1.dev28",
"project_urls": {
"Documentation": "https://github.com/wmelvin/pomodorable#readme",
"Source": "https://github.com/wmelvin/pomodorable"
},
"split_keywords": [
"textual",
" pomodoro"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "8bffd8c21f01fd740662d949024126aec15dc4c05f1915701b95214e59f622ef",
"md5": "a8f7ecdacd97ee8447953f43479603ac",
"sha256": "1357b74932d2d0e8a6bdef443b7f3542e007be649f89b427152061a45db777c0"
},
"downloads": -1,
"filename": "pomodorable-0.1.dev28-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a8f7ecdacd97ee8447953f43479603ac",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 27568,
"upload_time": "2024-05-11T19:16:18",
"upload_time_iso_8601": "2024-05-11T19:16:18.348252Z",
"url": "https://files.pythonhosted.org/packages/8b/ff/d8c21f01fd740662d949024126aec15dc4c05f1915701b95214e59f622ef/pomodorable-0.1.dev28-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1b8fdb67e870ab63d64b8c66374436f20655898e4afd5c15b877836a382e2ff0",
"md5": "cfe4726650d598300e1515bc2b453dbc",
"sha256": "8cf752732468eafc103b71723b748ff3ed8dcafeed85e72ffe96254e744b1fcb"
},
"downloads": -1,
"filename": "pomodorable-0.1.dev28.tar.gz",
"has_sig": false,
"md5_digest": "cfe4726650d598300e1515bc2b453dbc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 206430,
"upload_time": "2024-05-11T19:16:16",
"upload_time_iso_8601": "2024-05-11T19:16:16.586462Z",
"url": "https://files.pythonhosted.org/packages/1b/8f/db67e870ab63d64b8c66374436f20655898e4afd5c15b877836a382e2ff0/pomodorable-0.1.dev28.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-11 19:16:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "wmelvin",
"github_project": "pomodorable#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pomodorable"
}
