# fileutils-nandu

fileutils-nandu is a lightweight and practical Python utility package that provides commonly used file-handling operations through a clean and reusable API.  
The package is designed to reduce repetitive boilerplate code for everyday file operations in scripts, automation tasks, and small projects.

---

## Features

### Basic File Operations
- Read text files
- Write text files
- Append content to files
- Check whether a file exists
- Count the number of lines in a file

### Advanced File Utilities
- Copy files from one location to another
- Delete files safely
- Get file size in bytes or kilobytes
- List files in a directory using wildcard patterns (for example, `*.txt`)

---

## Installation

Install the package directly from PyPI:

```bash
pip install fileutils-nandu
```

---

## Basic Usage

```python
from fileutils import write_file, read_file, line_count

write_file("example.txt", "Hello\nWorld")
print(read_file("example.txt"))
print(line_count("example.txt"))
```

Output:
```
Hello
World
2
```

---

## Advanced Usage

```python
from fileutils import copy_file, delete_file, file_size, list_files

copy_file("example.txt", "example_copy.txt")

print(file_size("example.txt"))              # size in bytes
print(file_size("example.txt", unit="kb"))   # size in kilobytes

print(list_files(".", "*.txt"))

delete_file("example_copy.txt")
```

---

## Available Functions

| Function | Description |
|--------|-------------|
| read_file(path) | Reads and returns the content of a file |
| read_lines(path) | Returns file content as a list of lines |
| write_file(path, content) | Writes content to a file |
| append_file(path, content) | Appends content to an existing file |
| file_exists(path) | Checks if a file exists |
| line_count(path) | Returns the number of lines in a file |
| copy_file(src, dst) | Copies a file from source to destination |
| delete_file(path) | Deletes a file if it exists |
| file_size(path, unit) | Returns file size in bytes or KB |
| list_files(directory, pattern) | Lists files matching a pattern |

---

## Project Structure

```text
fileutils/
├── reader.py     # File reading utilities
├── writer.py     # File writing utilities
├── utils.py      # Advanced file operations
└── __init__.py   # Public package interface
```

---

## Why This Package

- Avoids rewriting common file-handling logic
- Clean and beginner-friendly API
- Useful for automation, scripting, and small projects
- Lightweight and dependency-free

---

## License

MIT License

---

## Author

Nandu
