simplecron 0.1.0a2__tar.gz

simplecron-0.1.0a2/PKG-INFO

@@ -0,0 +1,348 @@
+Metadata-Version: 2.3
+Name: simplecron
+Version: 0.1.0a2
+Summary: Simplecron is a simple and lightweight Python library for scheduling tasks using cron-like syntax.
+Keywords: cron,scheduler
+Author: John Pendenque, Daniel Bader
+Author-email: John Pendenque <pendenquejohn@gmail.com>, Daniel Bader <mail@dbader.org>
+Classifier: Development Status :: 3 - Alpha
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: Unix
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Utilities
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Natural Language :: English
+Classifier: Operating System :: Microsoft :: Windows :: Windows 11
+Classifier: Operating System :: MacOS
+Requires-Dist: asgiref>=3.11.1
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: pytz>=2026.2
+Requires-Dist: redis>=8.0.1
+Maintainer: John Pendenque
+Maintainer-email: John Pendenque <pendenquejohn@gmail.com>
+Requires-Python: >=3.14
+Project-URL: Changelog, https://github.com/Zadigo/simplecron/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://github.com/Zadigo/simplecron/wiki
+Project-URL: Homepage, https://github.com/Zadigo/simplecron
+Project-URL: Repository, https://github.com/Zadigo/simplecron.git
+Description-Content-Type: text/markdown
+
+# Simple Cron
+
+Simplecron is a simple and lightweight Python library for scheduling tasks using cron-like syntax. It allows you to define jobs that run at specific intervals or times, making it easy to automate repetitive tasks in your applications.
+
+This project was inspired by [**schedule.**](https://github.com/dbader/schedule) and improved to add:
+
+* Asynchronous functionnalities
+* Redis, SQLite, Postgres provider support
+
+## Creating a schedule
+
+### Default scheduler
+
+Simplecron uses a default scheduler that is created when the library is imported. You can create jobs using the `every` function, which creates a new job instance and attaches it to the default scheduler.
+
+```Python
+from simplecron import base
+
+
+def callback(job: base.Job, *args, **kwargs):
+    print("Hello, World!", job)
+
+
+base.every(1).second.do(callback)
+
+
+while True:
+    base.run_pending()
+    time.sleep(1)
+```
+
+The same code can be achieved using the `start_blocking` function, which simplifies the blocking loop:
+
+```python
+from simplecron import base
+
+def callback(job: base.Job, *args, **kwargs):
+    print("Hello, World!", job)
+
+base.every(1).second.do(callback)
+base.start_blocking()
+```
+
+By calling `every`, a new job is created. `second` attaches the unit of time to the job and finally `do` attaches the callback function.
+
+> [!NOTE]
+> `start_blocking` is a blocking function, in other words, it will block the main thread and will not allow other code to run while it is executing.
+
+### Custom scheduler
+
+You can also create your own scheduler by instantiating the `BaseScheduler` class. This can allow you to have multiple schedulers running concurrently, each with its own set of jobs.
+
+```python
+from simplecron.base import BaseScheduler
+
+s1 = BaseScheduler()
+s2 = BaseScheduler()
+
+# Adds a job to the first scheduler that runs every second
+s1.every(1).second.do(lambda job: print("Scheduler 1:", job))
+
+# Adds a job to the second scheduler that runs every 2 seconds
+s2.every(2).seconds.do(lambda job: print("Scheduler 2:", job))
+
+def main():
+	while True:
+		s1.run_pending_jobs()
+		s2.run_pending_jobs()
+		time.sleep(1)
+
+if __name__ == "__main__":
+	main()
+```
+
+<!-- 
+The same code can be achieved using the `Schedulers` class with the `start_blocking` method, which allows you to run multiple schedulers consecutively in a blocking manner.
+
+```Python
+import asyncio
+from simplecron.base import BaseScheduler, Job
+from simplecron.runners import Schedulers
+
+synchronizer = Schedulers()
+
+def callback(job: Job, *args, **kwargs):
+	print("Hello, World!", job)
+
+def main():
+	s1 = BaseScheduler()
+	s2 = BaseScheduler()
+
+	synchronizer.add_scheduler(s1, "seconds", 1, callback)
+	synchronizer.add_scheduler(s2, "seconds", 2, callback)
+
+	synchronizer.start_blocking()
+
+if __name__ == "__main__":
+	main()
+```
+
+### Concurrent schedulers
+
+To run multiple schedulers concurrently, you can use the `asyncio` library. This allows you to run multiple schedulers in an asynchronous manner, enabling better performance and responsiveness.
+
+```Python
+import asyncio
+from simplecron.base import BaseScheduler, Job
+from simplecron.runners import Schedulers
+
+synchronizer = Schedulers()
+
+def callback(job: Job, *args, **kwargs):
+	print("Hello, World!", job)
+
+async def main():
+	s1 = BaseScheduler()
+	s2 = BaseScheduler()
+
+	synchronizer.add_scheduler(s1, "seconds", 1, callback)
+	synchronizer.add_scheduler(s2, "seconds", 2, callback)
+
+	await synchronizer.async_blocking()
+
+if __name__ == "__main__":
+	asyncio.run(main())
+``` -->
+
+## Event Listeners
+
+You can attach event listeners to a scheduler to listen for specific events. There are three main listeners:
+
+* `before` - Triggered before a job is executed.
+* `after` - Triggered after a job is executed.
+* `before_all` - Triggered before all jobs are executed.
+
+```python
+from simplecron.base import default_scheduler
+from simplecron.utils import EventListenerEnum
+
+default_scheduler.event_listener(EventListenerEnum.BEFORE_ALL, lambda scheduler: print("Before all jobs"))
+```
+
+The same can be achieved using the shortcut method `before_all_events`, `after_events`, and `before_events`:
+
+```python
+from simplecron.base import default_scheduler
+
+default_scheduler.before_all_events(lambda scheduler: print("Before all jobs"))
+default_scheduler.before_events(lambda job: print("Before job:", job))
+default_scheduler.after_events(lambda job: print("After job:", job))
+```
+
+## Jobs
+
+### Cancelling
+
+To cancel a job, it simply needs to return an instance of `Cancel`.
+
+```python
+def callback(job: Job, *args, **kwargs):
+	print("Hello, World!", job)
+	return Cancel(job, reason="Some reason")  # This will cancel the job after it runs once
+```
+
+### Types of jobs
+
+**Every second**
+
+```python
+default_scheduler.every(1).second.do(callback)
+```
+
+**Every X second**
+
+```python
+default_scheduler.every(15).seconds.do(callback)
+```
+
+**Every minute**
+
+```python
+default_scheduler.every(1).minute.do(callback)
+```
+
+**Every X minutes**
+
+```python
+default_scheduler.every(15).minutes.do(callback)
+```
+
+**Every hour**
+
+```python
+default_scheduler.every(1).hour.do(callback)
+```
+
+**Every hours**
+
+```python
+default_scheduler.every(1).hours.do(callback)
+```
+
+**Every day**
+
+When no specific time is provided, the job will run automatically at the start of the day (00:00). If you need to run the job at a specific time, you must use the `at` method to specify the time in 24-hour format (HH:MM).
+
+```python
+default_scheduler.every(1).day.do(callback)
+```
+
+```python
+default_scheduler.every(1).day.at(datetime.time(12, 00)).do(callback)
+```
+
+**Every days**
+
+```python
+default_scheduler.every(1).days.do(callback)
+```
+
+**Every week**
+
+If no specific day and time is povided, the job will run automatically at the start of the week (Monday at 00:00). If you need to run the job at a specific day, you must use one of the properties `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday` or `sunday`.
+
+You can also use the `at` method to specify the time in 24-hour format (HH:MM).
+
+```python
+default_scheduler.every(1).week.do(callback)
+```
+
+```python
+default_scheduler.every(1).week.at(datetime.time(12, 00)).do(callback)
+```
+
+**Every X day**
+
+```python
+default_scheduler.every(1).monday.do(callback)
+default_scheduler.every(1).tuesday.do(callback)
+default_scheduler.every(1).wednesday.do(callback)
+default_scheduler.every(1).thursday.do(callback)
+default_scheduler.every(1).friday.do(callback)
+default_scheduler.every(1).saturday.do(callback)
+default_scheduler.every(1).sunday.do(callback)
+```
+
+## Tags
+
+Tags allow you to categorize and filter jobs based on specific labels. This can be useful for organizing jobs, applying actions to groups of jobs, or selectively running certain jobs based on their tags.
+
+```Python
+base.every(15, tag="my_tag").seconds.do(executor)
+```
+
+You can also attach event listeners to specific jobs matching a certain set of tags or criteria:
+
+```Python
+import time
+
+from simplecron.base import Job, default_scheduler, logger
+from simplecron.utils import EventListenerEnum
+
+
+def executor(job: Job):
+    logger.info("Executor called")
+
+
+def event_before(job: Job):
+    print("Before job:", job._tags)
+
+
+default_scheduler.create_every(10, tag="my_tag").seconds.do(executor)
+
+default_scheduler.with_event_listener(
+    EventListenerEnum.BEFORE, 
+	event_before, 
+	for_tags=["my_tag"]
+)
+
+while True:
+	default_scheduler.run_pending()
+	time.sleep(1)
+```
+
+## Providers
+
+Providers are external services or modules that can be integrated with the scheduler to extend its functionality. They allow you to connect your scheduled jobs with various platforms, APIs, or other systems seamlessly.
+
+### Redis Database provider
+
+The example below will save the details of the scheduler and the jobs that were runned in a Redis backend:
+
+```Python
+import time
+
+from simplecron import base
+from simplecron.base import Job, logger
+from simplecron.providers import RedisDatabase
+
+
+def executor(job: Job):
+    logger.warning("Executor called")
+
+
+base.default_scheduler.providers.attach(RedisDatabase())
+base.every(15).seconds.do(executor)
+base.every(30).seconds.do(executor)
+
+
+while True:
+    base.run_pending()
+    time.sleep(1)
+```

simplecron-0.1.0a2/README.md

@@ -0,0 +1,313 @@
+# Simple Cron
+
+Simplecron is a simple and lightweight Python library for scheduling tasks using cron-like syntax. It allows you to define jobs that run at specific intervals or times, making it easy to automate repetitive tasks in your applications.
+
+This project was inspired by [**schedule.**](https://github.com/dbader/schedule) and improved to add:
+
+* Asynchronous functionnalities
+* Redis, SQLite, Postgres provider support
+
+## Creating a schedule
+
+### Default scheduler
+
+Simplecron uses a default scheduler that is created when the library is imported. You can create jobs using the `every` function, which creates a new job instance and attaches it to the default scheduler.
+
+```Python
+from simplecron import base
+
+
+def callback(job: base.Job, *args, **kwargs):
+    print("Hello, World!", job)
+
+
+base.every(1).second.do(callback)
+
+
+while True:
+    base.run_pending()
+    time.sleep(1)
+```
+
+The same code can be achieved using the `start_blocking` function, which simplifies the blocking loop:
+
+```python
+from simplecron import base
+
+def callback(job: base.Job, *args, **kwargs):
+    print("Hello, World!", job)
+
+base.every(1).second.do(callback)
+base.start_blocking()
+```
+
+By calling `every`, a new job is created. `second` attaches the unit of time to the job and finally `do` attaches the callback function.
+
+> [!NOTE]
+> `start_blocking` is a blocking function, in other words, it will block the main thread and will not allow other code to run while it is executing.
+
+### Custom scheduler
+
+You can also create your own scheduler by instantiating the `BaseScheduler` class. This can allow you to have multiple schedulers running concurrently, each with its own set of jobs.
+
+```python
+from simplecron.base import BaseScheduler
+
+s1 = BaseScheduler()
+s2 = BaseScheduler()
+
+# Adds a job to the first scheduler that runs every second
+s1.every(1).second.do(lambda job: print("Scheduler 1:", job))
+
+# Adds a job to the second scheduler that runs every 2 seconds
+s2.every(2).seconds.do(lambda job: print("Scheduler 2:", job))
+
+def main():
+	while True:
+		s1.run_pending_jobs()
+		s2.run_pending_jobs()
+		time.sleep(1)
+
+if __name__ == "__main__":
+	main()
+```
+
+<!-- 
+The same code can be achieved using the `Schedulers` class with the `start_blocking` method, which allows you to run multiple schedulers consecutively in a blocking manner.
+
+```Python
+import asyncio
+from simplecron.base import BaseScheduler, Job
+from simplecron.runners import Schedulers
+
+synchronizer = Schedulers()
+
+def callback(job: Job, *args, **kwargs):
+	print("Hello, World!", job)
+
+def main():
+	s1 = BaseScheduler()
+	s2 = BaseScheduler()
+
+	synchronizer.add_scheduler(s1, "seconds", 1, callback)
+	synchronizer.add_scheduler(s2, "seconds", 2, callback)
+
+	synchronizer.start_blocking()
+
+if __name__ == "__main__":
+	main()
+```
+
+### Concurrent schedulers
+
+To run multiple schedulers concurrently, you can use the `asyncio` library. This allows you to run multiple schedulers in an asynchronous manner, enabling better performance and responsiveness.
+
+```Python
+import asyncio
+from simplecron.base import BaseScheduler, Job
+from simplecron.runners import Schedulers
+
+synchronizer = Schedulers()
+
+def callback(job: Job, *args, **kwargs):
+	print("Hello, World!", job)
+
+async def main():
+	s1 = BaseScheduler()
+	s2 = BaseScheduler()
+
+	synchronizer.add_scheduler(s1, "seconds", 1, callback)
+	synchronizer.add_scheduler(s2, "seconds", 2, callback)
+
+	await synchronizer.async_blocking()
+
+if __name__ == "__main__":
+	asyncio.run(main())
+``` -->
+
+## Event Listeners
+
+You can attach event listeners to a scheduler to listen for specific events. There are three main listeners:
+
+* `before` - Triggered before a job is executed.
+* `after` - Triggered after a job is executed.
+* `before_all` - Triggered before all jobs are executed.
+
+```python
+from simplecron.base import default_scheduler
+from simplecron.utils import EventListenerEnum
+
+default_scheduler.event_listener(EventListenerEnum.BEFORE_ALL, lambda scheduler: print("Before all jobs"))
+```
+
+The same can be achieved using the shortcut method `before_all_events`, `after_events`, and `before_events`:
+
+```python
+from simplecron.base import default_scheduler
+
+default_scheduler.before_all_events(lambda scheduler: print("Before all jobs"))
+default_scheduler.before_events(lambda job: print("Before job:", job))
+default_scheduler.after_events(lambda job: print("After job:", job))
+```
+
+## Jobs
+
+### Cancelling
+
+To cancel a job, it simply needs to return an instance of `Cancel`.
+
+```python
+def callback(job: Job, *args, **kwargs):
+	print("Hello, World!", job)
+	return Cancel(job, reason="Some reason")  # This will cancel the job after it runs once
+```
+
+### Types of jobs
+
+**Every second**
+
+```python
+default_scheduler.every(1).second.do(callback)
+```
+
+**Every X second**
+
+```python
+default_scheduler.every(15).seconds.do(callback)
+```
+
+**Every minute**
+
+```python
+default_scheduler.every(1).minute.do(callback)
+```
+
+**Every X minutes**
+
+```python
+default_scheduler.every(15).minutes.do(callback)
+```
+
+**Every hour**
+
+```python
+default_scheduler.every(1).hour.do(callback)
+```
+
+**Every hours**
+
+```python
+default_scheduler.every(1).hours.do(callback)
+```
+
+**Every day**
+
+When no specific time is provided, the job will run automatically at the start of the day (00:00). If you need to run the job at a specific time, you must use the `at` method to specify the time in 24-hour format (HH:MM).
+
+```python
+default_scheduler.every(1).day.do(callback)
+```
+
+```python
+default_scheduler.every(1).day.at(datetime.time(12, 00)).do(callback)
+```
+
+**Every days**
+
+```python
+default_scheduler.every(1).days.do(callback)
+```
+
+**Every week**
+
+If no specific day and time is povided, the job will run automatically at the start of the week (Monday at 00:00). If you need to run the job at a specific day, you must use one of the properties `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday` or `sunday`.
+
+You can also use the `at` method to specify the time in 24-hour format (HH:MM).
+
+```python
+default_scheduler.every(1).week.do(callback)
+```
+
+```python
+default_scheduler.every(1).week.at(datetime.time(12, 00)).do(callback)
+```
+
+**Every X day**
+
+```python
+default_scheduler.every(1).monday.do(callback)
+default_scheduler.every(1).tuesday.do(callback)
+default_scheduler.every(1).wednesday.do(callback)
+default_scheduler.every(1).thursday.do(callback)
+default_scheduler.every(1).friday.do(callback)
+default_scheduler.every(1).saturday.do(callback)
+default_scheduler.every(1).sunday.do(callback)
+```
+
+## Tags
+
+Tags allow you to categorize and filter jobs based on specific labels. This can be useful for organizing jobs, applying actions to groups of jobs, or selectively running certain jobs based on their tags.
+
+```Python
+base.every(15, tag="my_tag").seconds.do(executor)
+```
+
+You can also attach event listeners to specific jobs matching a certain set of tags or criteria:
+
+```Python
+import time
+
+from simplecron.base import Job, default_scheduler, logger
+from simplecron.utils import EventListenerEnum
+
+
+def executor(job: Job):
+    logger.info("Executor called")
+
+
+def event_before(job: Job):
+    print("Before job:", job._tags)
+
+
+default_scheduler.create_every(10, tag="my_tag").seconds.do(executor)
+
+default_scheduler.with_event_listener(
+    EventListenerEnum.BEFORE, 
+	event_before, 
+	for_tags=["my_tag"]
+)
+
+while True:
+	default_scheduler.run_pending()
+	time.sleep(1)
+```
+
+## Providers
+
+Providers are external services or modules that can be integrated with the scheduler to extend its functionality. They allow you to connect your scheduled jobs with various platforms, APIs, or other systems seamlessly.
+
+### Redis Database provider
+
+The example below will save the details of the scheduler and the jobs that were runned in a Redis backend:
+
+```Python
+import time
+
+from simplecron import base
+from simplecron.base import Job, logger
+from simplecron.providers import RedisDatabase
+
+
+def executor(job: Job):
+    logger.warning("Executor called")
+
+
+base.default_scheduler.providers.attach(RedisDatabase())
+base.every(15).seconds.do(executor)
+base.every(30).seconds.do(executor)
+
+
+while True:
+    base.run_pending()
+    time.sleep(1)
+```