arrangelt 0.3.2
A Python library for sorting and organizing files into usable lists or dictionaries.
License: Apache License 2.0
Requires Python: >=3.6

# 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
```python
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
```python
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
```python
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.2] - 02-04-2025
### Fixed
- Fixed detrimental error when encountering a symbolic link loop. Now skips symbolic links or directories that will cause an infinite loop. Also skips unreachable folders that throw errors.

## [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.