SymbX/systemd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

systemd-python: polish the docstrings

Browse Source
This commit is contained in:
Zbigniew Jędrzejewski-Szmek
2013-02-28 19:36:14 -05:00
parent 33ed3769b5
commit 2c07646764
3 changed files with 76 additions and 57 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/python-systemd/_reader.c
+29 -25
View File
@@ -68,10 +68,8 @@ static void Journal_dealloc(Journal* self)
}
PyDoc_STRVAR(Journal__doc__,
"Journal([flags][,path]) -> ...\n"
"Journal instance\n\n"
"Returns instance of Journal, which allows filtering and return\n"
"of journal entries.\n"
"Journal([flags][,path]) -> ...\n\n"
"Journal allows filtering and retrieval of Journal entries.\n"
"Argument `flags` sets open flags of the journal, which can be one\n"
"of, or ORed combination of constants: LOCAL_ONLY (default) opens\n"
"journal on local machine only; RUNTIME_ONLY opens only\n"
@@ -79,7 +77,7 @@ PyDoc_STRVAR(Journal__doc__,
"journal files of system services and the kernel.\n"
"Argument `path` is the directory of journal files. Note that\n"
"currently flags are ignored when `path` is present as they are\n"
" not relevant.");
"not relevant.");
static int Journal_init(Journal *self, PyObject *args, PyObject *keywds)
{
int flags = SD_JOURNAL_LOCAL_ONLY, r;
@@ -103,7 +101,7 @@ static int Journal_init(Journal *self, PyObject *args, PyObject *keywds)
PyDoc_STRVAR(Journal_get_next__doc__,
"get_next([skip]) -> dict\n\n"
"Return dictionary of the next log entry. Optional skip value will\n"
"return the `skip`th log entry.");
"return the `skip`\\-th log entry.");
static PyObject* Journal_get_next(Journal *self, PyObject *args)
{
PyObject *dict;
@@ -208,7 +206,7 @@ static PyObject* Journal_get_next(Journal *self, PyObject *args)
PyDoc_STRVAR(Journal_get_previous__doc__,
"get_previous([skip]) -> dict\n\n"
"Return dictionary of the previous log entry. Optional skip value\n"
"will return the -`skip`th log entry. Equivalent to get_next(-skip).");
"will return the -`skip`\\-th log entry. Equivalent to get_next(-skip).");
static PyObject* Journal_get_previous(Journal *self, PyObject *args)
{
int64_t skip = 1LL;
@@ -222,8 +220,8 @@ static PyObject* Journal_get_previous(Journal *self, PyObject *args)
PyDoc_STRVAR(Journal_add_match__doc__,
"add_match(match) -> None\n\n"
"Add a match to filter journal log entries. All matches of different\n"
"fields are combined in logical AND, and matches of the same field\n"
"are automatically combined in logical OR.\n"
"fields are combined with logical AND, and matches of the same field\n"
"are automatically combined with logical OR.\n"
"Match is a string of the form \"FIELD=value\".");
static PyObject* Journal_add_match(Journal *self, PyObject *args, PyObject *keywds)
{
@@ -242,8 +240,7 @@ static PyObject* Journal_add_match(Journal *self, PyObject *args, PyObject *keyw
PyDoc_STRVAR(Journal_add_disjunction__doc__,
"add_disjunction() -> None\n\n"
"Once called, all matches before and after are combined in logical\n"
"OR.");
"Inserts a logical OR between matches added before and afterwards.");
static PyObject* Journal_add_disjunction(Journal *self, PyObject *args)
{
int r;
@@ -256,7 +253,7 @@ static PyObject* Journal_add_disjunction(Journal *self, PyObject *args)
PyDoc_STRVAR(Journal_flush_matches__doc__,
"flush_matches() -> None\n\n"
"Clears all current match filters.");
"Clear all current match filters.");
static PyObject* Journal_flush_matches(Journal *self, PyObject *args)
{
sd_journal_flush_matches(self->j);
@@ -265,7 +262,7 @@ static PyObject* Journal_flush_matches(Journal *self, PyObject *args)
PyDoc_STRVAR(Journal_seek__doc__,
"seek(offset[, whence]) -> None\n\n"
"Seek through journal by `offset` number of entries. Argument\n"
"Jump `offset` entries in the journal. Argument\n"
"`whence` defines what the offset is relative to:\n"
"os.SEEK_SET (default) from first match in journal;\n"
"os.SEEK_CUR from current position in journal;\n"
@@ -393,11 +390,11 @@ static PyObject* Journal_seek_monotonic(Journal *self, PyObject *args)
}
PyDoc_STRVAR(Journal_wait__doc__,
"wait([timeout]) -> Change state (integer)\n\n"
"Waits until there is a change in the journal. Argument `timeout`\n"
"is the maximum number of seconds to wait before returning\n"
"regardless if journal has changed. If `timeout` is not given or is\n"
"0, then it will block forever.\n"
"wait([timeout]) -> state change (integer)\n\n"
"Wait for a change in the journal. Argument `timeout` specifies\n"
"the maximum number of seconds to wait before returning\n"
"regardless of wheter the journal has changed. If `timeout` is not given\n"
"or is 0, then block forever.\n"
"Will return constants: NOP if no change; APPEND if new\n"
"entries have been added to the end of the journal; and\n"
"INVALIDATE if journal files have been added or removed.");
@@ -420,7 +417,7 @@ static PyObject* Journal_wait(Journal *self, PyObject *args, PyObject *keywds)
PyDoc_STRVAR(Journal_seek_cursor__doc__,
"seek_cursor(cursor) -> None\n\n"
"Seeks to journal entry by given unique reference `cursor`.");
"Seek to journal entry by given unique reference `cursor`.");
static PyObject* Journal_seek_cursor(Journal *self, PyObject *args)
{
const char *cursor;
@@ -463,8 +460,8 @@ static PyObject* Journal_iternext(PyObject *self)
PyDoc_STRVAR(Journal_query_unique__doc__,
"query_unique(field) -> a set of values\n\n"
"Returns a set of unique values in journal for given `field`.\n"
"Note this does not respect any journal matches.");
"Return a set of unique values appearing in journal for the\n"
"given `field`. Note this does not respect any journal matches.");
static PyObject* Journal_query_unique(Journal *self, PyObject *args)
{
char *query;
@@ -497,6 +494,11 @@ static PyObject* Journal_query_unique(Journal *self, PyObject *args)
return value_set;
}
PyDoc_STRVAR(data_threshold__doc__,
"Threshold for field size truncation.\n\n"
"Fields longer than this will be truncated to the threshold size.\n"
"Defaults to 64Kb.");
static PyObject* Journal_get_data_threshold(Journal *self, void *closure)
{
size_t cvalue;
@@ -528,7 +530,7 @@ static PyGetSetDef Journal_getseters[] = {
{(char*) "data_threshold",
(getter)Journal_get_data_threshold,
(setter)Journal_set_data_threshold,
(char*) "data threshold",
(char*) data_threshold__doc__,
NULL},
{NULL}
};
@@ -600,11 +602,14 @@ static PyTypeObject JournalType = {
PyType_GenericNew, /* tp_new */
};
#define SUMMARY \
"Module that reads the systemd journal similar to journalctl."
#if PY_MAJOR_VERSION >= 3
static PyModuleDef _reader_module = {
PyModuleDef_HEAD_INIT,
"_reader",
"Module that reads systemd journal similar to journalctl.",
SUMMARY,
-1,
NULL, NULL, NULL, NULL, NULL
};
@@ -636,8 +641,7 @@ init_reader(void)
if (m == NULL)
return NULL;
#else
m = Py_InitModule3("_reader", NULL,
"Module that reads systemd journal similar to journalctl.");
m = Py_InitModule3("_reader", NULL, SUMMARY);
if (m == NULL)
return;
#endif
src/python-systemd/id128.c
+4 -4
View File
@@ -35,24 +35,24 @@ static void cleanup_Py_DECREFp(PyObject **p) {
PyDoc_STRVAR(module__doc__,
"Python interface to the libsystemd-id128 library.\n\n"
"Provides SD_MESSAGE_* constants and functions to query and generate\n"
"128bit unique identifiers."
"128-bit unique identifiers."
);
PyDoc_STRVAR(randomize__doc__,
"randomize() -> UUID\n\n"
"Return a new random 128bit unique identifier.\n"
"Return a new random 128-bit unique identifier.\n"
"Wraps sd_id128_randomize(3)."
);
PyDoc_STRVAR(get_machine__doc__,
"get_machine() -> UUID\n\n"
"Return a 128bit unique identifier for this machine.\n"
"Return a 128-bit unique identifier for this machine.\n"
"Wraps sd_id128_get_machine(3)."
);
PyDoc_STRVAR(get_boot__doc__,
"get_boot() -> UUID\n\n"
"Return a 128bit unique identifier for this boot.\n"
"Return a 128-bit unique identifier for this boot.\n"
"Wraps sd_id128_get_boot(3)."
);
src/python-systemd/journal.py
+43 -28
View File
@@ -90,12 +90,11 @@ class Journal(_Journal):
>>> myjournal.add_boot_match(journal.CURRENT_BOOT)
>>> myjournal.add_loglevel_matches(journal.LOG_ERR)
>>> myjournal.add_match(_SYSTEMD_UNIT="systemd-udevd.service")
>>> from __future__ import print_function
>>> for entry in myjournal:
... print(entry['MESSAGE'])
See man page "systemd.journal-fields" for more info on
typical fields found in the journal.
See systemd.journal-fields(7) for more info on typical fields
found in the journal.
"""
def __init__(self, converters=None, flags=LOCAL_ONLY, path=None):
"""Creates instance of Journal, which allows filtering and
@@ -123,7 +122,7 @@ class Journal(_Journal):
self.converters.update(converters)
def _convert_field(self, key, value):
""" Convert value based on callable from self.converters
"""Convert value based on callable from self.converters
based of field/key"""
try:
result = self.converters[key](value)
@@ -137,7 +136,7 @@ class Journal(_Journal):
return result
def _convert_entry(self, entry):
""" Convert entire journal entry utilising _covert_field"""
"""Convert entire journal entry utilising _covert_field"""
result = {}
for key, value in entry.items():
if isinstance(value, list):
@@ -149,44 +148,56 @@ class Journal(_Journal):
def add_match(self, *args, **kwargs):
"""Add one or more matches to the filter journal log entries.
All matches of different field are combined in a logical AND,
and matches of the smae field are automatically combined in a
and matches of the same field are automatically combined in a
logical OR.
Matches can be passed as strings of form "field=value", or
keyword arguments field="value"."""
Matches can be passed as strings of form "FIELD=value", or
keyword arguments FIELD="value".
"""
args = list(args)
args.extend(_make_line(key, val) for key, val in kwargs.items())
for arg in args:
super(Journal, self).add_match(arg)
def get_next(self, skip=1):
"""Return dictionary of the next log entry. Optional skip value
will return the `skip`th log entry.
Returned will be journal entry dictionary processed with
converters."""
"""Return the next log entry as a dictionary of fields.
Optional skip value will return the `skip`\-th log entry.
Entries will be processed with converters specified during
Journal creation.
"""
return self._convert_entry(
super(Journal, self).get_next(skip))
def query_unique(self, field):
"""Returns a set of unique values in journal for given `field`,
processed with converters.
Note this does not respect any journal matches."""
"""Return unique values appearing in the Journal for given `field`.
Note this does not respect any journal matches.
Entries will be processed with converters specified during
Journal creation.
"""
return set(self._convert_field(field, value)
for value in super(Journal, self).query_unique(field))
def seek_realtime(self, realtime):
"""Seek to nearest matching journal entry to `realtime`.
Argument `realtime` can must be either an integer unix timestamp
or datetime.datetime instance."""
"""Seek to a matching journal entry nearest to `realtime` time.
Argument `realtime` must be either an integer unix timestamp
or datetime.datetime instance.
"""
if isinstance(realtime, _datetime.datetime):
realtime = float(realtime.strftime("%s.%f"))
return super(Journal, self).seek_realtime(realtime)
def seek_monotonic(self, monotonic, bootid=None):
"""Seek to nearest matching journal entry to `monotonic`.
Argument `monotonic` is a timestamp from boot in either seconds
or a datetime.timedelta instance.
Argument `bootid` is a string or UUID representing which boot the
monotonic time is reference to. Defaults to current bootid."""
"""Seek to a matching journal entry nearest to `monotonic` time.
Argument `monotonic` is a timestamp from boot in either
seconds or a datetime.timedelta instance. Argument `bootid`
is a string or UUID representing which boot the monotonic time
is reference to. Defaults to current bootid.
"""
if isinstance(monotonic, _datetime.timedelta):
monotonic = monotonic.totalseconds()
if isinstance(bootid, _uuid.UUID):
@@ -194,7 +205,8 @@ class Journal(_Journal):
return super(Journal, self).seek_monotonic(monotonic, bootid)
def log_level(self, level):
"""Sets maximum log `level` by setting matches for PRIORITY."""
"""Set maximum log `level` by setting matches for PRIORITY.
"""
if 0 <= level <= 7:
for i in range(level+1):
self.add_match(PRIORITY="%s" % i)
@@ -202,10 +214,13 @@ class Journal(_Journal):
raise ValueError("Log level must be 0 <= level <= 7")
def messageid_match(self, messageid):
"""Sets match filter for log entries for specified `messageid`.
`messageid` can be string or UUID instance.
Standard message IDs can be found in systemd.id128
Equivalent to add_match(MESSAGE_ID=`messageid`)."""
"""Add match for log entries with specified `messageid`.
`messageid` can be string of hexadicimal digits or a UUID
instance. Standard message IDs can be found in systemd.id128.
Equivalent to add_match(MESSAGE_ID=`messageid`).
"""
if isinstance(messageid, _uuid.UUID):
messageid = messageid.get_hex()
self.add_match(MESSAGE_ID=messageid)