| Name | timesched JSON |
| Version |
1.8
JSON |
| download |
| home_page | |
| Summary | Improved simple time scheduler based on standard sched |
| upload_time | 2023-11-02 03:03:51 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.6 |
| license | GPLv3 |
| keywords |
sched
scheduler
timer
periodic
cron
crontab
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
## TIMESCHED
[](https://pypi.org/project/timesched/)
[](https://aur.archlinux.org/packages/python-timesched/)
The `timesched` Python module provides a simple time event scheduler. It
is implemented upon the standard Python
[`sched`](https://docs.python.org/3/library/sched.html) module and is
used in a similar way, but provides a nicer and more modern and
convenient programming interface. Apart from normal oneshot and repeat
timers, it can run timers at a given time of day, and for the given days
of week, providing simple cron-like functionality. It requires only
Python 3.6 or later, and the standard library. The latest version of
this document and code is available at
https://github.com/bulletmark/timesched.
```python
class timesched.Scheduler(timefunc=time.time, delayfunc=time.sleep)
```
Refer to the class description for Python
[sched.scheduler](https://docs.python.org/3/library/sched.html#sched.scheduler)
which is used in the [internal
implementation](#differences-to-standard-sched-module) of this class.
_Scheduler_ instances have the following methods.
#### Create one-shot timer
```python
oneshot(time, priority, func, *args, **kwargs)
```
- _time_: expiry time relative to now, or absolute time. Type can be one of:
- `int` at given relative seconds after now,
- `datetime.timedelta()` at given relative `timedelta()` after now,
- `datetime.time()` at given `time()` after now,
- `datetime.datetime()` at given absolute `datetime()`,
- `datetime.date()` at given absolute `date()`,
- _priority_: int value, lower value is higher priority. Refer
[description](https://docs.python.org/3/library/sched.html#sched.scheduler.enterabs).
- _func_ and _args_ and _kwargs_: user function and arguments to call
when timer is invoked.
Returns a _timer_ ID which can be used to cancel the timer using
[`cancel(timer)`](#cancel-timer).
#### Create repeating timer
```python
repeat(period, priority, func, *args, **kwargs)
```
- _period_: period for timer. Type can be one of:
- `int` at each given seconds after now,
- `datetime.timedelta()` at each given `timedelta()` after now,
- `datetime.time()` at given `time()` each day after now. E.g. at
10:30 every day for simple daily "cron-like" functionality.
- _priority_: int value, lower value is higher priority. Refer
[description](https://docs.python.org/3/library/sched.html#sched.scheduler.enterabs).
- _func_ and _args_ and _kwargs_: user function and arguments to call
when timer is invoked.
Returns a _timer_ ID which can be used to cancel the timer using
[`cancel(timer)`](#cancel-timer).
Note that for _int_ and _timedelta()_ periods, the specified period is
the delay between the end of the callback function and when it is called
again so the actual period will slowly "creep" by the run time of the
callback. Many applications are not concerned about this distinction but if
necessary you can instead invoke a _oneshot()_ absolute timer between
each call.
#### Create one-shot timer on next given day
Call this with _time_ = `datetime.time()` to invoke a `oneshot()` at the
given _time_ on the next day from the set of given _days_ of the week.
```python
oneshot_on_days(days, time, priority, func, *args, **kwargs)
```
- _days_: A list/set/sequence/range of integers 0-6 where 0 = Monday to
6 = Sunday. e.g. [0] means only invoke timer on a Monday, [0,6] = only
invoke on Monday and Sunday, etc. Using `days=range(7)` is same as
calling ordinary `oneshot()`.
Alternately, you can specify _days_ as a string "MTWTFSS" where each
char is upper case if the day is to be set, and lower case if not.
E.g. "MTWTFss" is the working week Mon-Fri, "mtwTfss" is Thu only,
etc. A utility function to explicitly parse this string into a set of
integers is available as `timesched.parse_days(string_arg)` if you
need.
Remaining parameters and return type are same as `oneshot()`.
#### Create repeating timer on given days
Call this with _time_ = `datetime.time()` to invoke a `repeat()` at the
given _period_ on each of the given _days_ of the week.
```python
repeat_on_days(days, period, priority, func, *args, **kwargs)
```
- _days_: parameter same as `oneshot_on_days()`.
Remaining parameters and return type are same as `repeat()`.
#### Return count of active timers
```python
count()
```
Returns the count of timers currently active. A timer is considered
active while it is pending and until it's callback function has
completed, unless it is explicitly cancelled.
#### Cancel timer
```python
cancel(timer)
```
Remove the timer with `timer` ID. If the timer is not currently active,
this method will raise a ValueError.
#### Run scheduler
```python
run(blocking=True)
```
Invokes the base `scheduler.run()`. Refer full
description at [Python sched
module](https://docs.python.org/3/library/sched.html#sched.scheduler.run).
## EXAMPLES
```python
#!/usr/bin/python3
'Very simple examples'
import timesched
from datetime import datetime, time
# Job function to be called for each timer
def job(jobid):
print(f'Job {jobid} called at {datetime.now()}')
# Create a scheduler
s = timesched.Scheduler()
# Execute job() once in 5 secs time
s.oneshot(5, 0, job, 1)
# Execute job() every 2 secs
s.repeat(2, 0, job, 2)
# Execute job() at 10:30am every work day (not weekends)
s.repeat_on_days('MTWTFss', time(10, 30), 0, job, 3)
# Run scheduler, will block until no timers left running
s.run()
```
## DIFFERENCES TO STANDARD SCHED MODULE
The `timesched` module is internally implemented using the standard
Python [`sched`](https://docs.python.org/3/library/sched.html) module
but differs in the following ways. Note that the `sched` implementation,
methods, and attributes are not directly exposed in the public interface.
- Provides `oneshot()` and `repeat()` methods to conveniently accept
standard
[`datetime.datetime()`](https://docs.python.org/3/library/datetime.html#datetime-objects),
[`datetime.date()`](https://docs.python.org/3/library/datetime.html#date-objects),
[`datetime.time()`](https://docs.python.org/3/library/datetime.html#time-objects),
[`datetime.timedelta()`](https://docs.python.org/3/library/datetime.html#timedelta-objects),
and also integer time arguments, based automatically on the type of the
passed time argument.
- The `repeat()` method sets itself up to be automatically invoked again
at the next repeat interval, unlike `sched` which only provides a
`oneshot()` equivalent method [i.e. `enter()` or `enterabs()`] so the user
does not need to explicitly set up the next timer.
- Provides a convenient way to schedule a timer at a given time each
day to give simple daily "cron-like" functionality, e.g.
`s.repeat(datetime.time(hour=10, minute=30), f)` to periodically
activate a timer at 10:30 every day.
- Further to the above `repeat()` which can run at a given time every
day, you can use `repeat_on_days()` to specify a given time on a set
of given days, e.g. `s.repeat_on_days('MTWTFss',
datetime.time(hour=10, minute=30), f)` to run the timer at 10:30 each
workday only (Mon to Fri). Alternately `s.repeat_on_days(range(5),
datetime.time(hour=10, minute=30), f)`
gives the same result.
- Consistent with modern Python, allows user to plainly specify `*args`
and `**kwargs` directly in timer setup call rather than in a tuple as
legacy `sched` requires.
- Does not provide the
[`enter()`](https://docs.python.org/3/library/sched.html#sched.scheduler.enter)
or
[`enterabs()`](https://docs.python.org/3/library/sched.html#sched.scheduler.enterabs)
methods. Use the superior `oneshot()`, `repeat()`,
`oneshot_on_days()`, or `repeat_on_days()` methods instead.
- Provides a more specific `count()` method instead of
[`empty()`](https://docs.python.org/3/library/sched.html#sched.scheduler.empty).
- Does not provide the
[`queue`](https://docs.python.org/3/library/sched.html#sched.scheduler.queue)
attribute.
- Uses `time.time` instead of `time.monotonic` as the default `timefunc`
for the internal
[scheduler](https://docs.python.org/3/library/sched.html#sched.scheduler).
This is to be compatible with
[`datetime.datetime.timestamp()`](https://docs.python.org/3/library/datetime.html#datetime.datetime.timestamp) which is used internally.
## INSTALLATION
Arch Linux users can install [timesched from the
AUR](https://aur.archlinux.org/packages/python-timesched/).
`timesched` is [available on PyPI](https://pypi.org/project/timesched/)
so install the usual way, e.g:
```bash
pip3 install timesched
```
Or explicitly from [github](https://github.com/bulletmark/timesched):
```bash
git clone https://github.com/bulletmark/timesched.git
cd timesched
sudo pip3 install .
```
<!-- vim: se ai syn=markdown: -->
Raw data
{
"_id": null,
"home_page": "",
"name": "timesched",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "sched,scheduler,timer,periodic,cron,crontab",
"author": "",
"author_email": "Mark Blakeney <mark.blakeney@bullet-systems.net>",
"download_url": "https://files.pythonhosted.org/packages/d1/8c/f789e6ff030966586244c8b6b0ffe4fddf7e900b2334cf3293300126e574/timesched-1.8.tar.gz",
"platform": null,
"description": "## TIMESCHED\n[](https://pypi.org/project/timesched/)\n[](https://aur.archlinux.org/packages/python-timesched/)\n\nThe `timesched` Python module provides a simple time event scheduler. It\nis implemented upon the standard Python\n[`sched`](https://docs.python.org/3/library/sched.html) module and is\nused in a similar way, but provides a nicer and more modern and\nconvenient programming interface. Apart from normal oneshot and repeat\ntimers, it can run timers at a given time of day, and for the given days\nof week, providing simple cron-like functionality. It requires only\nPython 3.6 or later, and the standard library. The latest version of\nthis document and code is available at\nhttps://github.com/bulletmark/timesched.\n\n```python\nclass timesched.Scheduler(timefunc=time.time, delayfunc=time.sleep)\n```\n\nRefer to the class description for Python\n[sched.scheduler](https://docs.python.org/3/library/sched.html#sched.scheduler)\nwhich is used in the [internal\nimplementation](#differences-to-standard-sched-module) of this class.\n\n_Scheduler_ instances have the following methods.\n\n#### Create one-shot timer\n\n```python\noneshot(time, priority, func, *args, **kwargs)\n```\n- _time_: expiry time relative to now, or absolute time. Type can be one of:\n - `int` at given relative seconds after now,\n - `datetime.timedelta()` at given relative `timedelta()` after now,\n - `datetime.time()` at given `time()` after now,\n - `datetime.datetime()` at given absolute `datetime()`,\n - `datetime.date()` at given absolute `date()`,\n- _priority_: int value, lower value is higher priority. Refer\n [description](https://docs.python.org/3/library/sched.html#sched.scheduler.enterabs).\n- _func_ and _args_ and _kwargs_: user function and arguments to call\n when timer is invoked.\n\nReturns a _timer_ ID which can be used to cancel the timer using\n[`cancel(timer)`](#cancel-timer).\n\n#### Create repeating timer\n\n```python\nrepeat(period, priority, func, *args, **kwargs)\n```\n- _period_: period for timer. Type can be one of:\n - `int` at each given seconds after now,\n - `datetime.timedelta()` at each given `timedelta()` after now,\n - `datetime.time()` at given `time()` each day after now. E.g. at\n 10:30 every day for simple daily \"cron-like\" functionality.\n- _priority_: int value, lower value is higher priority. Refer\n [description](https://docs.python.org/3/library/sched.html#sched.scheduler.enterabs).\n- _func_ and _args_ and _kwargs_: user function and arguments to call\n when timer is invoked.\n\nReturns a _timer_ ID which can be used to cancel the timer using\n[`cancel(timer)`](#cancel-timer).\n\nNote that for _int_ and _timedelta()_ periods, the specified period is\nthe delay between the end of the callback function and when it is called\nagain so the actual period will slowly \"creep\" by the run time of the\ncallback. Many applications are not concerned about this distinction but if\nnecessary you can instead invoke a _oneshot()_ absolute timer between\neach call.\n\n#### Create one-shot timer on next given day\n\nCall this with _time_ = `datetime.time()` to invoke a `oneshot()` at the\ngiven _time_ on the next day from the set of given _days_ of the week.\n\n```python\noneshot_on_days(days, time, priority, func, *args, **kwargs)\n```\n\n- _days_: A list/set/sequence/range of integers 0-6 where 0 = Monday to\n 6 = Sunday. e.g. [0] means only invoke timer on a Monday, [0,6] = only\n invoke on Monday and Sunday, etc. Using `days=range(7)` is same as\n calling ordinary `oneshot()`.\n\n Alternately, you can specify _days_ as a string \"MTWTFSS\" where each\n char is upper case if the day is to be set, and lower case if not.\n E.g. \"MTWTFss\" is the working week Mon-Fri, \"mtwTfss\" is Thu only,\n etc. A utility function to explicitly parse this string into a set of\n integers is available as `timesched.parse_days(string_arg)` if you\n need.\n\nRemaining parameters and return type are same as `oneshot()`.\n\n#### Create repeating timer on given days\n\nCall this with _time_ = `datetime.time()` to invoke a `repeat()` at the\ngiven _period_ on each of the given _days_ of the week.\n\n```python\nrepeat_on_days(days, period, priority, func, *args, **kwargs)\n```\n\n- _days_: parameter same as `oneshot_on_days()`.\n\nRemaining parameters and return type are same as `repeat()`.\n\n#### Return count of active timers\n\n```python\ncount()\n```\n\nReturns the count of timers currently active. A timer is considered\nactive while it is pending and until it's callback function has\ncompleted, unless it is explicitly cancelled.\n\n#### Cancel timer\n\n```python\ncancel(timer)\n```\n\nRemove the timer with `timer` ID. If the timer is not currently active,\nthis method will raise a ValueError.\n\n#### Run scheduler\n\n```python\nrun(blocking=True)\n```\n\nInvokes the base `scheduler.run()`. Refer full\ndescription at [Python sched\nmodule](https://docs.python.org/3/library/sched.html#sched.scheduler.run).\n\n## EXAMPLES\n\n```python\n#!/usr/bin/python3\n'Very simple examples'\nimport timesched\nfrom datetime import datetime, time\n\n# Job function to be called for each timer\ndef job(jobid):\n print(f'Job {jobid} called at {datetime.now()}')\n\n# Create a scheduler\ns = timesched.Scheduler()\n\n# Execute job() once in 5 secs time\ns.oneshot(5, 0, job, 1)\n\n# Execute job() every 2 secs\ns.repeat(2, 0, job, 2)\n\n# Execute job() at 10:30am every work day (not weekends)\ns.repeat_on_days('MTWTFss', time(10, 30), 0, job, 3)\n\n# Run scheduler, will block until no timers left running\ns.run()\n```\n\n## DIFFERENCES TO STANDARD SCHED MODULE\n\nThe `timesched` module is internally implemented using the standard\nPython [`sched`](https://docs.python.org/3/library/sched.html) module\nbut differs in the following ways. Note that the `sched` implementation,\nmethods, and attributes are not directly exposed in the public interface.\n\n- Provides `oneshot()` and `repeat()` methods to conveniently accept\n standard\n [`datetime.datetime()`](https://docs.python.org/3/library/datetime.html#datetime-objects),\n [`datetime.date()`](https://docs.python.org/3/library/datetime.html#date-objects),\n [`datetime.time()`](https://docs.python.org/3/library/datetime.html#time-objects),\n [`datetime.timedelta()`](https://docs.python.org/3/library/datetime.html#timedelta-objects),\n and also integer time arguments, based automatically on the type of the\n passed time argument.\n- The `repeat()` method sets itself up to be automatically invoked again\n at the next repeat interval, unlike `sched` which only provides a\n `oneshot()` equivalent method [i.e. `enter()` or `enterabs()`] so the user\n does not need to explicitly set up the next timer.\n- Provides a convenient way to schedule a timer at a given time each\n day to give simple daily \"cron-like\" functionality, e.g.\n `s.repeat(datetime.time(hour=10, minute=30), f)` to periodically\n activate a timer at 10:30 every day.\n- Further to the above `repeat()` which can run at a given time every\n day, you can use `repeat_on_days()` to specify a given time on a set\n of given days, e.g. `s.repeat_on_days('MTWTFss',\n datetime.time(hour=10, minute=30), f)` to run the timer at 10:30 each\n workday only (Mon to Fri). Alternately `s.repeat_on_days(range(5),\n datetime.time(hour=10, minute=30), f)`\n gives the same result.\n- Consistent with modern Python, allows user to plainly specify `*args`\n and `**kwargs` directly in timer setup call rather than in a tuple as\n legacy `sched` requires.\n- Does not provide the\n [`enter()`](https://docs.python.org/3/library/sched.html#sched.scheduler.enter)\n or\n [`enterabs()`](https://docs.python.org/3/library/sched.html#sched.scheduler.enterabs)\n methods. Use the superior `oneshot()`, `repeat()`,\n `oneshot_on_days()`, or `repeat_on_days()` methods instead.\n- Provides a more specific `count()` method instead of\n [`empty()`](https://docs.python.org/3/library/sched.html#sched.scheduler.empty).\n- Does not provide the\n [`queue`](https://docs.python.org/3/library/sched.html#sched.scheduler.queue)\n attribute.\n- Uses `time.time` instead of `time.monotonic` as the default `timefunc`\n for the internal\n [scheduler](https://docs.python.org/3/library/sched.html#sched.scheduler).\n This is to be compatible with\n [`datetime.datetime.timestamp()`](https://docs.python.org/3/library/datetime.html#datetime.datetime.timestamp) which is used internally.\n\n## INSTALLATION\n\nArch Linux users can install [timesched from the\nAUR](https://aur.archlinux.org/packages/python-timesched/).\n\n`timesched` is [available on PyPI](https://pypi.org/project/timesched/)\nso install the usual way, e.g:\n\n```bash\npip3 install timesched\n```\n\nOr explicitly from [github](https://github.com/bulletmark/timesched):\n\n```bash\ngit clone https://github.com/bulletmark/timesched.git\ncd timesched\nsudo pip3 install .\n```\n\n<!-- vim: se ai syn=markdown: -->\n",
"bugtrack_url": null,
"license": "GPLv3",
"summary": "Improved simple time scheduler based on standard sched",
"version": "1.8",
"project_urls": {
"Homepage": "https://github.com/bulletmark/timesched"
},
"split_keywords": [
"sched",
"scheduler",
"timer",
"periodic",
"cron",
"crontab"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2519983a8eae1e3789f1392b0368915ce126087119c086d130498dd20a1e3b9c",
"md5": "12112965f03476b8e1838d238b0f35c7",
"sha256": "0196acf07976c4685dffa6e10a1867c74619c5c76d55d916312d7e86813be834"
},
"downloads": -1,
"filename": "timesched-1.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "12112965f03476b8e1838d238b0f35c7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 5738,
"upload_time": "2023-11-02T03:03:49",
"upload_time_iso_8601": "2023-11-02T03:03:49.666350Z",
"url": "https://files.pythonhosted.org/packages/25/19/983a8eae1e3789f1392b0368915ce126087119c086d130498dd20a1e3b9c/timesched-1.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d18cf789e6ff030966586244c8b6b0ffe4fddf7e900b2334cf3293300126e574",
"md5": "59d50e3be46ef8d6b38cb8cab9163bac",
"sha256": "c90cd3ed59c1d038786c8bfa618c6eff31554ba9ff6e1f3a1e12d7cd262395fa"
},
"downloads": -1,
"filename": "timesched-1.8.tar.gz",
"has_sig": false,
"md5_digest": "59d50e3be46ef8d6b38cb8cab9163bac",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 7245,
"upload_time": "2023-11-02T03:03:51",
"upload_time_iso_8601": "2023-11-02T03:03:51.596726Z",
"url": "https://files.pythonhosted.org/packages/d1/8c/f789e6ff030966586244c8b6b0ffe4fddf7e900b2334cf3293300126e574/timesched-1.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-02 03:03:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bulletmark",
"github_project": "timesched",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "timesched"
}
