Package: ntlog
Author:Ken KundertVersion:0.3Released:2023-05-01Command-Line ApplicationntLogis a simple command line utility used to append discretely generated log
files into a running log formulated as aNestedTextfile.  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 usingntLogyou 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 messageWhen run,ntLogcopies the contents of<logfile>into<logfile>.nt.Log entries older than--keep-fordays are deleted.  If units are not
specified,--keep-foris 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-forlimit.If--deleteis 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 theNestedTextdocument 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-forlimit.Log entries are sorted from most recent to oldest, with the most recent at the
top of theNestedTextfile.  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.NTlog APIntLogprovides theNTlogclass, 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.NTlogprovides the normal methods for output file streams,write,flushandclose, and can act as a context manager.  Onlywritetakes an argument,
the text to be written to the logfile.NTlogArguments:running_log_file: (str, os.PathLike):The path to the composite log file.  Normally this uses .log.nt as the
suffix.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.Raises:OSError, NTlogErrorNTlogErroris a clone of theErrorexception fromInform.The use of thetemp_log_fileis 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')
    ...NTlogcan be specified as the logfile toInform.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')
    ...InstallationInstall with:pip install ntlogReleasesLatest Development Version:Version: 0.3Released: 2023-05-010.3 (2023-05-01)Add Python API.0.2 (2023-04-10)Improve error handling0.1 (2023-04-08)Add support for time units on--keep-for.