persian-devkit 1.0.0__py3-none-any.whl

persian_devkit/utils/crypto_utils.py

@@ -0,0 +1,157 @@
+"""توابع کمکی کریپتوگرافی، هش، رمز و base64."""
+from __future__ import annotations
+
+import base64
+import hashlib
+import math
+import secrets
+import string
+from pathlib import Path
+
+HASH_ALGOS = ("md5", "sha1", "sha256", "sha512", "blake2b", "blake2s")
+
+# مجموعه‌های کاراکتری برای تولید رمز
+PASSWORD_SETS: dict[str, str] = {
+    "lower": string.ascii_lowercase,
+    "upper": string.ascii_uppercase,
+    "digits": string.digits,
+    "symbols": "!@#$%^&*()-_=+[]{};:,.<>?/",
+}
+
+# الفبای Nano ID (URL-safe)
+_NANOID_ALPHABET = string.ascii_letters + string.digits + "_-"
+
+
+#hash
+
+
+def hash_text(text: str, algo: str = "sha256") -> str:
+    """هش یک رشتهٔ متنی را برمی‌گرداند."""
+    if algo not in HASH_ALGOS:
+        raise ValueError(f"الگوریتم پشتیبانی‌نشده: {algo}")
+    h = hashlib.new(algo)
+    h.update(text.encode("utf-8"))
+    return h.hexdigest()
+
+
+def hash_file(path: Path, algo: str = "sha256", chunk: int = 1 << 20) -> str:
+    """هش یک فایل را به‌صورت chunk-by-chunk حساب می‌کند (مناسب فایل‌های بزرگ)."""
+    if algo not in HASH_ALGOS:
+        raise ValueError(f"الگوریتم پشتیبانی‌نشده: {algo}")
+    h = hashlib.new(algo)
+    with path.open("rb") as f:
+        while True:
+            block = f.read(chunk)
+            if not block:
+                break
+            h.update(block)
+    return h.hexdigest()
+
+
+#base64
+
+
+def b64_encode(text: str, url_safe: bool = False) -> str:
+    """رمزگذاری Base64 با پشتیبانی UTF-8."""
+    raw = text.encode("utf-8")
+    if url_safe:
+        return base64.urlsafe_b64encode(raw).decode("ascii")
+    return base64.b64encode(raw).decode("ascii")
+
+
+def b64_decode(text: str, url_safe: bool = False) -> str:
+    """رمزگشایی Base64 به UTF-8."""
+    cleaned = text.strip().encode("ascii")
+    try:
+        if url_safe:
+            raw = base64.urlsafe_b64decode(cleaned)
+        else:
+            raw = base64.b64decode(cleaned, validate=True)
+    except Exception as exc:
+        raise ValueError(f"Base64 نامعتبر: {exc}") from exc
+    return raw.decode("utf-8")
+
+
+#password
+
+
+def generate_password(
+    length: int = 16,
+    use_lower: bool = True,
+    use_upper: bool = True,
+    use_digits: bool = True,
+    use_symbols: bool = True,
+) -> str:
+    """تولید رمز عبور امن با مجموعه‌های کاراکتری انتخابی."""
+    pools: list[str] = []
+    if use_lower:
+        pools.append(PASSWORD_SETS["lower"])
+    if use_upper:
+        pools.append(PASSWORD_SETS["upper"])
+    if use_digits:
+        pools.append(PASSWORD_SETS["digits"])
+    if use_symbols:
+        pools.append(PASSWORD_SETS["symbols"])
+
+    if not pools:
+        raise ValueError("حداقل یک مجموعهٔ کاراکتری باید فعال باشد.")
+    if length < len(pools):
+        raise ValueError(
+            f"طول رمز باید حداقل {len(pools)} باشد تا از هر مجموعه یک کاراکتر بیاید."
+        )
+
+    # تضمین حداقل یک کاراکتر از هر مجموعه
+    chars = [secrets.choice(pool) for pool in pools]
+    all_chars = "".join(pools)
+    chars.extend(secrets.choice(all_chars) for _ in range(length - len(pools)))
+    # Fisher-Yates shuffle امن
+    for i in range(len(chars) - 1, 0, -1):
+        j = secrets.randbelow(i + 1)
+        chars[i], chars[j] = chars[j], chars[i]
+    return "".join(chars)
+
+
+def password_strength(password: str) -> dict:
+    """امتیاز قدرت رمز عبور (۰ تا ۱۰۰) و برچسب."""
+    if not password:
+        return {"score": 0, "label": "خالی", "entropy": 0.0}
+
+    pools = 0
+    if any(c.islower() for c in password):
+        pools += 26
+    if any(c.isupper() for c in password):
+        pools += 26
+    if any(c.isdigit() for c in password):
+        pools += 10
+    if any(c in PASSWORD_SETS["symbols"] for c in password):
+        pools += len(PASSWORD_SETS["symbols"])
+
+    if pools == 0:
+        entropy = 0.0
+    else:
+        entropy = len(password) * math.log2(pools)
+
+    # نگاشت آنتروپی به امتیاز ۰-۱۰۰
+    # < 28 → خیلی ضعیف، 28-35 ضعیف، 36-59 متوسط، 60-127 قوی، 128+ خیلی قوی
+    if entropy < 28:
+        score, label = 15, "خیلی ضعیف"
+    elif entropy < 36:
+        score, label = 30, "ضعیف"
+    elif entropy < 60:
+        score, label = 55, "متوسط"
+    elif entropy < 128:
+        score, label = 80, "قوی"
+    else:
+        score, label = 100, "خیلی قوی"
+
+    return {"score": score, "label": label, "entropy": round(entropy, 1)}
+
+
+#nanoid
+
+
+def nanoid(length: int = 21) -> str:
+    """تولید شناسهٔ کوتاه Nano ID با الفبای URL-safe."""
+    if length < 1:
+        raise ValueError("طول باید حداقل ۱ باشد.")
+    return "".join(secrets.choice(_NANOID_ALPHABET) for _ in range(length))

persian_devkit/utils/data_utils.py

@@ -0,0 +1,146 @@
+"""توابع کمکی مشترک برای YAML، TOML، CSV و ENV."""
+from __future__ import annotations
+
+import csv
+import io
+import json
+import sys
+from pathlib import Path
+from typing import Any, Optional
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:  # pragma: no cover
+    import tomli as tomllib
+
+import tomli_w
+import yaml
+
+
+#IO
+
+
+def read_text(path: Path) -> str:
+    """فایل متنی را با UTF-8 می‌خواند."""
+    return path.read_text(encoding="utf-8")
+
+
+def write_text(path: Path, text: str) -> None:
+    """نوشتن متن در فایل با UTF-8."""
+    path.write_text(text, encoding="utf-8")
+
+
+#YAML
+
+
+def parse_yaml(text: str) -> Any:
+    """پارس YAML به شیء پایتون."""
+    try:
+        return yaml.safe_load(text)
+    except yaml.YAMLError as exc:
+        raise ValueError(f"YAML نامعتبر: {exc}") from exc
+
+
+def dump_yaml(data: Any) -> str:
+    """تبدیل شیء پایتون به YAML."""
+    return yaml.safe_dump(
+        data, allow_unicode=True, sort_keys=False, default_flow_style=False
+    )
+
+
+#TOML
+
+
+def parse_toml(text: str) -> dict:
+    """پارس TOML به دیکشنری."""
+    try:
+        return tomllib.loads(text)
+    except tomllib.TOMLDecodeError as exc:
+        raise ValueError(f"TOML نامعتبر: {exc}") from exc
+
+
+def dump_toml(data: dict) -> str:
+    """تبدیل دیکشنری به TOML."""
+    try:
+        return tomli_w.dumps(data)
+    except (TypeError, ValueError) as exc:
+        raise ValueError(f"خطا در تولید TOML: {exc}") from exc
+
+
+#JSON
+
+
+def parse_json(text: str) -> Any:
+    """پارس JSON با پیام خطای فارسی."""
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"JSON نامعتبر: {exc}") from exc
+
+
+def dump_json(data: Any, indent: int = 2, ensure_ascii: bool = False) -> str:
+    """تبدیل شیء به JSON با پشتیبانی یونیکد."""
+    return json.dumps(data, ensure_ascii=ensure_ascii, indent=indent)
+
+
+#CSV
+
+
+def read_csv(path: Path, delimiter: str = ",") -> tuple[list[str], list[dict]]:
+    """فایل CSV را می‌خواند و (هدر، ردیف‌ها) برمی‌گرداند.
+
+    هر ردیف یک دیکشنری با کلیدهای هدر است.
+    """
+    text = read_text(path)
+    reader = csv.DictReader(io.StringIO(text), delimiter=delimiter)
+    if reader.fieldnames is None:
+        return [], []
+    headers = list(reader.fieldnames)
+    rows = [dict(r) for r in reader]
+    return headers, rows
+
+
+def write_csv(path: Path, headers: list[str], rows: list[dict], delimiter: str = ",") -> None:
+    """نوشتن ردیف‌ها در فایل CSV."""
+    buf = io.StringIO()
+    writer = csv.DictWriter(buf, fieldnames=headers, delimiter=delimiter)
+    writer.writeheader()
+    for row in rows:
+        writer.writerow(row)
+    write_text(path, buf.getvalue())
+
+
+#ENV
+
+
+def parse_env(text: str) -> dict[str, str]:
+    """پارس محتوای .env به دیکشنری.
+
+    خطوط با # به‌عنوان کامنت نادیده گرفته می‌شوند.
+    مقادیر داخل "..." یا '...' بدون کوتیشن برمی‌گردند.
+    """
+    result: dict[str, str] = {}
+    for raw_line in text.splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        key = key.strip()
+        value = value.strip()
+        if len(value) >= 2 and value[0] == value[-1] and value[0] in ("'", '"'):
+            value = value[1:-1]
+        if key:
+            result[key] = value
+    return result
+
+
+def dump_env(data: dict[str, str]) -> str:
+    """تبدیل دیکشنری به محتوای .env."""
+    lines: list[str] = []
+    for key, value in data.items():
+        if any(c in value for c in (" ", "#", "'", '"')):
+            value = f'"{value}"'
+        lines.append(f"{key}={value}")
+    return "\n".join(lines) + "\n"

persian_devkit/utils/date_utils.py

@@ -0,0 +1,58 @@
+"""توابع کمکی تبدیل و محاسبهٔ تاریخ."""
+from __future__ import annotations
+
+from datetime import date, datetime
+
+import jdatetime
+
+
+class DateParseError(ValueError):
+    """خطا در تجزیهٔ تاریخ."""
+
+
+def parse_gregorian(value: str) -> date:
+    """تاریخ میلادی را از رشتهٔ YYYY-MM-DD می‌خواند."""
+    try:
+        return datetime.strptime(value.strip(), "%Y-%m-%d").date()
+    except (ValueError, AttributeError) as exc:
+        raise DateParseError(f"تاریخ میلادی نامعتبر: {value}") from exc
+
+
+def parse_jalali(value: str) -> jdatetime.date:
+    """تاریخ شمسی را از رشتهٔ YYYY/MM/DD یا YYYY-MM-DD می‌خواند."""
+    if not isinstance(value, str):
+        raise DateParseError(f"تاریخ شمسی نامعتبر: {value}")
+    normalized = value.strip().replace("-", "/")
+    parts = normalized.split("/")
+    if len(parts) != 3:
+        raise DateParseError(f"تاریخ شمسی نامعتبر: {value}")
+    try:
+        y, m, d = (int(p) for p in parts)
+        return jdatetime.date(y, m, d)
+    except (ValueError, TypeError) as exc:
+        raise DateParseError(f"تاریخ شمسی نامعتبر: {value}") from exc
+
+
+def gregorian_to_jalali(g: date) -> jdatetime.date:
+    """تبدیل تاریخ میلادی به شمسی."""
+    return jdatetime.date.fromgregorian(date=g)
+
+
+def jalali_to_gregorian(j: jdatetime.date) -> date:
+    """تبدیل تاریخ شمسی به میلادی."""
+    return j.togregorian()
+
+
+def format_jalali(j: jdatetime.date) -> str:
+    """قالب‌بندی تاریخ شمسی به صورت YYYY/MM/DD."""
+    return f"{j.year:04d}/{j.month:02d}/{j.day:02d}"
+
+
+def format_gregorian(g: date) -> str:
+    """قالب‌بندی تاریخ میلادی به صورت YYYY-MM-DD."""
+    return g.strftime("%Y-%m-%d")
+
+
+def diff_days(a: date, b: date) -> int:
+    """اختلاف روز بین دو تاریخ (b - a)."""
+    return (b - a).days

persian_devkit/utils/fake_utils.py

@@ -0,0 +1,144 @@
+"""تولید داده‌های نمونهٔ فارسی (Lorem، نام، شهر)."""
+from __future__ import annotations
+
+import secrets
+
+# متن لورم فارسی — جملات معنادار برای پر کردن قالب‌ها
+_LOREM_SENTENCES = [
+    "در این روزگار، فناوری به سرعت در حال تغییر است.",
+    "برنامه‌نویسی هنری است که نیازمند صبر و دقت است.",
+    "هر مسئله‌ای راه‌حلی دارد، فقط باید آن را پیدا کرد.",
+    "کتاب‌ها بهترین دوستان انسان در تنهایی هستند.",
+    "زبان فارسی گنجینه‌ای از ادبیات و فرهنگ است.",
+    "کار تیمی باعث می‌شود کارهای بزرگ به ثمر بنشینند.",
+    "یادگیری مداوم کلید موفقیت در هر حرفه‌ای است.",
+    "طراحی خوب نامرئی است؛ کاربر فقط راحتی را حس می‌کند.",
+    "داده‌ها اگر درست تحلیل شوند، به دانش تبدیل می‌شوند.",
+    "خلاقیت وقتی شکوفا می‌شود که ذهن آزاد باشد.",
+    "کیفیت مهم‌تر از کمیت است در هر کاری.",
+    "احترام به دیگران، اولین قدم در ساختن جامعه‌ای بهتر است.",
+    "سادگی بالاترین درجهٔ پیچیدگی است.",
+    "آینده از آن کسانی است که امروز یاد می‌گیرند.",
+    "همکاری بین‌المللی می‌تواند بسیاری از مشکلات را حل کند.",
+]
+
+_FIRST_NAMES_MALE = [
+    "علی", "محمد", "حسن", "حسین", "رضا", "امیر", "مهدی", "سعید", "احمد", "کاوه",
+    "بهرام", "داریوش", "کوروش", "سیاوش", "آرش", "فریدون", "نوید", "پیمان", "بابک",
+    "شاهین", "کیوان", "اردشیر", "پیروز", "فرهاد", "ساسان", "یاسر", "مانی",
+]
+
+_FIRST_NAMES_FEMALE = [
+    "فاطمه", "زهرا", "مریم", "سارا", "نرگس", "الهام", "نازنین", "شیما", "پریسا", "نازلی",
+    "نیلوفر", "شیرین", "لیلا", "ملیکا", "آیدا", "بهاره", "گلنار", "رعنا", "کتایون",
+    "رودابه", "تهمینه", "فرنگیس", "یاسمن", "آزاده", "سیمین", "پروین", "مینا", "هستی",
+]
+
+_LAST_NAMES = [
+    "احمدی", "محمدی", "رضایی", "حسینی", "موسوی", "کریمی", "صادقی", "جعفری", "قاسمی",
+    "حیدری", "نجفی", "محمودی", "اکبری", "قربانی", "رحیمی", "شریفی", "نوری", "کاظمی",
+    "زمانی", "مهدوی", "مرادی", "پورمحمدی", "سلطانی", "فرهادی", "امینی", "رستمی",
+    "بهرامی", "صالحی", "طاهری", "یزدانی", "جهانگیری", "خسروی", "زندی", "سپهری",
+]
+
+_CITIES = [
+    "تهران", "مشهد", "اصفهان", "کرج", "شیراز", "تبریز", "قم", "اهواز", "کرمانشاه",
+    "ارومیه", "رشت", "زاهدان", "همدان", "کرمان", "یزد", "اردبیل", "بندرعباس",
+    "اراک", "قزوین", "زنجان", "سنندج", "گرگان", "ساری", "بوشهر", "بیرجند",
+    "خرم‌آباد", "ایلام", "سمنان", "یاسوج", "شهرکرد",
+]
+
+_DOMAINS = ["example.com", "test.ir", "demo.ir", "sample.org", "fake.net"]
+
+
+#lorem
+
+
+def random_sentence() -> str:
+    """یک جملهٔ تصادفی فارسی."""
+    return secrets.choice(_LOREM_SENTENCES)
+
+
+def random_paragraph(sentences: int = 4) -> str:
+    """پاراگراف با تعداد جملهٔ مشخص."""
+    if sentences < 1:
+        sentences = 1
+    chosen = [secrets.choice(_LOREM_SENTENCES) for _ in range(sentences)]
+    return " ".join(chosen)
+
+
+def lorem_ipsum(paragraphs: int = 1, sentences_per_paragraph: int = 4) -> str:
+    """متن لورم فارسی با تعداد پاراگراف مشخص."""
+    if paragraphs < 1:
+        paragraphs = 1
+    return "\n\n".join(
+        random_paragraph(sentences_per_paragraph) for _ in range(paragraphs)
+    )
+
+
+def random_words(count: int = 5) -> str:
+    """چند کلمهٔ تصادفی از متن لورم."""
+    all_words: list[str] = []
+    for sent in _LOREM_SENTENCES:
+        all_words.extend(sent.split())
+    if count < 1:
+        count = 1
+    return " ".join(secrets.choice(all_words) for _ in range(count))
+
+
+#name
+
+
+def random_first_name(gender: str = "any") -> str:
+    """نام کوچک تصادفی فارسی. gender: any|male|female"""
+    if gender == "male":
+        return secrets.choice(_FIRST_NAMES_MALE)
+    if gender == "female":
+        return secrets.choice(_FIRST_NAMES_FEMALE)
+    return secrets.choice(_FIRST_NAMES_MALE + _FIRST_NAMES_FEMALE)
+
+
+def random_last_name() -> str:
+    """نام خانوادگی تصادفی فارسی."""
+    return secrets.choice(_LAST_NAMES)
+
+
+def random_full_name(gender: str = "any") -> str:
+    """نام و نام خانوادگی فارسی."""
+    return f"{random_first_name(gender)} {random_last_name()}"
+
+
+def random_city() -> str:
+    """نام شهر ایرانی."""
+    return secrets.choice(_CITIES)
+
+
+def random_email(first: str | None = None, last: str | None = None) -> str:
+    """ایمیل تصادفی (بر پایهٔ نام)."""
+    if first is None:
+        first = random_first_name()
+    if last is None:
+        last = random_last_name()
+
+    # تبدیل به ASCII برای سازگاری با ایمیل
+    first_ascii = _transliterate(first)
+    last_ascii = _transliterate(last)
+    num = secrets.randbelow(1000)
+    domain = secrets.choice(_DOMAINS)
+    return f"{first_ascii}.{last_ascii}{num}@{domain}".lower()
+
+
+_TRANSLIT_MAP = {
+    "ع": "a", "ا": "a", "ب": "b", "پ": "p", "ت": "t", "ث": "s", "ج": "j",
+    "چ": "ch", "ح": "h", "خ": "kh", "د": "d", "ذ": "z", "ر": "r", "ز": "z",
+    "ژ": "zh", "س": "s", "ش": "sh", "ص": "s", "ض": "z", "ط": "t", "ظ": "z",
+    "غ": "gh", "ف": "f", "ق": "gh", "ک": "k", "ك": "k", "گ": "g", "ل": "l",
+    "م": "m", "ن": "n", "و": "v", "ه": "h", "ی": "y", "ي": "y", "ء": "",
+    "آ": "a", "أ": "a", "إ": "e", "ؤ": "o", "ئ": "y", "\u200c": "",
+    " ": "",
+}
+
+
+def _transliterate(text: str) -> str:
+    """تبدیل سادهٔ حروف فارسی به لاتین (برای ایمیل و slug)."""
+    return "".join(_TRANSLIT_MAP.get(c, c) for c in text)