arrangelt 0.3.1

A Python library for sorting and organizing files into usable lists or dictionaries.

ArrangeLT

Overview

ArrangeLT is a Python library designed to help users quickly and efficiently organize files in a directory into lists and dictionaries. It provides functionality to sort files alphabetically, by extensions, and by size.

Installation

To install the library, you can use pip. Run:

pip install arrangelt

Usage

Here is a simple example of how to use the library:

Sorting Files Alphabetically

from arrangelt import alth_sort

# Sort files alphabetically in ascending order (default)
sorted_files = alth_sort("path/to/directory", style="asc", include_path=True)
print(sorted_files)

# Sort files alphabetically in descending order
sorted_files = alth_sort("path/to/directory", style="desc", include_path=False)
print(sorted_files)

Grouping Files by Extension

from arrangelt import ext_sort

# Group files by their extensions
grouped_files = ext_sort("path/to/directory", include_path=True)
print(grouped_files)

# Group files by their extensions, excluding specific types (e.g., .tmp and .log)
grouped_files = ext_sort("path/to/directory", exclude_types=[".tmp", ".log"], include_path=False)
print(grouped_files)

# Group files by their extensions, including only specific types (e.g., .txt and .csv)
grouped_files = ext_sort("path/to/directory", include_types=[".txt", ".csv"], include_path=True)
print(grouped_files)

Categorizing Files by Size

from arrangelt import size_sort

# Categorize files by size using default size categories
size_categories = {
    "small": (0, 10 * 1024 * 1024),   # Files smaller than 10 MB
    "medium": (10 * 1024 * 1024, 100 * 1024 * 1024),  # Files between 10 MB and 100 MB
    "large": (100 * 1024 * 1024, 1 * 1024 * 1024 * 1024),  # Files between 100 MB and 1 GB
    "extra_large": (1 * 1024 * 1024 * 1024, float('inf'))  # Files larger than 1 GB
}

categorized_files = size_sort("path/to/directory", size_categories=size_categories, include_path=True)
print(categorized_files)

# Example output:
# {
#     "small": ["path/to/directory/file1.txt"],
#     "medium": ["path/to/directory/file2.txt"],
#     "large": ["path/to/directory/file3.txt"],
#     "extra_large": ["path/to/directory/file4.txt"]
# }

Features

• Alphabetical Sorting:

  • Sort files in ascending or descending order by their names.
  • Option to include or exclude the full file path in the output.

• Extension Grouping:

  • Group files by their extensions.
  • Option to include or exclude the full file path in the output.
  • Include only specific file types or exclude specific file types.

• Size Categorization:

  • Categorize files into size-based groups (e.g., small, medium, large).
  • Fully customizable size categories.
  • Option to include or exclude the full file path in the output.

• Recursive Behavior:

  • Allows for the specification of a depth for a recursive search. If left alone no subfolders are searched, 0 = Unlimited depth, 1 = Root and immediate sub folders, 2 = Root plus a depth of two sub folders, and so on.

• Error Handling:

  • Provides clear error messages for invalid paths, permissions, and other issues.

• Non-File Handling:

  • Automatically ignores non-file items (e.g., directories, symbolic links) when sorting or categorizing.

License

This project is licensed under the Apache-2.0 License - see the LICENSE file for details.

Changelog

[v0.3.1] - 02-04-2025

Added

• Added support for recursive file searching with a depth parameter for alth_sort, ext_sort, and size_sort.

Changed

• Replaced glob with os.scandir for better control over file traversal.

[v0.2.0] - 02-04-2025

Added

• Introduced the size_sort function to categorize files based on their sizes.

[v0.1.0] - 01-04-2025

Added

• Initial release with alth_sort for alphabetical sorting of files.
• Added ext_sort for grouping files by their extensions.