| Name | ntlog JSON |
| Version |
0.5
JSON |
| download |
| home_page | None |
| Summary | Append a log file to an running NestedText log |
| upload_time | 2024-10-30 18:37:42 |
| maintainer | None |
| docs_url | None |
| author | Ken Kundert |
| requires_python | >=3.6 |
| license | None |
| keywords |
nestedtext
logging
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
|
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.5
:Released: 2024-10-30
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.
Headers
"""""""
Any headers you specify are added as comments above the appropriate entries.
When a year header is specified, it is added before the first entry found from
new year. The same is true for month, day, and hour headers. The entry header
it given before each entry. An entry is treated as an Arrow_ format. It
consists of tokens that are to be replaced by components from the entry date
stamp. For example, if you specify::
--entry 'D MMMM YYYY, h:mm A'
Then you will get a entry header command that looks like this::
# 31 December 2023, 6:00 PM
2023-12-31T18:00:25.680009-08:00:
> ...
If you specify a description, it will be prepended to the datestamp in the key
for the new log entry and will be prepended to the entry header. For example,
if ``--description create`` were specified, the result might look like::
# create — 31 December 2023, 6:00 PM
create — 2023-12-31T18:00:25.680009-08:00:
> ...
It is attractive to include editor fold markers in the headers. In doing so you
can collapse large log entries into a single line folds until they are needed,
at which point you can easily open the fold and examine the contents of the log
file. Here is an example set of header specifications that include Vim fold
markers::
--year 'YYYY {{{1'
--month 'MMMM YYYY {{{2'
--day 'D MMMM YYYY {{{3'
--entry 'D MMMM YYYY, h:mm A {{{4'
If your logfiles tend to include fold markers, they can confuse the folds. You
can prevent this by mapping the marker into a different string. Use
``--fold-marker``::
--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
Releases
--------
Latest Development Version
""""""""""""""""""""""""""
| Version: 0.5
| Released: 2024-10-30
0.5 (2024-10-30)
""""""""""""""""
- Add Vim mode line (--editor option).
0.4 (2024-01-29)
""""""""""""""""
- Add support for headers and fold markers.
0.3 (2023-05-01)
""""""""""""""""
- Add Python API.
0.2 (2023-04-10)
""""""""""""""""
- Improve error handling
0.1 (2023-04-08)
""""""""""""""""
- Add support for time units on ``--keep-for``.
.. _NestedText: https://nestedtext.org
.. _Inform: https://inform.readthedocs.io
.. _Error: https://inform.readthedocs.io/en/stable/api.html#inform.Error
.. _Arrow: https://arrow.readthedocs.io/en/latest/guide.html#supported-tokens
Raw data
{
"_id": null,
"home_page": null,
"name": "ntlog",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "nestedtext, logging",
"author": "Ken Kundert",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/8b/82/68eadc8b1a6aef4f8a0d248710fc5710b0f4a18ab01aee6d51db8afef8ee/ntlog-0.5.tar.gz",
"platform": null,
"description": "ntLog \u2014 a NestedText logfile aggregation utility\n================================================\n\n.. image:: https://pepy.tech/badge/ntlog/month\n :target: https://pepy.tech/project/ntlog\n\n.. image:: https://github.com/KenKundert/ntlog/actions/workflows/build.yaml/badge.svg\n :target: https://github.com/KenKundert/ntlog/actions/workflows/build.yaml\n\n.. image:: https://coveralls.io/repos/github/KenKundert/ntlog/badge.svg?branch=main\n :target: https://coveralls.io/github/KenKundert/ntlog?branch=main\n\n.. image:: https://img.shields.io/pypi/v/ntlog.svg\n :target: https://pypi.python.org/pypi/ntlog\n\n.. image:: https://img.shields.io/pypi/pyversions/ntlog.svg\n :target: https://pypi.python.org/pypi/ntlog/\n\n:Author: Ken Kundert\n:Version: 0.5\n:Released: 2024-10-30\n\n\nCommand-Line Application\n------------------------\n\n*ntLog* is a simple command line utility used to append discretely generated log \nfiles into a running log formulated as a NestedText_ file. You can specify \nlimits on how many log entries there are or how old they should be. Any entries \nthat do not satisfy the limits are purged.\n\nA discrete log file is a log file generated by program that runs at regular \nintervals or after particular events. This contrasts from log files generated \nby continuously running programs such as daemons. With discretely running \nprograms a existing log file will be overwritten on the next run. By using \n*ntLog* you can add the most recently generated log file to a running log that \nwill not be overwritten.\n\n::\n\n Usage:\n\n ntlog [options] <logfile>\n\n Options:\n\n -k, --keep-for [days] drop entries older than this [default: 7]\n -n, --max-entries [N] maximum number of log entries to keep\n -N, --min-entries [N] minimum number of log entries to keep [default: 1]\n -d, --delete delete given logfile after incorporating it\n -h, --help print this usage message\n -Y, --year <fmt> add year headers\n -M, --month <fmt> add month headers\n -D, --day <fmt> add day headers\n -H, --hour <fmt> add hour headers\n -E, --entry <fmt> add entry headers\n -d, --description <text> add entry headers\n --fold-marker <mapping> map fold markers contained in logfile\n -e, --editor <editor> add editor mode line, choose from: vim\n\nWhen run, *ntLog* copies the contents of ``<logfile>`` into ``<logfile>.nt``.\n\nLog entries older than ``--keep-for`` days are deleted. If units are not \nspecified, ``--keep-for`` is given in days. However you can directly specify \nthe units in terms of seconds (s, sec, second, seconds), minutes (m, min, \nminute, minutes), hours (h, hr, hour, hours), days (d, day, days), weeks (w, W, \nweek, weeks), months (M, month, months), and years (y, Y, year, years).\n\nIf the number of entries exceeds ``--max-entries``, the oldest entries are \ndeleted even if they are younger than the ``--keep-for`` limit.\n\nIf ``--delete`` is specified, the given log file is deleted after its contents \nare incorporated into the running log file.\n\nThe key used when filing log entries into the *NestedText* document is the \ntimestamp of the modification time of the given log file.\n\nThe given log file is always kept, even if it is older than the ``--keep-for`` \nlimit.\n\nLog entries are sorted from most recent to oldest, with the most recent at the \ntop of the *NestedText* file. The one exception to this rule is that the given \nlog file is always listed first, even if its modification time is older than \nexisting log entries.\n\n\nHeaders\n\"\"\"\"\"\"\"\n\nAny headers you specify are added as comments above the appropriate entries.\nWhen a year header is specified, it is added before the first entry found from \nnew year. The same is true for month, day, and hour headers. The entry header \nit given before each entry. An entry is treated as an Arrow_ format. It \nconsists of tokens that are to be replaced by components from the entry date \nstamp. For example, if you specify::\n\n --entry 'D MMMM YYYY, h:mm A'\n\nThen you will get a entry header command that looks like this::\n\n # 31 December 2023, 6:00 PM\n 2023-12-31T18:00:25.680009-08:00:\n > ...\n\nIf you specify a description, it will be prepended to the datestamp in the key \nfor the new log entry and will be prepended to the entry header. For example, \nif ``--description create`` were specified, the result might look like::\n\n # create \u2014 31 December 2023, 6:00 PM\n create \u2014 2023-12-31T18:00:25.680009-08:00:\n > ...\n\n\nIt is attractive to include editor fold markers in the headers. In doing so you \ncan collapse large log entries into a single line folds until they are needed, \nat which point you can easily open the fold and examine the contents of the log \nfile. Here is an example set of header specifications that include Vim fold \nmarkers::\n\n --year 'YYYY {{{1'\n --month 'MMMM YYYY {{{2'\n --day 'D MMMM YYYY {{{3'\n --entry 'D MMMM YYYY, h:mm A {{{4'\n\nIf your logfiles tend to include fold markers, they can confuse the folds. You \ncan prevent this by mapping the marker into a different string. Use \n``--fold-marker``::\n\n --fold-marker '{{{ {<{'\n\n\nNTlog API\n---------\n\n*ntLog* provides the *NTlog* class, whose instances can be used as an output \nfile stream in Python programs. Instead of writing to stand-alone files their \noutput is incorporated directly into a NestedText composite logfile.\n\n*NTlog* provides the normal methods for output file streams, *write*, *flush* \nand *close*, and can act as a context manager. Only *write* takes an argument, \nthe text to be written to the logfile.\n\n*NTlog* Arguments:\n running_log_file: (str, os.PathLike):\n The path to the composite log file. Normally this uses .log.nt as\n the suffix. If not given, then the name of the temp_log_file with\n an added .nt suffix is used.\n temp_log_file: (str, os.PathLike):\n The path to the temporary log file. Normally this uses .log as the \n suffix. This is optional.\n keep_for (float, str):\n Any entries older than keep_for (in seconds) are dropped.\n If keep_for is a string, it is converted to seconds. In this case\n it assumed to be a number followed by a unit. For example, '1w',\n '6M', etc.\n max_entries (int):\n Maximum number of log entries to keep.\n min_entries (int):\n Minimum number of log entries to keep.\n retain_temp (bool):\n Do not delete the temporary log file after writing composite log\n file.\n ctime (datetime):\n Used as the creation time of the log entry.\n If not specified, the current time is used.\n year_header (str):\n When specified, this header is added above the first entry from a new year.\n month_header (str):\n When specified, this header is added above the first entry from a new month.\n day_header (str):\n When specified, this header is added above the first entry from a new day.\n hour_header (str):\n When specified, this header is added above the first entry from a new hour.\n entry_header (str):\n When specified, this header is added above every entry.\n description (str):\n This string is prepended to the datestamp to create the key for the new \n log entry. It is also prepended to the entry header, if it is \n requested.\n fold_marker_mapping ([str, str]):\n When specified, any instances of the first string in a log file are\n replaced by the second string when incorporating that log into the\n output NestedText file.\n\nRaises:\n OSError, NTlogError\n\n *NTlogError* is a clone of the Error_ exception from Inform_.\n\nThe use of the *temp_log_file* is optional. It is helpful with long running \nprocesses as it provides a way of monitoring the progress of the process, \nespecially if the logfile is routinely flushed.\n\n**Example** (with error reporting)::\n\n from ntlog import NTlog, NTlogError\n from inform import Inform, fatal, os_error\n\n try:\n with NTlog('appname.log.nt', keep_for='7d', max_entries=20):\n ntlog.write('a log message')\n ntlog.write('another log message')\n ...\n except OSError as e:\n fatal(os_error(e))\n except NTlogError as e:\n e.terminate()\n\n**Example** (with temp log)::\n\n with NTlog('appname.log.nt', 'appname.log', keep_for='7d', retain_temp=True):\n ntlog.write('log message')\n ntlog.flush()\n ...\n\n*NTlog* can be specified as the logfile to Inform_.\n\n**Example** (with inform)::\n\n from ntlog import NTlog\n from inform import Inform, display, error, log\n\n with (\n NTlog('appname.log.nt', keep_for='7d') as ntlog,\n Inform(logfile=ntlog) as inform,\n ):\n display('status message')\n log('log message')\n if there_is_a_problem:\n error('error message')\n ...\n\n**Example** (with temp log and inform)::\n\n with (\n NTlog('appname.log.nt', 'appname.log', keep_for='7d') as ntlog,\n Inform(logfile=ntlog, flush=True) as inform,\n ):\n display('status message')\n log('log message')\n if there_is_a_problem:\n error('error message')\n ...\n\n\nInstallation\n------------\n\nInstall with::\n\n pip install ntlog\n\nReleases\n--------\n\nLatest Development Version\n\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\n| Version: 0.5\n| Released: 2024-10-30\n\n0.5 (2024-10-30)\n\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\n- Add Vim mode line (--editor option).\n\n0.4 (2024-01-29)\n\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\n- Add support for headers and fold markers.\n\n0.3 (2023-05-01)\n\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\n- Add Python API.\n\n0.2 (2023-04-10)\n\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\n- Improve error handling\n\n0.1 (2023-04-08)\n\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\n- Add support for time units on ``--keep-for``.\n\n.. _NestedText: https://nestedtext.org\n.. _Inform: https://inform.readthedocs.io\n.. _Error: https://inform.readthedocs.io/en/stable/api.html#inform.Error\n.. _Arrow: https://arrow.readthedocs.io/en/latest/guide.html#supported-tokens\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Append a log file to an running NestedText log",
"version": "0.5",
"project_urls": {
"changelog": "https://github.com/KenKundert/ntlog/blob/master/CHANGELOG.rst",
"documentation": "https://github.com/KenKundert/ntlog/blob/master/README.rst",
"homepage": "https://github.com/kenkundert/ntlog",
"repository": "https://github.com/kenkundert/ntlog"
},
"split_keywords": [
"nestedtext",
" logging"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "bb14955c6c9e799d702f7267f655b06414d008d80205edc25d0644f0ddb515ab",
"md5": "3b9b831c91482beb4800731a4c414f28",
"sha256": "a9f1f172b0af3e155f7a2e27982cc2e92350a04a7019ce88966a93ff7e95f14e"
},
"downloads": -1,
"filename": "ntlog-0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3b9b831c91482beb4800731a4c414f28",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 10778,
"upload_time": "2024-10-30T18:37:41",
"upload_time_iso_8601": "2024-10-30T18:37:41.470133Z",
"url": "https://files.pythonhosted.org/packages/bb/14/955c6c9e799d702f7267f655b06414d008d80205edc25d0644f0ddb515ab/ntlog-0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8b8268eadc8b1a6aef4f8a0d248710fc5710b0f4a18ab01aee6d51db8afef8ee",
"md5": "e4b68f47bdf738203e59febed8981e1b",
"sha256": "e7049e9316b81257d359b8a2d71a730d4c34ec01351775cebf7f09dd2a6e59e5"
},
"downloads": -1,
"filename": "ntlog-0.5.tar.gz",
"has_sig": false,
"md5_digest": "e4b68f47bdf738203e59febed8981e1b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 11115,
"upload_time": "2024-10-30T18:37:42",
"upload_time_iso_8601": "2024-10-30T18:37:42.842735Z",
"url": "https://files.pythonhosted.org/packages/8b/82/68eadc8b1a6aef4f8a0d248710fc5710b0f4a18ab01aee6d51db8afef8ee/ntlog-0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-30 18:37:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "KenKundert",
"github_project": "ntlog",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"tox": true,
"lcname": "ntlog"
}
