cmr-file-utils 1.0.0

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

File Utils

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

Table of Contents

• Features
• Installation
• Usage
  • Plain Text Files
  • JSON Files
  • YAML Files
  • Pickle Files
  • Error Handling
• API Reference
  • Reading Functions
  • Writing Functions
• Development
• Requirements
• License
• 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

pip install cmr-file-utils

Using Poetry

poetry add cmr-file-utils

Development Installation

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

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

Or visit the official Poetry installation guide.

Then clone and install the project:

git clone <repository-url>
cd cmr_file_utils
poetry install

Usage

Plain Text Files

Reading

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

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

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

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

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:

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

# 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

poetry run black cmr_file_utils tests

Linting

poetry run pylint cmr_file_utils

Requirements

• Python ^3.11
• pyyaml

License

See LICENSE file for details.

Author

CataMRubio