nicepython 0.1.0__tar.gz

nicepython-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,299 @@
+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/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/nicepy/__init__.py

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

nicepython-0.1.0/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}")

nicepython-0.1.0/nicepy/nicepath/__init__.py

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