Metadata-Version: 2.1
Name: ntlog
Version: 0.1
Summary: Append a log file to an running NestedText log
Keywords: nestedtext,logging
Author: Ken Kundert
Requires-Python: >=3.6
Description-Content-Type: text/x-rst
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Natural Language :: English
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Utilities
Requires-Dist: arrow>=0.15
Requires-Dist: docopt
Requires-Dist: inform>=1.28
Requires-Dist: nestedtext
Requires-Dist: quantiphy
Project-URL: changelog, https://github.com/KenKundert/ntlog/blob/master/CHANGELOG.rst
Project-URL: documentation, https://github.com/KenKundert/ntlog/blob/master/README.rst
Project-URL: homepage, https://github.com/kenkundert/ntlog
Project-URL: repository, https://github.com/kenkundert/ntlog

ntLog — a NestedText logfile aggregation utility
================================================

.. image:: https://pepy.tech/badge/ntlog/month
    :target: https://pepy.tech/project/ntlog

..  image:: https://github.com/KenKundert/ntlog/actions/workflows/build.yaml/badge.svg
    :target: https://github.com/KenKundert/ntlog/actions/workflows/build.yaml

.. image:: https://coveralls.io/repos/github/KenKundert/ntlog/badge.svg?branch=main
    :target: https://coveralls.io/github/KenKundert/ntlog?branch=main

.. image:: https://img.shields.io/pypi/v/ntlog.svg
    :target: https://pypi.python.org/pypi/ntlog

.. image:: https://img.shields.io/pypi/pyversions/ntlog.svg
    :target: https://pypi.python.org/pypi/ntlog/

:Author: Ken Kundert
:Version: 0.1
:Released: 2023-04-08

*ntLog* is a simple command line utility used to append discretely generated log 
files into a running log formulated as a `NestedText <nestedtext.org>`_ 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 contrast 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

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.


Installation
------------

Install with::

    pip install ntlog

