Changes to _Reader make it match closer to C API, by removing `get_next`
and `get_previous`. A `get_all` method added, which returns dictionary
of fields using C API SD_JOURNAL_FOREACH_DATA macro, which can be used
in conjunction with `next`.
_Reader `get`, `next`, `get_{realtime,monotonic,cursor}` and new
`previous` methods are made private. This is so the traversal and
getting of journal fields can be made transparent in the python
interface.
Reader now solely implements `get_next` and `get_previous`, returning a
standard dictionary (future: other mapping types?) with all standard and
special fields through the converters. This makes the output the same as
journalctl json/export format output.
Iterator methods also moved to Reader, as they do not function as intend
with changes to _Reader.
These changes also mean that more optimised journal interfaces can be
made more easily from _Reader, by avoiding getting of unrequired fields
by using the `_get` method, and avoiding field conversions.
get_timeout_ms is added as a convenience function, since
it is abysmally hard to call clock_gettime() in Python
versions lower than 3.3. And even for Python 3.3 users
it saves a few lines.
Before, we would initialize many fields twice: first
by filling the structure with zeros, and then a second
time with the real values. We can let the compiler do
the job for us, avoiding one copy.
A downside of this patch is that text gets slightly
bigger. This is because all zero() calls are effectively
inlined:
$ size build/.libs/systemd
text data bss dec hex filename
before 897737 107300 2560 1007597 f5fed build/.libs/systemd
after 897873 107300 2560 1007733 f6075 build/.libs/systemd
… actually less than 1‰.
A few asserts that the parameter is not null had to be removed. I
don't think this changes much, because first, it is quite unlikely
for the assert to fail, and second, an immediate SEGV is almost as
good as an assert.
This matches the C API more closely, and also enables the
user to get just partial information, should she desire to
do so.
Functions names in error messages are modified to not include
the class name, because Python uses just the function name
into functions declared as METH_NOARGS, and error messages
were inconsistent.
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.
