io#

PhyloZoo I/O utilities (phylozoo.utils.io).

Provides FormatRegistry, IOMixin, and file operations. Shared format structure (NEXUS, PHYLIP) is in phylozoo.utils.io.format_utils; class-specific readers/writers are in core/distance/io, core/sequence/io, core/split/io, etc.

IOMixin#

Mixin providing unified I/O methods for phylozoo classes.

Classes that inherit from IOMixin get save/load, to_string/from_string, and convert/convert_string. Format handlers must be registered via FormatRegistry.

class phylozoo.utils.io.mixin.IOMixin[source]#

Bases: object

Mixin providing unified I/O methods for phylozoo classes.

Classes that inherit from this mixin get consistent methods for saving/loading to/from files and converting to/from strings. Format handlers must be registered using FormatRegistry before use.

Classes should define:

_default_format: str - Default format name
_supported_formats: list[str] - List of supported format names

Examples

>>> from phylozoo.utils.io import IOMixin, FormatRegistry
>>>
>>> class MyNetwork(IOMixin):
...     _default_format = 'enewick'
...     _supported_formats = ['enewick']
...     def __init__(self, data):
...         self.data = data
>>>
>>> FormatRegistry.register(
...     MyNetwork, 'enewick',
...     reader=lambda s: MyNetwork(s.strip()),
...     writer=lambda n: str(n.data),
...     extensions=['.enewick'],
...     default=True
... )
>>> net = MyNetwork("test_data")
>>> net.save('network.enewick')
>>> net2 = MyNetwork.load('network.enewick')

classmethod convert(input_file: str | Path, output_file: str | Path, input_format: str | None = None, output_format: str | None = None, overwrite: bool = False, **kwargs: object) → None[source]#

Convert a file from one format to another.

Parameters:

input_file (str or Path) – Path to the input file.
output_file (str or Path) – Path to the output file.
input_format (str or None, optional) – Input format name. If None, inferred from the input file extension.
output_format (str or None, optional) – Output format name. If None, inferred from the output file extension.
overwrite (bool, optional) – If True, overwrite existing output file. Default is False.
**kwargs – Additional format-specific options passed to reader and writer.

Raises:

FileExistsError – If the output file already exists and overwrite is False.
PhyloZooFormatError – If either format is not supported.

classmethod convert_string(content: str, input_format: str, output_format: str, **kwargs: object) → str[source]#

Convert a string representation from one format to another.

Parameters:

content (str) – String content in the input format.
input_format (str) – Input format name.
output_format (str) – Output format name.
**kwargs – Additional format-specific options passed to reader and writer.

Returns:

String representation in the output format.

Return type:

str

Raises:

PhyloZooFormatError – If either format is not supported.

classmethod from_string(string: str, format: str | None = None, **kwargs: object)[source]#

Create instance from a string representation.

Parameters:

string (str) – String content in the specified format.
format (str or None, optional) – Input format name. If None, uses the class’s default format.
**kwargs – Additional format-specific options passed to the reader.

Returns:

A new instance parsed from the string.

Return type:

instance of cls

Raises:

PhyloZooFormatError – If the format is not supported.

classmethod load(filepath: str | Path, format: str | None = None, **kwargs: object)[source]#

Load instance from a file.

Parameters:

filepath (str or Path) – Path to the input file.
format (str or None, optional) – Input format name. If None, inferred from the file extension.
**kwargs – Additional format-specific options passed to the reader.

Returns:

A new instance loaded from the file.

Return type:

instance of cls

Raises:

PhyloZooFormatError – If the format is not supported.

save(filepath: str | Path, format: str | None = None, overwrite: bool = False, **kwargs: object) → None[source]#

Save instance to a file.

Parameters:

filepath (str or Path) – Path to the output file.
format (str or None, optional) – Output format name. If None, inferred from the file extension.
overwrite (bool, optional) – If True, overwrite existing file. Default is False.
**kwargs – Additional format-specific options passed to the writer.

Raises:

FileExistsError – If the file already exists and overwrite is False.
PhyloZooFormatError – If the format is not supported.

to_string(format: str | None = None, **kwargs: object) → str[source]#

Convert instance to string representation in the given format.

Parameters:

format (str or None, optional) – Output format name. If None, uses the class’s default format.
**kwargs – Additional format-specific options passed to the writer.

Returns:

String representation of the instance in the requested format.

Return type:

str

Raises:

PhyloZooFormatError – If the requested format is not in the class’s supported formats.

File operations#

Low-level file operations for phylozoo I/O.

Provides read_file_safely, write_file_safely, and ensure_directory_exists used by the IOMixin and format handlers.

phylozoo.utils.io.file_ops.ensure_directory_exists(filepath: str | Path) → Path[source]#

Ensure the directory containing the filepath exists, creating it if necessary.

Parameters:: filepath (str | Path) – Path to a file (directory will be created if needed).
Returns:: Path object to the directory.
Return type:: Path

Examples

>>> from phylozoo.utils.io import ensure_directory_exists
>>> dir_path = ensure_directory_exists("output/data.txt")
>>> dir_path.exists()
True

phylozoo.utils.io.file_ops.read_file_safely(filepath: str | Path, encoding: str = 'utf-8') → str[source]#

Read a file safely with error handling.

Parameters:

filepath (str | Path) – Path to the file to read.
encoding (str, optional) – File encoding, by default ‘utf-8’.

Returns:

File contents as string.

Return type:

str

Raises:

FileNotFoundError – If the file does not exist.
PhyloZooValueError – If the path is not a file.
PhyloZooIOError – If the file cannot be read.

Examples

>>> from phylozoo.utils.io import read_file_safely
>>> content = read_file_safely("data.txt")
>>> len(content) > 0
True

phylozoo.utils.io.file_ops.write_file_safely(filepath: str | Path, content: str, encoding: str = 'utf-8') → None[source]#

Write content to a file safely with error handling.

Parameters:

filepath (str | Path) – Path to the file to write.
content (str) – Content to write to the file.
encoding (str, optional) – File encoding, by default ‘utf-8’.

Raises:

PhyloZooIOError – If the file cannot be written.

Examples

>>> from phylozoo.utils.io import write_file_safely
>>> write_file_safely("output.txt", "Hello, world!")

FormatRegistry#

Central registry for I/O format handlers.

Provides FormatRegistry for registering format readers and writers for different object types. Formats can be detected from file extensions.

class phylozoo.utils.io.registry.FormatRegistry[source]#

Bases: object

Central registry for I/O format handlers.

This class provides a registry system for registering format readers and writers for different object types. Formats can be automatically detected from file extensions, and multiple formats can be registered for the same class.

Examples

>>> from phylozoo.utils.io import FormatRegistry
>>>
>>> # Register a format
>>> FormatRegistry.register(
...     MyClass, 'json',
...     reader=from_json,
...     writer=to_json,
...     extensions=['.json']
... )
>>>
>>> # Get handlers
>>> writer = FormatRegistry.get_writer(MyClass, 'json')
>>> reader = FormatRegistry.get_reader(MyClass, 'json')
>>>
>>> # Detect format from file extension
>>> format = FormatRegistry.detect_format('data.json', MyClass)
>>> format
'json'

classmethod detect_format(filepath: str | Path, obj_type: type) → str[source]#: Detect format from file extension.

classmethod get_reader(obj_type: type, format: str) → Callable[[...], Any][source]#: Get reader function for a type and format.

classmethod get_writer(obj_type: type, format: str) → Callable[[...], Any][source]#: Get writer function for a type and format.

classmethod register(obj_type: type, format: str, reader: Callable[[...], Any], writer: Callable[[...], Any], extensions: list[str] | None = None, default: bool = False) → None[source]#

Parameters:

obj_type (type) – The class type to register handlers for.
format (str) – Format name (e.g., ‘enewick’, ‘nexus’, ‘json’).
reader (Callable) – Function that takes a string and returns an instance of obj_type. Signature: reader(string: str, **kwargs) -> obj_type
writer (Callable) – Function that takes an instance of obj_type and returns a string. Signature: writer(obj: obj_type, **kwargs) -> str
extensions (list[str] | None, optional) – List of file extensions that map to this format. If None, no automatic detection is available. By default None.
default (bool, optional) – If True, set this format as the default for obj_type. By default False.

Format utilities#

format_utils

io#

IOMixin#

File operations#

FormatRegistry#

Format utilities#

This Page