exceptions

Custom exception hierarchy for PhyloZoo.

This package provides a comprehensive set of custom exceptions organized by domain. All exceptions inherit from PhyloZooError, allowing easy catching of PhyloZoo-specific errors. Many also inherit from built-in exceptions (e.g., ValueError) for backward compatibility.

Examples

>>> from phylozoo.utils.exceptions import PhyloZooError, PhyloZooNetworkError
>>>
>>> # Catch all PhyloZoo errors
>>> try:
...     network.validate()
... except PhyloZooError as e:
...     print(f"PhyloZoo error: {e}")
>>>
>>> # Catch specific domain errors
>>> try:
...     network.validate()
... except PhyloZooNetworkError as e:
...     print(f"Network error: {e}")
>>>
>>> # Still works with built-in exceptions (backward compatible)
>>> try:
...     network.validate()
... except ValueError as e:
...     print(f"Value error: {e}")

Base

Base exception for PhyloZoo.

All custom exceptions in PhyloZoo inherit from PhyloZooError.

exception phylozoo.utils.exceptions.base.PhyloZooError

Bases: Exception

Base exception for all PhyloZoo errors.

All custom exceptions in PhyloZoo inherit from this class, allowing users to catch all PhyloZoo-specific errors with a single except clause.

Examples

>>> from phylozoo.utils.exceptions import PhyloZooError
>>>
>>> try:
...     # Some PhyloZoo operation
...     pass
... except PhyloZooError as e:
...     print(f"Caught PhyloZoo error: {e}")

General

General-purpose exceptions for PhyloZoo.

exception phylozoo.utils.exceptions.general.PhyloZooAttributeError

Bases: PhyloZooError, AttributeError

Raised when an attribute is invalid.

This exception is used when an attribute is invalid. Inherits from both PhyloZooError and AttributeError for backward compatibility.

exception phylozoo.utils.exceptions.general.PhyloZooImportError

Bases: PhyloZooError, ImportError

Raised when an import fails.

This exception is used when a required module or dependency cannot be imported. Inherits from both PhyloZooError and ImportError for backward compatibility.

exception phylozoo.utils.exceptions.general.PhyloZooNotImplementedError

Bases: PhyloZooError, NotImplementedError

Raised when a feature is not implemented.

This exception is used when a method or feature is declared but not yet implemented. Inherits from both PhyloZooError and NotImplementedError for backward compatibility.

exception phylozoo.utils.exceptions.general.PhyloZooRuntimeError

Bases: PhyloZooError, RuntimeError

Raised when a runtime error occurs.

This exception is used for general runtime errors. Inherits from both PhyloZooError and RuntimeError for backward compatibility.

exception phylozoo.utils.exceptions.general.PhyloZooTypeError

Bases: PhyloZooError, TypeError

Raised when a type is incorrect.

This exception is used when an argument has the wrong type (e.g., string when number expected, wrong class instance). Inherits from both PhyloZooError and TypeError for backward compatibility.

Note: For value errors (right type, wrong value), use PhyloZooValueError instead.

exception phylozoo.utils.exceptions.general.PhyloZooValueError

Bases: PhyloZooError, ValueError

Raised when a value is invalid or out of range.

This exception is used for parameter validation errors where the type is correct but the value is inappropriate (e.g., out of range, negative when positive expected). Inherits from both PhyloZooError and ValueError for backward compatibility.

Note: For type errors (wrong type), use PhyloZooTypeError instead.

Network

Network domain exceptions for PhyloZoo.

exception phylozoo.utils.exceptions.network.PhyloZooNetworkAttributeError

Bases: PhyloZooNetworkError

Raised when network edge attributes are invalid.

This exception is used for attribute validation failures such as:

• Invalid gamma values (not in [0, 1] or don’t sum to 1.0)

• Invalid bootstrap values (not in [0, 1])

• Invalid branch_length values (inconsistent across parallel edges)

exception phylozoo.utils.exceptions.network.PhyloZooNetworkDegreeError

Bases: PhyloZooNetworkError

Raised when node degree constraints are violated.

This exception is used when nodes have invalid degrees, such as:

• Leaf nodes with wrong in-degree or out-degree

• Internal nodes with invalid degree combinations

• Root nodes with wrong in-degree

exception phylozoo.utils.exceptions.network.PhyloZooNetworkError

Bases: PhyloZooValueError

Base exception for network-related errors.

All network-specific errors inherit from this class, allowing users to catch all network errors with a single except clause.

exception phylozoo.utils.exceptions.network.PhyloZooNetworkStructureError

Bases: PhyloZooNetworkError

Raised when network structure is invalid.

This exception is used for structural validation failures such as:

• Directed cycles

• Disconnected networks

• Self-loops

• Invalid connectivity

I/O

I/O domain exceptions for PhyloZoo.

exception phylozoo.utils.exceptions.io.PhyloZooFormatError

Bases: PhyloZooIOError

Raised when format-related operations fail.

This exception is used for format-related errors such as:

• Unsupported formats

• Format conversion failures

• Format detection failures

exception phylozoo.utils.exceptions.io.PhyloZooIOError

Bases: PhyloZooError, OSError

Raised when I/O operations fail.

This exception is used for general I/O errors. Inherits from both PhyloZooError and IOError=OSError for backward compatibility.

exception phylozoo.utils.exceptions.io.PhyloZooParseError

Bases: PhyloZooIOError

Raised when parsing fails.

This exception is used for parsing errors in various formats such as:

• eNewick parsing errors

• Newick parsing errors

• Other format parsing errors

Algorithm

Algorithm domain exceptions for PhyloZoo.

exception phylozoo.utils.exceptions.algorithm.PhyloZooAlgorithmError

Bases: PhyloZooError

Base exception for algorithm-related errors.

All algorithm-specific errors inherit from this class, allowing users to catch all algorithm errors with a single except clause.

Visualization

Visualization domain exceptions for PhyloZoo.

exception phylozoo.utils.exceptions.visualization.PhyloZooBackendError

Bases: PhyloZooVisualizationError

Raised when backend operations fail.

This exception is used for backend-related errors such as:

• Backend not registered

• Backend initialization failures

• Backend operation failures

exception phylozoo.utils.exceptions.visualization.PhyloZooLayoutError

Bases: PhyloZooVisualizationError

Raised when layout computation fails.

This exception is used for layout computation errors such as:

• Empty network/graph layout errors

• Invalid layout algorithm

• Layout computation failures

exception phylozoo.utils.exceptions.visualization.PhyloZooStateError

Bases: PhyloZooVisualizationError

Raised when an operation is attempted in an invalid state.

This exception is used when an operation requires a certain state (e.g., plot must be created, figure must be initialized) but that state is not met. This is specific to visualization operations.

exception phylozoo.utils.exceptions.visualization.PhyloZooVisualizationError

Bases: PhyloZooError

Base exception for visualization-related errors.

All visualization-specific errors inherit from this class, allowing users to catch all visualization errors with a single except clause.

Generator

Network generator domain exceptions for PhyloZoo.

exception phylozoo.utils.exceptions.generator.PhyloZooGeneratorDegreeError

Bases: PhyloZooGeneratorError

Raised when network generator node degree constraints are violated.

exception phylozoo.utils.exceptions.generator.PhyloZooGeneratorError

Bases: PhyloZooValueError

Base exception for network generator-related errors.

exception phylozoo.utils.exceptions.generator.PhyloZooGeneratorStructureError

Bases: PhyloZooGeneratorError

Raised when network generator structure is invalid.

Warnings

Warning classes for PhyloZoo.

exception phylozoo.utils.exceptions.warning.PhyloZooEmptyNetworkWarning

Bases: PhyloZooWarning

Warning for empty network operations.

This warning is used when an operation is attempted on an empty network.

exception phylozoo.utils.exceptions.warning.PhyloZooIdentifierWarning

Bases: PhyloZooWarning

Warning for identifier-related issues.

This warning is used when Python keywords are used as identifiers or when None is used as a value, which may cause unexpected behavior.

exception phylozoo.utils.exceptions.warning.PhyloZooSingleNodeNetworkWarning

Bases: PhyloZooWarning

Warning for single-node network operations.

This warning is used when an operation is attempted on a single-node network.

exception phylozoo.utils.exceptions.warning.PhyloZooWarning

Bases: UserWarning

Base warning class for all PhyloZoo warnings.

All custom warnings in PhyloZoo inherit from this class, allowing users to filter or catch all PhyloZoo-specific warnings. Inherits from UserWarning for compatibility with Python’s warning system.

Examples

>>> import warnings
>>> from phylozoo.utils.exceptions import PhyloZooWarning
>>>
>>> warnings.filterwarnings('ignore', category=PhyloZooWarning)
>>> warnings.warn("This is a PhyloZoo warning", PhyloZooWarning)

Warning utilities

Warning utility functions for PhyloZoo.

phylozoo.utils.exceptions.utils.warn_on_keyword(value: Any, context: str) → None

Warn if value is a Python keyword (e.g., None, True, False).

Parameters:

• value (Any) – Value to check if it’s a Python keyword.

• context (str) – Context description (e.g., “Identifier”, “Key”, “Name”).

Examples

>>> warn_on_keyword("for", "Identifier")
UserWarning: Identifier 'for' is a Python keyword...

phylozoo.utils.exceptions.utils.warn_on_none_value(value: Any, context: str) → None

Warn if value is None (Python keyword).

Parameters:

• value (Any) – Value to check.

• context (str) – Context description (e.g., “Attribute ‘weight’”, “Parameter ‘x’”).

Examples

>>> warn_on_none_value(None, "Attribute 'weight'")
UserWarning: Attribute 'weight' has value None (Python keyword)...