# LogMagix
Beautiful & Simple Python Logger
## 🚀 Quick Start
```python
from logmagix import Logger, LogLevel
# Choose your logging style (1 = ColorLogger, 2 = SimpleLogger)
log = Logger(
style=1, # Default colorful style
prefix="MyApp",
github_repository="https://github.com/sexfrance/logmagix",
level=LogLevel.DEBUG,
log_file="logs/app.log" # Optional log file
)
# Basic logging
log.info("Hello World!")
log.success("Operation completed!")
log.warning("Something might be wrong")
log.error("An error occurred")
log.critical("Fatal error", exit_code=1)
```
## 🔥 Features
- Log messages for various levels: success, warning, failure, debug, critical, info, and more.
- Color customization using ANSI escape sequences.
- Time-stamped log messages for better tracking.
- Built-in animated loader for visually appealing loading spinners.
- Log saving to file with optional log file paths.
- 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
To install the package locally, clone the repository and run:
```bash
pip install .
```
You can also install it via `pip` from PyPI:
```bash
pip install logmagix
```
## 🔧 Usage
### Importing the Package
```python
from logmagix import Logger, Loader, Home
```
### Logging
Initialize the `Logger` class to log messages with different levels:
```python
log = Logger()
# 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")
# Critical message (also terminates the program with optional exit code)
log.critical("Critical failure encountered", exit_code=1)
```
### Log Levels
LogMagix provides several logging levels to help categorize the severity and type of log messages. You can configure the minimum log level to display based on your requirements:
- `DEBUG`: For detailed debug messages.
- `INFO`: For informational messages.
- `WARNING`: For warning messages.
- `SUCCESS`: For successful operations.
- `FAILURE`: For non-critical errors.
- `CRITICAL`: For critical errors; may terminate the program.
You can set the minimum logging level on initialization by passing a `LogLevel` value to the `Logger` constructor. For example:
```python
from logmagix import Logger, LogLevel
log = Logger(level=LogLevel.WARNING)
```
With this setting, only `WARNING`, `SUCCESS`, `FAILURE`, and `CRITICAL` messages will display.
## 🎨 Logging Styles
LogMagix offers two distinct logging styles:
### Style 1: ColorLogger (Default)
```python
log = Logger(style=1) # or just Logger()
```
Features colorful, detailed output with customizable prefixes and ANSI color formatting.
### Style 2: SimpleLogger
```python
log = Logger(style=2)
```
Provides a minimalist, clean output format with basic color coding.
### Style Comparison
```python
# Style 1 (ColorLogger)
log1 = Logger(prefix="ColorLogger")
log1.success("Operation successful!")
# Output: [ColorLogger] [12:34:56] [Success] -> Operation successful!
# Style 2 (SimpleLogger)
log2 = Logger(style=2, prefix="SimpleLogger")
log2.success("Operation successful!")
# Output: 12:34:56 » SUCCESS ➔ Operation successful!
```
### Log File Saving
You can specify a log file path to save logs to a file for further review or debugging. The logger will automatically strip ANSI color codes from messages saved to the log file for readability. Log files are appended with each new logging session.
```python
log = Logger(log_file="logs/app.log")
log.success("This message will also be saved to app.log")
```
To view logs saved to the file, open the specified path and review the recorded entries, which include timestamped log messages for tracking system state over time.
## 🔄 Loading Animation
The Loader class now supports custom prefixes and can be used in two ways:
```python
from logmagix import Loader
import time
# Method 1: Context Manager
with Loader(
prefix="MyApp",
desc="Processing...",
end="Completed!",
timeout=0.1
):
time.sleep(2) # Your task here
# Method 2: Manual Control
loader = Loader(
prefix="MyApp",
desc="Loading...",
end="Done!",
timeout=0.05
).start()
time.sleep(2) # Your task here
loader.stop()
```
## Custom Log and Loader Prefix
Both the `Logger` and `Loader` classes allow for customizing the prefix shown before each message:
#### Logger Prefix:
```python
log = Logger(prefix=".myapp/logs")
log.success("This message has a custom log prefix!")
```
#### Loader Prefix:
```python
loader = Loader(prefix=".myapp/loader", desc="Loading with a custom loader prefix...")
loader.start()
time.sleep(5) # Simulate a task
loader.stop()
```
### ASCII Art and Greeting (New `Home` Class)
The `Home` class lets you display customized ASCII art text along with system information, such as a welcome message, username, or credits.
#### Using the `Home` Class:
```python
home_screen = Home(
text="LogMagix",
align="center",
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 both logging, loader, and the new `Home` class functionality:
```python
from logmagix import Logger, Home, Loader, LogLevel
import time
import uuid
# Test ColorLogger (Style 1 - Default)
log1 = Logger(
prefix="ColorLogger",
github_repository="https://github.com/sexfrance/LogMagix",
level=LogLevel.DEBUG,
log_file="logs/color.log"
)
start_time = time.time()
log1.success("We are running style 1!")
log1.warning("Watch out, something might happen!")
log1.failure("Critical error occurred!")
log1.info("System is working properly")
log1.debug(f"The system uuid is {uuid.getnode()}")
log1.message("Dad", f"How are you? I'm gonna come soon!", start=start_time, end=time.time())
log1.question("How old are you? ")
# Test SimpleLogger (Style 2)
log2 = Logger(
style=2,
prefix="SimpleLogger",
level=LogLevel.INFO,
log_file="logs/simple.log"
)
start_time = time.time()
log2.success("We are running style 2 !")
log2.info("System is working properly")
log2.error("Critical error occurred!")
log2.warning("Watch out, something might happen!")
log2.message("System is working properly")
log2.debug(f"The system uuid is {uuid.getnode()}")
log2.question("How old are you? ")
# Test loader with custom prefix and context manager
print("\nTesting Loader:")
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()
# Display home screen
home_screen = Home(
text="LogMagix",
align="center",
adinfo1="Test Suite",
adinfo2="v1.0.0",
credits="Testing Framework",
clear=True
)
home_screen.display()
# Test critical error (commented out as it exits the program)
log1.critical("Critical error occurred!")
```
### Customization in `Home` Class
- **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.
### 📹 Preview
## ❗ Requirements
LogMagix requires:
- `colorama` for cross-platform color support in the terminal.
- `pystyle` for creating the colored text effects.
To install dependencies, run:
```bash
pip install colorama pystyle
```
## ©️ License
LogMagix is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details.
## 🖥️ Contributing
Contributions are welcome! Feel free to fork the repository, make changes, and submit a pull request.
## 👤 Author
LogMagix is developed and maintained by **sexfrance**.
<p align="center">
<img src="https://img.shields.io/github/license/sexfrance/LogMagix.svg?style=for-the-badge&labelColor=black&color=f429ff&logo=IOTA"/>
<img src="https://img.shields.io/github/stars/sexfrance/LogMagix.svg?style=for-the-badge&labelColor=black&color=f429ff&logo=IOTA"/>
<img src="https://img.shields.io/github/languages/top/sexfrance/LogMagix.svg?style=for-the-badge&labelColor=black&color=f429ff&logo=python"/>
<img alt="PyPI - Downloads" src="https://img.shields.io/pypi/dm/logmagix?style=for-the-badge&labelColor=black&color=f429ff&logo=IOTA">
</p>
Raw data
{
"_id": null,
"home_page": "https://github.com/sexfrance/LogMagix",
"name": "logmagix",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": null,
"author": "Sexfrance",
"author_email": "bwuuuuu@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/97/be/8e8c3669763abbd85d84676d077c7652fcbe8396e22e355a7fc32384b01d/logmagix-2.1.2.7.tar.gz",
"platform": null,
"description": "# LogMagix\n\nBeautiful & Simple Python Logger\n\n## \ud83d\ude80 Quick Start\n\n```python\nfrom logmagix import Logger, LogLevel\n\n# Choose your logging style (1 = ColorLogger, 2 = SimpleLogger)\nlog = Logger(\n style=1, # Default colorful style\n prefix=\"MyApp\",\n github_repository=\"https://github.com/sexfrance/logmagix\",\n level=LogLevel.DEBUG,\n log_file=\"logs/app.log\" # Optional log file\n)\n\n# Basic logging\nlog.info(\"Hello World!\")\nlog.success(\"Operation completed!\")\nlog.warning(\"Something might be wrong\")\nlog.error(\"An error occurred\")\nlog.critical(\"Fatal error\", exit_code=1)\n```\n\n## \ud83d\udd25 Features\n\n- Log messages for various levels: success, warning, failure, debug, critical, info, and more.\n- Color customization using ANSI escape sequences.\n- Time-stamped log messages for better tracking.\n- Built-in animated loader for visually appealing loading spinners.\n- Log saving to file with optional log file paths.\n- Customizable log and loader prefixes.\n- ASCII art display for personalized greetings, system info, and branding.\n- Simple and flexible API with multiple ways to use the `Loader` class.\n- Customizable text alignment for the `Home` ASCII art display.\n\n## \u2699\ufe0f Installation\n\nTo install the package locally, clone the repository and run:\n\n```bash\npip install .\n```\n\nYou can also install it via `pip` from PyPI:\n\n```bash\npip install logmagix\n```\n\n## \ud83d\udd27 Usage\n\n### Importing the Package\n\n```python\nfrom logmagix import Logger, Loader, Home\n```\n\n### Logging\n\nInitialize the `Logger` class to log messages with different levels:\n\n```python\nlog = Logger()\n\n# Success message\nlog.success(\"Operation completed successfully!\")\n\n# Failure message\nlog.failure(\"Something went wrong!\")\n\n# Warning message\nlog.warning(\"This is a warning!\")\n\n# Informational message\nlog.info(\"Informational log message\")\n\n# Debug message\nlog.debug(\"Debugging log message\")\n\n# Critical message (also terminates the program with optional exit code)\nlog.critical(\"Critical failure encountered\", exit_code=1)\n```\n\n### Log Levels\n\nLogMagix provides several logging levels to help categorize the severity and type of log messages. You can configure the minimum log level to display based on your requirements:\n\n- `DEBUG`: For detailed debug messages.\n- `INFO`: For informational messages.\n- `WARNING`: For warning messages.\n- `SUCCESS`: For successful operations.\n- `FAILURE`: For non-critical errors.\n- `CRITICAL`: For critical errors; may terminate the program.\n\nYou can set the minimum logging level on initialization by passing a `LogLevel` value to the `Logger` constructor. For example:\n\n```python\nfrom logmagix import Logger, LogLevel\n\nlog = Logger(level=LogLevel.WARNING)\n```\n\nWith this setting, only `WARNING`, `SUCCESS`, `FAILURE`, and `CRITICAL` messages will display.\n\n## \ud83c\udfa8 Logging Styles\n\nLogMagix offers two distinct logging styles:\n\n### Style 1: ColorLogger (Default)\n\n```python\nlog = Logger(style=1) # or just Logger()\n```\n\nFeatures colorful, detailed output with customizable prefixes and ANSI color formatting.\n\n### Style 2: SimpleLogger\n\n```python\nlog = Logger(style=2)\n```\n\nProvides a minimalist, clean output format with basic color coding.\n\n### Style Comparison\n\n```python\n# Style 1 (ColorLogger)\nlog1 = Logger(prefix=\"ColorLogger\")\nlog1.success(\"Operation successful!\")\n# Output: [ColorLogger] [12:34:56] [Success] -> Operation successful!\n\n# Style 2 (SimpleLogger)\nlog2 = Logger(style=2, prefix=\"SimpleLogger\")\nlog2.success(\"Operation successful!\")\n# Output: 12:34:56 \u00bb SUCCESS \u2794 Operation successful!\n```\n\n### Log File Saving\n\nYou can specify a log file path to save logs to a file for further review or debugging. The logger will automatically strip ANSI color codes from messages saved to the log file for readability. Log files are appended with each new logging session.\n\n```python\nlog = Logger(log_file=\"logs/app.log\")\nlog.success(\"This message will also be saved to app.log\")\n```\n\nTo view logs saved to the file, open the specified path and review the recorded entries, which include timestamped log messages for tracking system state over time.\n\n## \ud83d\udd04 Loading Animation\n\nThe Loader class now supports custom prefixes and can be used in two ways:\n\n```python\nfrom logmagix import Loader\nimport time\n\n# Method 1: Context Manager\nwith Loader(\n prefix=\"MyApp\",\n desc=\"Processing...\",\n end=\"Completed!\",\n timeout=0.1\n):\n time.sleep(2) # Your task here\n\n# Method 2: Manual Control\nloader = Loader(\n prefix=\"MyApp\",\n desc=\"Loading...\",\n end=\"Done!\",\n timeout=0.05\n).start()\ntime.sleep(2) # Your task here\nloader.stop()\n```\n\n## Custom Log and Loader Prefix\n\nBoth the `Logger` and `Loader` classes allow for customizing the prefix shown before each message:\n\n#### Logger Prefix:\n\n```python\nlog = Logger(prefix=\".myapp/logs\")\nlog.success(\"This message has a custom log prefix!\")\n```\n\n#### Loader Prefix:\n\n```python\nloader = Loader(prefix=\".myapp/loader\", desc=\"Loading with a custom loader prefix...\")\nloader.start()\ntime.sleep(5) # Simulate a task\nloader.stop()\n```\n\n### ASCII Art and Greeting (New `Home` Class)\n\nThe `Home` class lets you display customized ASCII art text along with system information, such as a welcome message, username, or credits.\n\n#### Using the `Home` Class:\n\n```python\nhome_screen = Home(\n text=\"LogMagix\",\n align=\"center\",\n adinfo1=\"discord.cyberious.xyz\",\n adinfo2=\"v1.0\",\n credits=\"Developed by sexfrance\",\n clear = False, # To clear the console, default is True\n)\n\nhome_screen.display()\n```\n\nThis 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.\n\n### Full Example\n\nHere\u2019s an example showing both logging, loader, and the new `Home` class functionality:\n\n```python\nfrom logmagix import Logger, Home, Loader, LogLevel\nimport time\nimport uuid\n\n# Test ColorLogger (Style 1 - Default)\nlog1 = Logger(\n prefix=\"ColorLogger\",\n github_repository=\"https://github.com/sexfrance/LogMagix\",\n level=LogLevel.DEBUG,\n log_file=\"logs/color.log\"\n)\n\nstart_time = time.time()\nlog1.success(\"We are running style 1!\")\nlog1.warning(\"Watch out, something might happen!\")\nlog1.failure(\"Critical error occurred!\")\nlog1.info(\"System is working properly\")\nlog1.debug(f\"The system uuid is {uuid.getnode()}\")\nlog1.message(\"Dad\", f\"How are you? I'm gonna come soon!\", start=start_time, end=time.time())\nlog1.question(\"How old are you? \")\n\n# Test SimpleLogger (Style 2)\nlog2 = Logger(\n style=2,\n prefix=\"SimpleLogger\",\n level=LogLevel.INFO,\n log_file=\"logs/simple.log\"\n)\n\nstart_time = time.time()\nlog2.success(\"We are running style 2 !\")\nlog2.info(\"System is working properly\")\nlog2.error(\"Critical error occurred!\")\nlog2.warning(\"Watch out, something might happen!\")\nlog2.message(\"System is working properly\")\nlog2.debug(f\"The system uuid is {uuid.getnode()}\")\nlog2.question(\"How old are you? \")\n\n# Test loader with custom prefix and context manager\nprint(\"\\nTesting Loader:\")\nwith Loader(prefix=\"custom/loader/prefix\", desc=\"Processing data...\"):\n time.sleep(2) # Simulate task\n\n# Use loader with custom prefix and start/stop methods\nloader = Loader(prefix=\"custom/loader/prefix\", desc=\"Saving files...\", end=\"Done !\", timeout=0.05).start()\ntime.sleep(2) # Simulate task\nloader.stop()\n\n\n# Display home screen\nhome_screen = Home(\n text=\"LogMagix\",\n align=\"center\",\n adinfo1=\"Test Suite\",\n adinfo2=\"v1.0.0\",\n credits=\"Testing Framework\",\n clear=True\n)\nhome_screen.display()\n\n# Test critical error (commented out as it exits the program)\nlog1.critical(\"Critical error occurred!\")\n```\n\n### Customization in `Home` Class\n\n- **text**: The text to be displayed in ASCII art.\n- **align**: Align the ASCII art text to \"left\", \"center\", or \"right\" in the terminal.\n- **adinfo1** and **adinfo2**: Additional information displayed below the ASCII art.\n- **credits**: Optional credits or user information.\n\n### \ud83d\udcf9 Preview\n\n\n\n## \u2757 Requirements\n\nLogMagix requires:\n\n- `colorama` for cross-platform color support in the terminal.\n- `pystyle` for creating the colored text effects.\n\nTo install dependencies, run:\n\n```bash\npip install colorama pystyle\n```\n\n## \u00a9\ufe0f License\n\nLogMagix is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details.\n\n## \ud83d\udda5\ufe0f Contributing\n\nContributions are welcome! Feel free to fork the repository, make changes, and submit a pull request.\n\n## \ud83d\udc64 Author\n\nLogMagix is developed and maintained by **sexfrance**.\n\n<p align=\"center\">\n <img src=\"https://img.shields.io/github/license/sexfrance/LogMagix.svg?style=for-the-badge&labelColor=black&color=f429ff&logo=IOTA\"/>\n <img src=\"https://img.shields.io/github/stars/sexfrance/LogMagix.svg?style=for-the-badge&labelColor=black&color=f429ff&logo=IOTA\"/>\n <img src=\"https://img.shields.io/github/languages/top/sexfrance/LogMagix.svg?style=for-the-badge&labelColor=black&color=f429ff&logo=python\"/>\n <img alt=\"PyPI - Downloads\" src=\"https://img.shields.io/pypi/dm/logmagix?style=for-the-badge&labelColor=black&color=f429ff&logo=IOTA\">\n\n</p>\n",
"bugtrack_url": null,
"license": null,
"summary": "A custom logger package",
"version": "2.1.2.7",
"project_urls": {
"Homepage": "https://github.com/sexfrance/LogMagix"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "950a21806d16466eeee3d8a0f2fe52872a7ca6ebbb5396278acffc04c5e55cc0",
"md5": "825362e32938438416b8b21bbb69d4e6",
"sha256": "373e714bae999be5140d682112b0afa62c0a411e4130528fad72fb384e1efe1e"
},
"downloads": -1,
"filename": "logmagix-2.1.2.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "825362e32938438416b8b21bbb69d4e6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 11904,
"upload_time": "2025-02-22T22:45:48",
"upload_time_iso_8601": "2025-02-22T22:45:48.925644Z",
"url": "https://files.pythonhosted.org/packages/95/0a/21806d16466eeee3d8a0f2fe52872a7ca6ebbb5396278acffc04c5e55cc0/logmagix-2.1.2.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "97be8e8c3669763abbd85d84676d077c7652fcbe8396e22e355a7fc32384b01d",
"md5": "1d3a1991f564d7e6185b9d1a05082694",
"sha256": "87f1e14a4aba212aec8b82ce85dc748da337102060204ba48415b01333454fbc"
},
"downloads": -1,
"filename": "logmagix-2.1.2.7.tar.gz",
"has_sig": false,
"md5_digest": "1d3a1991f564d7e6185b9d1a05082694",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 14402,
"upload_time": "2025-02-22T22:45:50",
"upload_time_iso_8601": "2025-02-22T22:45:50.574443Z",
"url": "https://files.pythonhosted.org/packages/97/be/8e8c3669763abbd85d84676d077c7652fcbe8396e22e355a7fc32384b01d/logmagix-2.1.2.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-22 22:45:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sexfrance",
"github_project": "LogMagix",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "colorama",
"specs": [
[
"==",
"0.4.6"
]
]
},
{
"name": "pystyle",
"specs": [
[
"==",
"2.9"
]
]
},
{
"name": "setuptools",
"specs": [
[
"==",
"70.0.0"
]
]
}
],
"lcname": "logmagix"
}
JSON
