I/O

momapy.io

IO subpackage for reading and writing maps.

Provides functions and registries for reading and writing molecular maps in various formats (SBGN-ML, CellDesigner, SBML, etc.).

Examples:

from momapy.io import get_reader, get_writer
reader = get_reader("sbgnml")
writer = get_writer("sbgnml")

Modules:

Name	Description
core	Base classes and functions for reading and writing maps.
pickle	Pickle-based reader and writer.
utils	Internal utilities for map readers.

Classes:

Name	Description
ReaderResult	Result from reading a map file.
WriterResult	Result from writing a map file.

Functions:

Name	Description
get_reader	Get a reader class by name.
get_writer	Get a writer class by name.
list_readers	List all available reader names.
list_writers	List all available writer names.
read	Read a map file.
register_lazy_reader	Register a reader for lazy loading.
register_lazy_writer	Register a writer for lazy loading.
register_reader	Register a reader class.
register_writer	Register a writer class.
write	Write an object to a file.

ReaderResult dataclass

ReaderResult(obj: Any | None = None, element_to_annotations: frozendict | None = None, element_to_notes: frozendict | None = None, id_to_element: frozendict | None = None, source_id_to_model_element: FrozenIdentityMultiDict | None = None, source_id_to_layout_element: FrozenSurjectionDict | None = None, source_id_to_annotations: frozendict | None = None, source_id_to_notes: frozendict | None = None, file_path: str | PathLike | None = None)

Bases: IOResult

Result from reading a map file.

Attributes:

Name	Type	Description

Parameters:

Name	Type	Description	Default
obj	Any | None		None
element_to_annotations	frozendict | None		None
element_to_notes	frozendict | None		None
id_to_element	frozendict | None		None
source_id_to_model_element	FrozenIdentityMultiDict | None		None
source_id_to_layout_element	FrozenSurjectionDict | None		None
source_id_to_annotations	frozendict | None		None
source_id_to_notes	frozendict | None		None
file_path	str | PathLike | None		None

WriterResult dataclass

WriterResult(obj: Any | None = None, file_path: str | PathLike | None = None)

Bases: IOResult

Result from writing a map file.

Attributes:

Name	Type	Description

Parameters:

Name	Type	Description	Default
obj	Any | None		None
file_path	str | PathLike | None		None

get_reader

get_reader(name: str) -> type[Reader]

Get a reader class by name.

Parameters:

Name	Type	Description	Default
name	str	Reader name (e.g., "sbgnml", "celldesigner").	required

Returns:

Type	Description
type[Reader]	Reader class for the specified format.

Raises:

Type	Description
ValueError	If no reader with that name exists.

Source code in src/momapy/io/core.py

def get_reader(name: str) -> type["Reader"]:
    """Get a reader class by name.

    Args:
        name: Reader name (e.g., "sbgnml", "celldesigner").

    Returns:
        Reader class for the specified format.

    Raises:
        ValueError: If no reader with that name exists.
    """
    reader = reader_registry.get(name)
    if reader is None:
        available = reader_registry.list_available()
        raise ValueError(
            f"No reader named '{name}'. Available readers: {', '.join(available)}"
        )
    return reader

get_writer

get_writer(name: str) -> type[Writer]

Get a writer class by name.

Parameters:

Name	Type	Description	Default
name	str	Writer name (e.g., "sbgnml", "pickle").	required

Returns:

Type	Description
type[Writer]	Writer class for the specified format.

Raises:

Type	Description
ValueError	If no writer with that name exists.

Source code in src/momapy/io/core.py

def get_writer(name: str) -> type["Writer"]:
    """Get a writer class by name.

    Args:
        name: Writer name (e.g., "sbgnml", "pickle").

    Returns:
        Writer class for the specified format.

    Raises:
        ValueError: If no writer with that name exists.
    """
    writer = writer_registry.get(name)
    if writer is None:
        available = writer_registry.list_available()
        raise ValueError(
            f"No writer named '{name}'. Available writers: {', '.join(available)}"
        )
    return writer

list_readers

list_readers() -> list[str]

List all available reader names.

Returns:

Type	Description
list[str]	Sorted list of available reader names.

Source code in src/momapy/io/core.py

def list_readers() -> list[str]:
    """List all available reader names.

    Returns:
        Sorted list of available reader names.
    """
    return reader_registry.list_available()

list_writers

list_writers() -> list[str]

List all available writer names.

Returns:

Type	Description
list[str]	Sorted list of available writer names.

Source code in src/momapy/io/core.py

def list_writers() -> list[str]:
    """List all available writer names.

    Returns:
        Sorted list of available writer names.
    """
    return writer_registry.list_available()

read

read(file_path: str | PathLike, reader: str | None = None, **options: Any) -> ReaderResult

Read a map file.

If reader is specified, uses that reader. Otherwise, checks all registered readers to find one that supports the file format using their check_file method. Uses the first matching reader found.

Parameters:

Name	Type	Description	Default
file_path	str | PathLike	Path of the file to read.	required
reader	str | None	Name of registered reader to use (e.g., "sbgnml"). If None, auto-detects based on file format.	None
options	Any	Additional options passed to the reader.	{}

Returns:

Type	Description
ReaderResult	ReaderResult containing the read object and metadata.

Raises:

Type	Description
ValueError	If no suitable reader is found.

Examples:

from momapy.io.core import read
result = read("map.sbgn")
map_obj = result.obj

Source code in src/momapy/io/core.py

def read(
    file_path: str | os.PathLike,
    reader: str | None = None,
    **options: typing.Any,
) -> ReaderResult:
    """Read a map file.

    If reader is specified, uses that reader. Otherwise, checks all registered
    readers to find one that supports the file format using their check_file
    method. Uses the first matching reader found.

    Args:
        file_path: Path of the file to read.
        reader: Name of registered reader to use (e.g., "sbgnml"). If None,
            auto-detects based on file format.
        options: Additional options passed to the reader.

    Returns:
        ReaderResult containing the read object and metadata.

    Raises:
        ValueError: If no suitable reader is found.

    Examples:
        ```python
        from momapy.io.core import read
        result = read("map.sbgn")
        map_obj = result.obj
        ```
    """
    if reader is not None:
        reader_cls = get_reader(reader)
    else:
        reader_cls = None
        for name in reader_registry.list_available():
            candidate_cls = get_reader(name)
            if candidate_cls.check_file(file_path):
                reader_cls = candidate_cls
                break
        if reader_cls is None:
            raise ValueError(
                f"could not find a suitable registered reader for file '{file_path}'"
            )
    result = reader_cls.read(file_path, **options)
    return result

register_lazy_reader

register_lazy_reader(name: str, import_path: str) -> None

Register a reader for lazy loading.

Parameters:

Name	Type	Description	Default
name	str	Name to register the reader under.	required
import_path	str	Import path in format "module.path:ClassName".	required

Source code in src/momapy/io/core.py

def register_lazy_reader(name: str, import_path: str) -> None:
    """Register a reader for lazy loading.

    Args:
        name: Name to register the reader under.
        import_path: Import path in format "module.path:ClassName".
    """
    reader_registry.register_lazy(name, import_path)

register_lazy_writer

register_lazy_writer(name: str, import_path: str) -> None

Register a writer for lazy loading.

Parameters:

Name	Type	Description	Default
name	str	Name to register the writer under.	required
import_path	str	Import path in format "module.path:ClassName".	required

Source code in src/momapy/io/core.py

def register_lazy_writer(name: str, import_path: str) -> None:
    """Register a writer for lazy loading.

    Args:
        name: Name to register the writer under.
        import_path: Import path in format "module.path:ClassName".
    """
    writer_registry.register_lazy(name, import_path)

register_reader

register_reader(name: str, cls: type[Reader]) -> None

Register a reader class.

Parameters:

Name	Type	Description	Default
name	str	Name to register the reader under.	required
cls	type[Reader]	Reader class (must inherit from Reader).	required

Source code in src/momapy/io/core.py

def register_reader(name: str, cls: type["Reader"]) -> None:
    """Register a reader class.

    Args:
        name: Name to register the reader under.
        cls: Reader class (must inherit from Reader).
    """
    reader_registry.register(name, cls)

register_writer

register_writer(name: str, cls: type[Writer]) -> None

Register a writer class.

Parameters:

Name	Type	Description	Default
name	str	Name to register the writer under.	required
cls	type[Writer]	Writer class (must inherit from Writer).	required

Source code in src/momapy/io/core.py

def register_writer(name: str, cls: type["Writer"]) -> None:
    """Register a writer class.

    Args:
        name: Name to register the writer under.
        cls: Writer class (must inherit from Writer).
    """
    writer_registry.register(name, cls)

write

write(obj: Any, file_path: str | PathLike, writer: str, **options: Any) -> WriterResult

Write an object to a file.

Parameters:

Name	Type	Description	Default
obj	Any	Object to write (typically a MapElement).	required
file_path	str | PathLike	Path of the file to write to.	required
writer	str	Name of registered writer to use (e.g., "sbgnml").	required
options	Any	Additional options passed to the writer.	{}

Returns:

Type	Description
WriterResult	WriterResult containing the written object and metadata.

Raises:

Type	Description
ValueError	If the writer is not found.

Examples:

from momapy.io.core import write
write(map_obj, "output.sbgn", writer="sbgnml")

Source code in src/momapy/io/core.py

def write(
    obj: typing.Any,
    file_path: str | os.PathLike,
    writer: str,
    **options: typing.Any,
) -> WriterResult:
    """Write an object to a file.

    Args:
        obj: Object to write (typically a MapElement).
        file_path: Path of the file to write to.
        writer: Name of registered writer to use (e.g., "sbgnml").
        options: Additional options passed to the writer.

    Returns:
        WriterResult containing the written object and metadata.

    Raises:
        ValueError: If the writer is not found.

    Examples:
        ```python
        from momapy.io.core import write
        write(map_obj, "output.sbgn", writer="sbgnml")
        ```
    """
    writer_cls = get_writer(writer)
    result = writer_cls.write(obj, file_path, **options)
    return result