Metadata-Version: 2.4
Name: pylogfile
Version: 0.4.1
Summary: Universal log files for Python
Author-email: Grant Giesbrecht <grant.giesbrecht@colorado.edu>
License: BSD 3-Clause License
        
        Copyright (c) 2024, Grant-Giesbrecht
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this
           list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
        
        3. Neither the name of the copyright holder nor the names of its
           contributors may be used to endorse or promote products derived from
           this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
        
Project-URL: Homepage, https://github.com/Grant-Giesbrecht/pylogfile
Project-URL: Issues, https://github.com/Grant-Giesbrecht/pylogfile/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=2.0.0
Requires-Dist: h5py>=3.11.0
Requires-Dist: colorama>=0.4.6
Requires-Dist: importlib>=1.0.0
Dynamic: license-file

<h1 align="center">
<img src="https://github.com/Grant-Giesbrecht/pylogfile/blob/main/docs/images/pylogfile_logo_banner.svg?raw=True" width="300">
</h1><br>

Pylogfile provides a better method for implementing logging in your Python scripts.

- **PyPI:** https://pypi.org/project/pylogfile/
- **Documentation:** https://pylogfile.readthedocs.io/en/latest/
- **Source Code:** [https://github.com/](https://github.com/Grant-Giesbrecht/pylogfile/)

Core features:

- automatically includes metadata such as timestamps.
- supports optional detail strings to supplement the main log message.
- integrated markdown makes it easy to highlight parts of log messages with color.
- easily read and write logs to binary files for better efficiency, or JSON and TXT for best readability.
- standardized format makes it easy to read previous log files, simplifying sorting and analysis.
- script `lumberjack` makes viewing, sorting and analyzing log files quick and easy.

Pylogfile is designed to be a better option than the Python standard logging module for simple to intermediate-complexity logging tasks. For professional applications in which you want to add custom logging handlers, the standard module is the better choice. However, for the majority of scripts, especially in the scientific, engineering and data analysis domains, pylogfile offers loads of capability and a much faster way of setting up proper logging than the standard module. With pylogfile, your application has access to efficient data management and display through the addition of detailed messages, integrated markdown, and log search functions through the `lumberjack` script.

## Installation

Pylogfile can be installed via pip using

```
pip install pylogfile
```

## Example usage

In this example, we create a simple program that sends two log messages and saves them to disk. Here we show how to save to both binary and plain text formats. The [HDF](https://www.hdfgroup.org/) file format is binary, allowing logs to be saved faster and while using less space on disk. We also show how to save to a JSON file, for those who prefer the simplicity of plain text files.

```python
from pylogfile.base import *

log = LogPile()
log.info("Something happened. Emphasize >this<.")
log.error("Something bad happened!")

log.save_hdf("example.log.hdf")
log.save_json("example.log.json")
```

With the corresponding output:

<img src="https://github.com/Grant-Giesbrecht/pylogfile/blob/main/docs/images/ex1_output.png?raw=True" width="600">

## Lumberjack

Lumberjack is a command line interface (CLI) script included with pylogfile that allows log files to quickly be viewed, sorted, and analyzed. A log file can be opened in lumberjack with:

```
lumber example.log.hdf
```

and the first few logs displayed with the `SHOW` command:

<img src="https://github.com/Grant-Giesbrecht/pylogfile/blob/main/docs/images/lumber_out1.png?raw=True" width="600">

Basic information about the log file can be displayed with the `INFO` command.

<img src="https://github.com/Grant-Giesbrecht/pylogfile/blob/main/docs/images/lumber_out2.png?raw=True" width="320">

Logs can also be sorted by applying flags to the `SHOW` command. Here the `--index` flag is used to search based on the index of the log entry, the `--contains` flag is used to search for the keyword or phrase 'RF' while specifying a max of 5 logs should be displayed using the `--num` flag, and the log level is filter by applying the `--min` and `--max` flags.

<img src="https://github.com/Grant-Giesbrecht/pylogfile/blob/main/docs/images/lumber_out3.png?raw=True" width="600">

Lumberjack has lots of other search functions, commands, and features. You can learn more about it from its integrated help menu which can list all available commands and provide detailed information on how to use them.

<img src="https://github.com/Grant-Giesbrecht/pylogfile/blob/main/docs/images/lumber_out4.png?raw=True" width="600">

## Documentation

Pylogfile's documentation can be found on [ReadTheDocs](https://pylogfile.readthedocs.io/en/latest/).

## Requirements

- Python >= 3.9
- numpy >= 1.0.0
- h5py >= 3.11.0
- colorama >= 0.4.6
- importlib >= 1.0.0
