Added way to retrieve existing jobs per tags.

AUTHORS.rst

@@ -24,4 +24,5 @@ Thanks to all the wonderful folks who have contributed to schedule over the year
 - eladbi <https://github.com/eladbi>
 - chankeypathak <https://github.com/chankeypathak>
 - vubon <https://github.com/vubon>
-- gaguirregabiria <https://github.com/gaguirregabiria>
+- gaguirregabiria <https://github.com/gaguirregabiria>
+- Skenvy <https://github.com/skenvy>

docs/examples.rst

@@ -99,6 +99,22 @@ Return ``schedule.CancelJob`` from a job to remove it from the scheduler.
         time.sleep(1)
 
 
+Get all jobs
+~~~~~~~~~~~~
+To retrieve all jobs from the scheduler, use ``schedule.get_jobs()``
+
+.. code-block:: python
+
+    import schedule
+
+    def hello():
+        print('Hello world')
+
+    schedule.every().second.do(hello)
+
+    all_jobs = schedule.get_jobs()
+
+
 Cancel all jobs
 ~~~~~~~~~~~~~~~
 To remove all jobs from the scheduler, use ``schedule.clear()``
@@ -115,8 +131,30 @@ To remove all jobs from the scheduler, use ``schedule.clear()``
     schedule.clear()
 
 
-Cancel several jobs at once
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Get several jobs, filtered by tags
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can retrieve a group of jobs from the scheduler, selecting them by a unique identifier.
+
+.. code-block:: python
+
+    import schedule
+
+    def greet(name):
+        print('Hello {}'.format(name))
+
+    schedule.every().day.do(greet, 'Andrea').tag('daily-tasks', 'friend')
+    schedule.every().hour.do(greet, 'John').tag('hourly-tasks', 'friend')
+    schedule.every().hour.do(greet, 'Monica').tag('hourly-tasks', 'customer')
+    schedule.every().day.do(greet, 'Derek').tag('daily-tasks', 'guest')
+
+    friends = schedule.get_jobs('friend')
+
+Will return a list of every job tagged as ``friend``.
+
+
+Cancel several jobs, filtered by tags
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 You can cancel the scheduling of a group of jobs selecting them by a unique identifier.
 
@@ -136,6 +174,7 @@ You can cancel the scheduling of a group of jobs selecting them by a unique iden
 
 Will prevent every job tagged as ``daily-tasks`` from running again.
 
+
 Run a job at random intervals
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/reference.rst

@@ -14,6 +14,7 @@ Main Interface
 .. autofunction:: every
 .. autofunction:: run_pending
 .. autofunction:: run_all
+.. autofunction:: get_jobs
 .. autofunction:: clear
 .. autofunction:: cancel_job
 .. autofunction:: next_run

schedule/__init__.py

@@ -109,6 +109,19 @@ def run_all(self, delay_seconds=0):
             self._run_job(job)
             time.sleep(delay_seconds)
 
+    def get_jobs(self, tag=None):
+        """
+        Gets scheduled jobs marked with the given tag, or all jobs
+        if tag is omitted.
+
+        :param tag: An identifier used to identify a subset of
+                    jobs to retrieve
+        """
+        if tag is None:
+            return self.jobs[:]
+        else:
+            return [job for job in self.jobs if tag in job.tags]
+
     def clear(self, tag=None):
         """
         Deletes scheduled jobs marked with the given tag, or all jobs
@@ -599,6 +612,13 @@ def run_all(delay_seconds=0):
     default_scheduler.run_all(delay_seconds=delay_seconds)
 
 
+def get_jobs(tag=None):
+    """Calls :meth:`get_jobs <Scheduler.get_jobs>` on the
+    :data:`default scheduler instance <default_scheduler>`.
+    """
+    return default_scheduler.get_jobs(tag)
+
+
 def clear(tag=None):
     """Calls :meth:`clear <Scheduler.clear>` on the
     :data:`default scheduler instance <default_scheduler>`.

test_schedule.py

@@ -557,6 +557,33 @@ def test_tag_type_enforcement(self):
         job1.tag(0, 'a', True)
         assert len(job1.tags) == 3
 
+    def test_get_by_tag(self):
+        every().second.do(make_mock_job()).tag('job1', 'tag1')
+        every().second.do(make_mock_job()).tag('job2', 'tag2', 'tag4')
+        every().second.do(make_mock_job()).tag('job3', 'tag3', 'tag4')
+
+        # Test None input yields all 3
+        jobs = schedule.get_jobs()
+        assert len(jobs) == 3
+        assert {'job1', 'job2', 'job3'}\
+            .issubset({*jobs[0].tags, *jobs[1].tags, *jobs[2].tags})
+
+        # Test each 1:1 tag:job
+        jobs = schedule.get_jobs('tag1')
+        assert len(jobs) == 1
+        assert 'job1' in jobs[0].tags
+
+        # Test multiple jobs found.
+        jobs = schedule.get_jobs('tag4')
+        assert len(jobs) == 2
+        assert 'job1' not in {*jobs[0].tags, *jobs[1].tags}
+
+        # Test no tag.
+        jobs = schedule.get_jobs('tag5')
+        assert len(jobs) == 0
+        schedule.clear()
+        assert len(schedule.jobs) == 0
+
     def test_clear_by_tag(self):
         every().second.do(make_mock_job(name='job1')).tag('tag1')
         every().second.do(make_mock_job(name='job2')).tag('tag1', 'tag2')