Download This Notebook: Introduction.ipynb

Introduction

This tutorial is intended to provide a brief overview to the core functionality of pylogfile, quickly covering the main concepts behind the package.

Making a LogPile

First we’ll import pylogfile and create a new LogPile object. This is the class used to represent a collection of LogEntrys, each of which represent a single log message.

from pylogfile.base import *

log = LogPile()

Now we can make some entries in the log.

# By calling lowdebug(), debug(), info(), warning(), error(), critcal() we can
# make logs at different levels.
log.info("This is an info message.")
log.error("This is an error message.")

# Sometimes you want to include additional info, but might not want it to
# clutter up the standard output. By including this as the `detail` string, we
# can later choose if we want to display or hide these verbose detail strings.
log.info("This is a log message.", detail=f"This is where we can add a ton of"\
    "extra details. This is hidden by default, but still saved with the logs."\
    "You can also set details to be shown by default using the code below:")

[INFO] This is an info message. | 2026-01-25 00:52:48.719332
[ERROR] This is an error message. | 2026-01-25 00:52:48.719735
[INFO] This is a log message. | 2026-01-25 00:52:48.719825

Configuring the Output Format

We can change various aspects of how LogPile handles new logs. First, lets see how to configure it to print details to the standard output.

# Tell LogPile to display detail strings
log.str_format.show_detail = True
log.info("We just set `show_detail` to `True`.", detail="This is the detail string.")

#TODO: We can also add an example modifying the colors and showing markdown

[INFO] We just set `show_detail` to `True`. | 2026-01-25 00:52:48.762569
         This is the detail string.

We can also change what colors are printed for the various components of logs. These color formatting rules can be adjusted by log level, making it easier to see what types of log messages are coming it at a glance. This is done by modifing the attributes inside a LogFormat class.

Lets change the main color from white to something a little easier to read on, like blue.

log.str_format.default_color['main'] = Fore.BLUE

log.info("The messages should now print in blue!")

# Let's reset it back to white
log.str_format.default_color['main'] = Fore.WHITE

[INFO] The messages should now print in blue! | 2026-01-25 00:52:48.768130

We can also turn off color all together if desired

log.str_format.use_color = False

log.info("The messages will now be colorless")

# Let's turn color back on
log.str_format.use_color = True

[INFO] The messages will now be colorless | 2026-01-25 00:52:48.773840

Pylogfile Markdown

Pylogfile uses a unique flavor of markdown to enable quick color changes to be applied in log messages. This is done by wrapping the phase whose color you want to change in > and <. Doing so will change the color to bold, one of five colors (main, bold, quiet, alt, and label) defined in pylogfile’s LogFormat class.

log.info(f"Let's demonstrate >bold< text.")

# This gets really handy when emphasizing data in a log!
pi = 3.1415926535
log.info(f"Pi = >{pi}<.")

[INFO] Let's demonstrate bold text. | 2026-01-25 00:52:48.779318
[INFO] Pi = 3.1415926535. | 2026-01-25 00:52:48.779500

You can change to any other color using >:n where ‘n’ is an ‘n’-code, as listed below:

- `1` or `m`: Main
- `2` or `b`: Bold
- `3` or `q`: Quiet
- `4` or `a`: Alt
- `5` or `l`: Label

For example, >:q would switch the color to quiet.

log.info(f"Text type >:bbold<. Can also use >:2bold<.")
log.info(f"Text type >:qquiet<. Can also use >:3quiet<.")
log.info(f"Text type >:aalt<. Can also use >:4alt<.")
log.info(f"Text type >:llabel<. Can also use >:5label<.")

[INFO] Text type bold. Can also use bold. | 2026-01-25 00:52:48.784877
[INFO] Text type quiet. Can also use quiet. | 2026-01-25 00:52:48.785022
[INFO] Text type alt. Can also use alt. | 2026-01-25 00:52:48.785079
[INFO] Text type label. Can also use label. | 2026-01-25 00:52:48.785138

The text color can also be permanently changed, meaning < will not revert back to the standard color, main, and will instead revert back to whatever color you change to. Making a permanent change is done by using >>.

log.info("Permanently change to >>:q quiet >:1 Show main < Now >bold< and back to quiet.")
log.info("New log resets back to main.")

[INFO] Permanently change to  quiet  Show main  Now bold and back to quiet. | 2026-01-25 00:52:48.790368
[INFO] New log resets back to main. | 2026-01-25 00:52:48.790497

If you want to type ‘>’ without changing colors, escape it with a backslash like so:

log.info(f"Backslash escapes color change sequences. \\>no color change\\<")
log.info(f"\\>\\>:3no color change\\<")

[INFO] Backslash escapes color change sequences. >no color change< | 2026-01-25 00:52:48.795836
[INFO] >>:3no color change< | 2026-01-25 00:52:48.795993

Logging Levels

Pylogfile defines six logging levels by defualt, LOWDEBUG, DEBUG, INFO, WARNING, ERROR, and CRITICAL, listed in ascending order. Only logs above a set level will be printed to the standard output (although all logs, regardless of level, are stored in the LogPile object). Notice below that only logs above the set logging level are displayed. This level in INFO by default.

# Tell LogPile to display detail strings
log.lowdebug("This is a lowdebug message")
log.debug("This is a debug message")
log.info("This is an info message")
log.warning("This is a warning message")
log.error("This is a error message")
log.critical("This is a critical message")

[INFO] This is an info message | 2026-01-25 00:52:48.801531
[WARNING] This is a warning message | 2026-01-25 00:52:48.801640
[ERROR] This is a error message | 2026-01-25 00:52:48.801685
[CRITICAL] This is a critical message | 2026-01-25 00:52:48.801728

We can change this using set_terminal_level(). Lets change it to DEBUG.

# Change the terminal display level to DEBUG
log.set_terminal_level("DEBUG")

log.debug("Changing terminal level to DEBUG.")
log.lowdebug("So lowdebug messages still will not be displayed.")

[DEBUG] Changing terminal level to DEBUG. | 2026-01-25 00:52:48.806964

How it Works

Lets look at the inside of a LogEntry to see why pylogfile is so handy.

• LogEntry.level : This is an integer describing the logging level

• LogEntry.message : Primary log message

• LogEntry.detail : Secondary log message, intended to allow additional verbose information to be added and displayed only if needed.

• LogEntry.timestamp : datetime object automatically created when the LogEntry was made.

Saving to Disk

Once we’re done logging, we can save the log as a JSON or HDF file. The key advantage of using these formats rather than simply saving a text file, is that they preserve the attributes of the LogEntry objects. This enables the log file to be quickly read and sorted, searched or filtered later on. Furthermore, HDF is a binary format, making the log file much smaller on disk.

# Save the log to an HDF file. HDF is an awesome binary format that has lots of advantages
# compared to JSON. For most user's we'd recommend saving your logs as HDF files.
log.save_hdf("example.log.hdf")

# If you want to keep your logs in plain text, you can save to JSON files without losing
# the object structure of the LogEntries. It'll just be larger on disk and slower to
# read and write than HDF.
log.save_json("example.log.json")


# If you're really a masochist you could save it as a .txt too :)