pytoolkit-advance 0.1.2

A Swiss Army Knife for developers, providing modular tools for common tasks.

pytoolkit_advance

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_advance 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:

git clone <repository_url>
cd pytoolkit_advance
pip install -e .

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

python -m build

Quick Usage

from pytoolkit_advance 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.

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:

pip install -e .

b. Running Tests It's always recommended to run tests before packaging.

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):

# 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).

# 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.
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!