{"id":13586323,"url":"https://github.com/rq/rq-scheduler","last_synced_at":"2025-05-11T03:49:53.798Z","repository":{"id":3609083,"uuid":"4674035","full_name":"rq/rq-scheduler","owner":"rq","description":"A lightweight library that adds job scheduling capabilities to RQ (Redis Queue)","archived":false,"fork":false,"pushed_at":"2024-10-29T13:29:27.000Z","size":543,"stargazers_count":1479,"open_issues_count":103,"forks_count":232,"subscribers_count":40,"default_branch":"master","last_synced_at":"2025-05-11T03:49:49.293Z","etag":null,"topics":["python","redis","rq","scheduled-tasks","scheduler","task-scheduler"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rq.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.rst","dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["selwin"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":"pypi/rq-scheduler","community_bridge":null,"custom":null}},"created_at":"2012-06-15T10:45:48.000Z","updated_at":"2025-05-06T23:46:41.000Z","dependencies_parsed_at":"2023-01-13T12:38:49.964Z","dependency_job_id":"41f071c3-1754-4c88-8622-ce1702ca6979","html_url":"https://github.com/rq/rq-scheduler","commit_stats":{"total_commits":210,"total_committers":64,"mean_commits":3.28125,"dds":0.6238095238095238,"last_synced_commit":"58dc4e4bfea4da651f84ecfed3de9b41333c1308"},"previous_names":["ui/rq-scheduler"],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rq%2Frq-scheduler","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rq%2Frq-scheduler/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rq%2Frq-scheduler/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rq%2Frq-scheduler/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rq","download_url":"https://codeload.github.com/rq/rq-scheduler/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253514567,"owners_count":21920334,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["python","redis","rq","scheduled-tasks","scheduler","task-scheduler"],"created_at":"2024-08-01T15:05:28.531Z","updated_at":"2025-05-11T03:49:53.779Z","avatar_url":"https://github.com/rq.png","language":"Python","funding_links":["https://github.com/sponsors/selwin","https://tidelift.com/funding/github/pypi/rq-scheduler","https://tidelift.com/subscription/pkg/pypi-rq_scheduler?utm_source=pypi-rq-scheduler\u0026utm_medium=referral\u0026utm_campaign=readme"],"categories":["Python"],"sub_categories":[],"readme":"============\nRQ Scheduler\n============\n\n`RQ Scheduler \u003chttps://github.com/rq/rq-scheduler\u003e`_ is a small package that\nadds job scheduling capabilities to `RQ \u003chttps://github.com/nvie/rq\u003e`_,\na `Redis \u003chttp://redis.io/\u003e`_ based Python queuing library.\n\n.. image:: https://travis-ci.org/rq/rq-scheduler.svg?branch=master\n    :target: https://travis-ci.org/rq/rq-scheduler\n\n====================\nSupport RQ Scheduler\n====================\n\nIf you find ``rq-scheduler`` useful, please consider supporting its development via `Tidelift \u003chttps://tidelift.com/subscription/pkg/pypi-rq_scheduler?utm_source=pypi-rq-scheduler\u0026utm_medium=referral\u0026utm_campaign=readme\u003e`_.\n\n============\nRequirements\n============\n\n* `RQ`_\n\n============\nInstallation\n============\n\nYou can install `RQ Scheduler`_ via pip::\n\n    pip install rq-scheduler\n\nOr you can download the latest stable package from `PyPI \u003chttp://pypi.python.org/pypi/rq-scheduler\u003e`_.\n\n=====\nUsage\n=====\n\nSchedule a job involves doing two different things:\n\n1. Putting a job in the scheduler\n2. Running a scheduler that will move scheduled jobs into queues when the time comes\n\n----------------\nScheduling a Job\n----------------\n\nThere are two ways you can schedule a job. The first is using RQ Scheduler's ``enqueue_at``\n\n.. code-block:: python\n\n    from redis import Redis\n    from rq import Queue\n    from rq_scheduler import Scheduler\n    from datetime import datetime\n\n    scheduler = Scheduler(connection=Redis()) # Get a scheduler for the \"default\" queue\n    scheduler = Scheduler('foo', connection=Redis()) # Get a scheduler for the \"foo\" queue\n\n    # You can also instantiate a Scheduler using an RQ Queue\n    queue = Queue('bar', connection=Redis())\n    scheduler = Scheduler(queue=queue, connection=queue.connection)\n\n    # Puts a job into the scheduler. The API is similar to RQ except that it\n    # takes a datetime object as first argument. So for example to schedule a\n    # job to run on Jan 1st 2020 we do:\n    scheduler.enqueue_at(datetime(2020, 1, 1), func) # Date time should be in UTC\n\n    # Here's another example scheduling a job to run at a specific date and time (in UTC),\n    # complete with args and kwargs.\n    scheduler.enqueue_at(datetime(2020, 1, 1, 3, 4), func, foo, bar=baz)\n\n    # You can choose the queue type where jobs will be enqueued by passing the name of the type to the scheduler\n    # used to enqueue\n    scheduler = Scheduler('foo', queue_class=\"rq.Queue\")\n    scheduler.enqueue_at(datetime(2020, 1, 1), func) # The job will be enqueued at the queue named \"foo\" using the queue type \"rq.Queue\"\n\n\nThe second way is using ``enqueue_in``. Instead of taking a ``datetime`` object,\nthis method expects a ``timedelta`` and schedules the job to run at\nX seconds/minutes/hours/days/weeks later. For example, if we want to monitor how\npopular a tweet is a few times during the course of the day, we could do something like\n\n.. code-block:: python\n\n    from datetime import timedelta\n\n    # Schedule a job to run 10 minutes, 1 hour and 1 day later\n    scheduler.enqueue_in(timedelta(minutes=10), count_retweets, tweet_id)\n    scheduler.enqueue_in(timedelta(hours=1), count_retweets, tweet_id)\n    scheduler.enqueue_in(timedelta(days=1), count_retweets, tweet_id)\n\n**IMPORTANT**: You should always use UTC datetime when working with `RQ Scheduler`_.\n\n------------------------\nPeriodic \u0026 Repeated Jobs\n------------------------\n\nAs of version 0.3, `RQ Scheduler`_ also supports creating periodic and repeated jobs.\nYou can do this via the ``schedule`` method. Note that this feature needs\n`RQ`_ \u003e= 0.3.1.\n\nThis is how you do it\n\n.. code-block:: python\n\n    scheduler.schedule(\n        scheduled_time=datetime.utcnow(), # Time for first execution, in UTC timezone\n        func=func,                     # Function to be queued\n        args=[arg1, arg2],             # Arguments passed into function when executed\n        kwargs={'foo': 'bar'},         # Keyword arguments passed into function when executed\n        interval=60,                   # Time before the function is called again, in seconds\n        repeat=10,                     # Repeat this number of times (None means repeat forever)\n        meta={'foo': 'bar'}            # Arbitrary pickleable data on the job itself\n    )\n\n**IMPORTANT NOTE**: If you set up a repeated job, you must make sure that you\neither do not set a `result_ttl` value or you set a value larger than the interval.\nOtherwise, the entry with the job details will expire and the job will not get re-scheduled.\n\n------------------------\nCron Jobs\n------------------------\n\nAs of version 0.6.0, `RQ Scheduler`_ also supports creating Cron Jobs, which you can use for\nrepeated jobs to run periodically at fixed times, dates or intervals, for more info check\nhttps://en.wikipedia.org/wiki/Cron. You can do this via the ``cron`` method.\n\nThis is how you do it\n\n.. code-block:: python\n\n    scheduler.cron(\n        cron_string,                # A cron string (e.g. \"0 0 * * 0\")\n        func=func,                  # Function to be queued\n        args=[arg1, arg2],          # Arguments passed into function when executed\n        kwargs={'foo': 'bar'},      # Keyword arguments passed into function when executed\n        repeat=10,                  # Repeat this number of times (None means repeat forever)\n        result_ttl=300,             # Specify how long (in seconds) successful jobs and their results are kept. Defaults to -1 (forever)\n        ttl=200,                    # Specifies the maximum queued time (in seconds) before it's discarded. Defaults to None (infinite TTL).\n        queue_name=queue_name,      # In which queue the job should be put in\n        meta={'foo': 'bar'},        # Arbitrary pickleable data on the job itself\n        use_local_timezone=False    # Interpret hours in the local timezone\n    )\n\n-------------------------\nRetrieving scheduled jobs\n-------------------------\n\nSometimes you need to know which jobs have already been scheduled. You can get a\nlist of enqueued jobs with the ``get_jobs`` method\n\n.. code-block:: python\n\n    list_of_job_instances = scheduler.get_jobs()\n\nIn it's simplest form (as seen in the above example) this method returns a list\nof all job instances that are currently scheduled for execution.\n\nAdditionally the method takes two optional keyword arguments ``until`` and\n``with_times``. The first one specifies up to which point in time scheduled jobs\nshould be returned. It can be given as either a datetime / timedelta instance\nor an integer denoting the number of seconds since epoch (1970-01-01 00:00:00).\nThe second argument is a boolean that determines whether the scheduled execution\ntime should be returned along with the job instances.\n\nExample\n\n.. code-block:: python\n\n    # get all jobs until 2012-11-30 10:00:00\n    list_of_job_instances = scheduler.get_jobs(until=datetime(2012, 10, 30, 10))\n\n    # get all jobs for the next hour\n    list_of_job_instances = scheduler.get_jobs(until=timedelta(hours=1))\n\n    # get all jobs with execution times\n    jobs_and_times = scheduler.get_jobs(with_times=True)\n    # returns a list of tuples:\n    # [(\u003crq.job.Job object at 0x123456789\u003e, datetime.datetime(2012, 11, 25, 12, 30)), ...]\n\n------------------------------\nChecking if a job is scheduled\n------------------------------\n\nYou can check whether a specific job instance or job id is scheduled for\nexecution using the familiar python ``in`` operator\n\n.. code-block:: python\n\n    if job_instance in scheduler:\n        # Do something\n    # or\n    if job_id in scheduler:\n        # Do something\n\n---------------\nCanceling a job\n---------------\n\nTo cancel a job, simply pass a ``Job`` or a job id to ``scheduler.cancel``\n\n.. code-block:: python\n\n    scheduler.cancel(job)\n\nNote that this method returns ``None`` whether the specified job was found or not.\n\n---------------------\nRunning the scheduler\n---------------------\n\n`RQ Scheduler`_ comes with a script ``rqscheduler`` that runs a scheduler\nprocess that polls Redis once every minute and move scheduled jobs to the\nrelevant queues when they need to be executed\n\n.. code-block:: bash\n\n    # This runs a scheduler process using the default Redis connection\n    rqscheduler\n\nIf you want to use a different Redis server you could also do\n\n.. code-block:: bash\n\n    rqscheduler --host localhost --port 6379 --db 0\n\nThe script accepts these arguments:\n\n* ``-H`` or ``--host``: Redis server to connect to\n* ``-p`` or ``--port``: port to connect to\n* ``-d`` or ``--db``: Redis db to use\n* ``-P`` or ``--password``: password to connect to Redis\n* ``-b`` or ``--burst``: runs in burst mode (enqueue scheduled jobs whose execution time is in the past and quit)\n* ``-i INTERVAL`` or ``--interval INTERVAL``: How often the scheduler checks for new jobs to add to the queue (in seconds, can be floating-point for more precision).\n* ``-j`` or ``--job-class``: specify custom job class for rq to use (python module.Class)\n* ``-q`` or ``--queue-class``: specify custom queue class for rq to use (python module.Class)\n\nThe arguments pull default values from environment variables with the\nsame names but with a prefix of ``RQ_REDIS_``.\n\nRunning the Scheduler as a Service on Ubuntu\n--------------------------------------------\n\nsudo /etc/systemd/system/rqscheduler.service\n\n.. code-block:: bash\n\n    [Unit]\n    Description=RQScheduler\n    After=network.target\n\n    [Service]\n    ExecStart=/home/\u003c\u003cUser\u003e\u003e/.virtualenvs/\u003c\u003cYourVirtualEnv\u003e\u003e/bin/python \\\n        /home/\u003c\u003cUser\u003e\u003e/.virtualenvs/\u003c\u003cYourVirtualEnv\u003e\u003e/lib/\u003c\u003cYourPythonVersion\u003e\u003e/site-packages/rq_scheduler/scripts/rqscheduler.py\n\n    [Install]\n    WantedBy=multi-user.target\n\nYou will also want to add any command line parameters if your configuration is not localhost or not set in the environment variables.\n\nStart, check Status and Enable the service\n\n.. code-block:: bash\n\n    sudo systemctl start rqscheduler.service\n    sudo systemctl status rqscheduler.service\n    sudo systemctl enable rqscheduler.service\n\n---------------------------\nRunning Multiple Schedulers\n---------------------------\n\nMultiple instances of the rq-scheduler can be run simultaneously. It allows for\n\n* Reliability (no single point of failure)\n* Failover (scheduler instances automatically retry to attain lock and schedule jobs)\n* Running scheduler on multiple server instances to make deployment identical and easier\n\nMultiple schedulers can be run in any way you want. Typically you'll only want to run one scheduler per server/instance.\n\n.. code-block:: bash\n\n   rqscheduler -i 5\n\n   # another shell/systemd service or ideally another server\n   rqscheduler -i 5\n\n   # different parameters can be provided to different schedulers\n   rqscheduler -i 10\n\n**Practical example**:\n\n- ``scheduler_a`` is running on ``ec2_instance_a``\n- If ``scheduler_a`` crashes or ``ec2_instance_a`` goes down, then our tasks won't be scheduled at all\n- Instead we can simply run 2 schedulers. Another scheduler called ``scheduler_b`` can be run on ``ec2_instance_b``\n- Now both ``scheduler_a`` and ``scheduler_b`` will periodically check and schedule the jobs\n- If one fails, the other still works\n\nYou can read more about multiple schedulers in `#212 \u003chttps://github.com/rq/rq-scheduler/pull/212\u003e`_ and `#195 \u003chttps://github.com/rq/rq-scheduler/issues/195\u003e`_\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frq%2Frq-scheduler","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frq%2Frq-scheduler","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frq%2Frq-scheduler/lists"}