journal: convert seek_realtime argument to microseconds

This somewhat breaks backwards compatibility, but not for the
previously documented arguments: floats are now interpreted
differently, but ints and datetime.datetime objects are interpreted
the same as before. But the documentation clearly stated that only
ints and datetime.datetime objects were allowed.

This makes seek_realtime match seek_monotonic and other functions
which take time and follows the principle of least surprise.

Fixes #21.

Author: keszybz

systemd/journal.py

@@ -298,14 +298,25 @@ def wait(self, timeout=None):
         return super(Reader, self).wait(us)
 
     def seek_realtime(self, realtime):
-        """Seek to a matching journal entry nearest to `realtime` time.
+        """Seek to a matching journal entry nearest to `timestamp` time.
 
-        Argument `realtime` must be either an integer unix timestamp or
-        datetime.datetime instance.
+        Argument `realtime` must be either an integer UNIX timestamp (in
+        microseconds since the beginning of the UNIX epoch), or an float UNIX
+        timestamp (in seconds since the beginning of the UNIX epoch), or a
+        datetime.datetime instance. The integer form is deprecated.
+
+        >>> import time
+        >>> from systemd import journal
+
+        >>> yesterday = time.time() - 24 * 60**2
+        >>> j = journal.Reader()
+        >>> j.seek_realtime(yesterday)
         """
         if isinstance(realtime, _datetime.datetime):
-            realtime = float(realtime.strftime("%s.%f")) * 1000000
-        return super(Reader, self).seek_realtime(int(realtime))
+            realtime = int(float(realtime.strftime("%s.%f")) * 1000000)
+        elif not isinstance(realtime, int):
+            realtime = int(realtime * 1000000)
+        return super(Reader, self).seek_realtime(realtime)
 
     def seek_monotonic(self, monotonic, bootid=None):
         """Seek to a matching journal entry nearest to `monotonic` time.

systemd/test/test_journal.py

@@ -1,8 +1,11 @@
-import logging
 import contextlib
-import uuid
+import datetime
 import errno
+import logging
 import os
+import time
+import uuid
+
 from systemd import journal, id128
 
 import pytest
@@ -176,3 +179,14 @@ def test_reader_convert_entry(tmpdir):
                    'y1' : b'\200\200',
                    'x2' : ['YYY', 'YYY'],
                    'y2' : [b'\200\200', b'\200\201']}
+
+def test_seek_realtime(tmpdir):
+    j = journal.Reader(path=tmpdir.strpath)
+
+    now = time.time()
+    j.seek_realtime(now)
+
+    j.seek_realtime(12345)
+
+    long_ago = datetime.datetime(1970, 5, 4)
+    j.seek_realtime(long_ago)