custerm 1.0.2

A custom terminal library with rich markdown support.

Terminal

This class provides various utility functions for interacting with the terminal, including options selection and text formatting.

Methods

• options(options_list: list) -> str: Allows the user to select an option from a list of options. Returns the selected option as a string.
• print(text: str, markdown: bool = False): Prints text to the terminal, optionally formatting it based on Markdown syntax. Markdown formatting includes support for headings, bold, underline, italics, list items, and code blocks.
• render_markdown(text: str) -> str: Renders text in the Markdown format, applying specific ANSI color codes to the text based on the Markdown syntax.

Usage

from custerm.terminal import Terminal

# Example options usage
options_list = ["Option 1", "Option 2", "Option 3"]
selected_option = Terminal.options(options_list)
print(f"Selected option: {selected_option}")

# Example text printing
Terminal.print("This is a sample text.", markdown=False)

# Example Markdown rendering
markdown_text = "### This is a heading\n**Bold text**\n*Italic text*\n- List item 1\n- List item 2\n```python\nprint('Hello, world!')\n```"
rendered_text = Terminal.render_markdown(markdown_text)
print(rendered_text)

Exceptions

• InvalidChoiceException: Raised when an invalid option choice is made during the options selection process.
• InvalidMarkdownException: Raised when the provided Markdown syntax is invalid during the rendering process.

Dependencies

• dataclasses: Used for creating data classes and defining their attributes.
• re: Required for handling regular expressions for Markdown formatting.
• custerm.ansi.Color: A module providing ANSI color codes for text formatting.
• custerm.exceptions: A module providing custom exceptions for the terminal class.

Color

The Color class in the custerm library provides ANSI color codes for text formatting and supports custom color definitions.

ANSI Color Attributes

• ANSI_RESET: Resets all ANSI formatting.
• Text Colors:
  • ANSI_BLACK, ANSI_RED, ANSI_GREEN, ANSI_YELLOW, ANSI_BLUE, ANSI_MAGENTA, ANSI_CYAN, ANSI_WHITE: Basic text colors.
  • ANSI_BRIGHT_BLACK, ANSI_BRIGHT_RED, ANSI_BRIGHT_GREEN, ANSI_BRIGHT_YELLOW, ANSI_BRIGHT_BLUE, ANSI_BRIGHT_MAGENTA, ANSI_BRIGHT_CYAN, ANSI_BRIGHT_WHITE: Bright text colors.
• Background Colors:
  • ANSI_BG_BLACK, ANSI_BG_RED, ANSI_BG_GREEN, ANSI_BG_YELLOW, ANSI_BG_BLUE, ANSI_BG_MAGENTA, ANSI_BG_CYAN, ANSI_BG_WHITE: Basic background colors.
  • ANSI_BG_BRIGHT_BLACK, ANSI_BG_BRIGHT_RED, ANSI_BG_BRIGHT_GREEN, ANSI_BG_BRIGHT_YELLOW, ANSI_BG_BRIGHT_BLUE, ANSI_BG_BRIGHT_MAGENTA, ANSI_BG_BRIGHT_CYAN, ANSI_BG_BRIGHT_WHITE: Bright background colors.
• Other Attributes:
  • ANSI_DIM_BLACK, ANSI_DIM_RED, ANSI_DIM_GREEN, ANSI_DIM_YELLOW, ANSI_DIM_BLUE, ANSI_DIM_MAGENTA, ANSI_DIM_CYAN, ANSI_DIM_WHITE: Dim text colors.
  • ANSI_LIGHT_BLACK, ANSI_LIGHT_RED, ANSI_LIGHT_GREEN, ANSI_LIGHT_YELLOW, ANSI_LIGHT_BLUE, ANSI_LIGHT_MAGENTA, ANSI_LIGHT_CYAN, ANSI_LIGHT_WHITE: Light text colors.
  • ANSI_BG_DIM_BLACK, ANSI_BG_DIM_RED, ANSI_BG_DIM_GREEN, ANSI_BG_DIM_YELLOW, ANSI_BG_DIM_BLUE, ANSI_BG_DIM_MAGENTA, ANSI_BG_DIM_CYAN, ANSI_BG_DIM_WHITE: Dim background colors.
  • ANSI_BG_LIGHT_BLACK, ANSI_BG_LIGHT_RED, ANSI_BG_LIGHT_GREEN, ANSI_BG_LIGHT_YELLOW, ANSI_BG_LIGHT_BLUE, ANSI_BG_LIGHT_MAGENTA, ANSI_BG_LIGHT_CYAN, ANSI_BG_LIGHT_WHITE: Light background colors.

Methods

• apply_color_tags(text: str) -> str: Applies ANSI color tags to text based on custom color definitions or predefined ANSI attributes. It parses text for color tags in the format [color]text[/color] and replaces them with the corresponding color codes. The parsed text is returned with ANSI formatting.

• add_custom_color(color_name: str, color_code: str): Adds a custom color definition to the Color class. The color_name is the name of the color in uppercase, and color_code is the ANSI color code to use.

• remove_custom_color(color_name: str): Removes a custom color definition from the Color class based on the color_name.

Usage

from custerm.ansi import Color

# Apply custom color tags
formatted_text = Color.apply_color_tags("[MYCOLOR]This is colored text[/MYCOLOR]")
print(formatted_text)

# Add custom color definition
Color.add_custom_color("MYCOLOR", "\033[38;5;203m")

# Apply custom color tags again
formatted_text = Color.apply_color_tags("[MYCOLOR]This is colored text[/MYCOLOR]")
print(formatted_text)

# Remove custom color definition
Color.remove_custom_color("MYCOLOR")

Dependencies

• re: Required for handling regular expressions in the apply_color_tags method for parsing color tags.
• Predefined color attributes, such as ANSI_RESET, ANSI_BLACK, ANSI_RED, etc., provide predefined ANSI color codes for various color formatting options.

CustomLogger

The CustomLogger class in the custerm library provides a custom logging utility built on top of Python's logging module. It allows you to configure and use loggers with different log levels.

Logger Configuration

LoggerConfig

LoggerConfig is a data class that holds the configuration for the logger:

• log_level (Optional, Default: logging.DEBUG): The desired logging level for the logger.
• log_file (Optional, Default: "my_library.log"): The path to the log file where logs will be stored.

Log Levels

LogLevel is a data class that defines different log levels that can be used with the logger:

• DEBUG: Debug log level.
• INFO: Info log level.
• WARNING: Warning log level.
• ERROR: Error log level.
• SUCCESS: Custom log level with the value 25.

Methods

• create_logger(cls, config: LoggerConfig) -> CustomLogger: Creates an instance of the CustomLogger class based on the provided LoggerConfig.
• log_debug(self, message: str): Logs a debug message.
• log_info(self, message: str): Logs an info message.
• log_warning(self, message: str): Logs a warning message.
• log_error(self, message: str): Logs an error message.
• log_success(self, message: str): Logs a success message using the custom log level defined in LogLevel.
• log(self, message: str, level=logging.INFO): Logs a message with the specified log level. If the level is not a valid log level, it defaults to INFO and logs a warning.
• set_log_level(level): Sets the log level for the logger to the specified level. If the provided level is not valid, it uses the default level of DEBUG.
• available_log_levels (Property): Returns the available log levels from LogLevel as a dictionary.

Usage

from custerm.log import CustomLogger, LoggerConfig

# Create a logger with custom configuration
config = LoggerConfig(log_level=LogLevel.WARNING, log_file="custom.log")
logger = CustomLogger.create_logger(config)

# Log messages at different levels
logger.log_debug("This is a debug message")
logger.log_info("This is an info message")
logger.log_warning("This is a warning message")
logger.log_error("This is an error message")
logger.log_success("This is a success message")

# Set the log level dynamically
logger.set_log_level(LogLevel.DEBUG)

# Log a message with the updated log level
logger.log("This is a debug message with the updated log level", level=LogLevel.DEBUG)

Dependencies

• logging: Required for creating and configuring loggers.
• Predefined log levels: DEBUG, INFO, WARNING, and ERROR, as well as a custom log level SUCCESS, provide different levels for logging messages.