Skip to content

Commit

Permalink
Update README and test script to enhance documentation and loader fun…
Browse files Browse the repository at this point in the history 
…ctionality; introduce new features in Home class and improve logging examples
  • Loading branch information
@sexfrance
sexfrance committed Nov 10, 2024
1 parent 52ba951 commit aab3ecd
Show file tree
Hide file tree
Showing 3 changed files with 116 additions and 163 deletions.
204 changes: 114 additions & 90 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,27 +1,27 @@
# LogMagix

**LogMagix** is a custom Python logging package that provides styled, colorful log messages for various logging levels, such as success, warning, failure, and more. It includes advanced features such as batch logging, file logging, customizable animated loaders, and ASCII art displays through the `Home` class, perfect for adding visual appeal to terminal-based applications.
**LogMagix** is a custom Python logging package that offers styled, colorful log messages for various logging levels such as success, warning, failure, and more. It also features an animated loader class for providing a visual indicator during long-running operations in the terminal. Additionally, the new `Home` class offers customizable ASCII art displays for greeting users with special messages, branding, or system information.

## 🔥 Features

- **Enhanced Logging Levels**: Support for `LogLevel` enumeration, including `DEBUG`, `INFO`, `WARNING`, `SUCCESS`, `ERROR`, and `CRITICAL`, allowing fine-grained control over log output.
- **Batch Logging Mode**: Queue messages to batch display them at once.
- **File Logging**: Optionally log messages to a file with rotating log handlers.
- **Color Customization**: ANSI escape sequences for colorful terminal output.
- **Timestamped Messages**: Precise logging with time-based messages.
- **Loader with Animation**: Built-in animated loader for long-running operations with customizable text and style.
- **ASCII Art Display**: Display ASCII art with custom messages, branding, or system information.
- **User Welcome**: Personalized greetings in the ASCII art screen.
- Log messages for success, warning, failure, and informational levels.
- Customize message colors using ANSI escape sequences.
- Time-stamped log messages for better tracking.
- Built-in animated loader for visually appealing loading spinners.
- Customizable log and loader prefixes.
- ASCII art display for personalized greetings, system info, and branding.
- Simple and flexible API with multiple ways to use the `Loader` class.
- Customizable text alignment for the `Home` ASCII art display.

## ⚙️ Installation

Install LogMagix locally:
To install the package locally, clone the repository and run:

```bash
pip install .
```

Or via PyPI:
You can also install it via `pip` from PyPI:

```bash
pip install logmagix
Expand All @@ -32,151 +32,175 @@ pip install logmagix
### Importing the Package

```python
from logmagix import Logger, Loader, Home, LogLevel
from logmagix import Logger, Loader, Home
```

### Logging

Initialize the `Logger` class and log messages at different levels. You can now also set the minimum log level, batch log messages, and write them to a file:
Initialize the `Logger` class to log messages with different levels:

```python
log = Logger(log_file="app.log", prefix="myapp/logs")

# Set minimum log level to control the output (optional)
log.set_min_level(LogLevel.INFO)
log = Logger()

# Log levels
# Success message
log.success("Operation completed successfully!")

# Failure message
log.failure("Something went wrong!")

# Warning message
log.warning("This is a warning!")

# Informational message
log.info("Informational log message")

# Debug message
log.debug("Debugging log message")
log.critical("Critical error encountered", exit_code=1) # Exits after logging
log.message("Custom", "Custom message with prefix")

# Batch Logging Example
log.batch() # Start batch mode
log.success("Batch message 1")
log.info("Batch message 2")
log.flush() # Output all batched messages

# Customizable message
log.message("Dad", f"How are you? I'm gonna come soon!", start="", end="") # Start and end optional

# Question input
log.question("This is an input question!")
```

### File Logging
### Loading Animation

The `Loader` class can be used in two ways:

Save logs to a file with rotation options:
#### Using a context manager:

```python
log = Logger(
log_file="my_app.log",
max_file_size=5_000_000, # 5MB max file size
backup_count=3 # Keep 3 backup files
)
log.info("Logging to file with rotation setup!")
from time import sleep

with Loader(desc="Loading with context manager..."):
for i in range(10):
sleep(0.25)
```

### Loading Animation
#### Using `start()` and `stop()` methods:

Use the `Loader` class in two ways:
```python
loader = Loader(desc="Loading with object...", end="That was fast!", timeout=0.05).start()
for i in range(10):
sleep(0.25)
loader.stop()
```

### Custom Log and Loader Prefix

1. **Context Manager**:
Both the `Logger` and `Loader` classes allow for customizing the prefix that is shown before each message:

```python
from time import sleep
#### Logger Prefix:

```python
log = Logger(prefix=".myapp/logs")
log.success("This message has a custom log prefix!")
```

with Loader(desc="Loading data..."):
sleep(2)
```
#### Loader Prefix:

2. **Start/Stop Methods**:
```python
loader = Loader(prefix=".myapp/loader", desc="Loading with a custom loader prefix...")
loader.start()
time.sleep(5) # Simulate a task
loader.stop()
```

```python
loader = Loader(desc="Saving files...", end="Done!").start()
sleep(2)
loader.stop()
```
### ASCII Art and Greeting (New `Home` Class)

### ASCII Art and Welcome Display
The `Home` class lets you display customized ASCII art text along with system information, such as a welcome message, username, or credits.

The `Home` class allows you to display ASCII art along with user greetings and system information.
#### Using the `Home` Class:

```python
home_screen = Home(
text="LogMagix",
align="center",
adinfo1="logmagix.io",
adinfo2="v1.2",
credits="Developed by sexfrance"
adinfo1="discord.cyberious.xyz",
adinfo2="v1.0",
credits="Developed by sexfrance",
clear = False, # To clear the console, default is True
)

home_screen.display()
```

This will display the ASCII art version of "LogMagix" in the center of the terminal, along with optional `adinfo1` and `adinfo2` texts at the bottom. The terminal width is automatically detected to align the text properly.

### Full Example

Here’s an example showing logging, loader, and the `Home` ASCII art functionality:
Here’s an example showing both logging, loader, and the new `Home` class functionality:

```python
from logmagix import Logger, Loader, Home
import time
import uuid

log = Logger(log_file="app.log", prefix="myapp")
log = Logger(prefix="custom/log/prefix")
start_time = time.time()

# Logging
# Log messages
log.success("Everything is running smoothly!")
log.warning("This is just a warning!")
log.failure("A critical error occurred.")
log.debug("System debug message")
log.warning("Watch out, something might happen!")
log.failure("Critical error occurred!")
log.info("System is working properly")
log.debug(f"The system uuid is {uuid.getnode()}")
log.message("Dad", f"How are you? I'm gonna come soon!", start=start_time, end=time.time())
log.question("How old are you? ")


# Use loader with custom prefix and context manager
with Loader(prefix="custom/loader/prefix", desc="Processing data..."):
time.sleep(2) # Simulate task

# Use loader with custom prefix and start/stop methods
loader = Loader(prefix="custom/loader/prefix", desc="Saving files...", end="Done !", timeout=0.05).start()
time.sleep(2) # Simulate task
loader.stop()

# Loader with context manager
with Loader(prefix="myapp/loader", desc="Processing data..."):
time.sleep(2)

# ASCII Art Home screen
home_screen = Home(
text="LogMagix",
align="center",
adinfo1="https://logmagix.io",
adinfo2="v1.2",
adinfo1="discord.cyberious.xyz",
adinfo2="v1.0",
credits="Developed by sexfrance"
)

home_screen.display()
```

## 🛠️ Configuration Options

### Logger
log.success("Processing completed!")
```

- **Log Levels**: Control which levels to log using `LogLevel` enumeration, including `DEBUG`, `INFO`, `WARNING`, `SUCCESS`, `ERROR`, and `CRITICAL`. Set a minimum level to ignore lower-priority messages.
- **prefix**: Custom prefix before each log message.
- **log_file**: File path to log messages.
- **max_file_size**: Maximum size for log files (default is 10MB).
- **backup_count**: Number of backup log files to keep.
### Customization in `Home` Class

### Loader
- **text**: The text to be displayed in ASCII art.
- **align**: Align the ASCII art text to "left", "center", or "right" in the terminal.
- **adinfo1** and **adinfo2**: Additional information displayed below the ASCII art.
- **credits**: Optional credits or user information.

- **desc**: Description displayed alongside the loading animation.
- **end**: Text displayed after the loader stops.
- **timeout**: Delay between animation frames (in seconds).
## ❗ Requirements

### Home
LogMagix requires:

- **text**: ASCII text to display.
- **align**: Text alignment in the terminal ("left", "center", "right").
- **adinfo1 / adinfo2**: Additional info displayed below the ASCII art.
- **credits**: Custom credits or developer name.
- `colorama` for cross-platform color support in the terminal.
- `pystyle` for creating the colored text effects.

## 🖥️ Contributing
To install dependencies, run:

Contributions are welcome! To contribute:
```bash
pip install colorama pystyle
```

1. Fork the repository.
2. Make your changes.
3. Submit a pull request for review.
## ©️ License

For major changes, please open an issue first to discuss what you’d like to change.
LogMagix is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details.

## ©️ License
## 🖥️ Contributing

LogMagix is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
Contributions are welcome! Feel free to fork the repository, make changes, and submit a pull request.

## 👤 Author

Expand Down
2 changes: 1 addition & 1 deletion setup.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

setup(
name="logmagix",
version="1.10.3",
version="2.0.2",
packages=find_packages(),
install_requires=["colorama"],
author="Sexfrance",
Expand Down
73 changes: 1 addition & 72 deletions test.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,75 +32,4 @@
adinfo2="v1.0.0",
credits="Testing Framework",
clear=True
)
home.display()

# Test loader animation
with Loader(prefix="TestLoader", desc="Initializing tests...", timeout=0.1):
time.sleep(2)

# Test all log levels
logger.info("Starting test suite")
logger.debug("Debug information")
logger.warning("Warning message")
logger.success("Success message")
logger.failure("Failure message")

# Test log level filtering
logger.info("Testing log level filtering...")
logger.set_min_level(LogLevel.WARNING) # Only show WARNING and above
logger.debug("This debug message should not appear")
logger.info("This info message should not appear")
logger.warning("This warning message should appear")
logger.success("This success message should appear")
logger.failure("This error message should appear")

# Reset log level
logger.set_min_level(LogLevel.DEBUG)

# Test batch logging
logger.info("Testing batch logging...")
logger.batch()
for i in range(2):
logger.info(f"Batch message {i+1}")
logger.success(f"Batch success {i+1}")
logger.warning(f"Batch warning {i+1}")
logger.failure(f"Batch failure {i+1}")
time.sleep(0.5)
logger.flush()

# Test message format with precise timing
logger.message("FORMAT1", "Testing message format 1")
start = time.time()
time.sleep(0.456)
end = time.time()
logger.message("FORMAT2", "Testing message format 2", start=start, end=end)

# Test user input
answer = logger.question("Would you like to test critical exit? (y/n)")
if answer.lower() == 'y':
logger.critical("Critical exit test", exit_code=1)

# Test loader with different end messages
with Loader(prefix="TestLoader", desc="Processing", end="Process completed!", timeout=0.05):
time.sleep(1)

with Loader(prefix="TestLoader", desc="Analyzing", end="Analysis done!", timeout=0.15):
time.sleep(1)

# Test Home with different alignments
home = Home(
text="TEST",
align="right",
adinfo1="Right Aligned",
adinfo2="Test",
credits="Alignment Test",
clear=False
)
home.display()

# Final loader with completion message
with Loader(prefix="TestLoader", desc="Finalizing", end="Tests completed!"):
time.sleep(2)

logger.success("All tests completed successfully!")
)

0 comments on commit aab3ecd

Please sign in to comment.