persian-devkit 1.0.0__py3-none-any.whl

persian_devkit/utils/gitignore_data.py

@@ -0,0 +1,211 @@
+"""قالب‌های `.gitignore` برای زبان‌ها و ابزارهای رایج."""
+
+GITIGNORES: dict[str, str] = {
+    "python": """# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtualenv
+.venv
+venv/
+ENV/
+env/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.mypy_cache/
+.ruff_cache/
+
+# Distribution
+*.whl
+
+# IDE
+.idea/
+.vscode/
+""",
+    "node": """# Node
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+.pnpm-debug.log*
+
+# Build
+dist/
+build/
+.next/
+.nuxt/
+out/
+
+# Cache
+.cache/
+.parcel-cache/
+.eslintcache
+
+# Env
+.env
+.env.local
+.env.*.local
+
+# IDE
+.idea/
+.vscode/
+""",
+    "go": """# Go
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+*.test
+*.out
+
+# Vendor
+vendor/
+
+# Binary
+/bin/
+main
+""",
+    "rust": """# Rust
+/target/
+**/*.rs.bk
+Cargo.lock
+
+# Debug
+*.pdb
+""",
+    "java": """# Java
+*.class
+*.jar
+*.war
+*.ear
+*.nar
+hs_err_pid*
+replay_pid*
+
+# Maven
+target/
+
+# Gradle
+.gradle/
+build/
+
+# IDE
+.idea/
+*.iml
+""",
+    "cpp": """# C/C++
+*.o
+*.obj
+*.exe
+*.out
+*.app
+*.so
+*.dylib
+*.dll
+
+# Build directories
+build/
+cmake-build-*/
+
+# Debug
+*.dSYM/
+""",
+    "macos": """# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+._*
+
+# Thumbnails
+**/.Spotlight-V100
+**/.Trashes
+**/.fseventsd
+""",
+    "windows": """# Windows
+Thumbs.db
+Thumbs.db:encryptable
+ehthumbs.db
+ehthumbs_vista.db
+Desktop.ini
+$RECYCLE.BIN/
+*.lnk
+""",
+    "linux": """# Linux
+*~
+.fuse_hidden*
+.directory
+.Trash-*
+.nfs*
+""",
+    "vscode": """# VS Code
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+!.vscode/*.code-snippets
+.history/
+*.vsix
+""",
+    "jetbrains": """# JetBrains IDEs
+.idea/
+*.iml
+*.iws
+*.ipr
+out/
+""",
+    "vim": """# Vim
+[._]*.s[a-v][a-z]
+[._]*.sw[a-p]
+[._]s[a-rt-v][a-z]
+[._]ss[a-gi-z]
+[._]sw[a-p]
+Session.vim
+.netrwhist
+*~
+""",
+}
+
+
+def combine_gitignores(langs: list[str]) -> str:
+    """ترکیب چند .gitignore با جداکننده."""
+    parts: list[str] = []
+    for lang in langs:
+        key = lang.lower()
+        if key not in GITIGNORES:
+            raise ValueError(
+                f"زبان ناشناخته: {lang}. "
+                f"موارد مجاز: {', '.join(GITIGNORES.keys())}"
+            )
+        parts.append(GITIGNORES[key].rstrip())
+    return "\n\n".join(parts) + "\n"
+
+
+def list_gitignores() -> list[str]:
+    """لیست همهٔ زبان‌ها و ابزارها."""
+    return sorted(GITIGNORES.keys())

persian_devkit/utils/image_utils.py

@@ -0,0 +1,37 @@
+"""اطلاعات و تبدیل تصاویر."""
+from __future__ import annotations
+
+from pathlib import Path
+
+from PIL import Image
+
+
+def image_info(path: Path) -> dict:
+    """اطلاعات فایل تصویری: فرمت، حالت، ابعاد، اندازه."""
+    with Image.open(path) as img:
+        return {
+            "format": img.format or "unknown",
+            "mode": img.mode,
+            "width": img.width,
+            "height": img.height,
+            "size_bytes": path.stat().st_size,
+        }
+
+
+def resize_image(src: Path, dst: Path, width: int, height: int | None = None) -> None:
+    """تغییر اندازهٔ تصویر (اگر height خالی باشد، نسبت حفظ می‌شود)."""
+    with Image.open(src) as img:
+        if height is None:
+            ratio = width / img.width
+            height = max(1, round(img.height * ratio))
+        resized = img.resize((width, height), Image.LANCZOS)
+        resized.save(dst)
+
+
+def convert_image(src: Path, dst: Path, quality: int = 90) -> None:
+    """تبدیل فرمت تصویر بر اساس پسوند مقصد."""
+    with Image.open(src) as img:
+        if dst.suffix.lower() in (".jpg", ".jpeg"):
+            img.convert("RGB").save(dst, quality=quality)
+        else:
+            img.save(dst)

persian_devkit/utils/jsonpath_utils.py

@@ -0,0 +1,94 @@
+"""پیاده‌سازی سادهٔ JSONPath با پشتیبانی از dot و [index] و [*]."""
+from __future__ import annotations
+
+import re
+from typing import Any
+
+
+class JSONPathError(ValueError):
+    """خطا در مسیر JSONPath."""
+
+
+# توکن‌ها: .key یا [0] یا ["key"] یا [*] یا key در ابتدای مسیر
+_TOKEN_RE = re.compile(
+    r"""
+      \.([A-Za-z_][\w\-]*)          # .key
+    | \[\s*(\d+)\s*\]               # [0]
+    | \[\s*['"]([^'"]+)['"]\s*\]    # ["key"]
+    | \[\s*(\*)\s*\]                # [*]
+    | ^([A-Za-z_][\w\-]*)           # key در ابتدای مسیر (بدون نقطه)
+    """,
+    re.VERBOSE,
+)
+
+
+def _tokenize(path: str) -> list[tuple[str, Any]]:
+    """مسیر را به توکن‌های (نوع, مقدار) تجزیه می‌کند."""
+    p = path.strip()
+    if p == "" or p == "$":
+        return []
+
+    if p.startswith("$"):
+        p = p[1:]
+
+    tokens: list[tuple[str, Any]] = []
+    pos = 0
+    while pos < len(p):
+        m = _TOKEN_RE.match(p, pos)
+        if not m:
+            raise JSONPathError(f"مسیر نامعتبر در موقعیت {pos}: {p[pos:pos+20]!r}")
+        key1, idx, key2, wildcard, key3 = m.groups()
+        if key1 is not None:
+            tokens.append(("key", key1))
+        elif idx is not None:
+            tokens.append(("index", int(idx)))
+        elif key2 is not None:
+            tokens.append(("key", key2))
+        elif wildcard is not None:
+            tokens.append(("wildcard", None))
+        elif key3 is not None:
+            tokens.append(("key", key3))
+        pos = m.end()
+    return tokens
+
+
+def query(data: Any, path: str) -> Any:
+    """اجرای مسیر روی داده و برگرداندن مقدار.
+
+    مسیرهای پشتیبانی‌شده:
+      .user.name           → کلید تودرتو
+      .items[0]            → اندیس آرایه
+      .items[*].name       → همهٔ عناصر
+      ["key with space"]   → کلید با کاراکتر خاص
+      $                    → خود داده
+    """
+    tokens = _tokenize(path)
+    results: list[Any] = [data]
+
+    for kind, value in tokens:
+        next_results: list[Any] = []
+        for item in results:
+            if kind == "key":
+                if isinstance(item, dict) and value in item:
+                    next_results.append(item[value])
+            elif kind == "index":
+                if isinstance(item, list) and -len(item) <= value < len(item):
+                    next_results.append(item[value])
+            elif kind == "wildcard":
+                if isinstance(item, list):
+                    next_results.extend(item)
+                elif isinstance(item, dict):
+                    next_results.extend(item.values())
+        results = next_results
+
+    if len(results) == 1:
+        return results[0]
+    return results
+
+
+def query_many(data: Any, path: str) -> list[Any]:
+    """مثل query اما همیشه لیست برمی‌گرداند."""
+    result = query(data, path)
+    if isinstance(result, list):
+        return result
+    return [result]

persian_devkit/utils/license_data.py

@@ -0,0 +1,190 @@
+"""قالب‌های متن لایسنس‌های متن‌باز رایج."""
+
+LICENSES: dict[str, dict[str, str]] = {
+    "MIT": {
+        "name": "MIT License",
+        "spdx": "MIT",
+        "template": """MIT License
+
+Copyright (c) {year} {author}
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+""",
+    },
+    "Apache-2.0": {
+        "name": "Apache License 2.0",
+        "spdx": "Apache-2.0",
+        "template": """                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Copyright {year} {author}
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+   For the full license text, see:
+   https://www.apache.org/licenses/LICENSE-2.0.txt
+""",
+    },
+    "BSD-3-Clause": {
+        "name": "BSD 3-Clause \"New\" or \"Revised\" License",
+        "spdx": "BSD-3-Clause",
+        "template": """BSD 3-Clause License
+
+Copyright (c) {year}, {author}
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+""",
+    },
+    "GPL-3.0": {
+        "name": "GNU General Public License v3.0",
+        "spdx": "GPL-3.0",
+        "template": """GNU GENERAL PUBLIC LICENSE
+Version 3, 29 June 2007
+
+Copyright (C) {year} {author}
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Full license text: https://www.gnu.org/licenses/gpl-3.0.txt
+""",
+    },
+    "MPL-2.0": {
+        "name": "Mozilla Public License 2.0",
+        "spdx": "MPL-2.0",
+        "template": """Mozilla Public License Version 2.0
+==================================
+
+Copyright (c) {year} {author}
+
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+Full license text: https://www.mozilla.org/MPL/2.0/
+""",
+    },
+    "ISC": {
+        "name": "ISC License",
+        "spdx": "ISC",
+        "template": """ISC License
+
+Copyright (c) {year} {author}
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+""",
+    },
+    "Unlicense": {
+        "name": "The Unlicense",
+        "spdx": "Unlicense",
+        "template": """This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or distribute
+this software, either in source code form or as a compiled binary, for any
+purpose, commercial or non-commercial, and by any means.
+
+In jurisdictions that recognize copyright laws, the author or authors of
+this software dedicate any and all copyright interest in the software to
+the public domain. We make this dedication for the benefit of the public
+at large and to the detriment of our heirs and successors.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <https://unlicense.org>
+""",
+    },
+}
+
+
+def render_license(spdx: str, author: str, year: int | str) -> str:
+    """رندر متن لایسنس با جایگذاری نویسنده و سال."""
+    if spdx not in LICENSES:
+        raise ValueError(
+            f"لایسنس ناشناخته: {spdx}. "
+            f"موارد مجاز: {', '.join(LICENSES.keys())}"
+        )
+    return LICENSES[spdx]["template"].format(author=author, year=year)
+
+
+def list_licenses() -> list[dict[str, str]]:
+    """لیست همهٔ لایسنس‌های پشتیبانی‌شده."""
+    return [
+        {"spdx": k, "name": v["name"]}
+        for k, v in LICENSES.items()
+    ]

persian_devkit/utils/number_utils.py

@@ -0,0 +1,78 @@
+"""تبدیل و قالب‌بندی اعداد با پشتیبانی فارسی."""
+from __future__ import annotations
+
+PERSIAN_DIGITS = "۰۱۲۳۴۵۶۷۸۹"
+ENGLISH_DIGITS = "0123456789"
+ARABIC_DIGITS = "٠١٢٣٤٥٦٧٨٩"
+
+_ONES = ["", "یک", "دو", "سه", "چهار", "پنج", "شش", "هفت", "هشت", "نه"]
+_TEENS = [
+    "ده", "یازده", "دوازده", "سیزده", "چهارده",
+    "پانزده", "شانزده", "هفده", "هجده", "نوزده",
+]
+_TENS = ["", "", "بیست", "سی", "چهل", "پنجاه", "شصت", "هفتاد", "هشتاد", "نود"]
+_HUNDREDS = ["", "صد", "دویست", "سیصد", "چهارصد", "پانصد", "ششصد", "هفتصد", "هشتصد", "نهصد"]
+_SCALES = ["", " هزار", " میلیون", " میلیارد", " بیلیون"]
+
+
+def to_persian_digits(value: str) -> str:
+    """تبدیل ارقام لاتین/عربی به ارقام فارسی."""
+    table = str.maketrans(
+        ENGLISH_DIGITS + ARABIC_DIGITS,
+        PERSIAN_DIGITS + PERSIAN_DIGITS,
+    )
+    return value.translate(table)
+
+
+def to_english_digits(value: str) -> str:
+    """تبدیل ارقام فارسی/عربی به ارقام لاتین."""
+    table = str.maketrans(
+        PERSIAN_DIGITS + ARABIC_DIGITS,
+        ENGLISH_DIGITS + ENGLISH_DIGITS,
+    )
+    return value.translate(table)
+
+
+def format_thousands(n: int) -> str:
+    """قالب‌بندی عدد با جداکنندهٔ هزارگان."""
+    return f"{n:,}"
+
+
+def _three_digit_to_words(n: int) -> str:
+    """تبدیل عدد سه‌رقمی (۰ تا ۹۹۹) به حروف فارسی."""
+    parts: list[str] = []
+    h, rem = divmod(n, 100)
+    if h:
+        parts.append(_HUNDREDS[h])
+    if 10 <= rem < 20:
+        parts.append(_TEENS[rem - 10])
+    else:
+        t, o = divmod(rem, 10)
+        if t:
+            parts.append(_TENS[t])
+        if o:
+            parts.append(_ONES[o])
+    return " و ".join(parts)
+
+
+def number_to_words(n: int) -> str:
+    """تبدیل عدد صحیح به معادل نوشتاری فارسی."""
+    if n == 0:
+        return "صفر"
+    if n < 0:
+        return "منفی " + number_to_words(-n)
+
+    groups: list[int] = []
+    value = n
+    while value > 0:
+        groups.append(value % 1000)
+        value //= 1000
+
+    parts: list[str] = []
+    for idx in range(len(groups) - 1, -1, -1):
+        group = groups[idx]
+        if group == 0:
+            continue
+        text = _three_digit_to_words(group)
+        parts.append(text + _SCALES[idx])
+    return " و ".join(parts)

persian_devkit/utils/qrcode_utils.py

@@ -0,0 +1,84 @@
+"""تولید QR Code برای چاپ در ترمینال یا ذخیره در فایل."""
+from __future__ import annotations
+
+from pathlib import Path
+
+import qrcode
+from qrcode.constants import (
+    ERROR_CORRECT_H,
+    ERROR_CORRECT_L,
+    ERROR_CORRECT_M,
+    ERROR_CORRECT_Q,
+)
+
+_ERROR_LEVELS = {
+    "L": ERROR_CORRECT_L,
+    "M": ERROR_CORRECT_M,
+    "Q": ERROR_CORRECT_Q,
+    "H": ERROR_CORRECT_H,
+}
+
+
+def _make_qr(text: str, error: str = "M", box_size: int = 10, border: int = 2):
+    """شیء QR را با تنظیمات داده‌شده می‌سازد."""
+    if error not in _ERROR_LEVELS:
+        raise ValueError(
+            f"سطح تصحیح خطا نامعتبر: {error}. مجاز: L, M, Q, H"
+        )
+    qr = qrcode.QRCode(
+        version=None,
+        error_correction=_ERROR_LEVELS[error],
+        box_size=box_size,
+        border=border,
+    )
+    qr.add_data(text)
+    qr.make(fit=True)
+    return qr
+
+
+def qr_to_ascii(text: str, error: str = "M", border: int = 1, invert: bool = True) -> str:
+    """تولید نمایش ASCII از QR برای چاپ در ترمینال.
+
+    با ``invert=True`` (پیش‌فرض)، ماژول‌های تیره به‌عنوان پس‌زمینه نمایش داده می‌شوند
+    که برای ترمینال‌های تیره مناسب است.
+    """
+    qr = _make_qr(text, error=error, box_size=1, border=border)
+    matrix = qr.get_matrix()
+    rows = len(matrix)
+    cols = len(matrix[0]) if rows else 0
+
+    def render(top: bool, bottom: bool) -> str:
+        if invert:
+            top, bottom = not top, not bottom
+        if top and bottom:
+            return "█"
+        if top:
+            return "▀"
+        if bottom:
+            return "▄"
+        return " "
+
+    lines: list[str] = []
+    for y in range(0, rows, 2):
+        chars = []
+        for x in range(cols):
+            top = matrix[y][x]
+            bottom = matrix[y + 1][x] if y + 1 < rows else False
+            chars.append(render(top, bottom))
+        lines.append("".join(chars))
+    return "\n".join(lines)
+
+
+def qr_to_image(
+    text: str,
+    output: Path,
+    error: str = "M",
+    box_size: int = 10,
+    border: int = 4,
+    fill_color: str = "black",
+    back_color: str = "white",
+) -> None:
+    """ذخیرهٔ QR به‌صورت فایل تصویری."""
+    qr = _make_qr(text, error=error, box_size=box_size, border=border)
+    img = qr.make_image(fill_color=fill_color, back_color=back_color)
+    img.save(str(output))