Getting the cursor is split out from .get_next() into
.get_cursor(). This mirrors the C API more closely, and
also makes things a bit faster if the cursor is not needed.
The behaviour wrt. seconds vs. microseconds was inconsistent.
Now _Reader always uses native units (us), while Reader always
uses seconds and accepts both floats and ints. This way the
conversion is always done in the Python layer, and the lower
level API allows access to the journal API without the potentially
lossy conversion between double and uint64_t.
Please see the documentation (e.g. pydoc3 systemd.daemon) for full
description. As usual, systemd._daemon wraps the raw interface, while
systemd.daemon provides the more pythonic API. sd_listen_fds,
sd_booted, sd_is_fifo, sd_is_socket, sd_is_socket_unix,
sd_is_socket_inet, sd_is_mq, and SD_LISTEN_FDS_START are currently
wrapped.
This should help readers of the man or HTML pages know if the documentation
is out of date. An alternative to use a date generated from 'git log' was
considered, but since we try to keep user visible documentation up to date,
showing the project version should be enough.
It's better to explictly check, instead of just documenting it.
The return value from init is changed from 1 to -1 on error.
Python seems to ignore 1 every second time. Looks like a bug
in Python, but the return value doesn't seem to be documented
anywhere, and -1 works as expected... so let's just use that.
sd_journal_get_fd(j) is called j.fileno(), for compatiblity with
Python conventions for file-like objects.
More importantly, those new .seek_head() and .seek_tail() do not
call .get_next(). This is better, if one wants to skip before
retrieving an entry.
First of all, 'try: ... except: ...' (with no exception specified) is
always a no-no, since it catches all BaseExceptions, which includes ^C
and other stuff which should almost never be caught.
Now the conversion is stricter, and only one conversion is attempted,
and only a ValueEror is caught. It seems reasonable to catch ValueErrors,
since the entries in the journal are not verified, and any erroneous
application might log a field which cannot be converted. The consumer
of events must only check if a field is an instance of bytes and can
otherwise assume that the conversion was performed correctly.
Order of arguments in Reader.__init__ has been changed to match order
in _Reader.__init__.
Conversions have been updated to work under Python 2 and 3.
It seems inevitable that we'll also grow a writing interface,
and then it'll be cumbersome to have a "Journal" for reading,
and a "Writer" for writing.
__REALTIME_TIMESTAMP and __MONOTONIC_TIMESTAMP return ints.
It doesn't make sense to convert to string, just to convert
back to a number later on.
Also try to follow systemd rules for indentation.
