persian-devkit 1.0.0__py3-none-any.whl

persian_devkit/commands/time_cmd.py

@@ -0,0 +1,96 @@
+"""دستور pdev time — کار با timestamp و مدت زمان."""
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from persian_devkit.utils.time_utils import (
+    from_unix,
+    humanize_duration,
+    now_unix,
+    parse_duration,
+    to_unix,
+)
+
+app = typer.Typer(help="کار با timestamp و مدت زمان.", no_args_is_help=True)
+console = Console()
+
+
+@app.command("now")
+def now_cmd(
+    ms: bool = typer.Option(False, "--ms", help="خروجی به میلی‌ثانیه."),
+) -> None:
+    """نمایش timestamp فعلی."""
+    ts = now_unix()
+    console.print(ts * 1000 if ms else ts)
+
+
+@app.command("to-unix")
+def to_unix_cmd(
+    value: str = typer.Argument(
+        ..., help="تاریخ به شکل YYYY-MM-DD یا YYYY-MM-DD HH:MM:SS."
+    ),
+) -> None:
+    """تبدیل تاریخ میلادی به timestamp."""
+    for fmt in ("%Y-%m-%d %H:%M:%S", "%Y-%m-%d"):
+        try:
+            dt = datetime.strptime(value.strip(), fmt)
+            console.print(to_unix(dt))
+            return
+        except ValueError:
+            continue
+    console.print(f"[red]✗ خطا:[/red] فرمت تاریخ نامعتبر: {value}")
+    raise typer.Exit(1)
+
+
+@app.command("from-unix")
+def from_unix_cmd(
+    ts: int = typer.Argument(..., help="timestamp (ثانیه)."),
+    local: bool = typer.Option(False, "--local", help="نمایش در زمان محلی."),
+) -> None:
+    """تبدیل timestamp به تاریخ میلادی."""
+    dt = from_unix(ts)
+    if local:
+        dt = dt.astimezone()
+        console.print(dt.strftime("%Y-%m-%d %H:%M:%S %Z"))
+    else:
+        console.print(dt.strftime("%Y-%m-%d %H:%M:%S UTC"))
+
+
+@app.command("duration")
+def duration_cmd(
+    value: str = typer.Argument(
+        ..., help="مدت زمان (مثل '2h30m' یا '2 ساعت و 30 دقیقه')."
+    ),
+) -> None:
+    """تبدیل رشتهٔ مدت زمان به ثانیه و معادل خوانا."""
+    try:
+        seconds = parse_duration(value)
+    except ValueError as e:
+        console.print(f"[red]✗ خطا:[/red] {e}")
+        raise typer.Exit(1)
+
+    table = Table(title="⏱  مدت زمان", title_style="bold cyan", show_header=False)
+    table.add_column("شاخص", style="bold")
+    table.add_column("مقدار", style="green")
+    table.add_row("ثانیه", f"{seconds:,}")
+    table.add_row("خوانا", humanize_duration(seconds))
+    console.print(table)
+
+
+@app.command("ago")
+def ago_cmd(
+    ts: int = typer.Argument(..., help="timestamp در گذشته."),
+) -> None:
+    """نمایش فاصلهٔ زمانی از یک timestamp تا الان."""
+    now = now_unix()
+    delta = now - ts
+    if delta < 0:
+        console.print(
+            f"[yellow]⚠ این زمان در آینده است:[/yellow] {humanize_duration(-delta)} بعد"
+        )
+    else:
+        console.print(f"{humanize_duration(delta)} پیش")

persian_devkit/commands/toml_cmd.py

@@ -0,0 +1,85 @@
+"""دستور pdev toml — کار با فایل‌های TOML."""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich.console import Console
+
+from persian_devkit.utils.data_utils import (
+    dump_json,
+    dump_toml,
+    parse_json,
+    parse_toml,
+    read_text,
+    write_text,
+)
+
+app = typer.Typer(help="کار با فایل‌های TOML.", no_args_is_help=True)
+console = Console()
+
+
+def _fail(msg: str) -> None:
+    console.print(f"[red]✗ خطا:[/red] {msg}")
+    raise typer.Exit(1)
+
+
+@app.command("validate")
+def validate_cmd(
+    path: Path = typer.Argument(..., help="مسیر فایل TOML."),
+) -> None:
+    """بررسی صحت TOML."""
+    if not path.exists():
+        _fail(f"فایل یافت نشد: {path}")
+    try:
+        parse_toml(read_text(path))
+    except ValueError as e:
+        _fail(str(e))
+    console.print("[green]✓ TOML معتبر است.[/green]")
+
+
+@app.command("to-json")
+def to_json_cmd(
+    path: Path = typer.Argument(..., help="مسیر فایل TOML."),
+    output: Optional[Path] = typer.Option(None, "--output", "-o"),
+    indent: int = typer.Option(2, "--indent", "-i", min=0, max=10),
+) -> None:
+    """تبدیل TOML به JSON."""
+    if not path.exists():
+        _fail(f"فایل یافت نشد: {path}")
+    try:
+        data = parse_toml(read_text(path))
+    except ValueError as e:
+        _fail(str(e))
+    text = dump_json(data, indent=indent)
+    if output:
+        write_text(output, text)
+        console.print(f"[green]✓ ذخیره شد:[/green] {output}")
+    else:
+        console.print(text, highlight=False)
+
+
+@app.command("from-json")
+def from_json_cmd(
+    path: Path = typer.Argument(..., help="مسیر فایل JSON."),
+    output: Optional[Path] = typer.Option(None, "--output", "-o"),
+) -> None:
+    """تبدیل JSON به TOML."""
+    if not path.exists():
+        _fail(f"فایل یافت نشد: {path}")
+    try:
+        data = parse_json(read_text(path))
+    except ValueError as e:
+        _fail(str(e))
+    if not isinstance(data, dict):
+        _fail("ساختار سطح اول JSON باید object باشد.")
+    try:
+        text = dump_toml(data)
+    except ValueError as e:
+        _fail(str(e))
+    if output:
+        write_text(output, text)
+        console.print(f"[green]✓ ذخیره شد:[/green] {output}")
+    else:
+        console.print(text, highlight=False)

persian_devkit/commands/url_cmd.py

@@ -0,0 +1,102 @@
+"""دستور pdev url — کار با URL و query string."""
+from __future__ import annotations
+
+import sys
+from typing import Optional
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from persian_devkit.utils.url_utils import (
+    build_query,
+    decode_query,
+    parse_url,
+    url_decode,
+    url_encode,
+)
+
+app = typer.Typer(help="کار با URL و query string.", no_args_is_help=True)
+console = Console()
+
+
+def _read(value: Optional[str]) -> str:
+    if value is not None and value != "":
+        return value
+    if not sys.stdin.isatty():
+        data = sys.stdin.read()
+        if data.strip():
+            return data.rstrip("\n")
+    console.print("[red]✗ خطا:[/red] ورودی‌ای داده نشده.")
+    raise typer.Exit(1)
+
+
+@app.command("encode")
+def encode_cmd(
+    text: Optional[str] = typer.Argument(None, help="متن ورودی (یا از stdin)."),
+    safe: str = typer.Option("", "--safe", help="کاراکترهای ایمن (رمزگذاری نمی‌شوند)."),
+) -> None:
+    """درصد-رمزگذاری متن."""
+    console.print(url_encode(_read(text), safe=safe))
+
+
+@app.command("decode")
+def decode_cmd(
+    text: Optional[str] = typer.Argument(None, help="رشتهٔ رمزگذاری‌شده (یا از stdin)."),
+) -> None:
+    """رمزگشایی متن درصد-رمزگذاری‌شده."""
+    console.print(url_decode(_read(text)))
+
+
+@app.command("parse")
+def parse_cmd(
+    url: str = typer.Argument(..., help="آدرس URL."),
+) -> None:
+    """تجزیهٔ URL به اجزای سازنده."""
+    result = parse_url(url)
+    table = Table(title="🔗 URL", title_style="bold cyan")
+    table.add_column("بخش", style="bold")
+    table.add_column("مقدار")
+
+    for key in ("scheme", "netloc", "host", "port", "path", "fragment", "username"):
+        value = result.get(key)
+        if value:
+            table.add_row(key, str(value))
+    if result["query"]:
+        for k, v in result["query"].items():
+            table.add_row(f"query.{k}", v)
+    console.print(table)
+
+
+@app.command("build")
+def build_cmd(
+    params: list[str] = typer.Argument(
+        ..., help="جفت‌های key=value برای ساخت query string."
+    ),
+) -> None:
+    """ساخت query string از جفت‌های key=value."""
+    data: dict[str, str] = {}
+    for item in params:
+        if "=" not in item:
+            console.print(f"[red]✗ خطا:[/red] فرمت نامعتبر: {item} (باید key=value باشد)")
+            raise typer.Exit(1)
+        k, v = item.split("=", 1)
+        data[k] = v
+    console.print(build_query(data))
+
+
+@app.command("decode-query")
+def decode_query_cmd(
+    query: str = typer.Argument(..., help="رشتهٔ query string."),
+) -> None:
+    """تجزیهٔ query string به کلید/مقدار."""
+    result = decode_query(query)
+    if not result:
+        console.print("[yellow]⚠ query string خالی است.[/yellow]")
+        return
+    table = Table(title="📋 Query", title_style="bold cyan")
+    table.add_column("کلید", style="bold")
+    table.add_column("مقدار")
+    for k, values in result.items():
+        table.add_row(k, ", ".join(values))
+    console.print(table)

persian_devkit/commands/uuid_cmd.py

@@ -0,0 +1,45 @@
+"""دستور `pdev uuid` — تولید UUID."""
+from __future__ import annotations
+
+import base64
+import uuid
+
+import typer
+from rich.console import Console
+
+app = typer.Typer(help="تولید UUID.", no_args_is_help=True)
+console = Console()
+
+
+def short_uuid() -> str:
+    """تولید UUID کوتاه بر پایهٔ Base64 (۲۲ کاراکتر)."""
+    raw = uuid.uuid4().bytes
+    return base64.urlsafe_b64encode(raw).rstrip(b"=").decode("ascii")
+
+
+@app.command("new")
+def new_cmd(
+    count: int = typer.Option(
+        1, "--count", "-c", min=1, max=10_000, help="تعداد UUID برای تولید."
+    ),
+    upper: bool = typer.Option(
+        False, "--upper", "-u", help="خروجی با حروف بزرگ."
+    ),
+) -> None:
+    """تولید UUID نسخهٔ ۴."""
+    for _ in range(count):
+        value = str(uuid.uuid4())
+        if upper:
+            value = value.upper()
+        console.print(value)
+
+
+@app.command("short")
+def short_cmd(
+    count: int = typer.Option(
+        1, "--count", "-c", min=1, max=10_000, help="تعداد UUID کوتاه."
+    ),
+) -> None:
+    """تولید UUID کوتاه (Base64، ۲۲ کاراکتر)."""
+    for _ in range(count):
+        console.print(short_uuid())

persian_devkit/commands/yaml_cmd.py

@@ -0,0 +1,94 @@
+"""دستور pdev yaml — کار با فایل‌های YAML."""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Optional
+
+import typer
+from rich.console import Console
+
+from persian_devkit.utils.data_utils import (
+    dump_json,
+    dump_yaml,
+    parse_json,
+    parse_yaml,
+    read_text,
+    write_text,
+)
+
+app = typer.Typer(help="کار با فایل‌های YAML.", no_args_is_help=True)
+console = Console()
+
+
+def _fail(msg: str) -> None:
+    console.print(f"[red]✗ خطا:[/red] {msg}")
+    raise typer.Exit(1)
+
+
+def _load(path: Path) -> Any:
+    if not path.exists():
+        _fail(f"فایل یافت نشد: {path}")
+    try:
+        return parse_yaml(read_text(path))
+    except ValueError as e:
+        _fail(str(e))
+
+
+@app.command("pretty")
+def pretty_cmd(
+    path: Path = typer.Argument(..., help="مسیر فایل YAML."),
+    output: Optional[Path] = typer.Option(None, "--output", "-o"),
+) -> None:
+    """زیباسازی فایل YAML."""
+    data = _load(path)
+    text = dump_yaml(data)
+    if output:
+        write_text(output, text)
+        console.print(f"[green]✓ ذخیره شد:[/green] {output}")
+    else:
+        console.print(text, highlight=False)
+
+
+@app.command("validate")
+def validate_cmd(
+    path: Path = typer.Argument(..., help="مسیر فایل YAML."),
+) -> None:
+    """بررسی صحت YAML."""
+    _load(path)
+    console.print("[green]✓ YAML معتبر است.[/green]")
+
+
+@app.command("to-json")
+def to_json_cmd(
+    path: Path = typer.Argument(..., help="مسیر فایل YAML."),
+    output: Optional[Path] = typer.Option(None, "--output", "-o"),
+    indent: int = typer.Option(2, "--indent", "-i", min=0, max=10),
+) -> None:
+    """تبدیل YAML به JSON."""
+    data = _load(path)
+    text = dump_json(data, indent=indent)
+    if output:
+        write_text(output, text)
+        console.print(f"[green]✓ ذخیره شد:[/green] {output}")
+    else:
+        console.print(text, highlight=False)
+
+
+@app.command("from-json")
+def from_json_cmd(
+    path: Path = typer.Argument(..., help="مسیر فایل JSON."),
+    output: Optional[Path] = typer.Option(None, "--output", "-o"),
+) -> None:
+    """تبدیل JSON به YAML."""
+    if not path.exists():
+        _fail(f"فایل یافت نشد: {path}")
+    try:
+        data = parse_json(read_text(path))
+    except ValueError as e:
+        _fail(str(e))
+    text = dump_yaml(data)
+    if output:
+        write_text(output, text)
+        console.print(f"[green]✓ ذخیره شد:[/green] {output}")
+    else:
+        console.print(text, highlight=False)

persian_devkit/main.py

@@ -0,0 +1,63 @@
+"""نقطهٔ ورود اصلی ابزار pdev."""
+from __future__ import annotations
+
+import sys
+
+# اصلاح encoding در ویندوز
+if sys.platform == "win32":
+    for _stream_name in ("stdin", "stdout", "stderr"):
+        _stream = getattr(sys, _stream_name, None)
+        if _stream is not None and hasattr(_stream, "reconfigure"):
+            try:
+                _stream.reconfigure(encoding="utf-8")
+            except Exception:
+                pass
+
+import typer
+from persian_devkit import __version__
+from persian_devkit.cli import register_commands
+
+app = typer.Typer(
+    name="pdev",
+    help="جعبه‌ابزار خط فرمان برای توسعه‌دهندگان فارسی‌زبان.",
+    no_args_is_help=True,
+    add_completion=True,
+    rich_markup_mode="rich",
+)
+
+
+def _version_callback(value: bool) -> None:
+    """نمایش نسخه و خروج فوری."""
+    if value:
+        typer.echo(f"persian-devkit {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main_callback(
+    ctx: typer.Context,
+    version: bool = typer.Option(
+        False,
+        "--version",
+        "-V",
+        help="نمایش نسخهٔ ابزار و خروج.",
+        callback=_version_callback,
+        is_eager=True,
+    ),
+    verbose: bool = typer.Option(
+        False, "--verbose", "-v", help="نمایش جزئیات بیشتر در خروجی."
+    ),
+    quiet: bool = typer.Option(
+        False, "--quiet", "-q", help="کاهش پیام‌های اضافی (فقط نتیجه)."
+    ),
+) -> None:
+    """گزینه‌های سراسری pdev."""
+    ctx.obj = {"verbose": verbose, "quiet": quiet}
+
+
+# ثبت زیرفرمان‌ها
+register_commands(app)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    app()

persian_devkit/utils/__init__.py

@@ -0,0 +1 @@
+"""توابع کمکی قابل استفادهٔ مجدد."""

persian_devkit/utils/color_utils.py

@@ -0,0 +1,112 @@
+"""تبدیل و پردازش رنگ‌ها."""
+from __future__ import annotations
+
+import colorsys
+import re
+import secrets
+
+_HEX_RE = re.compile(r"^#?([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$")
+_RGB_FUNC_RE = re.compile(r"^rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)")
+_RGB_TRIPLE_RE = re.compile(r"^\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*$")
+
+RGBTuple = tuple[int, int, int]
+
+
+def parse_color(value: str) -> RGBTuple:
+    """تشخیص خودکار فرمت رنگ و برگرداندن (r, g, b).
+
+    فرمت‌های پشتیبانی‌شده: #fff, #ffffff, ff0000, rgb(255,0,0), 255,0,0
+    """
+    v = value.strip()
+
+    m = _HEX_RE.match(v)
+    if m:
+        h = m.group(1)
+        if len(h) == 3:
+            h = "".join(c * 2 for c in h)
+        return (int(h[0:2], 16), int(h[2:4], 16), int(h[4:6], 16))
+
+    m = _RGB_FUNC_RE.match(v)
+    if m:
+        return (int(m.group(1)), int(m.group(2)), int(m.group(3)))
+
+    m = _RGB_TRIPLE_RE.match(v)
+    if m:
+        return (int(m.group(1)), int(m.group(2)), int(m.group(3)))
+
+    raise ValueError(f"فرمت رنگ نامعتبر: {value}")
+
+
+def rgb_to_hex(rgb: RGBTuple) -> str:
+    """تبدیل (r, g, b) به #rrggbb."""
+    return f"#{rgb[0]:02x}{rgb[1]:02x}{rgb[2]:02x}"
+
+
+def hex_to_rgb(hex_str: str) -> RGBTuple:
+    """تبدیل #rrggbb یا #rgb به (r, g, b)."""
+    return parse_color(hex_str)
+
+
+def rgb_to_hsl(rgb: RGBTuple) -> tuple[float, float, float]:
+    """تبدیل RGB به HSL (h درجه ۰-۳۶۰، s و l در بازهٔ ۰-۱)."""
+    r, g, b = (c / 255 for c in rgb)
+    h, l, s = colorsys.rgb_to_hls(r, g, b)
+    return (h * 360, s, l)
+
+
+def hsl_to_rgb(h: float, s: float, l: float) -> RGBTuple:
+    """تبدیل HSL به RGB."""
+    r, g, b = colorsys.hls_to_rgb(h / 360, l, s)
+    return (round(r * 255), round(g * 255), round(b * 255))
+
+
+def random_color() -> RGBTuple:
+    """رنگ کاملاً تصادفی."""
+    return (secrets.randbelow(256), secrets.randbelow(256), secrets.randbelow(256))
+
+
+def pleasant_color() -> RGBTuple:
+    """رنگ تصادفی با اشباع و روشنایی دلپذیر."""
+    h = secrets.randbelow(360)
+    s = 0.5 + secrets.randbelow(40) / 100
+    l = 0.4 + secrets.randbelow(30) / 100
+    return hsl_to_rgb(h, s, l)
+
+
+def generate_palette(rgb: RGBTuple, count: int = 5) -> list[RGBTuple]:
+    """تولید پالت از رنگ پایه (از تیره به روشن)."""
+    if count < 2:
+        return [rgb]
+    h, s, _ = rgb_to_hsl(rgb)
+    palette: list[RGBTuple] = []
+    for i in range(count):
+        new_l = 0.15 + (0.70 * i / (count - 1))
+        palette.append(hsl_to_rgb(h, s, new_l))
+    return palette
+
+
+def complementary(rgb: RGBTuple) -> RGBTuple:
+    """رنگ مکمل (۱۸۰ درجه چرخش hue)."""
+    h, s, l = rgb_to_hsl(rgb)
+    return hsl_to_rgb((h + 180) % 360, s, l)
+
+
+def luminance(rgb: RGBTuple) -> float:
+    """روشنایی نسبی (۰-۱) طبق فرمول WCAG."""
+    def channel(c: int) -> float:
+        v = c / 255
+        return v / 12.92 if v <= 0.03928 else ((v + 0.055) / 1.055) ** 2.4
+
+    return 0.2126 * channel(rgb[0]) + 0.7152 * channel(rgb[1]) + 0.0722 * channel(rgb[2])
+
+
+def contrast_ratio(a: RGBTuple, b: RGBTuple) -> float:
+    """نسبت کنتراست WCAG بین دو رنگ (۱ تا ۲۱)."""
+    la, lb = luminance(a), luminance(b)
+    lighter, darker = max(la, lb), min(la, lb)
+    return (lighter + 0.05) / (darker + 0.05)
+
+
+def best_text_color(bg: RGBTuple) -> str:
+    """بهترین رنگ متن (سیاه یا سفید) برای پس‌زمینه."""
+    return "black" if luminance(bg) > 0.5 else "white"