Metadata-Version: 2.1
Name: true-core
Version: 0.1.1
Summary: A boilerplate utility package
Home-page: https://github.com/alaamer12/true
License: MIT
Keywords: utilities,boilerplate,core
Author: alaamer12
Author-email: ahmedmuhmmed239@gmail.com
Requires-Python: >=3.11,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Provides-Extra: dev
Provides-Extra: docs
Provides-Extra: ulid
Requires-Dist: colorama (>=0.4.6,<0.5.0)
Requires-Dist: moviepy (>=1.0.3,<1.1.0)
Requires-Dist: pillow (>=9.5.0,<9.6.0)
Requires-Dist: psutil (>=6.1.0,<6.2.0)
Requires-Dist: pydub (>=0.25.1,<0.26.0)
Requires-Dist: pytz (>=2022.7.1,<2022.8.0)
Requires-Dist: uuid-utils (>=0.9.0,<0.10.0) ; extra == "ulid"
Requires-Dist: watchdog (>=6.0.0,<6.1.0)
Project-URL: Documentation, https://true.readthedocs.io
Project-URL: Repository, https://github.com/alaamer12/true
Description-Content-Type: text/markdown

# True Core

<div >

![Python Version](https://img.shields.io/badge/python-3.7%2B-blue)
[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](https://choosealicense.com/licenses/mit/)
[![PyPI version](https://badge.fury.io/py/true-core.svg)](https://badge.fury.io/py/true-core)
[![Documentation](https://img.shields.io/badge/docs-latest-brightgreen.svg)](docs/build/html/index.html)

<p >
  <img src="https://raw.githubusercontent.com/alaamer12/true/main/docs/source/_static/logo.png" alt="True Core Logo" width="200"/>
</p>

A comprehensive utility toolkit designed for Python developers seeking clean, efficient, and maintainable solutions.

[Documentation](docs/build/html/index.html) |
[PyPI Package](https://pypi.org/project/true-core/) |
[Issue Tracker](https://github.com/alaamer12/true/issues)

</div>

---

## 🚀 Quick Start

```bash
pip install true-core
```

```python
from true.toolkits import simple_debugger
from true.collections import Directory

# Quick example
simple_debugger("Starting application...")
work_dir = Directory("./workspace")
```

## 📋 Table of Contents

- [Features](#-features)
- [Installation](#-installation)
- [Documentation](#-documentation)
- [Module Overview](#-module-overview)
- [Usage Examples](#-usage-examples)
- [Contributing](#-contributing)
- [License](#-license)

## ✨ Features

- **🛡 Robust Error Handling**

  - Comprehensive exception hierarchy
  - Custom exception classes
  - Error recovery mechanisms

- **📝 Advanced Logging**

  - Built on top of `loguru`
  - Configurable logging strategies
  - Console and file logging support

- **🔧 Developer Tools**

  - Performance profiling
  - Debugging utilities
  - Type checking helpers
  - Retry mechanisms

- **⚡ High Performance**
  - Optimized collections
  - Efficient file operations
  - Smart caching capabilities

## 📦 Installation

### Prerequisites

- Python 3.7 or higher
- pip or poetry (recommended)

```bash
# Using pip
pip install true-core

# Using poetry
poetry add true-core

# From source
git clone https://github.com/alaamer12/true.git
cd true
pip install -r requirements.txt
```

## 📚 Documentation

Comprehensive documentation is available in multiple formats:

- [Online Documentation](docs/build/html/index.html)
- [API Reference](docs/build/html/api_reference.html)
- [Module Documentation](docs/build/html/modules.html)
- [Examples](docs/build/html/examples.html)

## 🔍 Module Overview

### Core Components

```python
# File Operations
from true.collections import File, Directory
workspace = Directory("./workspace")

# Performance Monitoring
from true.toolkits import profile
@profile
def expensive_operation():
    pass
```

### Available Modules

- **collections**: File system operations and data structures
- **exceptions**: Comprehensive error handling
- **log**: Advanced logging capabilities
- **toolkits**: Developer utilities and helpers
- **types**: Type definitions and validation
- **time**: Time manipulation utilities

## 🚀 Usage Examples

### Error Handling

```python
from true.collections import File
import logging

logger = logging.getLogger(__name__)

def read_secure_file(path: str) -> str:
    try:
        file = File(path)
        return file.read_text()
    except FileNotFoundError as e:
        logger.error(f"File not found: {e}")
        return ""
```

### Performance Monitoring

```python
from true.toolkits import monitor

@monitor
def process_data(items: list):
    for item in items:
        # Processing logic here
        pass
```

## 🤝 Contributing

We welcome contributions! Here's how you can help:

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

### Development Setup

```bash
# Clone repository
git clone https://github.com/alaamer12/true.git
cd true

# Install dependencies with poetry
poetry install

# Run tests
poetry run pytest
```

## 📝 License

This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.txt) file for details.

---

<div >

Made with ❤️ by [True Core Team](https://github.com/alaamer12)

</div>

