Metadata-Version: 2.4
Name: fileutils-dir
Version: 0.8.5
Summary: Small utilities for listing files in directories
Author: Jatavallabhula Sarat Anirudh
License-Expression: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# fileutils

[![PyPI Version](https://img.shields.io/pypi/v/fileutils-dir.svg)](https://pypi.org/project/fileutils-dir/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python Versions](https://img.shields.io/pypi/pyversions/fileutils-dir.svg)](https://pypi.org/project/fileutils-dir/)

**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

```bash
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.

```python
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
```python
files = in_dir().list()
```

### Filter by Extension
```python
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.

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

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

### Recursive Traversal
```python
files = (
    in_dir("project")
    .recursive()
    .list()
)
```

### Hidden Files
```python
files = (
    in_dir("project")
    .recursive()
    .show_hidden()
    .list()
)
```

### Directory-Only Queries
```python
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

```python
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.

```python
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**: &ge; 3.9
- **OS**: Platform-independent
- **Dependencies**: None (standard library only)

## License
MIT
