filoma 1.10.0

Modular Python tool for profiling files, analyzing directory structures, and inspecting image data

Fast, multi-backend file/directory profiling and data preparation.

🚧 Filoma is under active development — new features are being added regularly, APIs may evolve, and I'm always looking for feedback! Think of it as your friendly neighborhood file analysis toolkit that's still learning new tricks. Contributions, bug reports, and feature requests are more than welcome! 🎉

Installation • Documentation • Interactive CLI • Quickstart • Cookbook • Roboflow Dataset Demo • Source Code

---

filoma helps you analyze file directory trees, inspect file metadata, and prepare your data for exploration. It can achieve this blazingly fast using the best available backend (Rust, fd, or pure Python) ⚡🍃

Key Features

• 🖥️ Interactive CLI: Beautiful terminal interface for filesystem exploration and DataFrame analysis 📖 CLI Documentation →
• 🚀 High-Performance Backends: Automatic selection of Rust, fd, or Python for the best performance.
• 📊 Rich Directory Analysis: Get detailed statistics on file counts, extensions, sizes, and more.
• 🔍 Smart File Search: Use regex and glob patterns to find files with FdFinder.
• 🏗️ Architectural Clarity: High-level visual flows for discovery and processing. 📖 Architecture Documentation →
• 📈 DataFrame Integration: Convert scan results to Polars (or pandas) DataFrames for powerful analysis.
• 🖼️ File/Image Profiling: Extract metadata and statistics from various file formats.

Feature Highlights

Quick, copyable examples showing filoma's standout capabilities and where to learn more.

• Automatic multi-backend scanning: filoma picks the fastest available backend (Rust → fd → pure Python). You can also force a backend for reproducibility. See the backends docs: docs/backends.md.

import filoma as flm

# filoma will pick Rust > fd > Python depending on availability
analysis = flm.probe('.')
analysis.print_summary()  # Pretty Rich table output

• Polars-first DataFrame wrapper & enrichment: Returns a filoma.DataFrame (Polars) with helpers to add path components, depth, and file stats for immediate analysis. Docs: docs/dataframe.md.

df = flm.probe_to_df('.', enrich=True)  # returns a filoma.DataFrame
print(df.head(2))

📊 See Enriched DataFrame Output

filoma.DataFrame with 2 rows
shape: (2, 18)
┌────────────────┬───────┬────────┬──────────┬───┬─────────┬───────┬────────┬────────┐
│ path           ┆ depth ┆ parent ┆ name     ┆ … ┆ inode   ┆ nlink ┆ sha256 ┆ xattrs │
│ ---            ┆ ---   ┆ ---    ┆ ---      ┆   ┆ ---     ┆ ---   ┆ ---    ┆ ---    │
│ str            ┆ i64   ┆ str    ┆ str      ┆   ┆ i64     ┆ i64   ┆ str    ┆ str    │
╞════════════════╪═══════╪════════╪══════════╪═══╪═════════╪═══════╪════════╪════════╡
│ src/filoma.py  ┆ 1     ┆ src    ┆ filo.py  ┆ … ┆ 1465688 ┆ 1     ┆ null   ┆ {}     │
│ src/core/      ┆ 1     ┆ src    ┆ core     ┆ … ┆ 714364  ┆ 15    ┆ null   ┆ {}     │
└────────────────┴───────┴────────┴──────────┴───┴─────────┴───────┴────────┴────────┘

✨ Enriched columns added: parent, name, stem, suffix, size_bytes, modified_time, 
   created_time, is_file, is_dir, owner, group, mode_str, inode, nlink, sha256, xattrs, depth

• Ultra-fast discovery with fd: When fd is available filoma uses it for very fast file discovery. Advanced usage and patterns: docs/advanced-usage.md.

from filoma.directories.fd_finder import FdFinder

finder = FdFinder()
if finder.is_available():
    files = finder.find_files(pattern=r"\.py$", path='src', max_depth=3)
    print(len(files), 'python files found')

• Lightweight, lazy top-level API: Importing filoma is cheap; heavy dependencies load only when used. Quickstart and one-line helpers: docs/quickstart.md.

info = flm.probe_file('README.md')
df = flm.probe_to_df('.')

• Seamless Pandas & Polars integration: filoma.DataFrame wraps a Polars DataFrame but provides instant access to pandas.

df = flm.probe_to_df('.')
pd_df = df.pandas  # Instant conversion to pandas
# or set it globally
flm.set_default_dataframe_backend('pandas')
df.native  # returns pandas.DataFrame

Installation

Install filoma using uv or pip:

pip install filoma

uv pip install filoma
# or 'uv add filoma' to add it to your dependencies)

---

Workflow Demo

This guide follows a typical filoma workflow, from basic file profiling to creating dataframes for exploration.

1. Profile a Single File

Start by inspecting a single file. filoma provides a detailed dataclass with metadata.

import filoma as flm

# Profile a file
file_info = flm.probe_file("README.md")
print(file_info)

📄 See File Metadata Output

Filo(
    path=PosixPath('README.md'), 
    size=6683, 
    mode_str='-rw-r--r--', 
    owner='user', 
    modified=datetime.datetime(2025, 12, 30, 12, 59, 19), 
    is_file=True, 
    ...
)

For images, probe_image gives you additional details like shape and pixel statistics.

# Profile an image
img_info = flm.probe_image("docs/assets/images/logo.png")
print(img_info)

🖼️ See Image Analysis Output

ImageReport(
    path='docs/assets/images/logo.png', 
    file_type='png', 
    shape=(462, 433, 4), 
    mean=182.47, 
    unique=145, 
    ...
)

2. Analyze a Directory

Scan an entire directory to get a high-level overview.

# Analyze the current directory
analysis = flm.probe('.')

# Print a beautiful summary table
analysis.print_summary()

📂 See Directory Summary Table

 Directory Analysis: /project
           (🦀 Rust (Parallel)) - 0.50s
┏━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┓
┃ Metric                   ┃ Value                ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━┩
│ Total Files              │ 27,901               │
│ Total Folders            │ 1,761                │
│ Total Size               │ 596.21 MB            │
│ Average Files per Folder │ 15.84                │
│ Maximum Depth            │ 14                   │
│ Empty Folders            │ 14                   │
│ Analysis Time            │ 0.50s                │
│ Processing Speed         │ 59,167 items/sec     │
└──────────────────────────┴──────────────────────┘

3. Convert to a DataFrame

For detailed analysis, convert the scan results into a Polars DataFrame.

# Scan a directory and get a DataFrame
df = flm.probe_to_df('.')

print(df.head())

4. Enrich Your Data

Add more context to your DataFrame, like file depth and path components, with the enrich() method.

# The DataFrame returned by flm.probe_to_df is a filoma.DataFrame
# with extra capabilities.
df_enriched = df.enrich()

print(df_enriched.head(2))

5. Seamless Pandas Integration

While filoma uses Polars internally for speed, converting to pandas is just one property away.

# Convert to a standard pandas DataFrame
pd_df = df_enriched.pandas

print(type(pd_df))
# <class 'pandas.core.frame.DataFrame'>

✨ See Enriched DataFrame Features

Enrichment adds several groups of columns to your path data:

1. Path Components: parent, name, stem, suffix
2. File Statistics: size_bytes, modified_time, created_time, is_file, is_dir, owner, group, mode_str, inode, nlink, sha256, xattrs
3. Hierarchy: depth (relative nesting level)

filoma.DataFrame with 2 rows
shape: (2, 18)
┌────────────────┬───────┬────────┬──────────┬───┬─────────┬───────┬────────┬────────┐
│ path           ┆ depth ┆ parent ┆ name     ┆ … ┆ inode   ┆ nlink ┆ sha256 ┆ xattrs │
│ ---            ┆ ---   ┆ ---    ┆ ---      ┆   ┆ ---     ┆ ---   ┆ ---    ┆ ---    │
│ str            ┆ i64   ┆ str    ┆ str      ┆   ┆ i64     ┆ i64   ┆ str    ┆ str    │
╞════════════════╪═══════╪════════╪══════════╪═══╪═════════╪═══════╪════════╪════════╡
│ src/filoma.py  ┆ 1     ┆ src    ┆ filo.py  ┆ … ┆ 1465688 ┆ 1     ┆ null   ┆ {}     │
│ src/core/      ┆ 1     ┆ src    ┆ core     ┆ … ┆ 714364  ┆ 15    ┆ null   ┆ {}     │
└────────────────┴───────┴────────┴──────────┴───┴─────────┴───────┴────────┴────────┘

License

Shield:

This work is licensed under a Creative Commons Attribution 4.0 International License.

Contributing

Contributions welcome! Please check the issues for planned features and bug reports.

---

filoma - Fast, multi-backend file/directory profiling and data preparation.