From cc5f218a5082bd8a52f80d1bedad7bd4f78bca5e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Sat, 5 Sep 2015 12:48:07 +0200 Subject: tests: enable doctests in the sources Unfortunately the "standard" way to access the names in the defined module does not work. I find it nicer to explicitly import, e.g. from systemd import journal, because then the examples correspond more closely to what a user would use. The only exception is made for JournalHandler, because journal.JournalHandler is a tad to long. --- pytest.ini | 2 ++ systemd/journal.py | 18 ++++++++++++------ 2 files changed, 14 insertions(+), 6 deletions(-) create mode 100644 pytest.ini diff --git a/pytest.ini b/pytest.ini new file mode 100644 index 0000000..df3eb51 --- /dev/null +++ b/pytest.ini @@ -0,0 +1,2 @@ +[pytest] +addopts = --doctest-modules diff --git a/systemd/journal.py b/systemd/journal.py index 53bab0e..7105818 100644 --- a/systemd/journal.py +++ b/systemd/journal.py @@ -113,12 +113,15 @@ class Reader(_Reader): Example usage to print out all informational or higher level messages for systemd-udevd for this boot: + >>> from systemd import journal >>> j = journal.Reader() >>> j.this_boot() >>> j.log_level(journal.LOG_INFO) >>> j.add_match(_SYSTEMD_UNIT="systemd-udevd.service") >>> for entry in j: ... print(entry['MESSAGE']) + starting version ... + ... See systemd.journal-fields(7) for more info on typical fields found in the journal. @@ -361,6 +364,7 @@ def send(MESSAGE, MESSAGE_ID=None, **kwargs): r"""Send a message to the journal. + >>> from systemd import journal >>> journal.send('Hello world') >>> journal.send('Hello, again, world', FIELD2='Greetings!') >>> journal.send('Binary message', BINARY=b'\xde\xad\xbe\xef') @@ -415,10 +419,10 @@ def stream(identifier, priority=LOG_DEBUG, level_prefix=False): The file will be line buffered, so messages are actually sent after a newline character is written. + >>> from systemd import journal >>> stream = journal.stream('myapp') - >>> stream - ', mode 'w' at 0x...> >>> stream.write('message...\n') + 11 will produce the following message in the journal:: @@ -451,10 +455,11 @@ class JournalHandler(_logging.Handler): To create a custom logger whose messages go only to journal: + >>> import logging >>> log = logging.getLogger('custom_logger_name') >>> log.propagate = False - >>> log.addHandler(journal.JournalHandler()) - >>> log.warn("Some message: %s", detail) + >>> log.addHandler(JournalHandler()) + >>> log.warn("Some message: %s", 'detail') Note that by default, message levels `INFO` and `DEBUG` are ignored by the logging framework. To enable those log levels: @@ -464,7 +469,7 @@ class JournalHandler(_logging.Handler): To redirect all logging messages to journal regardless of where they come from, attach it to the root logger: - >>> logging.root.addHandler(journal.JournalHandler()) + >>> logging.root.addHandler(JournalHandler()) For more complex configurations when using `dictConfig` or `fileConfig`, specify `systemd.journal.JournalHandler` as the @@ -482,7 +487,8 @@ class JournalHandler(_logging.Handler): makes sense only for SYSLOG_IDENTIFIER and similar fields which are constant for the whole program: - >>> journal.JournalHandler(SYSLOG_IDENTIFIER='my-cool-app') + >>> JournalHandler(SYSLOG_IDENTIFIER='my-cool-app') + The following journal fields will be sent: `MESSAGE`, `PRIORITY`, `THREAD_NAME`, `CODE_FILE`, `CODE_LINE`, -- cgit v1.2.1