ntlog 1.2

Command-Line Application

ntLog is a simple command line utility used to append discretely generated log files into a running log formulated as a NestedText file. You can specify limits on how many log entries there are or how old they should be. Any entries that do not satisfy the limits are purged.

A discrete log file is a log file generated by program that runs at regular intervals or after particular events. This contrasts from log files generated by continuously running programs such as daemons. With discretely running programs a existing log file will be overwritten on the next run. By using ntLog you can add the most recently generated log file to a running log that will not be overwritten.

Usage:

    ntlog [options] <logfile>

Options:

    -k, --keep-for [days]     drop entries older than this [default: 7]
    -n, --max-entries [N]     maximum number of log entries to keep
    -N, --min-entries [N]     minimum number of log entries to keep [default: 1]
    -d, --delete              delete given logfile after incorporating it
    -h, --help                print this usage message
    -Y, --year <fmt>          add year headers
    -M, --month <fmt>         add month headers
    -D, --day <fmt>           add day headers
    -H, --hour <fmt>          add hour headers
    -E, --entry <fmt>         add entry headers
    -d, --description <text>  add entry headers
    --fold-marker <mapping>   map fold markers contained in logfile
    -e, --editor <editor>     add editor mode line, choose from: vim

When run, ntLog copies the contents of <logfile> into <logfile>.nt.

Log entries older than --keep-for days are deleted. If units are not specified, --keep-for is given in days. However you can directly specify the units in terms of seconds (s, sec, second, seconds), minutes (m, min, minute, minutes), hours (h, hr, hour, hours), days (d, day, days), weeks (w, W, week, weeks), months (M, month, months), and years (y, Y, year, years).

If the number of entries exceeds --max-entries, the oldest entries are deleted even if they are younger than the --keep-for limit.

If --delete is specified, the given log file is deleted after its contents are incorporated into the running log file.

The key used when filing log entries into the NestedText document is the timestamp of the modification time of the given log file.

The given log file is always kept, even if it is older than the --keep-for limit.

Log entries are sorted from most recent to oldest, with the most recent at the top of the NestedText file. The one exception to this rule is that the given log file is always listed first, even if its modification time is older than existing log entries.

--entry 'D MMMM YYYY, h:mm A'

# 31 December 2023, 6:00 PM
2023-12-31T18:00:25.680009-08:00:
    > ...

# create — 31 December 2023, 6:00 PM
create — 2023-12-31T18:00:25.680009-08:00:
    > ...

--year 'YYYY  {{{1'
--month 'MMMM YYYY  {{{2'
--day 'D MMMM YYYY  {{{3'
--entry 'D MMMM YYYY, h:mm A  {{{4'

--fold-marker '{{{ {<{'

NTlog API

ntLog provides the NTlog class, whose instances can be used as an output file stream in Python programs. Instead of writing to stand-alone files their output is incorporated directly into a NestedText composite logfile.

NTlog provides the normal methods for output file streams, write, flush and close, and can act as a context manager. Only write takes an argument, the text to be written to the logfile.

NTlog Arguments:

running_log_file: (str, os.PathLike):

The path to the composite log file. Normally this uses .log.nt as the suffix. If not given, then the name of the temp_log_file with an added .nt suffix is used.

temp_log_file: (str, os.PathLike):

The path to the temporary log file. Normally this uses .log as the suffix. This is optional.

keep_for (float, str):

Any entries older than keep_for (in seconds) are dropped. If keep_for is a string, it is converted to seconds. In this case it assumed to be a number followed by a unit. For example, ‘1w’, ‘6M’, etc.

max_entries (int):

Maximum number of log entries to keep.

min_entries (int):

Minimum number of log entries to keep.

retain_temp (bool):

Do not delete the temporary log file after writing composite log file.

ctime (datetime):

Used as the creation time of the log entry. If not specified, the current time is used.

year_header (str):

When specified, this header is added above the first entry from a new year.

month_header (str):

When specified, this header is added above the first entry from a new month.

day_header (str):

When specified, this header is added above the first entry from a new day.

hour_header (str):

When specified, this header is added above the first entry from a new hour.

entry_header (str):

When specified, this header is added above every entry.

description (str):

This string is prepended to the datestamp to create the key for the new log entry. It is also prepended to the entry header, if it is requested.

fold_marker_mapping ([str, str]):

When specified, any instances of the first string in a log file are replaced by the second string when incorporating that log into the output NestedText file.

Raises:

OSError, NTlogError

NTlogError is a clone of the Error exception from Inform.

The use of the temp_log_file is optional. It is helpful with long running processes as it provides a way of monitoring the progress of the process, especially if the logfile is routinely flushed.

Example (with error reporting):

from ntlog import NTlog, NTlogError
from inform import Inform, fatal, os_error

try:
    with NTlog('appname.log.nt', keep_for='7d', max_entries=20):
        ntlog.write('a log message')
        ntlog.write('another log message')
        ...
except OSError as e:
    fatal(os_error(e))
except NTlogError as e:
    e.terminate()

Example (with temp log):

with NTlog('appname.log.nt', 'appname.log', keep_for='7d', retain_temp=True):
    ntlog.write('log message')
    ntlog.flush()
    ...

NTlog can be specified as the logfile to Inform.

Example (with inform):

from ntlog import NTlog
from inform import Inform, display, error, log

with (
    NTlog('appname.log.nt', keep_for='7d') as ntlog,
    Inform(logfile=ntlog) as inform,
):
    display('status message')
    log('log message')
    if there_is_a_problem:
        error('error message')
    ...

Example (with temp log and inform):

with (
    NTlog('appname.log.nt', 'appname.log', keep_for='7d') as ntlog,
    Inform(logfile=ntlog, flush=True) as inform,
):
    display('status message')
    log('log message')
    if there_is_a_problem:
        error('error message')
    ...

Installation

Install with:

pip install ntlog