Summarizers

coola.summarizers

Contain the summarizer implementations.

coola.summarizers.BaseSummarizer

Bases: ABC

Define the base class to implement a summarizer.

>>> from coola import Summarizer
>>> summarizer = Summarizer()
>>> summarizer
Summarizer(
  (<class 'collections.abc.Mapping'>): MappingFormatter(max_items=5, num_spaces=2)
  (<class 'collections.abc.Sequence'>): SequenceFormatter(max_items=5, num_spaces=2)
  (<class 'dict'>): MappingFormatter(max_items=5, num_spaces=2)
  (<class 'list'>): SequenceFormatter(max_items=5, num_spaces=2)
  (<class 'object'>): DefaultFormatter(max_characters=-1)
  (<class 'set'>): SetFormatter(max_items=5, num_spaces=2)
  (<class 'tuple'>): SequenceFormatter(max_items=5, num_spaces=2)
  (<class 'numpy.ndarray'>): NDArrayFormatter(show_data=False)
  (<class 'torch.Tensor'>): TensorFormatter(show_data=False)
)
>>> print(summarizer.summary(1))
<class 'int'> 1
>>> print(summarizer.summary(["abc", "def"]))
<class 'list'> (length=2)
  (0): abc
  (1): def
>>> print(summarizer.summary([[0, 1, 2], {"key1": "abc", "key2": "def"}]))
<class 'list'> (length=2)
  (0): [0, 1, 2]
  (1): {'key1': 'abc', 'key2': 'def'}
>>> print(summarizer.summary([[0, 1, 2], {"key1": "abc", "key2": "def"}], max_depth=2))
<class 'list'> (length=2)
  (0): <class 'list'> (length=3)
      (0): 0
      (1): 1
      (2): 2
  (1): <class 'dict'> (length=2)
      (key1): abc
      (key2): def

coola.summarizers.BaseSummarizer.summary abstractmethod

summary(
    value: Any, depth: int = 0, max_depth: int = 1
) -> str

Summarize the input value in a string.

Parameters:

Name	Type	Description	Default
value	Any	The value to summarize.	required
depth	int	The current depth.	0
max_depth	int	The maximum depth to summarize if the input is nested.	1

Returns:

Type	Description
str	The summary as a string.

Example usage:

>>> from coola import Summarizer
>>> summarizer = Summarizer()
>>> print(summarizer.summary(1))
<class 'int'> 1
>>> print(summarizer.summary(["abc", "def"]))
<class 'list'> (length=2)
  (0): abc
  (1): def
>>> print(summarizer.summary([[0, 1, 2], {"key1": "abc", "key2": "def"}]))
<class 'list'> (length=2)
  (0): [0, 1, 2]
  (1): {'key1': 'abc', 'key2': 'def'}
>>> print(summarizer.summary([[0, 1, 2], {"key1": "abc", "key2": "def"}], max_depth=2))
<class 'list'> (length=2)
  (0): <class 'list'> (length=3)
      (0): 0
      (1): 1
      (2): 2
  (1): <class 'dict'> (length=2)
      (key1): abc
      (key2): def

coola.summarizers.Summarizer

Bases: BaseSummarizer

Implement the default summarizer.

The registry is a class variable, so it is shared with all the instances of this class.

Example usage:

>>> from coola import Summarizer
>>> summarizer = Summarizer()
>>> summarizer
Summarizer(
  (<class 'collections.abc.Mapping'>): MappingFormatter(max_items=5, num_spaces=2)
  (<class 'collections.abc.Sequence'>): SequenceFormatter(max_items=5, num_spaces=2)
  (<class 'dict'>): MappingFormatter(max_items=5, num_spaces=2)
  (<class 'list'>): SequenceFormatter(max_items=5, num_spaces=2)
  (<class 'object'>): DefaultFormatter(max_characters=-1)
  (<class 'set'>): SetFormatter(max_items=5, num_spaces=2)
  (<class 'tuple'>): SequenceFormatter(max_items=5, num_spaces=2)
  (<class 'numpy.ndarray'>): NDArrayFormatter(show_data=False)
  (<class 'torch.Tensor'>): TensorFormatter(show_data=False)
)
>>> print(summarizer.summary(1))
<class 'int'> 1
>>> print(summarizer.summary(["abc", "def"]))
<class 'list'> (length=2)
  (0): abc
  (1): def
>>> print(summarizer.summary([[0, 1, 2], {"key1": "abc", "key2": "def"}]))
<class 'list'> (length=2)
  (0): [0, 1, 2]
  (1): {'key1': 'abc', 'key2': 'def'}
>>> print(summarizer.summary([[0, 1, 2], {"key1": "abc", "key2": "def"}], max_depth=2))
<class 'list'> (length=2)
  (0): <class 'list'> (length=3)
      (0): 0
      (1): 1
      (2): 2
  (1): <class 'dict'> (length=2)
      (key1): abc
      (key2): def

coola.summarizers.Summarizer.add_formatter classmethod

add_formatter(
    data_type: type[object],
    formatter: BaseFormatter,
    exist_ok: bool = False,
) -> None

Add a formatter for a given data type.

Parameters:

Name	Type	Description	Default
data_type	type[object]	The data type for this test.	required
formatter	BaseFormatter	The formatter to use for the specified type.	required
exist_ok	bool	If False, RuntimeError is raised if the data type already exists. This parameter should be set to True to overwrite the formatter for a type.	False

Raises:

Type	Description
RuntimeError	if a formatter is already registered for the data type and exist_ok=False.

Example usage:

>>> from coola import Summarizer
>>> from coola.formatters import MappingFormatter
>>> Summarizer.add_formatter(dict, MappingFormatter(), exist_ok=True)

coola.summarizers.Summarizer.find_formatter classmethod

find_formatter(data_type: Any) -> BaseFormatter

Find the formatter associated to an object.

Parameters:

Name	Type	Description	Default
data_type	Any	The data type to get.	required

Returns:

Type	Description
BaseFormatter	The formatter associated to the data type.

Raises:

Type	Description
TypeError	if a formatter cannot be found for this data type.

Example usage:

>>> from coola import Summarizer
>>> Summarizer.find_formatter(list)
SequenceFormatter(max_items=5, num_spaces=2)
>>> Summarizer.find_formatter(str)
DefaultFormatter(max_characters=-1)

coola.summarizers.Summarizer.has_formatter classmethod

has_formatter(data_type: type[object]) -> bool

Indicate if a formatter is registered for the given data type.

Parameters:

Name	Type	Description	Default
data_type	type[object]	The data type to check.	required

Returns:

Type	Description
bool	True if a formatter is registered, otherwise False.

Example usage:

>>> from coola import Summarizer
>>> Summarizer.has_formatter(list)
True
>>> Summarizer.has_formatter(str)
False

coola.summarizers.Summarizer.load_state_dict classmethod

load_state_dict(state: dict) -> None

Load the state values from a dict.

Parameters:

Name	Type	Description	Default
state	dict	A dictionary with state values.	required

Example usage:

>>> from coola import Summarizer
>>> Summarizer.load_state_dict({object: {"max_characters": 10}})
>>> summarizer = Summarizer()
>>> summarizer.registry[object]
DefaultFormatter(max_characters=10)
>>> Summarizer.load_state_dict({object: {"max_characters": -1}})
>>> summarizer.registry[object]
DefaultFormatter(max_characters=-1)

coola.summarizers.Summarizer.set_max_characters classmethod

set_max_characters(max_characters: int) -> None

Set the maximum of characters for the compatible formatter to the specified value.

To be updated, the formatters need to implement the method set_max_characters.

Parameters:

Name	Type	Description	Default
max_characters	int	The maximum of characters.	required

Example usage:

>>> from coola import Summarizer
>>> Summarizer.set_max_characters(10)
>>> summarizer = Summarizer()
>>> summarizer.registry[object]
DefaultFormatter(max_characters=10)
>>> Summarizer.set_max_characters(-1)
>>> summarizer.registry[object]
DefaultFormatter(max_characters=-1)

coola.summarizers.Summarizer.set_max_items classmethod

set_max_items(max_items: int) -> None

Set the maximum number of items for the compatible formatter to the specified value.

To be updated, the formatters need to implement the method set_max_items.

Parameters:

Name	Type	Description	Default
max_items	int	The maximum number of items to show.	required

Example usage:

>>> from coola import Summarizer
>>> Summarizer.set_max_items(10)
>>> summarizer = Summarizer()
>>> summarizer.registry[dict]
MappingFormatter(max_items=10, num_spaces=2)
>>> Summarizer.set_max_items(5)
>>> summarizer.registry[dict]
MappingFormatter(max_items=5, num_spaces=2)

coola.summarizers.Summarizer.set_num_spaces classmethod

set_num_spaces(num_spaces: int) -> None

Set the maximum of items for the compatible formatter to the specified value.

To be updated, the formatters need to implement the method set_num_spaces.

Parameters:

Name	Type	Description	Default
num_spaces	int	The number of spaces for indentation.	required

Example usage:

>>> from coola import Summarizer
>>> Summarizer.set_num_spaces(4)
>>> summarizer = Summarizer()
>>> summarizer.registry[dict]
MappingFormatter(max_items=5, num_spaces=4)
>>> Summarizer.set_num_spaces(2)
>>> summarizer.registry[dict]
MappingFormatter(max_items=5, num_spaces=2)

coola.summarizers.Summarizer.state_dict classmethod

state_dict() -> dict

Return a dictionary containing state values.

Returns:

Type	Description
dict	The state values in a dict.

Example usage:

>>> from coola import Summarizer
>>> Summarizer.state_dict()
{<class 'collections.abc.Mapping'>: {'max_items': 5, 'num_spaces': 2},...}

coola.summarizers.set_summarizer_options

set_summarizer_options(
    max_characters: int | None = None,
    max_items: int | None = None,
    num_spaces: int | None = None,
) -> None

Set the Summarizer options.

Note: It is recommended to use summarizer_options rather than this function.

Parameters:

Name	Type	Description	Default
max_characters	int | None	The maximum number of characters to show. If None, the maximum number of characters is unchanged.	None
max_items	int | None	The maximum number of items to show. If None, the maximum number of items is unchanged.	None
num_spaces	int | None	The number of spaces for indentation. If None, the number of spaces for indentation is unchanged.	None

Example usage:

>>> from coola import set_summarizer_options, summary
>>> print(summary("abcdefghijklmnopqrstuvwxyz"))
<class 'str'> abcdefghijklmnopqrstuvwxyz
>>> set_summarizer_options(max_characters=10)
>>> print(summary("abcdefghijklmnopqrstuvwxyz"))
<class 'str'> abcdefghij...
>>> set_summarizer_options(max_characters=-1)
>>> print(summary("abcdefghijklmnopqrstuvwxyz"))
<class 'str'> abcdefghijklmnopqrstuvwxyz

coola.summarizers.summarizer_options

summarizer_options(**kwargs: Any) -> None

Context manager that temporarily changes the summarizer options.

Accepted arguments are same as set_summarizer_options. The context manager temporary change the configuration of Summarizer. This context manager has no effect if Summarizer is not used.

Parameters:

Name	Type	Description	Default
**kwargs	Any	Accepted arguments are same as set_summarizer_options.	{}

Example usage:

>>> from coola import summarizer_options, summary
>>> print(summary("abcdefghijklmnopqrstuvwxyz"))
<class 'str'> abcdefghijklmnopqrstuvwxyz
>>> with summarizer_options(max_characters=10):
...     print(summary("abcdefghijklmnopqrstuvwxyz"))
...
<class 'str'> abcdefghij...
>>> print(summary("abcdefghijklmnopqrstuvwxyz"))
<class 'str'> abcdefghijklmnopqrstuvwxyz