Metadata-Version: 2.4
Name: ahiska-log
Version: 0.1.0
Summary: Simple logging. Serious debugging. Zero-dependency Python logging and developer-output library.
License-Expression: Apache-2.0
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Logging
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# AhiskaLog

**Simple logging. Serious debugging. Zero-dependency.**

AhiskaLog is a lightweight Python logging and developer-output library built for clean terminal output, readable diagnostics, and simple file logging.

It is designed to be easy to use in everyday development while providing structured output primitives for developers working with AI, machine learning, data processing, and general Python applications.

No external runtime dependencies. Just Python's standard library.

[🇹🇷 Türkçe](readme.tr.md) | [🇬🇧 English](README.md)

---

## Features

- Zero runtime dependencies
- Simple and readable logging API
- `DEBUG`, `INFO`, `SUCCESS`, `WARNING`, `ERROR`, and `CRITICAL` levels
- Clean terminal output
- Structured output primitives
- Tables with automatic alignment
- Hierarchical tree output
- Human-readable exception diagnostics
- Full traceback support
- UTF-8 file logging
- Renderer-based output architecture
- Python standard library only
- Designed to be small, predictable, and easy to extend

---

## Installation

```bash
pip install ahiska-log
````

---

## Quick Start

```python
from ahiska.log import log

log.info("Loading dataset...")
log.success("Dataset loaded successfully")
log.warning("VRAM usage is close to the limit")
log.error("CUDA out of memory")
```

Output:

```text
INFO: Loading dataset...
SUCCESS: Dataset loaded successfully
WARNING: VRAM usage is close to the limit
ERROR: CUDA out of memory
```

---

## Log Levels

AhiskaLog provides familiar logging levels together with a success level:

```python
log.debug("Debug information")
log.info("Loading dataset...")
log.success("Training completed")
log.warning("VRAM usage is close to the limit")
log.error("CUDA out of memory")
log.critical("Training process cannot continue")
```

The output is intentionally simple and readable.

---

## Output Primitives

AhiskaLog is not limited to traditional log messages.

It also provides higher-level output primitives for displaying structured information.

### Title

```python
log.title("VRAM Estimation")
```

Output:

```text
======================
VRAM Estimation
======================
```

### Section

```python
log.section("Model Information")
```

Output:

```text
--- Model Information ---
```

### Table

Structured data can be displayed as aligned key-value output:

```python
log.table({
    "Model": "1.84 GB",
    "Gradients": "1.84 GB",
    "Optimizer": "3.68 GB",
    "Activations": "7.21 GB",
    "Buffers": "0.42 GB",
    "Total": "15.0 GB",
})
```

Output:

```text
Model:       1.84 GB
Gradients:   1.84 GB
Optimizer:   3.68 GB
Activations: 7.21 GB
Buffers:     0.42 GB
Total:       15.0 GB
```

The table renderer automatically aligns values based on the longest key.

---

## Tree

Hierarchical data can be rendered as a readable tree:

```python
log.tree({
    "Model": {
        "Architecture": "Transformer",
        "Layers": 12,
        "Hidden Size": 768,
    },
    "Parameters": {
        "Trainable": "124M",
        "Frozen": 0,
    },
})
```

Output:

```text
Model:
  Architecture: Transformer
  Layers: 12
  Hidden Size: 768
Parameters:
  Trainable: 124M
  Frozen: 0
```

Tree output is designed to remain readable without unnecessary visual complexity.

---

## Exception Diagnostics

Debugging is a core part of AhiskaLog.

Use `log.exception()` inside an exception handler:

```python
try:
    result = 10 / 0
except Exception:
    log.exception("Training failed")
```

Output:

```text
ERROR: Training failed
Exception: ZeroDivisionError Message: division by zero
Diagnostic Traceback:
File "train.py", line 10, in <module>
    result = 10 / 0
    ~~~~~~~^~~~~~~
ZeroDivisionError: division by zero
```

AhiskaLog uses Python's standard traceback information and does not invent diagnostic information that is not available from the exception context.

The goal is simple:

**Tell the developer what happened and where it happened.**

---

## File Logging

AhiskaLog can also write output to a UTF-8 log file.

```python
from ahiska.log import Logger

log = Logger(log_file="logs/app.log")

log.info("Application started")
log.success("Model loaded")
log.error("An error occurred")
```

The required directories are created automatically when necessary.

Console and file output can be used together.

---

## Renderer Architecture

AhiskaLog separates data from presentation through a renderer-based architecture.

Conceptually:

```text
Data
  ↓
Renderer
  ↓
Output
```

This allows the same structured data to be rendered in different formats without changing the underlying data.

The architecture is designed to support additional renderers such as:

* Key-value output
* Boxed tables
* JSON
* Other structured formats

The current implementation intentionally keeps the default output simple.

---

## Design Philosophy

AhiskaLog follows a few simple principles.

### Zero dependencies

AhiskaLog has no third-party runtime dependencies.

It is built entirely with Python's standard library.

### Readability first

Terminal output should be easy to scan and understand.

No unnecessary boxes, nested panels, or excessive decoration.

### Serious debugging

Errors should provide useful information instead of simply saying that something went wrong.

Tracebacks and exception information should remain accessible and readable.

### Small API

The library should be easy to learn.

Every public API should have a clear purpose.

### Extensible internals

The public API stays simple while the internal renderer architecture allows the library to grow.

---

## Project Status

AhiskaLog is currently in early development.

The current release focuses on the core logging system, structured output primitives, diagnostics, renderers, and file logging.

The API may evolve as the library is used across the AhıskaAI ecosystem.

---

## Roadmap

Planned improvements include:

* Additional output renderers
* JSON rendering
* Boxed table rendering
* Metrics output
* Progress indicators
* More advanced diagnostics
* Additional edge-case testing
* Cross-platform CI testing
* Performance improvements where useful

The roadmap is intentionally conservative.

AhiskaLog should remain small, predictable, and dependency-free.

---

## Development

Clone the repository:

```bash
git clone https://github.com/AhiskaAI/AhiskaLog.git
cd AhiskaLog
```

Run the test suite:

```bash
python -m unittest discover -s tests -v
```

AhiskaLog uses Python's standard library for its runtime implementation and test suite.

---

## Contributing

Contributions, bug reports, and ideas are welcome.

If you find a bug or have an idea for improving AhiskaLog, please open an issue or submit a pull request.

When proposing a new feature, please consider whether it keeps the library:

* Simple
* Readable
* Dependency-free
* Useful for real-world development

---

## License

AhiskaLog is licensed under the Apache License 2.0.

See the `LICENSE` file for the full license text.

---

## AhıskaAI

AhiskaLog is part of the **AhıskaAI** ecosystem.

The project is developed as a small foundational component for Python projects within the ecosystem.

**Simple logging. Serious debugging. Zero-dependency.**

