ayat saadati — Complete Guide

Ayat Saadati Toolkit: Enhancing Your Development Workflow

I've been in this game long enough to appreciate a well-crafted utility library. You know, those small, often overlooked collections of functions that just make your daily grind a little smoother. That's precisely what Ayat Saadati has put together with the saadati-toolkit. It's not trying to reinvent the wheel, but rather, it's about providing a robust, opinionated set of tools that tackle common development hurdles with elegance and efficiency.

I first stumbled upon Ayat's work a while back, probably through a thoughtful post on dev.to. What always struck me was the clarity in the code and the practical approach to problem-solving. This toolkit is a testament to that philosophy. It's built for developers who, like me, are tired of rewriting the same boilerplate functions for string manipulation, data validation, or date formatting. It saves you time, reduces cognitive load, and honestly, makes your codebase a darn sight cleaner.

🚀 Introduction

The saadati-toolkit is a lightweight yet powerful Python library designed to streamline common data processing, string manipulation, and utility tasks across various development domains. It's born from the real-world challenges faced by developers, offering a set of battle-tested functions that aim to be intuitive, performant, and reliable.

Think of it as your digital Swiss Army knife for those everyday coding tasks. Instead of hunting through Stack Overflow for that perfect regex or custom date formatter, you'll likely find a well-tested function right here.

✨ Key Features

Here's what I particularly like about the saadati-toolkit:

• Robust String Manipulation: From safe slug generation to intelligent text truncation and advanced sanitization, it covers a lot of ground.
• Data Validation & Cleaning: Functions to help you ensure your data is in the right format, handle missing values, and normalize inputs.
• Date & Time Utilities: Simplified handling of common date formatting, parsing, and relative time calculations. No more wrestling with datetime objects for simple tasks!
• Input/Output Helpers: Some handy functions for common file operations or console interactions.
• Type Hinted & Tested: As any good library should be, it's fully type-hinted for better IDE integration and has a solid test suite.
• Minimal Dependencies: Keeps your project's dependency tree lean. Nobody wants a bloated requirements.txt file for a utility library, right?

🛠️ Installation

Getting the saadati-toolkit up and running is as straightforward as you'd expect from a modern Python library.

Prerequisites

• Python 3.8+

Using pip

I always recommend using a virtual environment for your Python projects. It keeps your dependencies isolated and prevents conflicts, which is just good practice.

# Create a virtual environment (if you don't have one)
python3 -m venv venv
source venv/bin/activate # On Windows use `venv\Scripts\activate`

# Now, install the toolkit
pip install saadati-toolkit

To upgrade to the latest version, just run:

pip install --upgrade saadati-toolkit

💡 Usage

The beauty of this toolkit lies in its modularity. You can import exactly what you need, keeping your namespace clean. Let's dive into some common scenarios.

String Utilities

This module is a lifesaver for web development, data processing, or anything involving user-generated text.

from saadati_toolkit.string_helpers import slugify, truncate_text, sanitize_html

# Generate a URL-friendly slug
title = "My Awesome Blog Post Title! (with some special chars)"
slug = slugify(title)
print(f"Slug: {slug}")
# Expected: "my-awesome-blog-post-title-with-some-special-chars"

# Truncate text elegantly
long_text = "This is a very long piece of text that needs to be shortened for display purposes without cutting off words mid-sentence."
short_text = truncate_text(long_text, max_length=50, suffix="...")
print(f"Short Text: {short_text}")
# Expected: "This is a very long piece of text that needs..."

# Sanitize HTML to prevent XSS (uses a conservative approach)
user_input_html = "<script>alert('xss')</script>Hello <b>World</b>!"
clean_html = sanitize_html(user_input_html)
print(f"Clean HTML: {clean_html}")
# Expected: "Hello <b>World</b>!"

Data Cleaning & Validation

When you're dealing with external data sources, validation and cleaning are paramount. These functions give you a head start.

from saadati_toolkit.data_cleaner import (
    clean_numeric_input,
    is_valid_email,
    normalize_whitespace,
)

# Clean numeric input (e.g., from form fields where users might type "1,200.50")
price_str = "$1,200.50"
cleaned_price = clean_numeric_input(price_str)
print(f"Cleaned Price: {cleaned_price}")
# Expected: 1200.5

invalid_price_str = "not_a_number"
cleaned_invalid_price = clean_numeric_input(invalid_price_str, default=0.0)
print(f"Cleaned Invalid Price: {cleaned_invalid_price}")
# Expected: 0.0

# Validate email format
email1 = "[e-mail]"
email2 = "invalid-email"
print(f"'{email1}' is valid: {is_valid_email(email1)}")
print(f"'{email2}' is valid: {is_valid_email(email2)}")
# Expected: True, False

# Normalize whitespace (remove extra spaces, trim)
messy_text = "  Hello   World!  How are you?  "
normalized_text = normalize_whitespace(messy_text)
print(f"Normalized Text: '{normalized_text}'")
# Expected: "Hello World! How are you?"

Date & Time Utilities

I've lost count of how many times I've had to write these myself. It's great to have them consolidated.

from saadati_toolkit.date_utils import format_datetime_human, time_ago, parse_date_string
from datetime import datetime, timedelta

# Format datetime for display
now = datetime.now()
formatted_date = format_datetime_human(now)
print(f"Formatted Date: {formatted_date}")
# Expected: "2023-10-27 10:30 AM" (or similar, based on current time)

# Calculate "time ago" string
yesterday = now - timedelta(days=1, hours=2)
ago_text = time_ago(yesterday)
print(f"Time Ago: {ago_text}")
# Expected: "1 day ago" (or similar)

# Parse various date string formats
date_str1 = "2023-01-15"
date_str2 = "January 15, 2023"
parsed_date1 = parse_date_string(date_str1)
parsed_date2 = parse_date_string(date_str2)
print(f"Parsed Date 1: {parsed_date1.strftime('%Y-%m-%d')}")
print(f"Parsed Date 2: {parsed_date2.strftime('%Y-%m-%d')}")
# Expected: "2023-01-15" for both

⚙️ Configuration

The saadati-toolkit is designed to be largely configuration-free. Most functions accept parameters to customize their behavior, as shown in the usage examples (e.g., max_length for truncate_text, default for clean_numeric_input). This keeps things simple and avoids the need for global configuration files, which I find can often add more complexity than they solve for utility libraries.

🤝 Contributing

Ayat is a firm believer in open source, and contributions are always welcome! If you've found a bug, have an idea for a new utility function, or want to improve existing ones, here's how you can help:

1. Fork the repository: Head over to the project's GitHub page (you'll find the link on Ayat's dev.to profile or by searching saadati-toolkit on GitHub).
2. Clone your fork: git clone https://github.com/YOUR_USERNAME/saadati-toolkit.git
3. Create a new branch: git checkout -b feature/your-awesome-feature or bugfix/issue-description
4. Make your changes: Add tests for new features or bug fixes. Ensure existing tests pass.
5. Run tests: pytest
6. Commit your changes: Write clear, concise commit messages.
7. Push to your fork: git push origin feature/your-awesome-feature
8. Open a Pull Request: Explain your changes and why they're beneficial.

Ayat is usually quite responsive, and I've seen some great discussions unfold around proposed features. It's a healthy community.

❓ FAQ

Q: What are the core dependencies of saadati-toolkit?

A: The library strives for minimal dependencies. Currently, it primarily relies on standard Python libraries. If a specific function requires an external dependency (e.g., a more advanced HTML parser for sanitize_html), it will be listed in the pyproject.toml or setup.py and installed automatically. The goal is to keep the footprint small.

Q: Is saadati-toolkit production-ready?

A: Absolutely. While it's maintained by an individual, the functions are well-tested and designed with robustness in mind. I've personally used variations of these functions in production environments for years. Always make sure to test within your specific application context, as you would with any third-party library.

Q: How can I report a bug or suggest a feature?

A: The best way is to open an issue on the project's GitHub repository. Provide as much detail as possible, including steps to reproduce the bug or a clear description of your feature request and its use case.

Q: Why isn't saadati-toolkit doing X, Y, or Z?

A: Good question! The toolkit is focused on common, reusable utilities. If you have a specific need that isn't covered, consider opening a feature request on GitHub. If it aligns with the library's philosophy of providing general-purpose, lightweight utilities, it might be added. Alternatively, you can always fork the project and extend it for your specific needs, which is the beauty of open source!

⚠️ Troubleshooting

ModuleNotFoundError: No module named 'saadati_toolkit'

This is almost always an installation issue.

• Did you activate your virtual environment? If you're using venv, make sure you've run source venv/bin/activate (or venv\Scripts\activate on Windows) before running pip install saadati-toolkit and before executing your Python script.
• Is it installed in the correct environment? If you have multiple Python installations or virtual environments, ensure you're installing into and running from the one you intend.
• Typos? Double-check the spelling: saadati_toolkit (note the underscore).

Incorrect output from a function

• Check the documentation: Each function in the toolkit is designed for a specific purpose. Read its docstring or the examples provided here to ensure you're using it as intended. Pay close attention to parameters and their expected types.
• Input data: Verify the format and type of the data you're passing to the function. For example, clean_numeric_input expects a string.
• Version mismatch: Ensure you're on the latest version of the toolkit using pip install --upgrade saadati-toolkit. A bug might have been fixed in a newer release.

Performance Concerns

While the functions are generally optimized, if you're processing extremely large datasets in a tight loop, you might hit performance bottlenecks.

• Profiling: Use Python's built-in cProfile module to pinpoint exactly where time is being spent in your application.
• Batch processing: If applicable, try to process data in batches rather than calling a function repeatedly on individual items, which can sometimes reduce overhead.
• Specific function review: If you identify a specific saadati-toolkit function as a bottleneck, consider opening an issue on GitHub with your use case. There might be opportunities for optimization or an alternative approach.

📜 License

The saadati-toolkit is released under the MIT License. This means you're free to use, modify,