ayat saadati — Complete Guide

AyatUtils: Your Go-To Python Toolkit

Alright, let's talk about AyatUtils. If you've ever found yourself writing the same helper functions over and over again across different projects, you know the pain. That's exactly where AyatUtils comes in. This isn't just another random collection of Python scripts; it's a curated, opinionated toolkit born from countless hours spent in the trenches of real-world development.

I've always believed that good code isn't just about solving the immediate problem, but about making the next problem easier to tackle. AyatUtils embodies that philosophy by providing battle-tested utilities for common tasks, letting you focus on the unique challenges of your application rather than reinventing the wheel for data transformation, text processing, or configuration management.

What is AyatUtils?

AyatUtils is a lightweight, yet powerful, Python library designed to streamline common development tasks. It's not trying to be a full-fledged framework; think of it more as your trusty Swiss Army knife for those everyday coding challenges. Whether you're wrangling data, cleaning strings, or parsing configuration files, AyatUtils probably has a function that will save you a few lines of code and a lot of headaches.

I started building this collection because I kept noticing patterns in my own projects. "Why am I writing snake_case_to_camel_case again?" I'd ask myself. Eventually, it just made sense to consolidate these helpers into a single, well-documented, and easily installable package.

Key Features

Data Transformation: Functions for flattening dictionaries, deep merging, and general data manipulation.
Text Processing: Utilities for common string operations like case conversion, sanitization, and basic parsing.
Configuration Management: Simple, robust functions for reading and validating configuration from various sources (JSON, YAML, INI).
Web Helpers: Basic utilities for common HTTP requests and URL manipulation (nothing fancy, just the essentials).
Developer-Friendly: Designed with developer experience in mind – clear function names, sensible defaults, and comprehensive documentation.

Installation

Getting AyatUtils up and running is as straightforward as it gets. We're talking standard pip installation here.

pip install ayatutils

If you're working in a virtual environment (which, let's be honest, you should be), make sure you've activated it first:

python -m venv venv
source venv/bin/activate  # On Windows, use `venv\Scripts\activate`
pip install ayatutils

To upgrade to the latest version, just add the --upgrade flag:

pip install --upgrade ayatutils

Usage

Let's dive into some practical examples to show you how AyatUtils can make your life a bit easier.

Data Manipulation

One of my personal favorites is flatten_dict. I can't tell you how many times I've had to deal with nested JSON structures that just needed to be flattened for easier processing or database insertion.

from ayatutils.data import flatten_dict, deep_merge

# Example 1: Flattening a nested dictionary
nested_data = {
    "user": {
        "id": 123,
        "profile": {
            "name": "John Doe",
            "email": "john.doe@example.com"
        },
        "settings": {
            "notifications": True
        }
    },
    "timestamp": "2023-10-27T10:00:00Z"
}

flattened = flatten_dict(nested_data)
print("Flattened Dictionary:")
print(flattened)
# Expected output:
# {
#     'user.id': 123,
#     'user.profile.name': 'John Doe',
#     'user.profile.email': 'john.doe@example.com',
#     'user.settings.notifications': True,
#     'timestamp': '2023-10-27T10:00:00Z'
# }

# Example 2: Deep merging dictionaries
base_config = {
    "database": {
        "host": "localhost",
        "port": 5432,
        "user": "admin"
    },
    "logging": {
        "level": "INFO"
    }
}

override_config = {
    "database": {
        "port": 5433,
        "password": "securepassword"
    },
    "logging": {
        "format": "%(levelname)s: %(message)s"
    },
    "app": {
        "name": "MyCoolApp"
    }
}

merged_config = deep_merge(base_config, override_config)
print("\nMerged Configuration:")
print(merged_config)
# Expected output:
# {
#     'database': {
#         'host': 'localhost',
#         'port': 5433,
#         'user': 'admin',
#         'password': 'securepassword'
#     },
#     'logging': {
#         'level': 'INFO',
#         'format': '%(levelname)s: %(message)s'
#     },
#     'app': {
#         'name': 'MyCoolApp'
#     }
# }

Text Processing

Handling string cases correctly is a subtle art that can make or break API consistency. AyatUtils has you covered.

from ayatutils.text import snake_to_camel, camel_to_snake, slugify

# Example 1: Case conversion
snake_str = "this_is_a_snake_case_string"
camel_str = snake_to_camel(snake_str)
print(f"Snake to Camel: '{snake_str}' -> '{camel_str}'")
# Expected: 'thisIsASnakeCaseString'

camel_str_2 = "ThisIsAnotherCamelCaseString"
snake_str_2 = camel_to_snake(camel_str_2)
print(f"Camel to Snake: '{camel_str_2}' -> '{snake_str_2}'")
# Expected: 'this_is_another_camel_case_string'

# Example 2: Slugify for URLs or filenames
title = "My Awesome Blog Post Title! (with special chars)"
slug = slugify(title)
print(f"Slugify: '{title}' -> '{slug}'")
# Expected: 'my-awesome-blog-post-title-with-special-chars'

Configuration Management

Reading configuration should be simple, but robust enough to handle different formats and validation.

import os
import json
from ayatutils.config import read_config

# Let's create a dummy config file for demonstration
config_content = {
    "app": {
        "name": "AyatApp",
        "version": "1.0.0"
    },
    "database": {
        "type": "postgres",
        "host": "db.example.com"
    }
}

config_file_path = "app_config.json"
with open(config_file_path, "w") as f:
    json.dump(config_content, f, indent=4)

# Read the configuration
try:
    config = read_config(config_file_path)
    print("\nRead Configuration:")
    print(json.dumps(config, indent=2))

    # Accessing values
    print(f"App Name: {config['app']['name']}")
    print(f"DB Host: {config['database']['host']}")

except FileNotFoundError:
    print(f"Error: Config file '{config_file_path}' not found.")
except Exception as e:
    print(f"An error occurred: {e}")
finally:
    # Clean up the dummy file
    if os.path.exists(config_file_path):
        os.remove(config_file_path)

API Reference (Selected)

This table highlights some of the most commonly used functions. For a full API reference, I'd recommend checking the source code or the more detailed Sphinx documentation (once that's properly set up!).

Module	Function Name	Description	Parameters	Returns
`ayatutils.data`	`flatten_dict`	Flattens a nested dictionary, using a specified separator for keys.	`data` (dict), `separator` (str, default `.`)	`dict` (flattened dictionary)
`ayatutils.data`	`deep_merge`	Recursively merges two dictionaries. Keys in `source` override `target`.	`target` (dict), `source` (dict)	`dict` (merged dictionary)
`ayatutils.text`	`snake_to_camel`	Converts a snake_case string to camelCase.	`snake_str` (str)	`str` (camelCase string)
`ayatutils.text`	`camel_to_snake`	Converts a camelCase string to snake_case.	`camel_str` (str)	`str` (snake_case string)
`ayatutils.text`	`slugify`	Converts a string into a URL-friendly slug.	`text` (str), `separator` (str, default `-`)	`str` (slugified string)
`ayatutils.config`	`read_config`	Reads configuration from a file (JSON, YAML, INI supported).	`filepath` (str), `format` (str, optional)	`dict` (configuration data)
`ayatutils.web`	`simple_http_get`	Performs a basic HTTP GET request.	`url` (str), `params` (dict, optional), `headers` (dict, optional)	`requests.Response` object

Code Examples

Let's put a few of these together in a more integrated example. Imagine you're building a script to fetch some data from an API, process it, and then save it in a cleaned format.

import json
from ayatutils.web import simple_http_get
from ayatutils.data import flatten_dict
from ayatutils.text import slugify
from ayatutils.config import read_config

# --- 1. Load Configuration ---
# Let's assume you have a config.json file like this:
# {
#   "api": {
#     "base_url": "https://jsonplaceholder.typicode.com",
#     "endpoint": "/posts"
#   },
#   "output": {
#     "filename_prefix": "processed_data",
#     "format": "json"
#   }
# }

# Create a dummy config file for this example
dummy_config_path = "temp_config.json"
with open(dummy_config_path, "w") as f:
    json.dump({
        "api": {
            "base_url": "https://jsonplaceholder.typicode.com",
            "endpoint": "/posts"
        },
        "output": {
            "filename_prefix": "processed_data",
            "format": "json"
        }
    }, f, indent=2)

print("--- Loading Configuration ---")
config = read_config(dummy_config_path)
api_config = config.get("api", {})
output_config = config.get("output", {})

base_url = api_config.get("base_url")
endpoint = api_config.get("endpoint")
output_prefix = output_config.get("filename_prefix")

if not all([base_url, endpoint, output_prefix]):
    print("Error: Missing API or output configuration.")
    exit(1)

full_api_url = f"{base_url}{endpoint}"
print(f"API URL: {full_api_url}")

# --- 2. Fetch Data from API ---
print("\n--- Fetching Data ---")
try:
    response = simple_http_get(full_api_url, params={"_limit": 5}) # Get first 5 posts
    response.raise_for_status() # Raise an exception for HTTP errors
    raw_data = response.json()
    print(f"Fetched {len(raw_data)} items.")
except Exception as e:
    print(f"Failed to fetch data: {e}")
    exit(1)

# --- 3. Process and Clean Data ---
print("\n--- Processing Data ---")
processed_data = []
for item in raw_data:
    # Flatten the item if it's nested (jsonplaceholder posts are fairly flat,
    # but this demonstrates the utility)
    flattened_item = flatten_dict(item)

    # Convert title to a slug for potential use as an identifier or filename part
    if 'title' in flattened_item:
        flattened_item['title_slug'] = slugify(flattened_item['title'])

    # Example: remove 'userId' as it might not be needed in the final output
    flattened_item.pop('userId', None)
    processed_data.append(flattened_item)

print(f"Processed {len(processed_data)} items.")
# print(json.dumps(processed_data[0], indent=2)) # Uncomment to see an example processed item

# --- 4. Save Processed Data ---
print("\n--- Saving Data ---")
output_filename = f"{output_prefix}_{slugify('posts')}.json" # Using slugify for filename
try:
    with open(output_filename, "w") as f:
        json.dump(processed_data, f, indent=2)
    print(f"Data successfully saved to '{output_filename}'")
except Exception as e:
    print(f"Failed to save data: {e}")

# Clean up dummy config file
import os
if os.path.exists(dummy_config_path):
    os.remove(dummy_config_path)

This example shows how AyatUtils functions from different modules can be composed to perform a common data pipeline task. It's all about making those individual steps reliable and easy to implement.

FAQ

Q: Why another utility library? Aren't there enough already?

A: You're absolutely right, the Python ecosystem is rich with libraries. My motivation for AyatUtils wasn't to replace giants like requests or pandas. Instead, it's about providing a focused

推荐订阅源

DEV Community