Metadata-Version: 2.4
Name: cwdfast
Version: 0.0.2
Summary: A high-performance Python C extension providing native, cross-platform filesystem operations. Optimized for recursive directory traversal, bulk file moving, and batch renaming with minimal memory overhead.
License-Expression: Unlicense
Project-URL: Homepage, https://github.com/Mitra-88/c-wd-fast
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: Microsoft :: Windows :: Windows 10
Classifier: Operating System :: Microsoft :: Windows :: Windows 11
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Environment :: Console
Requires-Python: >=3.14
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# `cwdfast`

A high-performance Python C extension providing native, cross-platform filesystem operations. Optimized for recursive directory traversal, bulk file moving, and batch renaming with minimal memory overhead.

## Features
- **Cross-Platform**: Native support for Windows (Wide Char) and POSIX/Linux/macOS (FS-encoded bytes).
- **High Performance**: Written in C with direct OS API calls (`FindFirstFileW`/`opendir`), bypassing Python-level iteration overhead.
- **Smart Conflict Resolution**: Automatically appends counters (e.g., `-1`, `-2`) to filenames during moves to prevent overwrites.
- **Safe Traversal**: Skips `.` and `..`, ignores reparse points (Windows), and safely handles symlinks (POSIX).

## Installation & Building

Save the C code as `fastfs.c` and create a `setup.py`:

```python
from setuptools import setup, Extension

module = Extension(
    "cwdfast",
    sources=["cwdfast.c"],
)

setup(
    name="cwdfast",
    version="0.0.1",
    description="Native filesystem operations",
    ext_modules=[module],
)
```

Build and install:
```bash
python setup.py build_ext --inplace
# or
pip install .
```

## Usage Examples

```python
import cwdfast

# 1. Find all .txt and .log files, ignoring 'node_modules'
files = cwdfast.find_files(
    start="/path/to/dir",
    extensions=[".txt", ".log"],
    excluded=["node_modules", ".git"]
)

# 2. Remove all empty directories, ignoring '.git'
deleted_count = cwdfast.remove_empty_dirs(
    start="/path/to/dir",
    excluded=[".git"]
)

# 3. Move multiple files to a destination (auto-resolves name conflicts)
moved_count = cwdfast.move_files(
    files=["/src/file1.txt", "/src/file2.txt"],
    dest_dir="/dest/dir"
)

# 4. Add '.gma' extension to files without an extension
# (Skips files named 'WorkshopDecompressor' by default)
renamed_count = cwdfast.add_extension_to_files_without_format(
    start="/path/to/dir",
    excluded=[".git"],
    skip_name="WorkshopDecompressor",  # Default
    new_ext=".gma"                     # Default
)
```

## API Reference

| Function | Description | Returns |
| :--- | :--- | :--- |
| `find_files(start, extensions, excluded=None)` | Recursively finds files matching any extension in the list. | `list[str]` of matched paths |
| `remove_empty_dirs(start, excluded=None)` | Recursively deletes empty directories. | `int` (number of dirs deleted) |
| `move_files(files, dest_dir)` | Moves an iterable of file paths to `dest_dir`. Creates unique names on conflict. | `int` (number of files moved) |
| `add_extension_to_files_without_format(start, excluded=None, skip_name=None, new_ext=None)` | Recursively appends `new_ext` to files lacking a dot in their name. | `int` (number of files renamed) |

*Note: All path arguments accept standard Python strings. The extension handles OS-specific path encoding automatically.*
