Metadata-Version: 2.4
Name: pytoolkit-advance
Version: 0.1.1
Summary: A Swiss Army Knife for developers, providing modular tools for common tasks.
Author: Senior Python Architect
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: colorama

# pytoolkit_pro

A professional, multi-utility Python package serving as a "Swiss Army Knife" for developers.

## Why is this package needed?

Modern Python development often involves repeatedly writing the same boilerplate code for common tasks like deeply merging configuration dictionaries, adding retry logic to flaky network calls, validating complex user inputs, or handling repetitive file I/O operations. `pytoolkit_pro` centralizes these universally needed, non-trivial utilities into a single, rigorously tested, and easily accessible dependency, preventing code duplication across your projects.

## Key Benefits

- **Accelerates Development**: Stop writing basic utilities from scratch and focus on your core application logic.
- **Improved Reliability**: Use thoroughly tested, production-ready functions that handle edge cases seamlessly.
- **Code Consistency**: Establish a standard approach to common problems across all your team's codebases.
- **Lightweight & Modular**: Only import what you need without bloating your project with unnecessary dependencies.

## Features

- **data_utils**: Deep merge dictionaries and flatten nested lists effortlessly.
- **decorators**: Time function execution and automatically retry functions on failure.
- **validators**: Robust regex validations for international phone numbers, complex passwords, and hex colors.
- **io_tools**: Smart file writing with automatic directory creation and simple colored console logging.

## Installation

You can install this package locally for testing in editable mode:

```bash
git clone <repository_url>
cd pytoolkit_pro
pip install -e .
```

To build distribution packages (e.g. for PyPI):

```bash
python -m build
```

## Quick Usage

```python
from pytoolkit_pro import (
    deep_merge,
    time_it,
    validate_hex_color,
    smart_write,
    colored_log
)

# Merge dictionaries
dict1 = {"a": 1, "b": {"c": 2}}
dict2 = {"b": {"d": 3}, "e": 4}
merged = deep_merge(dict1, dict2)

# Time execution
@time_it
def heavy_task():
    return sum(i * i for i in range(10000))

heavy_task()

# Validate Hex
print(validate_hex_color("#FF5733")) # True

# Smart write
smart_write("output/reports/data.txt", "Hello World!")

# Colored Logging
# Colored Logging
colored_log("This is an info message", "INFO")
colored_log("This is a warning!", "WARNING")
colored_log("This is an error!!", "ERROR")
```

---

## Developer Guide: How to Build & Publish a Python Package

This section acts as a cheat sheet for standard Python package creation and publishing.

### 1. File Structure

A standard modern Python package uses a `src/` layout (as documented in PEP 621). This prevents confusing local folders with installed packages and ensures reliable testing.

```text
my_package_name/
├── pyproject.toml              # Main configuration file (metadata, dependencies, build system)
├── README.md                   # Long description displayed on PyPI
├── src/
│   └── my_package_name/        # The actual Python module
│       ├── __init__.py         # Makes the directory a package / exports functions
│       └── ...                 # Other Python scripts
└── tests/
    └── test_my_package.py      # Pytest files
```

### 2. Configuration (`pyproject.toml`)

Modern Python packaging has moved away from `setup.py` towards `pyproject.toml`. It defines everything you need:

- **Build System**: Usually `setuptools` or `hatchling`.
- **Project Metadata**: `name`, `version`, `description`, `authors`.
- **Dependencies**: Any external libraries your package needs (e.g., `requests`, `colorama`).

*Note: Crucially, your `name` must be perfectly **unique on PyPI** to publish without Errors!*

### 3. Essential Terminal Commands

Here is the entire lifecycle of a Python package, from development to publishing:

**a. Setting up Development Mode**
Locally install the package so that you can edit the code, and the changes take effect immediately without needing to reinstall:
```bash
pip install -e .
```

**b. Running Tests**
It's always recommended to run tests before packaging. 
```bash
pip install pytest
pytest tests/
```

**c. Building the Package**
This converts your raw source code into distribution formats (a source `.tar.gz` and a built `.whl` wheel file):
```bash
# Install the build tool first
pip install build

# Remove old builds to prevent conflicts
rm -rf dist/

# Build the archives (outputs to the dist/ folder)
python -m build
```

**d. Publishing to PyPI**
To share your package with the world using `pip install your_package`, you upload it to the Python Package Index (PyPI).
```bash
# Install twine
pip install twine

# Upload everything in the dist/ folder
twine upload dist/*
```

### 4. Required Information for PyPI

When you run `twine upload`, it will ask you for credentials. Due to modern security practices, you should **never use your account password**. Instead:

1. **Create an account** on [PyPI](https://pypi.org/).
2. Enable **Two-Factor Authentication (2FA)**.
3. Go to Account Settings -> **API tokens**.
4. Click **Add API token**. Give it a descriptive name (like "Upload Token"). 
5. Important: Set the token "Scope". You can make it "Entire account" (if this is a brand new project) or scope it strictly to an existing project name.
6. When `twine` asks for a username, type `__token__`.
7. When `twine` asks for a password, paste the token string starting with `pypi-`.
**Troubleshooting common errors:**
- `400 Bad Request` or `403 Forbidden`: Make sure your package name in `pyproject.toml` is globally unique. If a name is too similar to an existing popular package, PyPI blocks it for security (anti-typosquatting). Also, ensure your token scope matches your exact project name!
