fileutils-dir 0.8.5

Small utilities for listing files in directories

fileutils

fileutils is a minimalist Python library for selecting files from directories using a fluent, chainable API.

It is designed as a feeder tool for application pipelines — helping you declaratively select the right set of file paths to hand off to downstream processing.

---

Scope & Non-Goals

fileutils is intentionally limited in scope.

It does NOT:

• modify the filesystem
• delete, move, or rename files
• parse file contents
• perform cleanup or disk management

It DOES:

• traverse directories
• filter files by name, extension, or semantic type
• return predictable, composable sets of paths

---

Installation

pip install fileutils-dir

Core Concept

The primary entry point is in_dir(), which returns a DirQuery object.

You progressively narrow a candidate set of files using chainable selectors, then execute the query.

from fileutils import in_dir

files = (
    in_dir("src")
    .recursive()
    .include_type("code")
    .include_ext("py")
    .exclude_ext("log")
    .list()

This produces a list of file paths suitable for further processing.

Basic Usage

List Files in a Directory

files = in_dir().list()

Filter by Extension

python_files = in_dir().include_ext("py").list()

web_files = in_dir().include_ext("html", "css", "js").list()

Semantic Filtering (Types)

Instead of manually listing extensions, you can filter by semantic category.

media = in_dir().include_type("image", "video").list()

data_files = in_dir("data").include_type("data").count()

Recursive Traversal

files = (
    in_dir("project")
    .recursive()
    .list()
)

Hidden Files

files = (
    in_dir("project")
    .recursive()
    .show_hidden()
    .list()
)

Directory-Only Queries

folders = in_dir().dirs().list()

Include & Exclude Rules

Selectors are monotonic and composable.

• include_* narrows the candidate set
• exclude_* removes matches from the candidate set

files = (
    in_dir()
    .include_type("image")
    .exclude_ext("png")
    .list()
)

If a file matches both an include and an exclude filter, it is excluded.

Directory Trees

Generate a nested dictionary representation of the directory structure.

tree = in_dir("src").recursive().tree()

This is a structural view and does not modify the filesystem.

---

API Reference

in_dir(path=".")

Initializes a DirQuery object for a target directory.

• Validates that the path exists and is a directory
• Defaults to "." if no path is provided

DirQuery Methods

Selection

• .name(pattern) – Sets the glob pattern for discovery (e.g., "*.py")
• .include_ext(*exts) – Filter to include specific extensions
• .exclude_ext(*exts) – Filter to exclude specific extensions
• .include_type(*types) – Filter to include semantic file categories
• .exclude_type(*types) – Filter to exclude semantic file categories

Traversal

• .recursive() – Enables recursive subdirectory traversal
• .dirs() – Switches the query to match directories instead of files
• .show_hidden() – Includes items starting with . (hidden files)

Execution

• .list() – Executes the query and returns list[str] of paths
• .count() – Executes the query and returns the total number of matches
• .tree() – Executes the query and returns a nested dictionary representing the structure

---

Supported Semantic Types

Type	Extensions
image	.jpg, .jpeg, .png, .webp, .bmp, .gif, .tiff
text	.txt, .md, .rst, .log
pdf	.pdf
doc	.doc, .docx, .odt
sheet	.xls, .xlsx, .ods, .csv
presentation	.ppt, .pptx, .odp
code	.py, .js, .ts, .java, .c, .cpp, .h, .go, .rs, .rb, .php, .sh
data	.json, .yaml, .yml, .xml, .toml
audio	.mp3, .wav, .flac, .ogg, .aac, .m4a
video	.mp4, .mkv, .avi, .mov, .webm
archive	.zip, .tar, .gz, .bz2, .7z, .rar

---

Compatibility

• Python: ≥ 3.9
• OS: Platform-independent
• Dependencies: None (standard library only)

License

MIT