# Schedrem
A cross-platform task scheduler and reminder configured in YAML.
## How it Works
Schedrem is a Python package that provides a tool for scheduling tasks and setting reminders.
As a resident program, it monitors changes in the configuration file, triggers tasks to execute commands or display message boxes as reminders. It also validates the configuration format every time the file is saved.
The configuration file, which is a YAML file, is easy to read and write. You can use your favorite text editor to configure your schedules.
Audible alarm using a sound file (currently WAV format only) is available.
## Installation
Python 3.11 or later is required.
### From PyPI
Install from [PyPI](https://pypi.org/project/schedrem/) using `pip`:
```sh
python -m pip install -U schedrem
```
### From Source Using pip
```sh
git clone https://github.com/hikyae/schedrem
cd schedrem
python -m pip install -e .
```
### From AUR
There also exists an [AUR](https://aur.archlinux.org/packages/schedrem) package.
Install from AUR using a helper such as `yay` or `paru`:
```sh
yay -S schedrem
```
```sh
paru -S schedrem
```
#### From Source Using Makepkg
```sh
git clone https://aur.archlinux.org/packages/schedrem
cd schedrem
makepkg -si
```
## Configuration
Schedrem searches for the configuration file in the order specified below and uses the first one that is found. The actual path depends on the platform and environment variables.
The file format must be YAML. Use your favorite text editor to edit the file.
Schedrem will automatically detect the changes you've made to the configuration file. If there is an error in the file, a message box will pop up and it will try to tell you the reason. Please fix the file and save it, then close the message box. Otherwise, the message box will keep popping up.
Note that there is no configuration file to set **command-line options** such as `--config` or `--debug`.
### Path Specified by Command-Line Parameter
You can set the file path by passing it as a command-line parameter:
```sh
schedrem --config path/to/config
```
### Default Paths for Linux/macOS
- `${XDG_CONFIG_HOME}/schedrem/config.yml`
- `${XDG_CONFIG_HOME}/schedrem/config.yaml`
- `${HOME}/.config/schedrem/config.yml`
- `${HOME}/.config/schedrem/config.yaml`
### Default Paths for Windows
- `%USERPROFILE%\.config\schedrem\config.yml`
- `%USERPROFILE%\.config\schedrem\config.yaml`
- `%APPDATA%\schedrem\config.yml`
- `%APPDATA%\schedrem\config.yaml`
### Examples
Please refer to the [examples](https://github.com/hikyae/schedrem/tree/main/examples) directory in this repository.
### Structure
#### Schedules
All the schedules should be listed here.
Each schedule is an item in the list of `schedules`, denoted by a leading hyphen (-).
It can have `description` (abbreviated as `desc`), `time`, `wait`, `enabled`, and an action that consists of `message` (abbreviated as `msg`), `yesno`, `command` (abbreviated as `cmd`), `sound`, and `font`.
Basically, every key is optional with a few exceptions. If there is no action specified out of `message`, `yesno`, or `command`, an error occurs.
```yaml
schedules:
- message: This is the simplest schedule. This message is shown every minute.
- description: The message "Good morning" is shown every day at 6 o'clock.
time:
hour: 6
minute: 0
message: Good morning.
```
##### Description
A string to describe the schedule.
##### Time
The time specification is inspired by cron, but is more readable and has some differences.
Specify integers or a list of integers for `year`, `month`, `day`, `hour`, `minute` to schedule the date(s) and time(s).
Specify string or a list of strings for `weekday` (abbreviated as `dow`) to schedule the day(s) of the week.
If you omit any of them, then the task is triggered at any of the times within that range. This is similar to using `*` in a crontab.
If you don't specify the time, then the task is triggered every minute.
##### Wait
The time to wait before triggering the task. The task won't be triggered until the specified time has elapsed.
You can specify integers for `year`, `month`, `day`, `hour`, `minute`, but only `year` is mandatory.
##### Enabled
A boolean (`true`/`false`, `yes`/`no`, `on`/`off`) to set whether the task should be triggered or not. The default value is `true`.
Useful when you toggle multiple schedules with a single flag using an anchor in YAML.
##### Action
The "action" is a conceptual term, not a configuration file key. The configuration file consists of the following keys: `message` (abbreviated as `msg`), `yesno`, `command` (abbreviated as `cmd`), `sound`, and `font`.
The detail of these keys is as follows:
- `message`: A string to show in a message box with an OK button.
- `yesno`: A string to display in a message box asking for a Yes or No response. If the user selects "Yes", the `command` will be executed, and the `message` will be shown if they are specified. If "No" is selected, neither the `command` nor the `message` will be run.
- `command`: A string of an arbitrary shell command.
- `sound`: A string of the path to a sound file to play, or a boolean (`true`/`false`, `yes`/`no`, `on`/`off`) to set whether the default sound should be played while showing a message box. The only acceptable sound file format is WAV.
- `font`: A string specifying the font family and font size to use in the message box, in the format `<font family> <font size>`, for example, "Cica 40".
#### Optional global settings
These are optional settings that affect all schedules.
- `disabled`: A boolean (`true`/`false`, `yes`/`no`, `on`/`off`) to set whether Schedrem should run or not. Set this to `true` when you want Schedrem to stop waiting for all schedules or when you want all running tasks, including all visible message boxes, to be killed. The default value is `false`.
```yaml
disabled: true
```
- `weekdaynames`: A list of lists of strings to set the names for the days of the week. They start from Monday and are case-insensitive. The default value is `[mon, tue, wed, thu, fri, sat, sun]`.
```yaml
weekdaynames:
- [mon, tue, wed, thu, fri, sat, sun]
- [月, 火, 水, 木, 金, 土, 日]
schedules:
- description: Time to take out the burnable trash
time:
hour: 7
minute: 50
weekday: 月
message: 燃えるゴミを捨てる
```
- `font`: A string specifying the font family and font size to use in the message box, in the format `<font family> <font size>`, for example, "Cica 40". If you set this value outside of `schedules`, each action will use this font setting unless the font is explicitly set within the action. The default value is `Arial 19`.
```yaml
font: Arial 70
schedules:
- description: You will see the huge text every minute
message: HUGE
```
- `aliases`: Thanks to the YAML specification, it is possible to make aliases for values for schedules. The naming of the key `aliases` is not mandatory.
```yaml
aliases:
- &workdays [mon, tue, wed, thu, fri]
- &friday13th
day: 13
dow: fri
schedules:
- desc: Time to go
time:
hour: 8
minute: 0
dow: *workdays
msg: Go to work
- desc: Beware of unluckiness in the morning
time:
hour: 8
minute: 0
<<: *friday13th
msg: Good morning, and beware!
```
## Usage
First, you need to put your configuration file into one of the places described in the [Configuration](#configuration) section.
Try starting Schedrem from a terminal to check for any errors:
```sh
schedrem --debug
```
This starts Schedrem in the foreground with the debug option, displaying configuration information if there are no issues. If no errors appear, you're good to proceed. You can stop the process by pressing `<Ctrl>+C`.
Set the config path if you put it besides the defaults:
```sh
schedrem --config path/to/config
```
### Auto-starting
On Linux, to start Schedrem as a background program in a stand-alone window manager, add the following line to your startup script, such as `~/.xinitrc`:
```sh
schedrem &
```
The trailing ampersand "&" means that the program should run in the background. To stop Schedrem, just type `pkill schedrem`.
In a desktop environment (such as GNOME, KDE, Xfce, MATE, Cinnamon, etc.), you can simply add Schedrem to the list of autostarted applications without the trailing "&".
On Windows, you need to create a shortcut for the command:
1. Open the Startup Folder:
- Press Win + R, type `shell:startup`, and press Enter.
2. Create a New Shortcut:
- Right-click inside the Startup folder, then select New > Shortcut.
3. Enter the Shortcut Target:
- In the Location field, use PowerShell to run the command in hidden mode. Enter this command:
```cmd
powershell -windowstyle hidden -command "schedrem"
```
On macOS, you need to put a plist file as `~/Library/LaunchAgents/com.yourusername.schedrem.plist`:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.yourusername.schedrem</string>
<key>ProgramArguments</key>
<array>
<string>schedrem</string> <!-- Assuming "schedrem" is accessible via PATH -->
</array>
<key>RunAtLoad</key>
<true/>
</dict>
</plist>
```
## Tips
- There is a command-line option `--action` that can receive a JSON string as an action.
Though this option is used internally for executing tasks, you can also manually execute it as a command. Answering "No" to yesno prompt lets the command exit with the code 1.
```sh
schedrem --action '{"msg":"test","sound":true}'
schedrem --action '{"yesno":"yes?","cmd":"echo yes"}'; echo $?
schedrem --action '{"yesno":"Did you do push-ups?","msg":"Nice."}' || schedrem --action '{"msg":"Do it."}'
```
- Unlike cron, you can configure the time with constraints on both the day of the month **and** the day of the week.
Raw data
{
"_id": null,
"home_page": null,
"name": "schedrem",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "YAML, cross-platform, desktop, reminder, scheduler, task, tkinter",
"author": null,
"author_email": "hikyae <h1ky43@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/da/44/bda09f72adefc50ad5f695bc498232b96a9b5b8203b327c99e8c9eb7807e/schedrem-1.3.1.tar.gz",
"platform": null,
"description": "# Schedrem\n\nA cross-platform task scheduler and reminder configured in YAML.\n\n## How it Works\n\nSchedrem is a Python package that provides a tool for scheduling tasks and setting reminders.\n\nAs a resident program, it monitors changes in the configuration file, triggers tasks to execute commands or display message boxes as reminders. It also validates the configuration format every time the file is saved.\n\nThe configuration file, which is a YAML file, is easy to read and write. You can use your favorite text editor to configure your schedules.\n\nAudible alarm using a sound file (currently WAV format only) is available.\n\n## Installation\n\nPython 3.11 or later is required.\n\n### From PyPI\n\nInstall from [PyPI](https://pypi.org/project/schedrem/) using `pip`:\n\n```sh\npython -m pip install -U schedrem\n```\n\n### From Source Using pip\n\n```sh\ngit clone https://github.com/hikyae/schedrem\ncd schedrem\npython -m pip install -e .\n```\n\n### From AUR\n\nThere also exists an [AUR](https://aur.archlinux.org/packages/schedrem) package.\n\nInstall from AUR using a helper such as `yay` or `paru`:\n\n```sh\nyay -S schedrem\n```\n\n```sh\nparu -S schedrem\n```\n\n#### From Source Using Makepkg\n\n```sh\ngit clone https://aur.archlinux.org/packages/schedrem\ncd schedrem\nmakepkg -si\n```\n\n## Configuration\n\nSchedrem searches for the configuration file in the order specified below and uses the first one that is found. The actual path depends on the platform and environment variables.\n\nThe file format must be YAML. Use your favorite text editor to edit the file.\n\nSchedrem will automatically detect the changes you've made to the configuration file. If there is an error in the file, a message box will pop up and it will try to tell you the reason. Please fix the file and save it, then close the message box. Otherwise, the message box will keep popping up.\n\nNote that there is no configuration file to set **command-line options** such as `--config` or `--debug`.\n\n### Path Specified by Command-Line Parameter\n\nYou can set the file path by passing it as a command-line parameter:\n\n```sh\nschedrem --config path/to/config\n```\n\n### Default Paths for Linux/macOS\n\n- `${XDG_CONFIG_HOME}/schedrem/config.yml`\n- `${XDG_CONFIG_HOME}/schedrem/config.yaml`\n- `${HOME}/.config/schedrem/config.yml`\n- `${HOME}/.config/schedrem/config.yaml`\n\n### Default Paths for Windows\n\n- `%USERPROFILE%\\.config\\schedrem\\config.yml`\n- `%USERPROFILE%\\.config\\schedrem\\config.yaml`\n- `%APPDATA%\\schedrem\\config.yml`\n- `%APPDATA%\\schedrem\\config.yaml`\n\n### Examples\n\nPlease refer to the [examples](https://github.com/hikyae/schedrem/tree/main/examples) directory in this repository.\n\n### Structure\n\n#### Schedules\n\nAll the schedules should be listed here.\n\nEach schedule is an item in the list of `schedules`, denoted by a leading hyphen (-).\nIt can have `description` (abbreviated as `desc`), `time`, `wait`, `enabled`, and an action that consists of `message` (abbreviated as `msg`), `yesno`, `command` (abbreviated as `cmd`), `sound`, and `font`.\nBasically, every key is optional with a few exceptions. If there is no action specified out of `message`, `yesno`, or `command`, an error occurs.\n\n```yaml\nschedules:\n - message: This is the simplest schedule. This message is shown every minute.\n\n - description: The message \"Good morning\" is shown every day at 6 o'clock.\n time:\n hour: 6\n minute: 0\n message: Good morning.\n```\n\n##### Description\n\nA string to describe the schedule.\n\n##### Time\n\nThe time specification is inspired by cron, but is more readable and has some differences.\n\nSpecify integers or a list of integers for `year`, `month`, `day`, `hour`, `minute` to schedule the date(s) and time(s).\nSpecify string or a list of strings for `weekday` (abbreviated as `dow`) to schedule the day(s) of the week.\n\nIf you omit any of them, then the task is triggered at any of the times within that range. This is similar to using `*` in a crontab.\n\nIf you don't specify the time, then the task is triggered every minute.\n\n##### Wait\n\nThe time to wait before triggering the task. The task won't be triggered until the specified time has elapsed.\n\nYou can specify integers for `year`, `month`, `day`, `hour`, `minute`, but only `year` is mandatory.\n\n##### Enabled\n\nA boolean (`true`/`false`, `yes`/`no`, `on`/`off`) to set whether the task should be triggered or not. The default value is `true`.\n\nUseful when you toggle multiple schedules with a single flag using an anchor in YAML.\n\n##### Action\n\nThe \"action\" is a conceptual term, not a configuration file key. The configuration file consists of the following keys: `message` (abbreviated as `msg`), `yesno`, `command` (abbreviated as `cmd`), `sound`, and `font`.\n\nThe detail of these keys is as follows:\n\n- `message`: A string to show in a message box with an OK button.\n- `yesno`: A string to display in a message box asking for a Yes or No response. If the user selects \"Yes\", the `command` will be executed, and the `message` will be shown if they are specified. If \"No\" is selected, neither the `command` nor the `message` will be run.\n- `command`: A string of an arbitrary shell command.\n- `sound`: A string of the path to a sound file to play, or a boolean (`true`/`false`, `yes`/`no`, `on`/`off`) to set whether the default sound should be played while showing a message box. The only acceptable sound file format is WAV.\n- `font`: A string specifying the font family and font size to use in the message box, in the format `<font family> <font size>`, for example, \"Cica 40\".\n\n#### Optional global settings\n\nThese are optional settings that affect all schedules.\n\n- `disabled`: A boolean (`true`/`false`, `yes`/`no`, `on`/`off`) to set whether Schedrem should run or not. Set this to `true` when you want Schedrem to stop waiting for all schedules or when you want all running tasks, including all visible message boxes, to be killed. The default value is `false`.\n\n ```yaml\n disabled: true\n ```\n\n- `weekdaynames`: A list of lists of strings to set the names for the days of the week. They start from Monday and are case-insensitive. The default value is `[mon, tue, wed, thu, fri, sat, sun]`.\n\n ```yaml\n weekdaynames:\n - [mon, tue, wed, thu, fri, sat, sun]\n - [\u6708, \u706b, \u6c34, \u6728, \u91d1, \u571f, \u65e5]\n\n schedules:\n - description: Time to take out the burnable trash\n time:\n hour: 7\n minute: 50\n weekday: \u6708\n message: \u71c3\u3048\u308b\u30b4\u30df\u3092\u6368\u3066\u308b\n ```\n\n- `font`: A string specifying the font family and font size to use in the message box, in the format `<font family> <font size>`, for example, \"Cica 40\". If you set this value outside of `schedules`, each action will use this font setting unless the font is explicitly set within the action. The default value is `Arial 19`.\n\n ```yaml\n font: Arial 70\n\n schedules:\n - description: You will see the huge text every minute\n message: HUGE\n ```\n\n- `aliases`: Thanks to the YAML specification, it is possible to make aliases for values for schedules. The naming of the key `aliases` is not mandatory.\n\n```yaml\naliases:\n - &workdays [mon, tue, wed, thu, fri]\n - &friday13th\n day: 13\n dow: fri\n\nschedules:\n - desc: Time to go\n time:\n hour: 8\n minute: 0\n dow: *workdays\n msg: Go to work\n\n - desc: Beware of unluckiness in the morning\n time:\n hour: 8\n minute: 0\n <<: *friday13th\n msg: Good morning, and beware!\n```\n\n## Usage\n\nFirst, you need to put your configuration file into one of the places described in the [Configuration](#configuration) section.\n\nTry starting Schedrem from a terminal to check for any errors:\n\n```sh\nschedrem --debug\n```\n\nThis starts Schedrem in the foreground with the debug option, displaying configuration information if there are no issues. If no errors appear, you're good to proceed. You can stop the process by pressing `<Ctrl>+C`.\n\nSet the config path if you put it besides the defaults:\n\n```sh\nschedrem --config path/to/config\n```\n\n### Auto-starting\n\nOn Linux, to start Schedrem as a background program in a stand-alone window manager, add the following line to your startup script, such as `~/.xinitrc`:\n\n```sh\nschedrem &\n```\n\nThe trailing ampersand \"&\" means that the program should run in the background. To stop Schedrem, just type `pkill schedrem`.\n\nIn a desktop environment (such as GNOME, KDE, Xfce, MATE, Cinnamon, etc.), you can simply add Schedrem to the list of autostarted applications without the trailing \"&\".\n\nOn Windows, you need to create a shortcut for the command:\n\n1. Open the Startup Folder:\n - Press Win + R, type `shell:startup`, and press Enter.\n2. Create a New Shortcut:\n - Right-click inside the Startup folder, then select New > Shortcut.\n3. Enter the Shortcut Target:\n - In the Location field, use PowerShell to run the command in hidden mode. Enter this command:\n ```cmd\n powershell -windowstyle hidden -command \"schedrem\"\n ```\n\nOn macOS, you need to put a plist file as `~/Library/LaunchAgents/com.yourusername.schedrem.plist`:\n\n```xml\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<!DOCTYPE plist PUBLIC \"-//Apple//DTD PLIST 1.0//EN\" \"http://www.apple.com/DTDs/PropertyList-1.0.dtd\">\n<plist version=\"1.0\">\n<dict>\n <key>Label</key>\n <string>com.yourusername.schedrem</string>\n <key>ProgramArguments</key>\n <array>\n <string>schedrem</string> <!-- Assuming \"schedrem\" is accessible via PATH -->\n </array>\n <key>RunAtLoad</key>\n <true/>\n</dict>\n</plist>\n```\n\n## Tips\n\n- There is a command-line option `--action` that can receive a JSON string as an action.\nThough this option is used internally for executing tasks, you can also manually execute it as a command. Answering \"No\" to yesno prompt lets the command exit with the code 1.\n\n```sh\nschedrem --action '{\"msg\":\"test\",\"sound\":true}'\nschedrem --action '{\"yesno\":\"yes?\",\"cmd\":\"echo yes\"}'; echo $?\nschedrem --action '{\"yesno\":\"Did you do push-ups?\",\"msg\":\"Nice.\"}' || schedrem --action '{\"msg\":\"Do it.\"}'\n```\n\n- Unlike cron, you can configure the time with constraints on both the day of the month **and** the day of the week.\n",
"bugtrack_url": null,
"license": null,
"summary": "A cross-platform task scheduler and reminder configured in YAML.",
"version": "1.3.1",
"project_urls": {
"Homepage": "https://github.com/hikyae/schedrem",
"Issues": "https://github.com/hikyae/schedrem/issues"
},
"split_keywords": [
"yaml",
" cross-platform",
" desktop",
" reminder",
" scheduler",
" task",
" tkinter"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "671d7494683ae40ee5cf15b936acf9a9545008fb49f174de5ac0dd705e036ffb",
"md5": "0b9b97599fd77a9b3b7534c477539b39",
"sha256": "5bf48a4ccbadee16d11f251c2ae50c8a817d6f798b8d12ba0f8744e9517b6739"
},
"downloads": -1,
"filename": "schedrem-1.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0b9b97599fd77a9b3b7534c477539b39",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 157518,
"upload_time": "2024-11-22T04:42:13",
"upload_time_iso_8601": "2024-11-22T04:42:13.879486Z",
"url": "https://files.pythonhosted.org/packages/67/1d/7494683ae40ee5cf15b936acf9a9545008fb49f174de5ac0dd705e036ffb/schedrem-1.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "da44bda09f72adefc50ad5f695bc498232b96a9b5b8203b327c99e8c9eb7807e",
"md5": "6403d524b2bd2832a24521d1d16d9c33",
"sha256": "6d9920c151dbe75e5b29f917dfc4283cce0bd1f0b89c96e91fca6f6c1b285b0e"
},
"downloads": -1,
"filename": "schedrem-1.3.1.tar.gz",
"has_sig": false,
"md5_digest": "6403d524b2bd2832a24521d1d16d9c33",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 159622,
"upload_time": "2024-11-22T04:42:15",
"upload_time_iso_8601": "2024-11-22T04:42:15.688673Z",
"url": "https://files.pythonhosted.org/packages/da/44/bda09f72adefc50ad5f695bc498232b96a9b5b8203b327c99e8c9eb7807e/schedrem-1.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-22 04:42:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "hikyae",
"github_project": "schedrem",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "schedrem"
}
JSON
