cmr-file-utils 1.0.1
A simple and intuitive Python library for reading and writing files in various formats
License: MIT
Requires Python: <4.0,>=3.11
Keywords: file, io, json, yaml, pickle, utilities

# File Utils

A simple and intuitive Python library for reading and writing files in various formats.

## Table of Contents

- [Features](#features)
- [Installation](#installation)
- [Usage](#usage)
  - [Plain Text Files](#plain-text-files)
  - [JSON Files](#json-files)
  - [YAML Files](#yaml-files)
  - [Pickle Files](#pickle-files)
  - [Error Handling](#error-handling)
- [API Reference](#api-reference)
  - [Reading Functions](#reading-functions)
  - [Writing Functions](#writing-functions)
- [Development](#development)
- [Requirements](#requirements)
- [License](#license)
- [Author](#author)

## Features

- **Multiple file format support**: Plain text, JSON, YAML, and Pickle
- **Encoding support**: Configurable encoding for all text operations (default: UTF-8)
- **Flexible I/O**: Read/write entire files or line-by-line
- **Smart line appending**: Automatic newline handling with `write_line()`
- **Extensible**: Pass custom arguments to underlying parsers (json, yaml, pickle)
- **Type-safe**: Full parameter documentation with types
- **Well-tested**: Comprehensive test suite with error handling

## Installation

### Using pip

```bash
pip install cmr-file-utils
```

### Using Poetry

```bash
poetry add cmr-file-utils
```

### Development Installation

For development, Poetry is recommended. First, install Poetry if you don't have it:

```bash
curl -sSL https://install.python-poetry.org | python3 -
```

Or visit the [official Poetry installation guide](https://python-poetry.org/docs/#installation).

Then clone and install the project:

```bash
git clone <repository-url>
cd cmr_file_utils
poetry install
```

## Usage

### Plain Text Files

#### Reading

```python
from cmr_file_utils import read, read_lines

# Read entire file as a single string
content = read("file.txt")
print(content)  # "Line 1\nLine 2\nLine 3"

# Read file as a list of lines
lines = read_lines("file.txt")
print(lines)  # ["Line 1", "Line 2", "Line 3"]

# With custom encoding
content = read("file.txt", encoding="latin-1")
```

#### Writing

```python
from cmr_file_utils import write, write_line, write_lines

# Write a string to a file
write("Hello, World!", "output.txt")

# Append to a file
write("More content", "output.txt", mode="a")

# Append a line with automatic newline handling
write_line("First line", "output.txt")   # Creates file with "First line\n"
write_line("Second line", "output.txt")  # Appends "Second line\n"

# Write multiple lines at once
lines = ["Line 1", "Line 2", "Line 3"]
write_lines(lines, "output.txt")

# With custom encoding
write("Hello", "output.txt", encoding="utf-16")
```

### JSON Files

```python
from cmr_file_utils import read_json, write_json

# Read JSON
data = read_json("config.json")
print(data)  # {"name": "example", "version": 1}

# Write JSON
data = {"name": "example", "version": 2}
write_json(data, "config.json")

# With custom json.dump() arguments
write_json(data, "config.json", indent=2, sort_keys=True)

# With custom json.load() arguments
data = read_json("config.json", object_hook=custom_decoder)
```

### YAML Files

```python
from cmr_file_utils import read_yaml, write_yaml

# Read YAML
config = read_yaml("config.yaml")

# Write YAML
config = {"database": {"host": "localhost", "port": 5432}}
write_yaml(config, "config.yaml")

# With custom yaml.dump() arguments
write_yaml(config, "config.yaml", default_flow_style=False)
```

### Pickle Files

```python
from cmr_file_utils import read_pkl, write_pkl

# Write Python object to pickle file
data = {"users": [{"id": 1, "name": "Alice"}], "count": 1}
write_pkl(data, "data.pkl")

# Read pickle file
data = read_pkl("data.pkl")
print(data)  # {"users": [{"id": 1, "name": "Alice"}], "count": 1}

# With custom pickle.dump() arguments
write_pkl(data, "data.pkl", protocol=4)
```

### Error Handling

All read functions raise `FileNotFoundError` when the file doesn't exist:

```python
from cmr_file_utils import read

try:
    content = read("nonexistent.txt")
except FileNotFoundError:
    print("File not found!")
```

## API Reference

### Reading Functions

#### `read(path, encoding='utf-8')`
Reads file content as a single string.
- **path** (str): Path to the file
- **encoding** (str): File encoding, defaults to 'utf-8'
- **Returns**: str - File content with trailing newline stripped

#### `read_lines(path, encoding='utf-8')`
Reads file content as a list of lines.
- **path** (str): Path to the file
- **encoding** (str): File encoding, defaults to 'utf-8'
- **Returns**: list of str - List of lines with newlines stripped

#### `read_json(file_path, encoding='utf-8', **kwargs)`
Reads and parses a JSON file.
- **file_path** (str): Path to the JSON file
- **encoding** (str): File encoding, defaults to 'utf-8'
- **kwargs**: Additional arguments passed to `json.load()`
- **Returns**: dict or list - Parsed JSON data

#### `read_yaml(file_path, encoding='utf-8', **kwargs)`
Reads and parses a YAML file.
- **file_path** (str): Path to the YAML file
- **encoding** (str): File encoding, defaults to 'utf-8'
- **kwargs**: Additional arguments passed to `yaml.safe_load()`
- **Returns**: dict, list, or any - Parsed YAML data

#### `read_pkl(path, **kwargs)`
Reads and deserializes a pickle file.
- **path** (str): Path to the pickle file
- **kwargs**: Additional arguments passed to `pickle.load()`
- **Returns**: any - Deserialized Python object

### Writing Functions

#### `write(data, path, encoding='utf-8', mode="w")`
Writes a string to a file.
- **data** (str): String to write
- **path** (str): Path to the output file
- **encoding** (str): File encoding, defaults to 'utf-8'
- **mode** (str): File open mode (w, a, w+, a+), defaults to 'w'
- **Returns**: None

#### `write_line(data, path, encoding='utf-8')`
Appends a line to a file with automatic newline handling.
- **data** (str): String to append as a new line
- **path** (str): Path to the output file
- **encoding** (str): File encoding, defaults to 'utf-8'
- **Returns**: None

#### `write_lines(data, path, encoding='utf-8', mode="w")`
Writes a list of strings to a file, one per line.
- **data** (list of str): List of strings to write
- **path** (str): Path to the output file
- **encoding** (str): File encoding, defaults to 'utf-8'
- **mode** (str): File open mode (w, a, w+, a+), defaults to 'w'
- **Returns**: None

#### `write_json(data, path, encoding='utf-8', ensure_ascii=False, indent=4, **kwargs)`
Writes data to a JSON file.
- **data** (dict or list): Data to serialize to JSON
- **path** (str): Path to the output file
- **encoding** (str): File encoding, defaults to 'utf-8'
- **ensure_ascii** (bool): Whether to escape non-ASCII characters, defaults to False
- **indent** (int): Number of spaces for indentation, defaults to 4
- **kwargs**: Additional arguments passed to `json.dump()`
- **Returns**: None

#### `write_yaml(data, path, encoding='utf-8', **kwargs)`
Writes data to a YAML file.
- **data** (dict, list, or any): Data to serialize to YAML
- **path** (str): Path to the output file
- **encoding** (str): File encoding, defaults to 'utf-8'
- **kwargs**: Additional arguments passed to `yaml.dump()`
- **Returns**: None

#### `write_pkl(data, path, **kwargs)`
Serializes and writes a Python object to a pickle file.
- **data** (any): Python object to serialize
- **path** (str): Path to the output pickle file
- **kwargs**: Additional arguments passed to `pickle.dump()`
- **Returns**: None

## Development

### Running Tests

```bash
# Run all tests
poetry run pytest

# Run specific test file
poetry run pytest tests/test_file_utils.py

# Run with coverage
poetry run pytest --cov=cmr_file_utils
```

### Code Formatting

```bash
poetry run black cmr_file_utils tests
```

### Linting

```bash
poetry run pylint cmr_file_utils
```

## Requirements

- Python ^3.11
- pyyaml

## License

See LICENSE file for details.

## Author

CataMRubio