Serialization Module¶

The rite.serialization module provides utilities for working with various data formats including JSON, CSV, TOML, Pickle, and INI files.

Overview¶

serialization ¶

Serialization Module¶

Data serialization and deserialization utilities.

This module provides comprehensive utilities for working with various data formats including JSON, CSV, INI, Pickle, and TOML using only Python's standard library.

Submodules¶

json: JSON file and string operations
csv: CSV file operations with delimiter detection
ini: INI/config file operations
pickle: Python object serialization
toml: TOML file operations (Python 3.11+)

Examples¶

from rite.serialization import json_load, csv_read data = json_load("data.json") rows = csv_read("data.csv")

Notes¶

Legacy classes JSONHandler, INIHandler, and detect_delimiter are still available for backward compatibility.

Modules¶

csv ¶

CSV Module¶

CSV file operations.

This submodule provides utilities for reading and writing CSV files with automatic delimiter detection.

Examples¶

from rite.serialization.csv import csv_read, csv_write data = csv_read("input.csv") csv_write("output.csv", data)

Modules¶

csv_detect_delimiter ¶

CSV Delimiter Detector¶

Detect delimiter from filename.

Examples¶

from rite.serialization.csv import csv_detect_delimiter csv_detect_delimiter("data.tsv") '\t'

Functions¶

csv_detect_delimiter ¶

csv_detect_delimiter(filename: str) -> str

Detect delimiter from filename extension.

Parameters:

Name	Type	Description	Default
`filename`	`str`	CSV filename or path.	required

Returns:

Type	Description
`str`	Delimiter character (tab or comma).

Examples:

>>> csv_detect_delimiter("data.csv")
','
>>> csv_detect_delimiter("data.tsv")
'\t'
>>> csv_detect_delimiter("path/to/data.tsv")
'\t'

Notes

Returns tab for .tsv, comma otherwise.

csv_read ¶

CSV Reader¶

Read CSV file to list of dicts.

Examples¶

from rite.serialization.csv import csv_read rows = csv_read("data.csv")

Functions¶

csv_read ¶

csv_read(path: str | Path, delimiter: str = ',') -> list[dict[str, Any]]

Read CSV file to list of dictionaries.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to CSV file.	required
`delimiter`	`str`	CSV delimiter character.	`','`

Returns:

Type	Description
`list[dict[str, Any]]`	List of row dictionaries.

Examples:

>>> csv_read("data.csv")
[{'col1': 'val1', 'col2': 'val2'}, ...]
>>> csv_read("data.tsv", delimiter="\t")
[...]

Notes

Uses DictReader for named columns. First row is header.

csv_write ¶

CSV Writer¶

Write list of dicts to CSV file.

Examples¶

from rite.serialization.csv import csv_write data = [{"col1": "val1", "col2": "val2"}] csv_write("output.csv", data)

Functions¶

csv_write ¶

csv_write(path: str | Path, data: list[dict[str, Any]], delimiter: str = ',') -> None

Write list of dictionaries to CSV file.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to output CSV file.	required
`data`	`list[dict[str, Any]]`	List of row dictionaries.	required
`delimiter`	`str`	CSV delimiter character.	`','`

Returns:

Type	Description
`None`	None

Examples:

>>> data = [{"col1": "val1", "col2": "val2"}]
>>> csv_write("output.csv", data)
>>> csv_write("output.tsv", data, delimiter="\t")

Notes

Creates parent directories if needed. Header from first row keys.

csv_detect_delimiter ¶

CSV Delimiter Detector¶

Detect delimiter from filename.

Examples¶

from rite.serialization.csv import csv_detect_delimiter csv_detect_delimiter("data.tsv") '\t'

Functions¶

csv_detect_delimiter ¶

csv_detect_delimiter(filename: str) -> str

Detect delimiter from filename extension.

Parameters:

Name	Type	Description	Default
`filename`	`str`	CSV filename or path.	required

Returns:

Type	Description
`str`	Delimiter character (tab or comma).

Examples:

>>> csv_detect_delimiter("data.csv")
','
>>> csv_detect_delimiter("data.tsv")
'\t'
>>> csv_detect_delimiter("path/to/data.tsv")
'\t'

Notes

Returns tab for .tsv, comma otherwise.

csv_read ¶

CSV Reader¶

Read CSV file to list of dicts.

Examples¶

from rite.serialization.csv import csv_read rows = csv_read("data.csv")

Functions¶

csv_read ¶

csv_read(path: str | Path, delimiter: str = ',') -> list[dict[str, Any]]

Read CSV file to list of dictionaries.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to CSV file.	required
`delimiter`	`str`	CSV delimiter character.	`','`

Returns:

Type	Description
`list[dict[str, Any]]`	List of row dictionaries.

Examples:

>>> csv_read("data.csv")
[{'col1': 'val1', 'col2': 'val2'}, ...]
>>> csv_read("data.tsv", delimiter="\t")
[...]

Notes

Uses DictReader for named columns. First row is header.

csv_write ¶

CSV Writer¶

Write list of dicts to CSV file.

Examples¶

from rite.serialization.csv import csv_write data = [{"col1": "val1", "col2": "val2"}] csv_write("output.csv", data)

Functions¶

csv_write ¶

csv_write(path: str | Path, data: list[dict[str, Any]], delimiter: str = ',') -> None

Write list of dictionaries to CSV file.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to output CSV file.	required
`data`	`list[dict[str, Any]]`	List of row dictionaries.	required
`delimiter`	`str`	CSV delimiter character.	`','`

Returns:

Type	Description
`None`	None

Examples:

>>> data = [{"col1": "val1", "col2": "val2"}]
>>> csv_write("output.csv", data)
>>> csv_write("output.tsv", data, delimiter="\t")

Notes

Creates parent directories if needed. Header from first row keys.

ini ¶

INI Module¶

INI configuration file operations.

This submodule provides utilities for reading and writing INI/config files with section and key-value operations.

Examples¶

from rite.serialization.ini import ini_read, ini_write config = ini_read("config.ini") ini_write("output.ini", config)

Modules¶

ini_get ¶

INI Get Value¶

Get value from INI configuration.

Examples¶

from rite.serialization.ini import ini_get ini_get("config.ini", "section", "key") 'value'

Functions¶

ini_get ¶

ini_get(path: str | Path, section: str, key: str, default: str | None = None) -> str | None

Get value from INI file.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to INI file.	required
`section`	`str`	Section name.	required
`key`	`str`	Key name.	required
`default`	`str \| None`	Default value if not found.	`None`

Returns:

Type	Description
`str \| None`	Value string or default.

Examples:

>>> ini_get("config.ini", "section", "key")
'value'
>>> ini_get("config.ini", "section", "missing", "default")
'default'

Notes

Returns default if section or key not found.

ini_read ¶

INI Reader¶

Read INI configuration file.

Examples¶

from rite.serialization.ini import ini_read config = ini_read("config.ini")

Functions¶

ini_read ¶

ini_read(path: str | Path) -> dict[str, dict[str, str]]

Read INI file to nested dictionary.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to INI file.	required

Returns:

Type	Description
`dict[str, dict[str, str]]`	Nested dictionary of sections and key-value pairs.

Examples:

>>> ini_read("config.ini")
{'section': {'key': 'value'}}

Notes

Uses ConfigParser for INI parsing. Returns nested dict structure.

ini_set ¶

INI Set Value¶

Set value in INI configuration.

Examples¶

from rite.serialization.ini import ini_set ini_set("config.ini", "section", "key", "value")

Functions¶

ini_set ¶

ini_set(path: str | Path, section: str, key: str, value: str) -> None

Set value in INI file.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to INI file.	required
`section`	`str`	Section name.	required
`key`	`str`	Key name.	required
`value`	`str`	Value to set.	required

Returns:

Type	Description
`None`	None

Examples:

>>> ini_set("config.ini", "section", "key", "value")

Notes

Creates section if not exists. Creates file if not exists.

ini_write ¶

INI Writer¶

Write nested dict to INI file.

Examples¶

from rite.serialization.ini import ini_write config = {"section": {"key": "value"}} ini_write("config.ini", config)

Functions¶

ini_write ¶

ini_write(path: str | Path, data: dict[str, dict[str, str]]) -> None

Write nested dictionary to INI file.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to output INI file.	required
`data`	`dict[str, dict[str, str]]`	Nested dict of sections and key-value pairs.	required

Returns:

Type	Description
`None`	None

Examples:

>>> config = {"section": {"key": "value"}}
>>> ini_write("config.ini", config)

Notes

Creates parent directories if needed. Uses ConfigParser for formatting.

ini_get ¶

INI Get Value¶

Get value from INI configuration.

Examples¶

from rite.serialization.ini import ini_get ini_get("config.ini", "section", "key") 'value'

Functions¶

ini_get ¶

ini_get(path: str | Path, section: str, key: str, default: str | None = None) -> str | None

Get value from INI file.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to INI file.	required
`section`	`str`	Section name.	required
`key`	`str`	Key name.	required
`default`	`str \| None`	Default value if not found.	`None`

Returns:

Type	Description
`str \| None`	Value string or default.

Examples:

>>> ini_get("config.ini", "section", "key")
'value'
>>> ini_get("config.ini", "section", "missing", "default")
'default'

Notes

Returns default if section or key not found.

ini_read ¶

INI Reader¶

Read INI configuration file.

Examples¶

from rite.serialization.ini import ini_read config = ini_read("config.ini")

Functions¶

ini_read ¶

ini_read(path: str | Path) -> dict[str, dict[str, str]]

Read INI file to nested dictionary.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to INI file.	required

Returns:

Type	Description
`dict[str, dict[str, str]]`	Nested dictionary of sections and key-value pairs.

Examples:

>>> ini_read("config.ini")
{'section': {'key': 'value'}}

Notes

Uses ConfigParser for INI parsing. Returns nested dict structure.

ini_set ¶

INI Set Value¶

Set value in INI configuration.

Examples¶

from rite.serialization.ini import ini_set ini_set("config.ini", "section", "key", "value")

Functions¶

ini_set ¶

ini_set(path: str | Path, section: str, key: str, value: str) -> None

Set value in INI file.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to INI file.	required
`section`	`str`	Section name.	required
`key`	`str`	Key name.	required
`value`	`str`	Value to set.	required

Returns:

Type	Description
`None`	None

Examples:

>>> ini_set("config.ini", "section", "key", "value")

Notes

Creates section if not exists. Creates file if not exists.

ini_write ¶

INI Writer¶

Write nested dict to INI file.

Examples¶

from rite.serialization.ini import ini_write config = {"section": {"key": "value"}} ini_write("config.ini", config)

Functions¶

ini_write ¶

ini_write(path: str | Path, data: dict[str, dict[str, str]]) -> None

Write nested dictionary to INI file.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to output INI file.	required
`data`	`dict[str, dict[str, str]]`	Nested dict of sections and key-value pairs.	required

Returns:

Type	Description
`None`	None

Examples:

>>> config = {"section": {"key": "value"}}
>>> ini_write("config.ini", config)

Notes

Creates parent directories if needed. Uses ConfigParser for formatting.

json ¶

JSON Module¶

JSON serialization utilities.

This submodule provides utilities for JSON operations like loading, dumping, parsing, and validation.

Examples¶

from rite.serialization.json import json_load, json_dump data = json_load("input.json") json_dump("output.json", data)

Modules¶

json_dump ¶

JSON Dumper¶

Save JSON to file.

Examples¶

from rite.serialization.json import json_dump json_dump("output.json", {"key": "value"})

Functions¶

json_dump ¶

json_dump(path: str | Path, data: Any, indent: int | None = 2) -> None

Save JSON data to file.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to output JSON file.	required
`data`	`Any`	Data to serialize.	required
`indent`	`int \| None`	Indentation spaces (None for compact).	`2`

Returns:

Type	Description
`None`	None

Examples:

>>> json_dump("output.json", {"key": "value"})
>>> json_dump("compact.json", data, indent=None)

Notes

Creates parent directories if needed. Uses UTF-8 encoding.

json_dumps ¶

JSON Dumps¶

Serialize data to JSON string.

Examples¶

from rite.serialization.json import json_dumps json_dumps({"key": "value"}) '{"key": "value"}'

Functions¶

json_dumps ¶

json_dumps(data: Any, indent: int | None = None) -> str

Serialize data to JSON string.

Parameters:

Name	Type	Description	Default
`data`	`Any`	Data to serialize.	required
`indent`	`int \| None`	Indentation spaces (None for compact).	`None`

Returns:

Type	Description
`str`	JSON string.

Examples:

>>> json_dumps({"key": "value"})
'{"key": "value"}'
>>> json_dumps({"key": "value"}, indent=2)
'{\n  "key": "value"\n}'

Notes

Wrapper around json.dumps.

json_load ¶

JSON Loader¶

Load JSON from file.

Examples¶

from rite.serialization.json import json_load data = json_load("data.json")

Functions¶

json_load ¶

json_load(path: str | Path) -> Any

Load JSON data from file.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to JSON file.	required

Returns:

Type	Description
`Any`	Parsed JSON data.

Raises:

Type	Description
`FileNotFoundError`	If file doesn't exist.
`JSONDecodeError`	If JSON is invalid.

Examples:

>>> json_load("config.json")
{'key': 'value'}

Notes

Uses UTF-8 encoding.

json_loads ¶

JSON Loads¶

Parse JSON from string.

Examples¶

from rite.serialization.json import json_loads json_loads('{"key": "value"}')

Functions¶

json_loads ¶

json_loads(text: str) -> Any

Parse JSON from string.

Parameters:

Name	Type	Description	Default
`text`	`str`	JSON string to parse.	required

Returns:

Type	Description
`Any`	Parsed JSON data.

Raises:

Type	Description
`JSONDecodeError`	If JSON is invalid.

Examples:

>>> json_loads('{"key": "value"}')
{'key': 'value'}
>>> json_loads('[1, 2, 3]')
[1, 2, 3]

Notes

Wrapper around json.loads.

json_validate ¶

JSON Validator¶

Validate JSON string.

Examples¶

from rite.serialization.json import json_validate json_validate('{"key": "value"}') True

Functions¶

json_validate ¶

json_validate(text: str) -> bool

Validate JSON string.

Parameters:

Name	Type	Description	Default
`text`	`str`	JSON string to validate.	required

Returns:

Type	Description
`bool`	True if valid JSON, False otherwise.

Examples:

>>> json_validate('{"key": "value"}')
True
>>> json_validate('{invalid}')
False
>>> json_validate('[1, 2, 3]')
True

Notes

Returns False on any JSON decode error.

json_dump ¶

JSON Dumper¶

Save JSON to file.

Examples¶

from rite.serialization.json import json_dump json_dump("output.json", {"key": "value"})

Functions¶

json_dump ¶

json_dump(path: str | Path, data: Any, indent: int | None = 2) -> None

Save JSON data to file.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to output JSON file.	required
`data`	`Any`	Data to serialize.	required
`indent`	`int \| None`	Indentation spaces (None for compact).	`2`

Returns:

Type	Description
`None`	None

Examples:

>>> json_dump("output.json", {"key": "value"})
>>> json_dump("compact.json", data, indent=None)

Notes

Creates parent directories if needed. Uses UTF-8 encoding.

json_dumps ¶

JSON Dumps¶

Serialize data to JSON string.

Examples¶

from rite.serialization.json import json_dumps json_dumps({"key": "value"}) '{"key": "value"}'

Functions¶

json_dumps ¶

json_dumps(data: Any, indent: int | None = None) -> str

Serialize data to JSON string.

Parameters:

Name	Type	Description	Default
`data`	`Any`	Data to serialize.	required
`indent`	`int \| None`	Indentation spaces (None for compact).	`None`

Returns:

Type	Description
`str`	JSON string.

Examples:

>>> json_dumps({"key": "value"})
'{"key": "value"}'
>>> json_dumps({"key": "value"}, indent=2)
'{\n  "key": "value"\n}'

Notes

Wrapper around json.dumps.

json_load ¶

JSON Loader¶

Load JSON from file.

Examples¶

from rite.serialization.json import json_load data = json_load("data.json")

Functions¶

json_load ¶

json_load(path: str | Path) -> Any

Load JSON data from file.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to JSON file.	required

Returns:

Type	Description
`Any`	Parsed JSON data.

Raises:

Type	Description
`FileNotFoundError`	If file doesn't exist.
`JSONDecodeError`	If JSON is invalid.

Examples:

>>> json_load("config.json")
{'key': 'value'}

Notes

Uses UTF-8 encoding.

json_loads ¶

JSON Loads¶

Parse JSON from string.

Examples¶

from rite.serialization.json import json_loads json_loads('{"key": "value"}')

Functions¶

json_loads ¶

json_loads(text: str) -> Any

Parse JSON from string.

Parameters:

Name	Type	Description	Default
`text`	`str`	JSON string to parse.	required

Returns:

Type	Description
`Any`	Parsed JSON data.

Raises:

Type	Description
`JSONDecodeError`	If JSON is invalid.

Examples:

>>> json_loads('{"key": "value"}')
{'key': 'value'}
>>> json_loads('[1, 2, 3]')
[1, 2, 3]

Notes

Wrapper around json.loads.

json_validate ¶

JSON Validator¶

Validate JSON string.

Examples¶

from rite.serialization.json import json_validate json_validate('{"key": "value"}') True

Functions¶

json_validate ¶

json_validate(text: str) -> bool

Validate JSON string.

Parameters:

Name	Type	Description	Default
`text`	`str`	JSON string to validate.	required

Returns:

Type	Description
`bool`	True if valid JSON, False otherwise.

Examples:

>>> json_validate('{"key": "value"}')
True
>>> json_validate('{invalid}')
False
>>> json_validate('[1, 2, 3]')
True

Notes

Returns False on any JSON decode error.

pickle ¶

Pickle Module¶

Pickle serialization operations.

This submodule provides utilities for serializing and deserializing Python objects using the pickle protocol.

Examples¶

from rite.serialization.pickle import pickle_dump, pickle_load pickle_dump("data.pkl", {"key": "value"}) data = pickle_load("data.pkl")

Modules¶

pickle_dump ¶

Pickle Dump¶

Serialize object to pickle file.

Examples¶

from rite.serialization.pickle import pickle_dump pickle_dump("data.pkl", {"key": "value"})

Functions¶

pickle_dump ¶

pickle_dump(path: str | Path, data: Any) -> None

Serialize object to pickle file.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to output pickle file.	required
`data`	`Any`	Object to serialize.	required

Returns:

Type	Description
`None`	None

Examples:

>>> pickle_dump("data.pkl", {"key": "value"})
>>> pickle_dump("data.pkl", [1, 2, 3])

Notes

Creates parent directories if needed. Uses binary mode.

pickle_dumps ¶

Pickle Dumps¶

Serialize object to bytes.

Examples¶

from rite.serialization.pickle import pickle_dumps data = pickle_dumps({"key": "value"})

Functions¶

pickle_dumps ¶

pickle_dumps(data: Any) -> bytes

Serialize object to bytes.

Parameters:

Name	Type	Description	Default
`data`	`Any`	Object to serialize.	required

Returns:

Type	Description
`bytes`	Serialized bytes.

Examples:

>>> pickle_dumps({"key": "value"})
b'\x80\x04...'

Notes

Returns bytes for network transmission.

pickle_load ¶

Pickle Load¶

Deserialize object from pickle file.

Examples¶

from rite.serialization.pickle import pickle_load data = pickle_load("data.pkl")

Functions¶

pickle_load ¶

pickle_load(path: str | Path) -> Any

Deserialize object from pickle file.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to pickle file.	required

Returns:

Type	Description
`Any`	Deserialized object.

Examples:

>>> pickle_load("data.pkl")
{'key': 'value'}

Notes

Uses binary mode. Be careful with untrusted data.

pickle_loads ¶

Pickle Loads¶

Deserialize object from bytes.

Examples¶

from rite.serialization.pickle import pickle_loads data = pickle_loads(b'\x80\x04...')

Functions¶

pickle_loads ¶

pickle_loads(data: bytes) -> Any

Deserialize object from bytes.

Parameters:

Name	Type	Description	Default
`data`	`bytes`	Serialized bytes.	required

Returns:

Type	Description
`Any`	Deserialized object.

Examples:

>>> pickle_loads(b'\x80\x04...')
{'key': 'value'}

Notes

Be careful with untrusted data.

pickle_dump ¶

Pickle Dump¶

Serialize object to pickle file.

Examples¶

from rite.serialization.pickle import pickle_dump pickle_dump("data.pkl", {"key": "value"})

Functions¶

pickle_dump ¶

pickle_dump(path: str | Path, data: Any) -> None

Serialize object to pickle file.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to output pickle file.	required
`data`	`Any`	Object to serialize.	required

Returns:

Type	Description
`None`	None

Examples:

>>> pickle_dump("data.pkl", {"key": "value"})
>>> pickle_dump("data.pkl", [1, 2, 3])

Notes

Creates parent directories if needed. Uses binary mode.

pickle_dumps ¶

Pickle Dumps¶

Serialize object to bytes.

Examples¶

from rite.serialization.pickle import pickle_dumps data = pickle_dumps({"key": "value"})

Functions¶

pickle_dumps ¶

pickle_dumps(data: Any) -> bytes

Serialize object to bytes.

Parameters:

Name	Type	Description	Default
`data`	`Any`	Object to serialize.	required

Returns:

Type	Description
`bytes`	Serialized bytes.

Examples:

>>> pickle_dumps({"key": "value"})
b'\x80\x04...'

Notes

Returns bytes for network transmission.

pickle_load ¶

Pickle Load¶

Deserialize object from pickle file.

Examples¶

from rite.serialization.pickle import pickle_load data = pickle_load("data.pkl")

Functions¶

pickle_load ¶

pickle_load(path: str | Path) -> Any

Deserialize object from pickle file.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to pickle file.	required

Returns:

Type	Description
`Any`	Deserialized object.

Examples:

>>> pickle_load("data.pkl")
{'key': 'value'}

Notes

Uses binary mode. Be careful with untrusted data.

pickle_loads ¶

Pickle Loads¶

Deserialize object from bytes.

Examples¶

from rite.serialization.pickle import pickle_loads data = pickle_loads(b'\x80\x04...')

Functions¶

pickle_loads ¶

pickle_loads(data: bytes) -> Any

Deserialize object from bytes.

Parameters:

Name	Type	Description	Default
`data`	`bytes`	Serialized bytes.	required

Returns:

Type	Description
`Any`	Deserialized object.

Examples:

>>> pickle_loads(b'\x80\x04...')
{'key': 'value'}

Notes

Be careful with untrusted data.

toml ¶

TOML Module¶

TOML file operations.

This submodule provides utilities for reading TOML files using the stdlib tomllib (Python 3.11+). Write operations are not supported in stdlib.

Examples¶

from rite.serialization.toml import toml_load config = toml_load("config.toml")

Modules¶

toml_load ¶

TOML Load¶

Load TOML from file.

Examples¶

from rite.serialization.toml import toml_load config = toml_load("config.toml")

Functions¶

toml_load ¶

toml_load(path: str | Path) -> dict[str, Any]

Load TOML from file.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to TOML file.	required

Returns:

Type	Description
`dict[str, Any]`	Parsed TOML as dictionary.

Raises:

Type	Description
`ImportError`	If Python version < 3.11.

Examples:

>>> toml_load("config.toml")
{'section': {'key': 'value'}}

Notes

Requires Python 3.11+ (tomllib). Read-only (no write support in stdlib).

toml_loads ¶

TOML Loads¶

Parse TOML from string.

Examples¶

from rite.serialization.toml import toml_loads config = toml_loads('[section]\nkey = "value"')

Functions¶

toml_loads ¶

toml_loads(text: str) -> dict[str, Any]

Parse TOML from string.

Parameters:

Name	Type	Description	Default
`text`	`str`	TOML string to parse.	required

Returns:

Type	Description
`dict[str, Any]`	Parsed TOML as dictionary.

Raises:

Type	Description
`ImportError`	If Python version < 3.11.

Examples:

>>> toml_loads('[section]\nkey = "value"')
{'section': {'key': 'value'}}

Notes

Requires Python 3.11+ (tomllib).

toml_load ¶

TOML Load¶

Load TOML from file.

Examples¶

from rite.serialization.toml import toml_load config = toml_load("config.toml")

Functions¶

toml_load ¶

toml_load(path: str | Path) -> dict[str, Any]

Load TOML from file.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to TOML file.	required

Returns:

Type	Description
`dict[str, Any]`	Parsed TOML as dictionary.

Raises:

Type	Description
`ImportError`	If Python version < 3.11.

Examples:

>>> toml_load("config.toml")
{'section': {'key': 'value'}}

Notes

Requires Python 3.11+ (tomllib). Read-only (no write support in stdlib).

toml_loads ¶

TOML Loads¶

Parse TOML from string.

Examples¶

from rite.serialization.toml import toml_loads config = toml_loads('[section]\nkey = "value"')

Functions¶

toml_loads ¶

toml_loads(text: str) -> dict[str, Any]

Parse TOML from string.

Parameters:

Name	Type	Description	Default
`text`	`str`	TOML string to parse.	required

Returns:

Type	Description
`dict[str, Any]`	Parsed TOML as dictionary.

Raises:

Type	Description
`ImportError`	If Python version < 3.11.

Examples:

>>> toml_loads('[section]\nkey = "value"')
{'section': {'key': 'value'}}

Notes

Requires Python 3.11+ (tomllib).

Submodules¶

JSON¶

Parse and generate JSON data.

JSON Module¶

JSON serialization utilities.

This submodule provides utilities for JSON operations like loading, dumping, parsing, and validation.

Examples¶

from rite.serialization.json import json_load, json_dump data = json_load("input.json") json_dump("output.json", data)

Modules¶

json_load ¶

JSON Loader¶

Load JSON from file.

Examples¶

from rite.serialization.json import json_load data = json_load("data.json")

Functions¶

json_load ¶

json_load(path: str | Path) -> Any

Load JSON data from file.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to JSON file.	required

Returns:

Type	Description
`Any`	Parsed JSON data.

Raises:

Type	Description
`FileNotFoundError`	If file doesn't exist.
`JSONDecodeError`	If JSON is invalid.

Examples:

>>> json_load("config.json")
{'key': 'value'}

Notes

Uses UTF-8 encoding.

json_loads ¶

JSON Loads¶

Parse JSON from string.

Examples¶

from rite.serialization.json import json_loads json_loads('{"key": "value"}')

Functions¶

json_loads ¶

json_loads(text: str) -> Any

Parse JSON from string.

Parameters:

Name	Type	Description	Default
`text`	`str`	JSON string to parse.	required

Returns:

Type	Description
`Any`	Parsed JSON data.

Raises:

Type	Description
`JSONDecodeError`	If JSON is invalid.

Examples:

>>> json_loads('{"key": "value"}')
{'key': 'value'}
>>> json_loads('[1, 2, 3]')
[1, 2, 3]

Notes

Wrapper around json.loads.

json_dump ¶

JSON Dumper¶

Save JSON to file.

Examples¶

from rite.serialization.json import json_dump json_dump("output.json", {"key": "value"})

Functions¶

json_dump ¶

json_dump(path: str | Path, data: Any, indent: int | None = 2) -> None

Save JSON data to file.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to output JSON file.	required
`data`	`Any`	Data to serialize.	required
`indent`	`int \| None`	Indentation spaces (None for compact).	`2`

Returns:

Type	Description
`None`	None

Examples:

>>> json_dump("output.json", {"key": "value"})
>>> json_dump("compact.json", data, indent=None)

Notes

Creates parent directories if needed. Uses UTF-8 encoding.

json_dumps ¶

JSON Dumps¶

Serialize data to JSON string.

Examples¶

from rite.serialization.json import json_dumps json_dumps({"key": "value"}) '{"key": "value"}'

Functions¶

json_dumps ¶

json_dumps(data: Any, indent: int | None = None) -> str

Serialize data to JSON string.

Parameters:

Name	Type	Description	Default
`data`	`Any`	Data to serialize.	required
`indent`	`int \| None`	Indentation spaces (None for compact).	`None`

Returns:

Type	Description
`str`	JSON string.

Examples:

>>> json_dumps({"key": "value"})
'{"key": "value"}'
>>> json_dumps({"key": "value"}, indent=2)
'{\n  "key": "value"\n}'

Notes

Wrapper around json.dumps.

json_validate ¶

JSON Validator¶

Validate JSON string.

Examples¶

from rite.serialization.json import json_validate json_validate('{"key": "value"}') True

Functions¶

json_validate ¶

json_validate(text: str) -> bool

Validate JSON string.

Parameters:

Name	Type	Description	Default
`text`	`str`	JSON string to validate.	required

Returns:

Type	Description
`bool`	True if valid JSON, False otherwise.

Examples:

>>> json_validate('{"key": "value"}')
True
>>> json_validate('{invalid}')
False
>>> json_validate('[1, 2, 3]')
True

Notes

Returns False on any JSON decode error.

CSV¶

Read and write CSV files.

CSV Module¶

CSV file operations.

This submodule provides utilities for reading and writing CSV files with automatic delimiter detection.

Examples¶

from rite.serialization.csv import csv_read, csv_write data = csv_read("input.csv") csv_write("output.csv", data)

Modules¶

csv_read ¶

CSV Reader¶

Read CSV file to list of dicts.

Examples¶

from rite.serialization.csv import csv_read rows = csv_read("data.csv")

Functions¶

csv_read ¶

csv_read(path: str | Path, delimiter: str = ',') -> list[dict[str, Any]]

Read CSV file to list of dictionaries.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to CSV file.	required
`delimiter`	`str`	CSV delimiter character.	`','`

Returns:

Type	Description
`list[dict[str, Any]]`	List of row dictionaries.

Examples:

>>> csv_read("data.csv")
[{'col1': 'val1', 'col2': 'val2'}, ...]
>>> csv_read("data.tsv", delimiter="\t")
[...]

Notes

Uses DictReader for named columns. First row is header.

csv_write ¶

CSV Writer¶

Write list of dicts to CSV file.

Examples¶

from rite.serialization.csv import csv_write data = [{"col1": "val1", "col2": "val2"}] csv_write("output.csv", data)

Functions¶

csv_write ¶

csv_write(path: str | Path, data: list[dict[str, Any]], delimiter: str = ',') -> None

Write list of dictionaries to CSV file.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to output CSV file.	required
`data`	`list[dict[str, Any]]`	List of row dictionaries.	required
`delimiter`	`str`	CSV delimiter character.	`','`

Returns:

Type	Description
`None`	None

Examples:

>>> data = [{"col1": "val1", "col2": "val2"}]
>>> csv_write("output.csv", data)
>>> csv_write("output.tsv", data, delimiter="\t")

Notes

Creates parent directories if needed. Header from first row keys.

csv_detect_delimiter ¶

CSV Delimiter Detector¶

Detect delimiter from filename.

Examples¶

from rite.serialization.csv import csv_detect_delimiter csv_detect_delimiter("data.tsv") '\t'

Functions¶

csv_detect_delimiter ¶

csv_detect_delimiter(filename: str) -> str

Detect delimiter from filename extension.

Parameters:

Name	Type	Description	Default
`filename`	`str`	CSV filename or path.	required

Returns:

Type	Description
`str`	Delimiter character (tab or comma).

Examples:

>>> csv_detect_delimiter("data.csv")
','
>>> csv_detect_delimiter("data.tsv")
'\t'
>>> csv_detect_delimiter("path/to/data.tsv")
'\t'

Notes

Returns tab for .tsv, comma otherwise.

TOML¶

Parse TOML configuration files (Python 3.11+).

TOML Module¶

TOML file operations.

This submodule provides utilities for reading TOML files using the stdlib tomllib (Python 3.11+). Write operations are not supported in stdlib.

Examples¶

from rite.serialization.toml import toml_load config = toml_load("config.toml")

Modules¶

toml_load ¶

TOML Load¶

Load TOML from file.

Examples¶

from rite.serialization.toml import toml_load config = toml_load("config.toml")

Functions¶

toml_load ¶

toml_load(path: str | Path) -> dict[str, Any]

Load TOML from file.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to TOML file.	required

Returns:

Type	Description
`dict[str, Any]`	Parsed TOML as dictionary.

Raises:

Type	Description
`ImportError`	If Python version < 3.11.

Examples:

>>> toml_load("config.toml")
{'section': {'key': 'value'}}

Notes

Requires Python 3.11+ (tomllib). Read-only (no write support in stdlib).

toml_loads ¶

TOML Loads¶

Parse TOML from string.

Examples¶

from rite.serialization.toml import toml_loads config = toml_loads('[section]\nkey = "value"')

Functions¶

toml_loads ¶

toml_loads(text: str) -> dict[str, Any]

Parse TOML from string.

Parameters:

Name	Type	Description	Default
`text`	`str`	TOML string to parse.	required

Returns:

Type	Description
`dict[str, Any]`	Parsed TOML as dictionary.

Raises:

Type	Description
`ImportError`	If Python version < 3.11.

Examples:

>>> toml_loads('[section]\nkey = "value"')
{'section': {'key': 'value'}}

Notes

Requires Python 3.11+ (tomllib).

Pickle¶

Serialize and deserialize Python objects.

Pickle Module¶

Pickle serialization operations.

This submodule provides utilities for serializing and deserializing Python objects using the pickle protocol.

Examples¶

from rite.serialization.pickle import pickle_dump, pickle_load pickle_dump("data.pkl", {"key": "value"}) data = pickle_load("data.pkl")

Modules¶

pickle_dump ¶

Pickle Dump¶

Serialize object to pickle file.

Examples¶

from rite.serialization.pickle import pickle_dump pickle_dump("data.pkl", {"key": "value"})

Functions¶

pickle_dump ¶

pickle_dump(path: str | Path, data: Any) -> None

Serialize object to pickle file.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to output pickle file.	required
`data`	`Any`	Object to serialize.	required

Returns:

Type	Description
`None`	None

Examples:

>>> pickle_dump("data.pkl", {"key": "value"})
>>> pickle_dump("data.pkl", [1, 2, 3])

Notes

Creates parent directories if needed. Uses binary mode.

pickle_load ¶

Pickle Load¶

Deserialize object from pickle file.

Examples¶

from rite.serialization.pickle import pickle_load data = pickle_load("data.pkl")

Functions¶

pickle_load ¶

pickle_load(path: str | Path) -> Any

Deserialize object from pickle file.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to pickle file.	required

Returns:

Type	Description
`Any`	Deserialized object.

Examples:

>>> pickle_load("data.pkl")
{'key': 'value'}

Notes

Uses binary mode. Be careful with untrusted data.

pickle_dumps ¶

Pickle Dumps¶

Serialize object to bytes.

Examples¶

from rite.serialization.pickle import pickle_dumps data = pickle_dumps({"key": "value"})

Functions¶

pickle_dumps ¶

pickle_dumps(data: Any) -> bytes

Serialize object to bytes.

Parameters:

Name	Type	Description	Default
`data`	`Any`	Object to serialize.	required

Returns:

Type	Description
`bytes`	Serialized bytes.

Examples:

>>> pickle_dumps({"key": "value"})
b'\x80\x04...'

Notes

Returns bytes for network transmission.

pickle_loads ¶

Pickle Loads¶

Deserialize object from bytes.

Examples¶

from rite.serialization.pickle import pickle_loads data = pickle_loads(b'\x80\x04...')

Functions¶

pickle_loads ¶

pickle_loads(data: bytes) -> Any

Deserialize object from bytes.

Parameters:

Name	Type	Description	Default
`data`	`bytes`	Serialized bytes.	required

Returns:

Type	Description
`Any`	Deserialized object.

Examples:

>>> pickle_loads(b'\x80\x04...')
{'key': 'value'}

Notes

Be careful with untrusted data.

INI¶

Read and write INI configuration files.

INI Module¶

INI configuration file operations.

This submodule provides utilities for reading and writing INI/config files with section and key-value operations.

Examples¶

from rite.serialization.ini import ini_read, ini_write config = ini_read("config.ini") ini_write("output.ini", config)

Modules¶

ini_read ¶

INI Reader¶

Read INI configuration file.

Examples¶

from rite.serialization.ini import ini_read config = ini_read("config.ini")

Functions¶

ini_read ¶

ini_read(path: str | Path) -> dict[str, dict[str, str]]

Read INI file to nested dictionary.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to INI file.	required

Returns:

Type	Description
`dict[str, dict[str, str]]`	Nested dictionary of sections and key-value pairs.

Examples:

>>> ini_read("config.ini")
{'section': {'key': 'value'}}

Notes

Uses ConfigParser for INI parsing. Returns nested dict structure.

ini_write ¶

INI Writer¶

Write nested dict to INI file.

Examples¶

from rite.serialization.ini import ini_write config = {"section": {"key": "value"}} ini_write("config.ini", config)

Functions¶

ini_write ¶

ini_write(path: str | Path, data: dict[str, dict[str, str]]) -> None

Write nested dictionary to INI file.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to output INI file.	required
`data`	`dict[str, dict[str, str]]`	Nested dict of sections and key-value pairs.	required

Returns:

Type	Description
`None`	None

Examples:

>>> config = {"section": {"key": "value"}}
>>> ini_write("config.ini", config)

Notes

Creates parent directories if needed. Uses ConfigParser for formatting.

ini_get ¶

INI Get Value¶

Get value from INI configuration.

Examples¶

from rite.serialization.ini import ini_get ini_get("config.ini", "section", "key") 'value'

Functions¶

ini_get ¶

ini_get(path: str | Path, section: str, key: str, default: str | None = None) -> str | None

Get value from INI file.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to INI file.	required
`section`	`str`	Section name.	required
`key`	`str`	Key name.	required
`default`	`str \| None`	Default value if not found.	`None`

Returns:

Type	Description
`str \| None`	Value string or default.

Examples:

>>> ini_get("config.ini", "section", "key")
'value'
>>> ini_get("config.ini", "section", "missing", "default")
'default'

Notes

Returns default if section or key not found.

ini_set ¶

INI Set Value¶

Set value in INI configuration.

Examples¶

from rite.serialization.ini import ini_set ini_set("config.ini", "section", "key", "value")

Functions¶

ini_set ¶

ini_set(path: str | Path, section: str, key: str, value: str) -> None

Set value in INI file.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to INI file.	required
`section`	`str`	Section name.	required
`key`	`str`	Key name.	required
`value`	`str`	Value to set.	required

Returns:

Type	Description
`None`	None

Examples:

>>> ini_set("config.ini", "section", "key", "value")

Notes

Creates section if not exists. Creates file if not exists.

Examples¶

JSON Operations¶

from rite.serialization import json_load, json_dump, json_validate

# Load JSON from file
data = json_load("config.json")

# Save JSON to file
json_dump({"key": "value"}, "output.json")

# Validate JSON string
is_valid = json_validate('{"valid": true}')

CSV Operations¶

from rite.serialization import csv_read, csv_write

# Read CSV file
rows = csv_read("data.csv")

# Write CSV file
csv_write("output.csv", [
    ["name", "age"],
    ["Alice", 30],
    ["Bob", 25]
])

TOML Operations (Python 3.11+)¶

from rite.serialization import toml_load

# Load TOML configuration
config = toml_load("pyproject.toml")