Metadata-Version: 2.4
Name: fileutils-dir
Version: 0.4.0
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

A minimalist Python library for listing and filtering files with a fluent interface.

## Installation

```bash
pip install fileutils-dir
```

## Usage

The `in_dir` function returns a query object, allowing for a fluent and readable way to list or count files.

```python
from fileutils import in_dir

# List all files in the current directory
files = in_dir().list()

# Filter by extension
python_files = in_dir(ext="py").list()

# Filter by predefined categories
media_files = in_dir(dtype=["image", "video"]).list()

# Including hidden files
hidden_and_all = in_dir().show_hidden().list()

# Counting files directly
count = in_dir(path="src", dtype="code").count()
```

## API Reference

### `in_dir(path=".", *, ext=None, dtype=None)`

Creates a `DirQuery` object.

- **path**: The directory to search. Accepts `str` or `pathlib.Path`. Defaults to `"."`.
- **ext**: A string or an iterable of file extensions (e.g., `"py"`, `".py"`, or `["py", "js"]`).
- **dtype**: A string or an iterable of predefined file categories (e.g., `"image"`, or `["text", "pdf"]`).

### `DirQuery` Methods

The following methods can be called on the object returned by `in_dir()`:

- **`.list()`**: Returns a `list[str]` of file paths matching the criteria.
- **`.count()`**: Returns the integer count of matching files.
- **`.show_hidden()`**: Sets the query to include hidden files (those starting with a dot). Returns the query object itself for chaining.

## Supported Types

The `dtype` parameter supports the following categories:

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

## License

MIT
