GitHub - ghetea-patrick/filorithm: A fluent Python eDSL for high-level directory manipulation. It utilizes chainable filtering pipelines and intuitive operator overloading to replace boilerplate file system code with clean terminal-like actions. · GitHub
/" data-turbo-transient="true" />
Skip to content
Search or jump to...
Search code, repositories, users, issues, pull requests...
-->
Search
Clear
Search syntax tips
Provide feedback
--><br>We read every piece of feedback, and take your input very seriously.
Include my email address so I can be contacted
Cancel
Submit feedback
Saved searches
Use saved searches to filter your results more quickly
-->
Name
Query
To see all available qualifiers, see our documentation.
Cancel
Create saved search
Sign in
/;ref_cta:Sign up;ref_loc:header logged out"}"<br>Sign up
Appearance settings
Resetting focus
You signed in with another tab or window. Reload to refresh your session.<br>You signed out in another tab or window. Reload to refresh your session.<br>You switched accounts on another tab or window. Reload to refresh your session.
Dismiss alert
{{ message }}
ghetea-patrick
filorithm
Public
Notifications<br>You must be signed in to change notification settings
Fork
Star
main
BranchesTags
Go to file
CodeOpen more actions menu
Folders and files<br>NameNameLast commit message<br>Last commit date<br>Latest commit
History<br>11 Commits<br>11 Commits
filorithm
filorithm
.gitignore
.gitignore
LICENSE
LICENSE
README.md
README.md
View all files
Repository files navigation
filorithm
Filorithm is an expressive Python embedded Domain Specific Language (eDSL) designed for high-level file and folder manipulation. By utilizing operator overloading and chainable filtering interfaces, Filorithm abstracts the verbose complexities of standard libraries like os, shutil, and pathlib into clean, intuitive pipeline operations.
Abstract & Architecture
Filorithm operates on the concept of wrapping directory contents into managed collection objects (Files and Folders). Instead of executing procedural function calls, workflows are declared using fluent filter interfaces and completed using standard operators that mimic terminal actions.
The framework is split into distinct components:
storage.py: The underlying engine handling safe path validation, file copy/move operations, and strict error handling.
files.py / folders.py: The user-facing API containing collection wrappers and the fluent filter classes (FilterFiles, FilterFolders).
file_types.py: Constant tuples grouping common extensions (e.g., CODE_INTERPRETED, DATA, IMAGES) for rapid batch processing.
Syntax Rules & Operators
Filorithm overrides standard Python operators to execute file system tasks directly on collection objects or evaluated filters:
>> (Right-shift): Moves items in the collection to a destination directory.
@ (Matmul): Copies items in the collection to a destination directory.
~ (Invert / Unary tilde): Deletes all items in the collection permanently.
Pipeline Rules:
Instantiating Files("dir") or Folders("dir") gathers all immediate items inside that directory.
Invoking the .filter() method transitions the collection into an evaluation state.
Filtering methods can be chained infinitely (e.g., .bigger_than().with_extensions()).
The pipeline MUST be closed with .collect() before an operator (>>, @, ~) can be applied to the filtered subset.
To directly inspect or iterate over the elements without executing a filesystem mutation (move, copy, or delete), access the raw contents via list iteration, index lookup, or by calling .collect().
API Reference & Filter Methods
Collection Initializers
Files(directory: str | Path, *, overwrite: bool = False)
Folders(directory: str | Path, *, overwrite: bool = False)
If overwrite=True, any existing file or folder at the target destination with a conflicting name will be removed before the copy or move operation executes.
Chainable Filter Pipeline
Calling .filter() exposes the following evaluation constraints:
Size Constraints:
.bigger_than(size: int, unit: SizeUnit)
.smaller_than(size: int, unit: SizeUnit)
.between_sizes(min_size: int, min_unit: SizeUnit, max_size: int, max_unit: SizeUnit)
Supported Units: "kb", "mb", "gb", "tb"
String Matching Constraints:
.name_startswith(prefix: str)
.name_endswith(suffix: str)
.name_contains(text: str)
.name_matches(regex: str | Pattern)
Metadata & Quantity Constraints:
.modified_after(dt: datetime)
.modified_before(dt: datetime)
.largest(count: int)
.smallest(count: int)
.top(count: int)
.last(count: int)
Extension Specifics (Files Only):
.with_extensions(extensions: Sequence[str])
.without_extensions(extensions: Sequence[str])
Examples
>) syntax wrapper.
Files("staging_area") >> "processing_vault"
# ==============================================================================<br># EXAMPLE 2: Size Filtering and Copying Assets<br>#...