make datetime objs timezone-aware and UTC default

.travis.yml

@@ -1,13 +1,20 @@
 dist: xenial
 language: python
+
 python:
     - "2.7"
     - "3.5"
     - "3.6"
     - "3.7"
     - "3.8-dev"
     - "nightly"
+
 install: pip install tox-travis coveralls
+
+before_install:
+    - export TZ=America/Los_Angeles
+    - date
+
 script:
     - tox
 after_success:

schedule/__init__.py

@@ -48,7 +48,12 @@
 import re
 import time
 
-logger = logging.getLogger('schedule')
+try:
+    from datetime import timezone
+    utc = timezone.utc
+except ImportError:
+    from schedule.timezone import UTC
+    utc = UTC()
 
 
 class ScheduleError(Exception):
@@ -81,6 +86,7 @@ class Scheduler(object):
     """
     def __init__(self):
         self.jobs = []
+        self.logger = logging.getLogger('schedule.Scheduler')
 
     def run_pending(self):
         """
@@ -96,19 +102,30 @@ def run_pending(self):
         for job in sorted(runnable_jobs):
             self._run_job(job)
 
-    def run_all(self, delay_seconds=0):
+    def run_all(self, delay_seconds=0, tag=None):
         """
-        Run all jobs regardless if they are scheduled to run or not.
+        Run all jobs regardless if they are scheduled to run or not,
+        optionally matching one or more tags.
 
         A delay of `delay` seconds is added between each job. This helps
         distribute system load generated by the jobs more evenly
         over time.
 
         :param delay_seconds: A delay added between every executed job
+
+        :param tag: An identifier used to identify a subset of
+                    jobs to run
         """
-        logger.info('Running *all* %i jobs with %is delay inbetween',
-                    len(self.jobs), delay_seconds)
-        for job in self.jobs[:]:
+
+        if tag is None:
+            runnable_jobs = self.jobs[:]
+        else:
+            runnable_jobs = (job for job in self.jobs if tag in job.tags)
+
+        self.logger.info('Running *all* %i jobs with %is delay inbetween',
+                         len(self.jobs), delay_seconds)
+
+        for job in sorted(runnable_jobs):
             self._run_job(job)
             time.sleep(delay_seconds)
 
@@ -121,8 +138,10 @@ def clear(self, tag=None):
                     jobs to delete
         """
         if tag is None:
+            self.logger.info('Deleting *all* jobs')
             del self.jobs[:]
         else:
+            self.logger.info('Deleting all jobs tagged "%s"', tag)
             self.jobs[:] = (job for job in self.jobs if tag not in job.tags)
 
     def cancel_job(self, job):
@@ -168,7 +187,28 @@ def idle_seconds(self):
         :return: Number of seconds until
                  :meth:`next_run <Scheduler.next_run>`.
         """
-        return (self.next_run - datetime.datetime.now()).total_seconds()
+        return (self.next_run - datetime.datetime.now(utc)).total_seconds()
+
+    @property
+    def last_run(self):
+        """
+        Datetime when the last job ran (check for NoneType before using).
+
+        :return: A :class:`~datetime.datetime` object
+        """
+        if not self.jobs:
+            return None
+        return max(self.jobs).last_run
+
+    @property
+    def idle_seconds_since(self):
+        """
+        :return: Number of seconds since (check for NoneType before using).
+                 :meth:`next_run <Scheduler.next_run>`.
+        """
+        if self.last_run is None:
+            return None
+        return (datetime.datetime.now(utc) - self.last_run).total_seconds()
 
 
 class Job(object):
@@ -192,6 +232,8 @@ def __init__(self, interval, scheduler=None):
         self.interval = interval  # pause interval * unit between runs
         self.latest = None  # upper limit to the interval
         self.job_func = None  # the job job_func to run
+        self.job_name = None  # the name of job_func to run
+        self.job_info = None  # the job timestats (see below)
         self.unit = None  # time units, e.g. 'minutes', 'hours', ...
         self.at_time = None  # optional time at which this job runs
         self.last_run = None  # datetime of the last run
@@ -200,6 +242,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.logger = logging.getLogger('schedule.Job')
 
     def __lt__(self, other):
         """
@@ -223,7 +266,7 @@ def __str__(self):
 
     def __repr__(self):
         def format_time(t):
-            return t.strftime('%Y-%m-%d %H:%M:%S') if t else '[never]'
+            return t.strftime('%Y-%m-%d %H:%M:%S %Z') if t else '[never]'
 
         def is_repr(j):
             return not isinstance(j, Job)
@@ -240,6 +283,9 @@ def is_repr(j):
                   for k, v in self.job_func.keywords.items()]
         call_repr = job_func_name + '(' + ', '.join(args + kwargs) + ')'
 
+        self.job_name = call_repr
+        self.job_info = timestats
+
         if self.at_time is not None:
             return 'Every %s %s at %s do %s %s' % (
                    self.interval,
@@ -473,17 +519,24 @@ def should_run(self):
         """
         :return: ``True`` if the job should be run now.
         """
-        return datetime.datetime.now() >= self.next_run
+        return datetime.datetime.now(utc) >= self.next_run
+
+    @property
+    def info(self):
+        """
+        :return: ``string`` with `job_func` name and timestats
+        """
+        return self.job_name + self.job_info
 
     def run(self):
         """
         Run the job and immediately reschedule it.
 
         :return: The return value returned by the `job_func`
         """
-        logger.info('Running job %s', self)
+        self.logger.info('Running job %s', self)
         ret = self.job_func()
-        self.last_run = datetime.datetime.now()
+        self.last_run = datetime.datetime.now(utc)
         self._schedule_next_run()
         return ret
 
@@ -502,7 +555,7 @@ def _schedule_next_run(self):
             interval = self.interval
 
         self.period = datetime.timedelta(**{self.unit: interval})
-        self.next_run = datetime.datetime.now() + self.period
+        self.next_run = datetime.datetime.now(utc) + self.period
         if self.start_day is not None:
             if self.unit != 'weeks':
                 raise ScheduleValueError('`unit` should be \'weeks\'')
@@ -539,7 +592,7 @@ def _schedule_next_run(self):
             # If we are running for the first time, make sure we run
             # at the specified time *today* (or *this hour*) as well
             if not self.last_run:
-                now = datetime.datetime.now()
+                now = datetime.datetime.now(utc)
                 if (self.unit == 'days' and self.at_time > now.time() and
                         self.interval == 1):
                     self.next_run = self.next_run - datetime.timedelta(days=1)
@@ -554,7 +607,7 @@ def _schedule_next_run(self):
                                     datetime.timedelta(minutes=1)
         if self.start_day is not None and self.at_time is not None:
             # Let's see if we will still make that time we specified today
-            if (self.next_run - datetime.datetime.now()).days >= 7:
+            if (self.next_run - datetime.datetime.now(utc)).days >= 7:
                 self.next_run -= self.period
 
 
@@ -582,11 +635,11 @@ def run_pending():
     default_scheduler.run_pending()
 
 
-def run_all(delay_seconds=0):
+def run_all(delay_seconds=0, tag=None):
     """Calls :meth:`run_all <Scheduler.run_all>` on the
     :data:`default scheduler instance <default_scheduler>`.
     """
-    default_scheduler.run_all(delay_seconds=delay_seconds)
+    default_scheduler.run_all(delay_seconds, tag)
 
 
 def clear(tag=None):
@@ -615,3 +668,17 @@ def idle_seconds():
     :data:`default scheduler instance <default_scheduler>`.
     """
     return default_scheduler.idle_seconds
+
+
+def last_run():
+    """Calls :meth:`last_run <Scheduler.last_run>` on the
+    :data:`default scheduler instance <default_scheduler>`.
+    """
+    return default_scheduler.last_run
+
+
+def idle_seconds_since():
+    """Calls :meth:`idle_seconds_since <Scheduler.idle_seconds_since>` on the
+    :data:`default scheduler instance <default_scheduler>`.
+    """
+    return default_scheduler.idle_seconds_since

schedule/parent_logger.py

@@ -0,0 +1,32 @@
+#!/usr/bin/env python
+# coding: utf-8
+
+import time
+import logging
+
+
+def setup_logging(debug, filename):
+    """
+    Can be imported by ``<my_package>`` to create a log file for current
+    scheduler and job class logging.  In this example we use a ``debug``
+    flag set in ``<my_package>`` to change the Log Level and ``filename``
+    to set log path.  We also use UTC time and force the name in ``datefmt``.
+    """
+    if debug:
+        log_level = logging.getLevelName('DEBUG')
+    else:
+        log_level = logging.getLevelName('INFO')
+
+    logging.basicConfig(level=log_level,
+                        format="%(asctime)s %(name)s[%(process)d] %(levelname)s - %(message)s",
+                        datefmt='%Y-%m-%d %H:%M:%S UTC',
+                        filename=filename)
+
+    # BUG: This does not print the TZ name because logging module uses
+    #      time instead of tz-aware datetime objects (so we force the
+    #      correct name in datefmt above).
+    logging.Formatter.converter = time.gmtime
+
+    # To also log parent info, try something like this
+    # global logger
+    # logger = logging.getLogger("my_package")

schedule/timezone.py

@@ -0,0 +1,19 @@
+import datetime
+
+
+class UTC(datetime.tzinfo):
+    """tzinfo derived concrete class named "UTC" with offset of 0"""
+    # can be changed to another timezone name/offset
+    def __init__(self):
+        self.__offset = datetime.timedelta(seconds=0)
+        self.__dst = datetime.timedelta(0)
+        self.__name = "UTC"
+
+    def utcoffset(self, dt):
+        return self.__offset
+
+    def dst(self, dt):
+        return self.__dst
+
+    def tzname(self, dt):
+        return self.__name