# doFolder
[](https://badge.fury.io/py/doFolder) [](https://github.com/kuankuan2007/do-folder)  [](./LICENSE) [](https://do-folder.doc.kuankuan.site)
**doFolder** is a powerful, intuitive, and cross-platform file system management library that provides a high-level, object-oriented interface for working with files and directories. Built on Python's `pathlib`, it simplifies common file operations while offering advanced features like hashing, content manipulation, and directory tree operations.
## ✨ Key Features
- **🎯 Object-oriented Design**: Work with files and directories as Python objects
- **🌐 Cross-platform Compatibility**: Seamlessly works on Windows, macOS, and Linux
- **🛤️ Advanced Path Handling**: Built on Python's pathlib for robust path management
- **📁 Complete File Operations**: Create, move, copy, delete, and modify files and directories
- **📝 Content Management**: Read and write file content with encoding support
- **🌳 Directory Tree Operations**: Navigate and manipulate directory structures
- **🔍 File Comparison**: Compare files and directories with various comparison modes
- **🔒 Hash Support**: Generate and verify file hashes for integrity checking
- **⚠️ Flexible Error Handling**: Comprehensive error modes for different use cases
- **🏷️ Type Safety**: Full type hints for better IDE support and code reliability
## 📦 Installation
```bash
pip install doFolder
```
**Requirements:** Python 3.8+
## 🚀 Quick Start
```python
from doFolder import File, Directory, ItemType
# Create directory and file objects
project_dir = Directory("./my_project")
config_file = project_dir["config.json"]
# Create a new file in the directory
readme = project_dir.create("README.md", ItemType.FILE)
readme_zh = project_dir.createFile("README.zh-cn.md")
# Write content to the file
readme.content = "# My Project\n\nWelcome to my project!".encode("utf-8")
# Create a subdirectory
src_dir = project_dir.create("src", ItemType.DIR)
# Copy and move files
backup_config = config_file.copy("./backup/")
config_file.move("./settings/")
# List directory contents
for item in project_dir:
print(f"{item.name} ({'Directory' if item.isDir else 'File'})")
```
## 📖 Usage Examples
### Working with Files
```python
from doFolder import File
# Create a file object
file = File("data.txt")
# Work with binary content
print(file.content) # Reads content as bytes
file.content = "Binary data here".encode("utf-8") # Writes content as bytes
# JSON operations
file.saveAsJson({"name": "John", "age": 30})
data = file.loadAsJson()
# Quickly open file
with file.open("w", encoding="utf-8") as f:
f.write("Hello, World!")
# File information
print(f"Size: {file.state.st_size} bytes")
print(f"Modified: {file.state.st_mtime}")
# File hashing
print(f"Hash: {file.hash()}")
```
### Working with Directories
```python
from doFolder import Directory, ItemType
# Create a directory object
d = Directory("./workspace")
# Create nested directory structure
d.create("src/utils", ItemType.DIR)
d.create("tests", ItemType.DIR)
d.createDir("docs")
d.createFile("README.md")
# Create files
main_file = d.create("src/main.py", ItemType.FILE)
test_file = d.create("tests/test_main.py", ItemType.FILE)
# List all items (non-recursive)
for item in d:
print(item.path)
# List all items recursively
for item in d.recursiveTraversal(hideDirectory=False):
print(f"{'📁' if item.isDir else '📄'} {item.path}")
# Find specific sub items
py_files = ['__init__.py']
```
### Advanced Operations
```python
from doFolder import File, Directory, compare
# File comparison
file1 = File("version1.txt")
file2 = File("version2.txt")
if compare.compare(file1, file2):
print("Files are identical")
else:
print("Files differ")
# Directory comparison
dir1 = Directory("./project_v1")
dir2 = Directory("./project_v2")
diff=getDifference(dir1, dir2)
# Hash verification
file = File("important_data.txt")
original_hash = file.hash()
# ... file operations ...
if file.hash() == original_hash:
print("File integrity verified")
# Safe operations with error handling
from doFolder import UnExistsMode
safe_file = File("might_not_exist.txt", unExists=UnExistsMode.CREATE)
# File will be created if it doesn't exist
```
### Path Utilities
```python
from doFolder import Path
# Enhanced path operations
path = Path("./documents/projects/my_app/src/main.py")
print(f"Project root: {path.parents[3]}") # ./documents/projects/my_app
print(f"Relative to project: {path.relative_to_parent(3)}") # src/main.py
print(f"Extension: {path.suffix}") # .py
print(f"Filename: {path.stem}") # main
# Path manipulation
config_path = path.sibling("config.json") # Same directory, different file
backup_path = path.with_name(f"{path.stem}_backup{path.suffix}")
```
## 🔧 Advanced Features
### Error Handling Modes
doFolder provides flexible error handling through `UnExistsMode`:
```python
from doFolder import File, UnExistsMode
# Different modes for handling non-existent files
file1 = File("missing.txt", unExistsMode=UnExistsMode.ERROR) # Raises exception
file2 = File("missing.txt", unExistsMode=UnExistsMode.WARN) # Issues warning
file3 = File("missing.txt", unExistsMode=UnExistsMode.IGNORE) # Silent handling
file4 = File("missing.txt", unExistsMode=UnExistsMode.CREATE) # Creates if missing
```
### File System Item Types
```python
from doFolder import ItemType, createItem
# Factory function to create appropriate objects
item1 = createItem("./some_path", ItemType.FILE) # Creates File object
item2 = createItem("./some_path", ItemType.DIR) # Creates Directory object
item3 = createItem("./some_path") # Auto-detects type
```
## 🔄 Migration from v1.x.x
doFolder v2.x.x introduces several improvements while maintaining backward compatibility:
- **Enhanced Path Management**: Now uses Python's built-in `pathlib`
- **Renamed Classes**: `Folder` → `Directory` (backward compatibility maintained)
- **Flexible File Creation**: `File` class can handle directory paths with redirection
- **Improved Type Safety**: Full type hints throughout the codebase
### Migration Example
```python
# v1.x.x style (still works)
from doFolder import Folder
folder = Folder("./my_directory")
# v2.x.x recommended style
from doFolder import Directory
directory = Directory("./my_directory")
# Both work identically!
```
## 📚 Documentation
- **Full API Documentation**: [https://do-folder.doc.kuankuan.site](https://do-folder.doc.kuankuan.site)
- **GitHub Repository**: [https://github.com/kuankuan2007/do-folder](https://github.com/kuankuan2007/do-folder)
- **Issue Tracker**: [https://github.com/kuankuan2007/do-folder/issues](https://github.com/kuankuan2007/do-folder/issues)
## 🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
## 📄 License
This project is licensed under the [MulanPSL-2.0 License](./LICENSE) - see the LICENSE file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "doFolder",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "folder, file, manage, filesystem, directory",
"author": null,
"author_email": "kuankuan <2163826131@qq.com>",
"download_url": "https://files.pythonhosted.org/packages/5c/8c/10a0d1fc4e2e63194c998ce122e689b9ed4f5b68ce47f96d901fb7255094/dofolder-2.2.5.tar.gz",
"platform": null,
"description": "# doFolder\n\n[](https://badge.fury.io/py/doFolder) [](https://github.com/kuankuan2007/do-folder)  [](./LICENSE) [](https://do-folder.doc.kuankuan.site)\n\n**doFolder** is a powerful, intuitive, and cross-platform file system management library that provides a high-level, object-oriented interface for working with files and directories. Built on Python's `pathlib`, it simplifies common file operations while offering advanced features like hashing, content manipulation, and directory tree operations.\n\n## \u2728 Key Features\n\n- **\ud83c\udfaf Object-oriented Design**: Work with files and directories as Python objects\n- **\ud83c\udf10 Cross-platform Compatibility**: Seamlessly works on Windows, macOS, and Linux\n- **\ud83d\udee4\ufe0f Advanced Path Handling**: Built on Python's pathlib for robust path management\n- **\ud83d\udcc1 Complete File Operations**: Create, move, copy, delete, and modify files and directories\n- **\ud83d\udcdd Content Management**: Read and write file content with encoding support\n- **\ud83c\udf33 Directory Tree Operations**: Navigate and manipulate directory structures\n- **\ud83d\udd0d File Comparison**: Compare files and directories with various comparison modes\n- **\ud83d\udd12 Hash Support**: Generate and verify file hashes for integrity checking\n- **\u26a0\ufe0f Flexible Error Handling**: Comprehensive error modes for different use cases\n- **\ud83c\udff7\ufe0f Type Safety**: Full type hints for better IDE support and code reliability\n\n## \ud83d\udce6 Installation\n\n```bash\npip install doFolder\n```\n\n**Requirements:** Python 3.8+\n\n## \ud83d\ude80 Quick Start\n\n```python\nfrom doFolder import File, Directory, ItemType\n\n# Create directory and file objects\nproject_dir = Directory(\"./my_project\")\nconfig_file = project_dir[\"config.json\"]\n\n# Create a new file in the directory\nreadme = project_dir.create(\"README.md\", ItemType.FILE)\nreadme_zh = project_dir.createFile(\"README.zh-cn.md\")\n\n# Write content to the file\nreadme.content = \"# My Project\\n\\nWelcome to my project!\".encode(\"utf-8\")\n\n# Create a subdirectory\nsrc_dir = project_dir.create(\"src\", ItemType.DIR)\n\n# Copy and move files\nbackup_config = config_file.copy(\"./backup/\")\nconfig_file.move(\"./settings/\")\n\n# List directory contents\nfor item in project_dir:\n print(f\"{item.name} ({'Directory' if item.isDir else 'File'})\")\n```\n\n## \ud83d\udcd6 Usage Examples\n\n### Working with Files\n\n```python\nfrom doFolder import File\n\n# Create a file object\nfile = File(\"data.txt\")\n\n# Work with binary content\nprint(file.content) # Reads content as bytes\nfile.content = \"Binary data here\".encode(\"utf-8\") # Writes content as bytes\n\n# JSON operations\nfile.saveAsJson({\"name\": \"John\", \"age\": 30})\ndata = file.loadAsJson()\n\n# Quickly open file\nwith file.open(\"w\", encoding=\"utf-8\") as f:\n f.write(\"Hello, World!\")\n\n\n# File information\nprint(f\"Size: {file.state.st_size} bytes\")\nprint(f\"Modified: {file.state.st_mtime}\")\n\n# File hashing\nprint(f\"Hash: {file.hash()}\")\n```\n\n### Working with Directories\n\n```python\nfrom doFolder import Directory, ItemType\n\n# Create a directory object\nd = Directory(\"./workspace\")\n\n# Create nested directory structure\nd.create(\"src/utils\", ItemType.DIR)\nd.create(\"tests\", ItemType.DIR)\nd.createDir(\"docs\")\nd.createFile(\"README.md\")\n\n# Create files\nmain_file = d.create(\"src/main.py\", ItemType.FILE)\ntest_file = d.create(\"tests/test_main.py\", ItemType.FILE)\n\n# List all items (non-recursive)\nfor item in d:\n print(item.path)\n\n# List all items recursively\nfor item in d.recursiveTraversal(hideDirectory=False):\n print(f\"{'\ud83d\udcc1' if item.isDir else '\ud83d\udcc4'} {item.path}\")\n\n# Find specific sub items\npy_files = ['__init__.py']\n```\n\n### Advanced Operations\n\n```python\nfrom doFolder import File, Directory, compare\n\n# File comparison\nfile1 = File(\"version1.txt\")\nfile2 = File(\"version2.txt\")\n\nif compare.compare(file1, file2):\n print(\"Files are identical\")\nelse:\n print(\"Files differ\")\n\n# Directory comparison\ndir1 = Directory(\"./project_v1\")\ndir2 = Directory(\"./project_v2\")\n\ndiff=getDifference(dir1, dir2)\n\n# Hash verification\nfile = File(\"important_data.txt\")\noriginal_hash = file.hash()\n# ... file operations ...\nif file.hash() == original_hash:\n print(\"File integrity verified\")\n\n# Safe operations with error handling\nfrom doFolder import UnExistsMode\n\nsafe_file = File(\"might_not_exist.txt\", unExists=UnExistsMode.CREATE)\n# File will be created if it doesn't exist\n```\n\n### Path Utilities\n\n```python\nfrom doFolder import Path\n\n# Enhanced path operations\npath = Path(\"./documents/projects/my_app/src/main.py\")\n\nprint(f\"Project root: {path.parents[3]}\") # ./documents/projects/my_app\nprint(f\"Relative to project: {path.relative_to_parent(3)}\") # src/main.py\nprint(f\"Extension: {path.suffix}\") # .py\nprint(f\"Filename: {path.stem}\") # main\n\n# Path manipulation\nconfig_path = path.sibling(\"config.json\") # Same directory, different file\nbackup_path = path.with_name(f\"{path.stem}_backup{path.suffix}\")\n```\n\n## \ud83d\udd27 Advanced Features\n\n### Error Handling Modes\n\ndoFolder provides flexible error handling through `UnExistsMode`:\n\n```python\nfrom doFolder import File, UnExistsMode\n\n# Different modes for handling non-existent files\nfile1 = File(\"missing.txt\", unExistsMode=UnExistsMode.ERROR) # Raises exception\nfile2 = File(\"missing.txt\", unExistsMode=UnExistsMode.WARN) # Issues warning\nfile3 = File(\"missing.txt\", unExistsMode=UnExistsMode.IGNORE) # Silent handling\nfile4 = File(\"missing.txt\", unExistsMode=UnExistsMode.CREATE) # Creates if missing\n```\n\n### File System Item Types\n\n```python\nfrom doFolder import ItemType, createItem\n\n# Factory function to create appropriate objects\nitem1 = createItem(\"./some_path\", ItemType.FILE) # Creates File object\nitem2 = createItem(\"./some_path\", ItemType.DIR) # Creates Directory object\nitem3 = createItem(\"./some_path\") # Auto-detects type\n```\n\n## \ud83d\udd04 Migration from v1.x.x\n\ndoFolder v2.x.x introduces several improvements while maintaining backward compatibility:\n\n- **Enhanced Path Management**: Now uses Python's built-in `pathlib`\n- **Renamed Classes**: `Folder` \u2192 `Directory` (backward compatibility maintained)\n- **Flexible File Creation**: `File` class can handle directory paths with redirection\n- **Improved Type Safety**: Full type hints throughout the codebase\n\n### Migration Example\n\n```python\n# v1.x.x style (still works)\nfrom doFolder import Folder\nfolder = Folder(\"./my_directory\")\n\n# v2.x.x recommended style\nfrom doFolder import Directory\ndirectory = Directory(\"./my_directory\")\n\n# Both work identically!\n```\n\n## \ud83d\udcda Documentation\n\n- **Full API Documentation**: [https://do-folder.doc.kuankuan.site](https://do-folder.doc.kuankuan.site)\n- **GitHub Repository**: [https://github.com/kuankuan2007/do-folder](https://github.com/kuankuan2007/do-folder)\n- **Issue Tracker**: [https://github.com/kuankuan2007/do-folder/issues](https://github.com/kuankuan2007/do-folder/issues)\n\n## \ud83e\udd1d Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the [MulanPSL-2.0 License](./LICENSE) - see the LICENSE file for details.\n",
"bugtrack_url": null,
"license": null,
"summary": "Manage files more easily",
"version": "2.2.5",
"project_urls": {
"Documentation": "https://do-folder.doc.kuankuan.site",
"Issues": "https://github.com/kuankuan2007/do-folder/issues",
"Repository": "https://github.com/kuankuan2007/do-folder"
},
"split_keywords": [
"folder",
" file",
" manage",
" filesystem",
" directory"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "191140de032422f3fcdbb2cdefcae7adcb23de8b373fc5dec86b4c171c4db6d2",
"md5": "b56817c90007152799977e05d783fa0e",
"sha256": "df0fb3a143d2b49c81f84344d7a97562c05f1766c60ed89ac44fce3307c6f6f8"
},
"downloads": -1,
"filename": "dofolder-2.2.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b56817c90007152799977e05d783fa0e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 35973,
"upload_time": "2025-08-17T05:38:06",
"upload_time_iso_8601": "2025-08-17T05:38:06.644424Z",
"url": "https://files.pythonhosted.org/packages/19/11/40de032422f3fcdbb2cdefcae7adcb23de8b373fc5dec86b4c171c4db6d2/dofolder-2.2.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5c8c10a0d1fc4e2e63194c998ce122e689b9ed4f5b68ce47f96d901fb7255094",
"md5": "d4133cb590fce420f2d5d119a98eb387",
"sha256": "9e8cd44ed80e38b54cc29be84ffc2844904436e910a2f3644c94a40045949928"
},
"downloads": -1,
"filename": "dofolder-2.2.5.tar.gz",
"has_sig": false,
"md5_digest": "d4133cb590fce420f2d5d119a98eb387",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 36315,
"upload_time": "2025-08-17T05:38:08",
"upload_time_iso_8601": "2025-08-17T05:38:08.227099Z",
"url": "https://files.pythonhosted.org/packages/5c/8c/10a0d1fc4e2e63194c998ce122e689b9ed4f5b68ce47f96d901fb7255094/dofolder-2.2.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-17 05:38:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kuankuan2007",
"github_project": "do-folder",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "deprecated",
"specs": []
},
{
"name": "types-Deprecated",
"specs": []
},
{
"name": "typing_extensions",
"specs": [
[
">=",
"4.10.0"
]
]
},
{
"name": "exceptiongroup",
"specs": []
},
{
"name": "pytest",
"specs": []
},
{
"name": "pylint",
"specs": []
},
{
"name": "build",
"specs": []
},
{
"name": "rich",
"specs": []
}
],
"lcname": "dofolder"
}
JSON
