Merge 253c2f1 into 41f88b3

FAQ.rst

@@ -125,6 +125,15 @@ Another option would be to subclass Schedule like @mplewis did in `this example
 How can I run a job only once?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+.. code-block:: python
+
+    def job_that_executes_once():
+        # Do some work ...
+
+    schedule.one().day.at('22:30').do(job_that_executes_once)
+
+Or you can do it this way:
+
 .. code-block:: python
 
     def job_that_executes_once():

docs/api.rst

@@ -16,6 +16,7 @@ Main Interface
 .. autodata:: jobs
 
 .. autofunction:: every
+.. autofunction:: one
 .. autofunction:: run_pending
 .. autofunction:: run_all
 .. autofunction:: clear

schedule/__init__.py

@@ -146,6 +146,15 @@ def every(self, interval=1):
         job = Job(interval, self)
         return job
 
+    def one(self, interval=1):
+        """
+        Schedule a new job, that run once.
+
+        :param interval: A quantity of a certain time unit
+        :return: An unconfigured :class:`Job <Job>`
+        """
+        return self.every(interval).once
+
     def _run_job(self, job):
         ret = job.run()
         if isinstance(ret, CancelJob) or ret is CancelJob:
@@ -200,6 +209,7 @@ def __init__(self, interval, scheduler=None):
         self.start_day = None  # Specific day of the week to start on
         self.tags = set()  # unique set of tags for the job
         self.scheduler = scheduler  # scheduler to register with
+        self._times = None
 
     def __lt__(self, other):
         """
@@ -364,6 +374,15 @@ def sunday(self):
         self.start_day = 'sunday'
         return self.weeks
 
+    @property
+    def once(self):
+        self._times = 1
+        return self
+
+    def times(self, num):
+        self._times = num
+        return self
+
     def tag(self, *tags):
         """
         Tags the job with one or more unique indentifiers.
@@ -465,7 +484,8 @@ def do(self, job_func, *args, **kwargs):
             # call will fail.
             pass
         self._schedule_next_run()
-        self.scheduler.jobs.append(self)
+        if self.scheduler:
+            self.scheduler.jobs.append(self)
         return self
 
     @property
@@ -484,9 +504,21 @@ def run(self):
         logger.info('Running job %s', self)
         ret = self.job_func()
         self.last_run = datetime.datetime.now()
-        self._schedule_next_run()
+        if self._times:
+            self._times -= 1
+        if self._times or self._times is None:
+            self._schedule_next_run()
+        else:
+            self.cancel()
         return ret
 
+    def cancel(self):
+        """
+        Delete current job from scheduler.
+        """
+        if self.scheduler:
+            self.scheduler.cancel_job(self)
+
     def _schedule_next_run(self):
         """
         Compute the instant when this job should run next.
@@ -575,6 +607,13 @@ def every(interval=1):
     return default_scheduler.every(interval)
 
 
+def one(interval=1):
+    """Calls :meth:`one <Scheduler.every>` on the
+    :data:`default scheduler instance <default_scheduler>`.
+    """
+    return default_scheduler.one(interval)
+
+
 def run_pending():
     """Calls :meth:`run_pending <Scheduler.run_pending>` on the
     :data:`default scheduler instance <default_scheduler>`.