nicepython 0.1.0__py3-none-any.whl

nicepy/__init__.py

@@ -0,0 +1,4 @@
+from .nicepath.core import NicePath
+from .nicepath.exceptios import NicePathError
+
+all = ["NicePath", "NicePathError"]

nicepy/logger.py

@@ -0,0 +1,51 @@
+import logging
+from functools import wraps
+
+
+logger = logging.getLogger("nicepy")
+
+if not logger.handlers:
+    handler = logging.StreamHandler()
+    formatter = logging.Formatter(
+        "(%(filename)s-%(lineno)d)[%(levelname)s] %(name)s | %(message)s"
+    )
+    handler.setFormatter(formatter)
+    logger.addHandler(handler)
+
+logger.setLevel(30)
+
+
+
+from functools import wraps
+from nicepy.logger import logger
+
+
+def log_operation(func):
+    @wraps(func)
+    def wrapper(self ):
+        logger.debug(f"{func.__name__} started -> {self._path}")
+        try:
+            result = func(self)   
+            logger.info(f"{func.__name__} success -> {self._path}")
+            return result
+        except Exception as e:
+            logger.exception(
+                f"{func.__name__} failed -> {self._path} | Reason: {e}"
+            )
+            raise
+    return wrapper
+
+
+from nicepy.logger import logger
+
+def log_start(instance, func_name):
+    path_info = getattr(instance, "_path", "unknown")
+    logger.debug(f"{func_name} started -> {path_info}")
+
+def log_end(instance, func_name):
+    path_info = getattr(instance, "_path", "unknown")
+    logger.info(f"{func_name} finished -> {path_info}")
+
+def log_error(instance, func_name, e):
+    path_info = getattr(instance, "_path", "unknown")
+    logger.exception(f"{func_name} failed -> {path_info} | Reason: {e}")

nicepy/nicepath/__init__.py

@@ -0,0 +1 @@
+from .core import NicePath

nicepy/nicepath/core.py

@@ -0,0 +1,702 @@
+# nicepath/core.py
+from __future__ import annotations
+from dataclasses import dataclass
+from pathlib import Path
+import inspect
+import shutil
+from datetime import datetime
+import re
+from nicepy.logger import logger
+from nicepy.nicepath.exceptios import (
+    NicePathError,
+    NotADirectoryError,
+    NotAFileError,
+    PathNotFoundError,
+    WriteError,
+    DeleteError
+)
+
+@dataclass
+class NicePath:
+    """
+    📝 NicePath: A powerful, user-friendly wrapper around pathlib.Path with logging, smart search, and tree view.
+
+    Hint (English):
+        - _input_path: str or Path - input path for initialization
+        - base_dir: Optional base path for relative paths
+
+    راهنمای فارسی:
+        - _input_path: مسیر فایل/پوشه ورودی (str یا Path)
+        - base_dir: مسیر پایه برای مسیرهای نسبی
+    """
+    _input_path: str | Path
+    base_dir: Path | None = None
+
+    def __post_init__(self):
+        """Initialize internal resolved path"""
+        if isinstance(self._input_path, Path):
+            self._path: Path = self._input_path.resolve()
+            return
+
+        input_path = Path(self._input_path)
+        if input_path.is_absolute():
+            self._path = input_path.resolve()
+            return
+
+        # relative path based on caller file
+        caller_file = inspect.stack()[1].filename
+        base = Path(caller_file).resolve().parent if self.base_dir is None else Path(self.base_dir).resolve()
+        self._path: Path = (base / input_path).resolve()
+
+    # -------------------------
+    # Logger helpers
+    # -------------------------
+    def _log_start(self, action: str):
+        logger.debug(f"{action} started -> {self._path}")
+
+    def _log_success(self, action: str):
+        logger.info(f"{action} success -> {self._path}")
+
+    def _log_error(self, action: str, e: Exception):
+        logger.exception(f"{action} failed -> {self._path} | Reason: {e}")
+
+    # -------------------------
+    # Info Properties
+    # -------------------------
+    @property
+    def path(self) -> Path:
+        """Return the internal resolved Path object / برگرداندن مسیر"""
+        return self._path
+
+    @property
+    def name(self) -> str:
+        """File or folder name (with extension) / نام فایل یا پوشه"""
+        return self._path.name
+
+    @property
+    def stem(self) -> str:
+        """File name without extension / نام فایل بدون پسوند"""
+        return self._path.stem
+
+    @property
+    def suffix(self) -> str:
+        """File extension / پسوند فایل"""
+        return self._path.suffix
+
+    @property
+    def parent(self) -> NicePath:
+        """Return parent folder as NicePath / پوشه والد به صورت NicePath"""
+        return NicePath(self._path.parent)
+
+    @property
+    def exists(self) -> bool:
+        """Check if path exists / بررسی وجود مسیر"""
+        return self._path.exists()
+
+    @property
+    def is_file(self) -> bool:
+        """Check if path is a file / بررسی اینکه مسیر فایل است"""
+        return self._path.is_file()
+
+    @property
+    def is_dir(self) -> bool:
+        """Check if path is a directory / بررسی اینکه مسیر پوشه است"""
+        return self._path.is_dir()
+
+    @property
+    def size(self) -> int:
+        """Return file size or total folder size in bytes / حجم فایل یا کل پوشه"""
+        if self.is_file:
+            return self._path.stat().st_size
+        return sum(p.stat().st_size for p in self._path.rglob("*") if p.is_file())
+
+    @property
+    def created_at(self) -> datetime:
+        """Return creation datetime / زمان ایجاد فایل یا پوشه"""
+        return datetime.fromtimestamp(self._path.stat().st_ctime)
+
+    @property
+    def modified_at(self) -> datetime:
+        """Return last modification datetime / زمان آخرین ویرایش"""
+        return datetime.fromtimestamp(self._path.stat().st_mtime)
+        # -------------------------
+    # File Actions
+    # -------------------------
+    def read(self, encoding: str = "utf-8") -> str:
+        """
+        Read file content / خواندن محتوای فایل
+
+        Args:
+            encoding: File encoding / انکودینگ فایل
+
+        Returns:
+            str: file content / محتوای فایل
+        """
+        self._log_start("read")
+        if not self.exists:
+            self._log_error("read", PathNotFoundError(f"{self._path} not found"))
+            raise PathNotFoundError(f"File not found: {self._path}")
+
+        if not self.is_file:
+            self._log_error("read", NotAFileError(f"{self._path} is not a file"))
+            raise NotAFileError(f"Cannot read because it is not a file: {self._path}")
+
+        try:
+            content = self._path.read_text(encoding=encoding)
+            self._log_success("read")
+            return content
+        except Exception as e:
+            self._log_error("read", e)
+            raise
+
+    def write(self, data: str, encoding: str = "utf-8") -> NicePath:
+        """
+        Write text to file / نوشتن متن در فایل
+
+        Returns:
+            self / خود شیء برای زنجیره متدها
+        """
+        self._log_start("write")
+        try:
+            self._path.parent.mkdir(parents=True, exist_ok=True)
+            self._path.write_text(data, encoding=encoding)
+            self._log_success("write")
+            return self
+        except Exception as e:
+            self._log_error("write", e)
+            raise WriteError(f"Failed to write file: {self._path}") from e
+
+    def append(self, data: str, encoding: str = "utf-8") -> NicePath:
+        """
+        Append text to file / اضافه کردن متن به فایل
+        """
+        self._log_start("append")
+        try:
+            self._path.parent.mkdir(parents=True, exist_ok=True)
+            with self._path.open("a", encoding=encoding) as f:
+                f.write(data)
+            self._log_success("append")
+            return self
+        except Exception as e:
+            self._log_error("append", e)
+            raise WriteError(f"Failed to append file: {self._path}") from e
+
+    def mkdir(self, parents: bool = True, exist_ok: bool = True) -> NicePath:
+        """
+        Create directory / ایجاد پوشه
+        """
+        self._log_start("mkdir")
+        try:
+            self._path.mkdir(parents=parents, exist_ok=exist_ok)
+            self._log_success("mkdir")
+            return self
+        except Exception as e:
+            self._log_error("mkdir", e)
+            raise NicePathError(f"Failed to create directory: {self._path}") from e
+
+    def delete(self) -> NicePath:
+        """
+        Delete file or directory / حذف فایل یا پوشه
+        """
+        self._log_start("delete")
+        if not self.exists:
+            self._log_error("delete", PathNotFoundError(f"{self._path} not found"))
+            raise PathNotFoundError(f"Path not found: {self._path}")
+
+        try:
+            if self.is_file:
+                self._path.unlink()
+            elif self.is_dir:
+                shutil.rmtree(self._path)
+            self._log_success("delete")
+            return self
+        except Exception as e:
+            self._log_error("delete", e)
+            raise DeleteError(f"Failed to delete: {self._path}") from e
+
+    def copy_to(self, destination: NicePath) -> NicePath:
+        """
+        Copy file or folder to destination / کپی فایل یا پوشه
+        """
+        self._log_start("copy_to")
+        try:
+            dest = Path(destination._path)
+            if self.is_file:
+                shutil.copy2(self._path, dest)
+            else:
+                shutil.copytree(self._path, dest, dirs_exist_ok=True)
+            self._log_success("copy_to")
+            return NicePath(dest)
+        except Exception as e:
+            self._log_error("copy_to", e)
+            raise NicePathError(f"Failed to copy to {destination._path}") from e
+
+    def move_to(self, destination: NicePath) -> NicePath:
+        """
+        Move file or folder to destination / انتقال فایل یا پوشه
+        """
+        self._log_start("move_to")
+        try:
+            dest = shutil.move(self._path, destination._path)
+            self._log_success("move_to")
+            return NicePath(dest)
+        except Exception as e:
+            self._log_error("move_to", e)
+            raise NicePathError(f"Failed to move to {destination._path}") from e
+
+    # -------------------------
+    # Tree View
+    # -------------------------
+    def tree(
+        self,
+        recursive: bool = True,
+        ignore_hidden: bool = True,
+        ignore_venv: bool = True,
+    ) -> str:
+        """
+        EN:
+        Generate a visual tree representation of the directory structure.
+
+        FA:
+        تولید نمایش گرافیکی درختی از ساختار فایل‌ها و پوشه‌ها.
+
+        Parameters
+        ----------
+        recursive : bool, default=True
+            EN: If True, traverses subdirectories recursively.
+            FA: اگر True باشد، زیرپوشه‌ها را نیز به صورت بازگشتی بررسی می‌کند.
+
+        ignore_hidden : bool, default=True
+            EN: If True, hidden files and folders (starting with ".") are ignored.
+            FA: اگر True باشد، فایل‌ها و پوشه‌های مخفی نادیده گرفته می‌شوند.
+
+        ignore_venv : bool, default=True
+            EN: If True, any folder named 'venv' and its entire subtree will be skipped.
+            FA: اگر True باشد، پوشه venv و تمام زیرمجموعه آن نادیده گرفته می‌شود.
+
+        Returns
+        -------
+        str
+            EN: A formatted tree string.
+            FA: رشته‌ای شامل ساختار درختی مسیر.
+
+        Notes
+        -----
+        EN:
+            - Safe by default (venv ignored)
+            - Does not raise error if path does not exist (returns empty string)
+
+        FA:
+            - به صورت پیش‌فرض ایمن است (venv نادیده گرفته می‌شود)
+            - اگر مسیر وجود نداشته باشد خطا نمی‌دهد و رشته خالی برمی‌گرداند
+        """
+
+        self._log_start("tree")
+
+        if not self.exists:
+            logger.warning(f"Tree skipped (path not found) -> {self._path}")
+            return ""
+
+        try:
+            lines: list[str] = []
+
+            def build_tree(path: Path, prefix=""):
+                entries = list(path.iterdir())
+
+                # ---- Filters ----
+                filtered: list[Path] = []
+                for e in entries:
+                    if ignore_hidden and e.name.startswith("."):
+                        continue
+                    if ignore_venv and e.is_dir() and e.name.lower() == "venv":
+                        logger.debug(f"tree skipped venv -> {e}")
+                        continue
+                    filtered.append(e)
+
+                filtered.sort(key=lambda x: (x.is_file(), x.name.lower()))
+
+                for index, entry in enumerate(filtered):
+                    connector = "└── " if index == len(filtered) - 1 else "├── "
+                    lines.append(prefix + connector + entry.name)
+
+                    if entry.is_dir() and recursive:
+                        extension = "    " if index == len(filtered) - 1 else "│   "
+                        build_tree(entry, prefix + extension)
+
+            lines.append(self._path.name)
+
+            if self.is_dir:
+                build_tree(self._path)
+
+            self._log_success("tree")
+            return "\n".join(lines)
+
+        except Exception as e:
+            self._log_error("tree", e)
+            return ""
+        
+    # -------------------------
+    # Smart Search
+    # -------------------------
+
+    def search(
+        self,
+        name_contains: str | None = None,
+        suffix: str | None = None,
+        stem: str | None = None,
+        regex: str | None = None,
+        min_size: int | None = None,
+        max_size: int | None = None,
+        only_files: bool = False,
+        only_dirs: bool = False,
+        recursive: bool = True,
+        ignore_hidden: bool = True,
+        ignore_venv: bool = True,
+    ) -> list["NicePath"]:
+        """
+        EN:
+        Advanced file and directory search with multiple filters.
+    
+        FA:
+        جستجوی پیشرفته فایل و پوشه با فیلترهای متنوع.
+    
+        Parameters
+        ----------
+        name_contains : str | None
+            EN: Return items whose name contains this substring (case-insensitive).
+            FA: فایل‌هایی که نام آن‌ها شامل این رشته باشد.
+    
+        suffix : str | None
+            EN: Filter by file extension (e.g. ".py").
+            FA: فیلتر بر اساس پسوند فایل (مثلاً ".py").
+    
+        stem : str | None
+            EN: Match exact file name without extension.
+            FA: تطابق دقیق نام فایل بدون پسوند.
+    
+        regex : str | None
+            EN: Apply regex pattern to file name.
+            FA: اعمال عبارت منظم روی نام فایل.
+    
+        min_size : int | None
+            EN: Minimum file size in bytes.
+            FA: حداقل اندازه فایل (بر حسب بایت).
+    
+        max_size : int | None
+            EN: Maximum file size in bytes.
+            FA: حداکثر اندازه فایل (بر حسب بایت).
+    
+        only_files : bool, default=False
+            EN: Return only files.
+            FA: فقط فایل‌ها را برگرداند.
+    
+        only_dirs : bool, default=False
+            EN: Return only directories.
+            FA: فقط پوشه‌ها را برگرداند.
+    
+        recursive : bool, default=True
+            EN: Search recursively in subdirectories.
+            FA: جستجوی بازگشتی در زیرپوشه‌ها.
+    
+        ignore_hidden : bool, default=True
+            EN: Ignore hidden files and folders.
+            FA: نادیده گرفتن فایل‌ها و پوشه‌های مخفی.
+    
+        ignore_venv : bool, default=True
+            EN: Ignore any folder named 'venv' and its subtree.
+            FA: نادیده گرفتن پوشه venv و تمام زیرمجموعه آن.
+    
+        Returns
+        -------
+        list[NicePath]
+            EN: A list of NicePath objects matching filters.
+            FA: لیستی از اشیاء NicePath مطابق با فیلترها.
+    
+        Safety
+        ------
+        EN:
+            - venv is ignored by default for safety and performance.
+            - Returns empty list if nothing is found (no exception).
+    
+        FA:
+            - به صورت پیش‌فرض venv نادیده گرفته می‌شود.
+            - در صورت عدم یافتن نتیجه، آرایه خالی برمی‌گرداند و خطا نمی‌دهد.
+        """
+    
+        self._log_start("search")
+    
+        if not self.exists:
+            logger.warning(f"Search skipped (path not found) -> {self._path}")
+            return []
+    
+        candidates = (
+            [self._path]
+            if self.is_file
+            else (self._path.rglob("*") if recursive else self._path.glob("*"))
+        )
+    
+        results: list[NicePath] = []
+    
+        for p in candidates:
+        
+            # ---- Skip hidden ----
+            if ignore_hidden and p.name.startswith("."):
+                continue
+            
+            # ---- Skip venv folders and their children ----
+            if ignore_venv and any(part.lower() == "venv" for part in p.parts):
+                logger.debug(f"search skipped venv path -> {p}")
+                continue
+            
+            if only_files and not p.is_file():
+                continue
+            
+            if only_dirs and not p.is_dir():
+                continue
+            
+            if name_contains and name_contains.lower() not in p.name.lower():
+                continue
+            
+            if suffix and p.suffix.lower() != suffix.lower():
+                continue
+            
+            if stem and stem.lower() != p.stem.lower():
+                continue
+            
+            if regex:
+                try:
+                    if not re.search(regex, p.name):
+                        continue
+                except re.error as e:
+                    self._log_error("search-regex", e)
+                    continue
+                
+            if p.is_file():
+                size = p.stat().st_size
+                if min_size is not None and size < min_size:
+                    continue
+                if max_size is not None and size > max_size:
+                    continue
+                
+            results.append(NicePath(p))
+    
+        self._log_success("search")
+        return results
+    
+    # -------------------------
+    # logAll: Tree + Search + Save to file
+    # -------------------------
+
+    def logAll(
+        self,
+        file_output: "NicePath",
+        search_name_contains: str | None = None,
+        search_suffix: str | None = None,
+        search_stem: str | None = None,
+        search_regex: str | None = None,
+        search_only_files: bool = True,
+        search_only_dirs: bool = False,
+        search_recursive: bool = True,
+        search_ignore_hidden: bool = True,
+        max_files: int = 500,          # safety: max number of files to log
+        max_total_size: int = 50_000_000,  # safety: max total bytes (50MB)
+        ignore_venv: bool = True,      # ignore virtual environments by default
+        ignore_libs: bool = True,      # ignore internal library folders by default
+        encoding: str = "utf-8"
+    ) -> str:
+        """
+        Log full structure: Tree + search results into a file
+
+        EN:
+        Logs the tree of the current path and all matching search files line by line.
+        - Safety limits prevent logging too many files or too large total size.
+        - Automatically skips venv and library folders by default.
+        - If the original path does not exist, logs until last existing parent with a warning.
+
+        FA:
+        ساختار درختی مسیر و تمام فایل‌های مطابق با سرچ را خط به خط لاگ می‌کند.
+        - محدودیت‌های ایمنی از لاگ بیش از حد فایل‌ها یا حجم جلوگیری می‌کند.
+        - به صورت پیشفرض پوشه‌های venv و کتابخانه‌ها را ایگنور می‌کند.
+        - در صورت وجود نداشتن مسیر اصلی، تا آخرین مسیر موجود لاگ می‌کند و هشدار می‌دهد.
+
+        Returns:
+            str: full text (tree + files) for printing or saving
+
+        ------------------------------------------------------------
+    
+        Parameters
+        ----------
+        file_output : NicePath
+            EN: Destination file to store the generated log.
+            FA: فایل مقصد برای ذخیره گزارش.
+    
+        search_name_contains : str | None
+            EN: Filter by substring in filename.
+            FA: فیلتر بر اساس بخشی از نام فایل.
+    
+        search_suffix : str | None
+            EN: Filter by file extension (e.g. ".py").
+            FA: فیلتر بر اساس پسوند فایل.
+    
+        search_stem : str | None
+            EN: Match exact filename without extension.
+            FA: تطابق دقیق نام فایل بدون پسوند.
+    
+        search_regex : str | None
+            EN: Apply regex pattern to filename.
+            FA: اعمال عبارت منظم روی نام فایل.
+    
+        search_only_files : bool, default=True
+            EN: Include only files in search results.
+            FA: فقط فایل‌ها در نتایج جستجو لحاظ شوند.
+    
+        search_only_dirs : bool, default=False
+            EN: Include only directories in search results.
+            FA: فقط پوشه‌ها در نتایج لحاظ شوند.
+    
+        search_recursive : bool, default=True
+            EN: Search subdirectories recursively.
+            FA: جستجوی بازگشتی در زیرپوشه‌ها.
+    
+        search_ignore_hidden : bool, default=True
+            EN: Ignore hidden files and folders.
+            FA: نادیده گرفتن فایل‌ها و پوشه‌های مخفی.
+    
+        safe_mode : bool, default=True
+            EN:
+                Enables protection limits:
+                    - max_files
+                    - max_file_size
+                    - ignore_venv
+            FA:
+                فعال‌سازی محدودیت‌های ایمنی شامل:
+                    - حداکثر تعداد فایل
+                    - حداکثر حجم فایل
+                    - نادیده گرفتن venv
+    
+        max_files : int, default=200
+            EN: Maximum number of files to log.
+            FA: حداکثر تعداد فایل قابل ثبت در گزارش.
+    
+        max_file_size : int, default=1_000_000 (1MB)
+            EN: Maximum file size allowed for reading (in bytes).
+            FA: حداکثر حجم فایل برای خواندن (بر حسب بایت).
+    
+        ignore_venv : bool, default=True
+            EN: Ignore 'venv' directories and their subtree.
+            FA: نادیده گرفتن پوشه venv و زیرمجموعه آن.
+    
+        encoding : str, default="utf-8"
+            EN: Encoding used when writing output file.
+            FA: نوع انکودینگ برای نوشتن فایل خروجی.
+    
+        ------------------------------------------------------------
+        
+        Warning
+        -------
+        EN:
+            Disabling safe_mode on very large projects may cause
+            high memory usage and long execution time.
+    
+        FA:
+            خاموش کردن safe_mode در پروژه‌های بسیار بزرگ
+            ممکن است باعث مصرف بالای حافظه و کندی سیستم شود.
+        
+        """
+        self._log_start("logAll")
+
+        try:
+            lines: list[str] = []
+
+            # ---------- Safety: find last existing parent ----------
+            path_to_use = self._path
+            while not path_to_use.exists() and path_to_use.parent != path_to_use:
+                path_to_use = path_to_use.parent
+
+            if path_to_use != self._path:
+                logger.warning(
+                    f"logAll: Path {self._path} not found, logging stopped at {path_to_use}"
+                )
+
+            # ---------- Tree ----------
+            tree_text = NicePath(path_to_use).tree(
+                recursive=True, ignore_hidden=not search_ignore_hidden
+            )
+            lines.append("Tree Structure:\n")
+            lines.append(tree_text + "\n\n")
+
+            # ---------- Search ----------
+            search_results = NicePath(path_to_use).search(
+                name_contains=search_name_contains,
+                suffix=search_suffix,
+                stem=search_stem,
+                regex=search_regex,
+                only_files=search_only_files,
+                only_dirs=search_only_dirs,
+                recursive=search_recursive,
+                ignore_hidden=search_ignore_hidden,
+            )
+
+            # Apply safety filters
+            total_size = 0
+            logged_files = 0
+            output_lines: list[str] = []
+
+            for f in search_results:
+                if ignore_venv and "venv" in f.path.parts:
+                    continue
+                if ignore_libs and "nicepy" in f.path.parts:
+                    continue
+
+                try:
+                    content = f.read()
+                except Exception as e:
+                    content = f"[Could not read: {e}]"
+
+                file_size = len(content.encode(encoding))
+                total_size += file_size
+                logged_files += 1
+
+                if logged_files > max_files:
+                    output_lines.append(
+                        f"[Safety Limit] Skipped remaining files, max_files={max_files}\n"
+                    )
+                    break
+                if total_size > max_total_size:
+                    output_lines.append(
+                        f"[Safety Limit] Max total_size reached, {max_total_size} bytes\n"
+                    )
+                    break
+
+                output_lines.append(f"{f.path} -> {content}\n")
+
+            if output_lines:
+                lines.append("Search Results:\n")
+                lines.extend(output_lines)
+            else:
+                lines.append("Search Results: None\n")
+
+            # ---------- Write to file ----------
+            file_output.write("".join(lines), encoding=encoding)
+
+            self._log_success("logAll")
+            return "".join(lines)
+        except Exception as e:
+            self._log_error("logAll", e)
+            raise NicePathError(f"logAll failed for {self._path}") from e
+    
+    # -------------------------
+    # Operator Overloads
+    # -------------------------
+
+    def __truediv__(self, other: str) -> "NicePath":
+        """
+        Path division operator / استفاده از / برای ساخت مسیر جدید
+        """
+        return NicePath(self._path / other)
+
+    def __str__(self) -> str:
+        return str(self._path)
+
+    def __repr__(self) -> str:
+        return f"NicePath({self._path})"

nicepy/nicepath/exceptios.py

@@ -0,0 +1,28 @@
+
+# -------------------------
+# Costume Expertions
+# -------------------------
+
+class NicePathError(Exception):
+    """Base exception for nicepath"""
+
+
+class PathNotFoundError(NicePathError):
+    pass
+
+
+class NotAFileError(NicePathError):
+    pass
+
+
+class NotADirectoryError(NicePathError):
+    pass
+
+
+class WriteError(NicePathError):
+    pass
+
+
+class DeleteError(NicePathError):
+    pass
+

nicepython-0.1.0.dist-info/METADATA

@@ -0,0 +1,320 @@
+Metadata-Version: 2.4
+Name: nicepython
+Version: 0.1.0
+Summary: Advanced OOP file and directory management library with powerful search, logging and chainable file operations.
+Author-email: amin13m <aminm13aminm@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/amin13m/nicepy
+Project-URL: Repository, https://github.com/amin13m/nicepy
+Project-URL: Issues, https://github.com/amin13m/nicepy/issues
+Keywords: pathlib,filesystem,path,file,search,logging,oop
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: license
+Dynamic: license-file
+
+Tired of writing hundreds of lines with pathlib's verbose syntax? 🤯
+
+Meet NicePath.
+
+A clean OOP path object with dozens of short, chainable methods and properties.
+
+No try/except boilerplate.
+Just .read(), .write(), .move_to() … and it works.
+
+✨ Smart search
+🌳 Tree visualization
+📝 Automatic logging of hundreds of files with a single method
+
+Less code. More clarity.
+
+------------------------------------------------------------
+
+🚀 NicePy
+
+Advanced OOP File & Directory Management Library for Python
+Built on top of pathlib with logging, search engine, tree view and smart utilities.
+
+------------------------------------------------------------
+
+✨ Why NicePy?
+
+NicePath is a powerful wrapper around Python’s built-in pathlib, designed to make file management:
+
+✔ Cleaner
+✔ More readable
+✔ More powerful
+✔ Fully logged
+✔ Searchable
+✔ Tree-view ready
+
+------------------------------------------------------------
+
+📦 Installation
+
+🔹 Local Development Mode
+
+pip install -e .
+
+🔹 Future PyPI Installation
+
+pip install nicepython
+
+------------------------------------------------------------
+
+🚀 Quick Start
+
+from nicepy import NicePath
+
+# Create path
+p = NicePath("example.txt")
+
+# Write data
+p.write("Hello NicePy!")
+
+# Read data
+print(p.read())
+
+# Append
+p.append("\nNew Line")
+
+# Show tree
+root = NicePath(".")
+print(root.tree())
+
+# Search files
+for f in root.search(suffix=".py"):
+    print(f.path)
+
+------------------------------------------------------------
+
+🌳 Tree Visualization
+
+root = NicePath("my_project")
+print(root.tree(ignore_hidden=False))
+
+Example Output:
+
+my_project
+├── main.py
+├── nicepy
+│   ├── core.py
+└── README.md
+
+------------------------------------------------------------
+
+🔎 Advanced Search
+
+root.search(
+    name_contains="core",
+    suffix=".py",
+    recursive=True,
+    ignore_hidden=True
+)
+
+Supported Filters:
+
+- name_contains
+- suffix
+- stem
+- regex
+- only_files
+- only_dirs
+- recursive
+- ignore_hidden
+
+If nothing is found → returns [] (never raises error)
+
+------------------------------------------------------------
+
+🧾 logAll – Full Project Logger
+
+Generate:
+- Full tree structure
+- Content of matched files
+- Save everything into a file
+
+project = NicePath("my_project")
+output = NicePath("log.txt")
+
+project.logAll(
+    file_output=output,
+    search_suffix=".py"
+)
+
+Useful for:
+- Project snapshot
+- Debug logging
+- Code export
+- Archiving structure
+
+------------------------------------------------------------
+
+📚 Available Methods
+
+write(data)              → Write text to file
+read()                   → Read file content
+append(data)             → Append to file
+delete()                 → Remove file or directory
+copy_to(dest)            → Copy file/folder
+move_to(dest)            → Move file/folder
+search(...)              → Smart search engine
+tree(...)                → Visual tree display
+logAll(...)              → Full structured log export
+
+Properties:
+exists
+is_file
+is_dir
+size
+created_time
+modified_time
+
+------------------------------------------------------------
+
+⚖ NicePy vs pathlib
+
+Feature                        | pathlib | NicePy
+------------------------------------------------------------
+Basic read/write               | Yes     | Yes
+Append built-in                | No      | Yes
+Tree view                      | No      | Yes
+Search engine                  | No      | Yes
+Regex search                   | No      | Yes
+Logging system                 | No      | Yes
+Full project log export        | No      | Yes
+Unified OOP interface          | Basic   | Advanced
+Custom exceptions              | No      | Yes
+
+------------------------------------------------------------
+
+## ⚠️ Safety Limits in NicePath
+
+NicePath library includes powerful methods like logAll, tree, and search that can traverse large directories or read/write many files.
+
+To prevent accidental overloads, these methods have default safety limits:
+
+- logAll: limits the maximum number of files and total size it processes.
+  - Default max_files=500
+  - Default max_total_size=10_000_000 bytes (10 MB)
+- tree and search:
+  - Can ignore virtual environments and library folders (ignore_venv=True by default)
+  - Can limit recursion depth or number of entries if needed.
+
+Behavior when limits are reached:
+
+- The operation does not crash.
+- Partial results are written to the output file.
+- A warning message is logged with logger.warning stating that safety limits were reached.
+
+Customizing Safety:
+
+You can override safety defaults in method calls:
+
+`python
+dir = NicePath("D:/Projects")
+output_file = dir / "log.txt"
+
+dir.logAll(
+    file_output=output_file,
+    search_suffix=".py",
+    max_files=1000,          # increase limit
+    max_total_size=50_000_000, # 50 MB
+    ignore_venv=False         # include virtual environments
+)
+
+🛠 Logging System
+
+All critical operations are logged:
+
+- Start
+- Success
+- Failure
+- Error reason
+
+Helps debugging and production stability.
+
+------------------------------------------------------------
+
+🧪 Testing
+
+pytest -v
+
+------------------------------------------------------------
+
+🏗 Project Structure
+
+nicepy_python
+├── pycache
+│   ├── init.pythonc
+│   └── main.cpython-314.pyc
+├── nicepy
+│   ├── pycache
+│   │   ├── init.pyc
+│   │   └── logger.cpython-314.pyc
+│   ├── nicepath
+│   │   ├── pycache
+│   │   │   ├── init.pyc
+│   │   │   ├── core.cpython-314.pyc
+│   │   │   └── exceptios.cpython-314.pyc
+│   │   ├── init.py
+│   │   ├── core.py
+│   │   └── exceptios.py
+│   ├── init.py
+│   └── logger.py
+├── nicepy.egg-info
+│   ├── dependency_links.txt
+│   ├── PKG-INFO
+│   ├── SOURCES.txt
+│   └── top_level.txt
+├── tests
+│   ├── pycache
+│   │   ├── test_nicepath.cpython-314-pytest-9.0.2.pyc
+│   │   └── test_nicepath.cpython-314.pyc
+│   ├── newfolder
+│   │   ├── ksc.txt
+│   │   ├── tet.txt
+│   │   └── text.txt
+│   └── test_nicepath.py
+├── init.py
+├── main.py
+├── pyproject.toml
+└── README.md
+
+------------------------------------------------------------
+
+🔮 Roadmap
+
+[ ] PyPI release
+[ ] Async support
+[ ] Caching search engine
+[ ] Watchdog integration
+[ ] Colored tree output
+[ ] CLI interface
+
+------------------------------------------------------------
+
+👤 Author
+
+Amin
+GitHub: https://github.com/amin13m
+
+------------------------------------------------------------
+
+📜 License
+
+MIT License
+
+------------------------------------------------------------
+
+💎 Philosophy
+
+Clean code.
+Predictable behavior.
+Zero surprise file handling.

nicepython-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+nicepy/__init__.py,sha256=Jp-5qqGmZu3ATFx3OB22gOEDkclQP_UEgrb0qV5uDNI,123
+nicepy/logger.py,sha256=PZb0abNyg8ufKekUX-P4A85ypA0zztkb6Vn7McXnHpE,1414
+nicepy/nicepath/__init__.py,sha256=Mh94eCfVVfNHYg03UzvHAh1-wbua6Sy_IsIQhGfs-So,26
+nicepy/nicepath/core.py,sha256=ofpekMNs4-NV9LTSK6hPF-VjiLcrMn1j770QkFNBSxQ,26383
+nicepy/nicepath/exceptios.py,sha256=CqXucAoDn9IsGYMpdddO11tXLLHFE7nrfMOc-p65Jjg,417
+nicepython-0.1.0.dist-info/licenses/license,sha256=wq4_Pe5i7o3kBG_NJJBio60kQaRFalOYHYxFPC9MleA,378
+nicepython-0.1.0.dist-info/METADATA,sha256=w75FjEk4KrP-KvqfIrX8ukhmqXDXfZYjI-drEGKj3TA,8041
+nicepython-0.1.0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+nicepython-0.1.0.dist-info/top_level.txt,sha256=YIbxzgo9858-SzJJHZcjdqzzXxIiSx3OvljR_aPZ7r8,7
+nicepython-0.1.0.dist-info/RECORD,,

nicepython-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

nicepython-0.1.0.dist-info/licenses/license

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 amin13m
+
+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.

nicepython-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+nicepy