`ultraprint` - A Python Library for Enhanced Terminal Output
Welcome to `ultraprint`! This Python library is designed to enhance terminal output with colorful and styled text, making your console logs more readable and aesthetically pleasing developed by [*Ranit Bhowmick*](https://www.linkedin.com/in/ranitbhowmick/) & [*Sayanti Chatterjee*](https://www.linkedin.com/in/sayantichatterjee/). Whether you're building a command-line application, debugging code, or just want to add some flair to your terminal, `ultraprint` provides a simple and effective solution.
Table of Contents
1. [Introduction](introduction)
2. [Installation](installation)
3. [Basic Usage](basic-usage)
- [Color Functions](color-functions)
- [Text Style Functions](text-style-functions)
- [Background Color Functions](background-color-functions)
- [Newline Function](newline-function)
4. [Advanced Usage: Logging](advanced-usage-logging)
- [Logger Class](logger-class)
- [Logger Methods](logger-methods)
5. [Documentation](documentation)
- [Color Functions](color-functions)
- [Text Style Functions](text-style-functions)
- [Background Color Functions](background-color-functions)
- [Logger Class](logger-class)
6. [Examples](examples)
7. [Contributing](contributing)
Introduction
`ultraprint` is a Python library that extends the capabilities of the standard `print` function. It allows you to easily print text in different colors, styles, and backgrounds in the terminal. Additionally, it includes a logger class that can log messages with different severity levels and styles, both in the terminal and to a file.
This library is ideal for developers who want to make their terminal outputs more organized and visually appealing. With `ultraprint`, you can quickly identify important information, warnings, errors, and other message types based on their color and style.
Installation
To install `ultraprint`, simply use `pip`:
bash
pip install ultraprint
Basic Usage
Color Functions
The `ultraprint` library provides functions to print text in various colors:
python
import ultraprint.common as p
p.red("This is red text")
p.green("This is green text")
p.yellow("This is yellow text")
p.blue("This is blue text")
p.purple("This is purple text")
p.cyan("This is cyan text")
p.lgray("This is light gray text")
p.dgray("This is dark gray text")
Text Style Functions
In addition to colors, you can apply styles like bold, underline, and negative:
python
p.bold("This is bold text")
p.underline("This is underlined text")
p.negative("This is negative text")
Background Color Functions
You can also change the background color of the text:
python
p.red_bg("This is red background text")
p.green_bg("This is green background text")
p.yellow_bg("This is yellow background text")
p.blue_bg("This is blue background text")
p.purple_bg("This is purple background text")
p.cyan_bg("This is cyan background text")
p.lgray_bg("This is light gray background text")
p.dgray_bg("This is dark gray background text")
Newline Function
For convenience, you can easily print new lines:
python
p.n() Prints one new line
p.n(3) Prints three new lines
Screen Management Functions
The `ultraprint` library also provides functions to manage the terminal screen:
python
p.cls() Clears the terminal screen
p.cls_prev() Clears the previous line
Advanced Usage: Logging
Logger Class
The `ultraprint` library includes an enhanced `logger` class for structured logging with different severity levels, customizable formats, log rotation, and optional extra contextual information (like the file name, function, and line number). Logs can be output both to the console and to a log file, with thread safety ensured for multi-threaded applications.
python
from ultraprint.logging import logger
Create a logger object with extra info enabled
log = logger('example_log', include_extra_info=True)
Log some messages
log.info('This is an info message')
log.error('This is an error message')
log.warning('This is a warning message')
log.success('This is a success message')
log.debug('This is a debug message')
log.critical('This is a critical message')
Logger Methods
The `logger` class provides the following methods:
- `info(msg)`: Logs an informational message (in cyan).
- `error(msg)`: Logs an error message (in red).
- `warning(msg)`: Logs a warning message (in yellow).
- `success(msg)`: Logs a success message (in green).
- `debug(msg)`: Logs a debug message (in dark gray).
- `critical(msg)`: Logs a critical message (with a red background).
Each method writes the log entry to both the console (using colored output) and to a log file named after the logger (e.g., `example_log.log`).
Extra Information
The `logger` class allows you to include extra context, such as the filename, function name, and line number where the log message was called, using the `include_extra_info=True` flag. This is particularly useful for debugging.
python
log = logger('detailed_log', include_extra_info=True)
log.info('Logging with extra information')
This will output something like:
[2024-09-29 12:34:56] [INFO] [detailed_log] Logging with extra information [script.py:my_function:42]
Custom Filename for Logs
You can specify a custom filename for the log file by passing the `filename` argument when creating a logger object. If not provided, the default filename will be the name of the logger followed by `.log`.
python
log = logger('custom_logger', filename='custom_log_file.log')
log.info('This will be logged in custom_log_file.log')
Documentation
Color Functions
These functions print the provided text in different colors:
- **red(*args)**: Prints text in red.
- **green(*args)**: Prints text in green.
- **yellow(*args)**: Prints text in yellow.
- **blue(*args)**: Prints text in blue.
- **purple(*args)**: Prints text in purple.
- **cyan(*args)**: Prints text in cyan.
- **lgray(*args)**: Prints text in light gray.
- **dgray(*args)**: Prints text in dark gray.
Text Style Functions
These functions apply different styles to the text:
- **bold(*args)**: Prints bold text.
- **underline(*args)**: Prints underlined text.
- **negative(*args)**: Prints text with a negative style.
Background Color Functions
These functions print the provided text with different background colors:
- **red_bg(*args)**: Prints text with a red background.
- **green_bg(*args)**: Prints text with a green background.
- **yellow_bg(*args)**: Prints text with a yellow background.
- **blue_bg(*args)**: Prints text with a blue background.
- **purple_bg(*args)**: Prints text with a purple background.
- **cyan_bg(*args)**: Prints text with a cyan background.
- **lgray_bg(*args)**: Prints text with a light gray background.
- **dgray_bg(*args)**: Prints text with a dark gray background.
Logger Class
The `logger` class provides structured logging with timestamped entries and colored outputs. Each log method corresponds to a different severity level and prints in a specific color.
Logger Methods:
- **info(msg)**: Logs an informational message in cyan.
- **error(msg)**: Logs an error message in red.
- **warning(msg)**: Logs a warning message in yellow.
- **success(msg)**: Logs a success message in green.
- **debug(msg)**: Logs a debug message in dark gray.
- **critical(msg)**: Logs a critical message with a red background.
You can enable extra context (like the file name, function name, and line number) with `include_extra_info=True`.
Setting Log Level:
By default, the log level is set to `INFO`, which means that all log messages with a severity level of `INFO` or higher will be displayed. You can change the log level by calling the `set_log_level` method with one of the following options: `INFO`, `SUCCESS`, `WARNING`, `ERROR`, `CRITICAL`.
Setting Log File:
By default, logs are written to a file with the same name as the logger followed by `.log`. You can disable writing to a file by setting `write_to_file=False` when creating the logger object or by calling the `set_write_to_file` method. If you want to specify a custom filename, you can pass the `filename` argument when creating the logger object.
Custom Log Formats
You can customize the format of your log messages by providing the `log_format` parameter when creating a `logger` object. The default format is `[{time}] [{level}] [{name}] {message}`. You can include the following placeholders in your custom format:
- `{time}`: Timestamp of the log entry.
- `{level}`: Log level (e.g., INFO, ERROR).
- `{name}`: Name of the logger.
- `{message}`: The log message.
- `{extra_info}`: Extra context information if `include_extra_info` is `True`.
**Example:**
python
log = logger('custom_format_log', log_format='[{time}] [{level}] {message} - {extra_info}', include_extra_info=True)
log.info('This is a custom formatted log message')
Exception Method
The `logger` class also provides an `exception` method to log exceptions with traceback information. This is useful for debugging purposes.
**Example:**
python
try:
1 / 0
except ZeroDivisionError as e:
log.exception('An exception occurred')
This will log the exception message along with the traceback information.
Examples
Basic Color and Style Printing
python
import ultraprint.common as p
p.red("This is red text")
p.bold("This is bold text")
p.red_bg("This is red background text")
Using the Logger with Extra Information
python
from ultraprint.logging import logger
log = logger('example_log', include_extra_info=True)
log.info('Starting the process...')
log.success('Process completed successfully!')
log.warning('This is a warning')
log.error('An error occurred')
log.critical('Critical failure, system shutting down!')
Contributing
We welcome contributions to `ultraprint`! If you have suggestions, find a bug, or want to add a new feature, please open an issue or submit a pull request on GitHub.
v.2.0.0
`ultraprint` - A Python Library for Enhanced Terminal Output
Welcome to `ultraprint`! This Python library is designed to enhance terminal output with colorful and styled text, making your console logs more readable and aesthetically pleasing developed by [*Ranit Bhowmick*](https://www.linkedin.com/in/ranitbhowmick/) & [*Sayanti Chatterjee*](https://www.linkedin.com/in/sayantichatterjee/). Whether you're building a command-line application, debugging code, or just want to add some flair to your terminal, `ultraprint` provides a simple and effective solution.
Table of Contents
1. [Introduction](introduction)
2. [Installation](installation)
3. [Basic Usage](basic-usage)
- [Color Functions](color-functions)
- [Text Style Functions](text-style-functions)
- [Background Color Functions](background-color-functions)
- [Newline Function](newline-function)
4. [Advanced Usage: Logging](advanced-usage-logging)
- [Logger Class](logger-class)
- [Logger Methods](logger-methods)
5. [Documentation](documentation)
- [Color Functions](color-functions)
- [Text Style Functions](text-style-functions)
- [Background Color Functions](background-color-functions)
- [Logger Class](logger-class)
6. [Examples](examples)
7. [Contributing](contributing)
Introduction
`ultraprint` is a Python library that extends the capabilities of the standard `print` function. It allows you to easily print text in different colors, styles, and backgrounds in the terminal. Additionally, it includes a logger class that can log messages with different severity levels and styles, both in the terminal and to a file.
This library is ideal for developers who want to make their terminal outputs more organized and visually appealing. With `ultraprint`, you can quickly identify important information, warnings, errors, and other message types based on their color and style.
Installation
To install `ultraprint`, simply use `pip`:
bash
pip install ultraprint
Basic Usage
Color Functions
The `ultraprint` library provides functions to print text in various colors:
python
import ultraprint.common as p
p.red("This is red text")
p.green("This is green text")
p.yellow("This is yellow text")
p.blue("This is blue text")
p.purple("This is purple text")
p.cyan("This is cyan text")
p.lgray("This is light gray text")
p.dgray("This is dark gray text")
Text Style Functions
In addition to colors, you can apply styles like bold, underline, and negative:
python
p.bold("This is bold text")
p.underline("This is underlined text")
p.negative("This is negative text")
Background Color Functions
You can also change the background color of the text:
python
p.red_bg("This is red background text")
p.green_bg("This is green background text")
p.yellow_bg("This is yellow background text")
p.blue_bg("This is blue background text")
p.purple_bg("This is purple background text")
p.cyan_bg("This is cyan background text")
p.lgray_bg("This is light gray background text")
p.dgray_bg("This is dark gray background text")
Newline Function
For convenience, you can easily print new lines:
python
p.n() Prints one new line
p.n(3) Prints three new lines
Advanced Usage: Logging
Logger Class
The `ultraprint` library includes a `logger` class for structured logging with different severity levels, timestamped entries, and optional extra contextual information (like the file name, function, and line number). Logs can be output both to the console and to a log file.
python
from ultraprint.logging import logger
Create a logger object with extra info enabled
log = logger('example_log', include_extra_info=True)
Log some messages
log.info('This is an info message')
log.error('This is an error message')
log.warning('This is a warning message')
log.success('This is a success message')
log.debug('This is a debug message')
log.critical('This is a critical message')
Logger Methods
The `logger` class provides the following methods:
- `info(msg)`: Logs an informational message (in cyan).
- `error(msg)`: Logs an error message (in red).
- `warning(msg)`: Logs a warning message (in yellow).
- `success(msg)`: Logs a success message (in green).
- `debug(msg)`: Logs a debug message (in dark gray).
- `critical(msg)`: Logs a critical message (with a red background).
Each method writes the log entry to both the console (using colored output) and to a log file named after the logger (e.g., `example_log.log`).
Extra Information
The `logger` class allows you to include extra context, such as the filename, function name, and line number where the log message was called, using the `include_extra_info=True` flag. This is particularly useful for debugging.
python
log = logger('detailed_log', include_extra_info=True)
log.info('Logging with extra information')
This will output something like:
[2024-09-29 12:34:56] [INFO] [detailed_log] Logging with extra information [script.py:my_function:42]
Custom Filename for Logs
You can specify a custom filename for the log file by passing the `filename` argument when creating a logger object. If not provided, the default filename will be the name of the logger followed by `.log`.
python
log = logger('custom_logger', filename='custom_log_file.log')
log.info('This will be logged in custom_log_file.log')
Documentation
Color Functions
These functions print the provided text in different colors:
- **red(*args)**: Prints text in red.
- **green(*args)**: Prints text in green.
- **yellow(*args)**: Prints text in yellow.
- **blue(*args)**: Prints text in blue.
- **purple(*args)**: Prints text in purple.
- **cyan(*args)**: Prints text in cyan.
- **lgray(*args)**: Prints text in light gray.
- **dgray(*args)**: Prints text in dark gray.
Text Style Functions
These functions apply different styles to the text:
- **bold(*args)**: Prints bold text.
- **underline(*args)**: Prints underlined text.
- **negative(*args)**: Prints text with a negative style.
Background Color Functions
These functions print the provided text with different background colors:
- **red_bg(*args)**: Prints text with a red background.
- **green_bg(*args)**: Prints text with a green background.
- **yellow_bg(*args)**: Prints text with a yellow background.
- **blue_bg(*args)**: Prints text with a blue background.
- **purple_bg(*args)**: Prints text with a purple background.
- **cyan_bg(*args)**: Prints text with a cyan background.
- **lgray_bg(*args)**: Prints text with a light gray background.
- **dgray_bg(*args)**: Prints text with a dark gray background.
Logger Class
The `logger` class provides structured logging with timestamped entries and colored outputs. Each log method corresponds to a different severity level and prints in a specific color.
Logger Methods:
- **info(msg)**: Logs an informational message in cyan.
- **error(msg)**: Logs an error message in red.
- **warning(msg)**: Logs a warning message in yellow.
- **success(msg)**: Logs a success message in green.
- **debug(msg)**: Logs a debug message in dark gray.
- **critical(msg)**: Logs a critical message with a red background.
You can enable extra context (like the file name, function name, and line number) with `include_extra_info=True`.
Examples
Basic Color and Style Printing
python
import ultraprint.common as p
p.red("This is red text")
p.bold("This is bold text")
p.red_bg("This is red background text")
Using the Logger with Extra Information
python
from ultraprint.logging import logger
log = logger('example_log', include_extra_info=True)
log.info('Starting the process...')
log.success('Process completed successfully!')
log.warning('This is a warning')
log.error('An error occurred')
log.critical('Critical failure, system shutting down!')
Contributing
We welcome contributions to `ultraprint`! If you have suggestions, find a bug, or want to add a new feature, please open an issue or submit a pull request on GitHub.