omnipy.data.multi

CLASS	DESCRIPTION
MultiModelDataset	Variant of Dataset that allows custom models to be set on individual data files

MultiModelDataset

Bases: Dataset[_GeneralModelT], Generic[_GeneralModelT]

Variant of Dataset that allows custom models to be set on individual data files

Note that the general model still needs to hold for all data files, in addition to any custom models.

CLASS	DESCRIPTION
Config

METHOD	DESCRIPTION
__init__
absorb
absorb_and_replace
as_multi_model_dataset
browse	Opens the model or dataset in a browser, if possible.
clone_dataset_cls
copy
deepcopy_context
default_repr_to_terminal_str
dict
do
failed_task_details
from_data
from_json
full	Display the content of the Model or Dataset in full height.
get_model
get_type	Returns the concrete type (Model or Dataset class) used for all
json	Preview the data content of the Model or Dataset as JSON.
list	Displays a summary list of all models in the dataset.
load
load_into
peek	Display a preview of the Model or Dataset content.
pending_task_details
save
set_model
to
to_data
to_json
to_json_schema
update_forward_refs
validate	Hack to allow overwriting of iter method without compromising pydantic validation. Part

ATTRIBUTE	DESCRIPTION
available_data	TYPE: Self
config	TYPE: IsDataConfig
data	TYPE: dict[str, _ModelOrDatasetT]
failed_data	TYPE: Self
pending_data	TYPE: Self
reactive_objects	TYPE: IsReactiveObjects | None
snapshot_holder	TYPE: IsSnapshotHolder[HasContent, ContentT]

Source code in src/omnipy/data/multi.py

class MultiModelDataset(Dataset[_GeneralModelT], Generic[_GeneralModelT]):
    """
        Variant of Dataset that allows custom models to be set on individual data files

        Note that the general model still needs to hold for all data files, in addition to any
        custom models.
    """

    # Custom field models should really be a subtype of _GeneralModelT,
    # however this is currently not checkable in the type system. Instead,
    # we rely on the _validate method to ensure that the custom field
    # models are valid.

    _custom_field_models: 'dict[str, type[Model]]' = pyd.PrivateAttr(default={})

    def set_model(self, data_file: str, model: 'type[Model]') -> None:
        try:
            self._custom_field_models[data_file] = model
            if data_file in self.data:
                self._validate_data_file(data_file)
            else:
                self.data[data_file] = model()
        except ValidationError:
            del self._custom_field_models[data_file]
            raise

    def get_model(self, data_file: str) -> type[Model]:
        if data_file in self._custom_field_models:
            return self._custom_field_models[data_file]
        else:
            return self.get_type()

    def from_data(self,
                  data: Mapping[str, Any] | Iterable[tuple[str, Any]],
                  update: bool = True) -> None:
        super().from_data(data, update)
        for data_file in self:
            self._validate_data_file_according_to_custom_field_model(data_file)
        self._force_full_validation()

    def _validate_data_file(self, data_file: str) -> None:
        self._validate_data_file_according_to_custom_field_model(data_file)
        self._force_full_validation()

    def _validate_data_file_according_to_custom_field_model(self, data_file: str):
        from omnipy.data.model import is_model_instance, Model

        if data_file in self._custom_field_models:
            model = self._custom_field_models[data_file]
            if not is_model_instance(model):
                model = Model[model]
            data_obj = self._to_data_if_model(self.data[data_file])
            parsed_data = self._to_data_if_model(model(data_obj))
            self.data[data_file] = parsed_data

    @staticmethod
    def _to_data_if_model(data_obj: Any):
        from omnipy.data.model import is_model_instance

        if is_model_instance(data_obj):
            data_obj = data_obj.to_data()
        return data_obj

available_data property

available_data: Self

config property

config: IsDataConfig

data class-attribute instance-attribute

data: dict[str, _ModelOrDatasetT] = pyd.Field(default={})

failed_data property

failed_data: Self

pending_data property

pending_data: Self

reactive_objects property

reactive_objects: IsReactiveObjects | None

snapshot_holder property

snapshot_holder: IsSnapshotHolder[HasContent, ContentT]

Config

ATTRIBUTE	DESCRIPTION
arbitrary_types_allowed
validate_assignment

Source code in src/omnipy/data/dataset.py

class Config:
    validate_assignment = True
    arbitrary_types_allowed = True

arbitrary_types_allowed class-attribute instance-attribute

arbitrary_types_allowed = True

validate_assignment class-attribute instance-attribute

validate_assignment = True

__init__

__init__(
    value: Mapping[str, object] | Iterable[tuple[str, object]] | UndefinedType = Undefined,
    *,
    data: Mapping[str, object] | UndefinedType = Undefined,
    **kwargs: object,
) -> None

Source code in src/omnipy/data/dataset.py

def __init__(  # noqa: C901
    self,
    value: Mapping[str, object] | Iterable[tuple[str, object]] | UndefinedType = Undefined,
    *,
    data: Mapping[str, object] | UndefinedType = Undefined,
    **kwargs: object,
) -> None:
    from omnipy.data.model import is_model_instance, is_pure_pydantic_model

    # TODO: Error message when forgetting parenthesis when creating Dataset should be improved.
    #       Unclear where this can be done, if anywhere? E.g.:
    #           a = Dataset[Model[int]]
    #           a['adsfas'] = 2
    #           Traceback (most recent call last):
    #             ...
    #           TypeError: 'ModelMetaclass' object does not support item assignment
    #
    # TODO: Disallow e.g.:
    #       Dataset[Model[str]](Model[int](5)) ==  Dataset[Model[str]](data=Model[int](5))
    #       == Dataset[Model[str]](data={'__root__': Model[str]('5')})

    super_kwargs = {}

    assert DATA_KEY not in kwargs, \
        ('Not allowed with "data" as kwargs key. Not sure how you managed this? Are you trying '
         'to break Dataset init on purpose?')

    if value != Undefined:
        assert data == Undefined, \
            'Not allowed to combine positional and "data" keyword argument'
        assert len(kwargs) == 0, \
            'Not allowed to combine positional and keyword arguments'
        super_kwargs[DATA_KEY] = value

    if data != Undefined:
        assert len(kwargs) == 0, \
            f"Not allowed to combine '{DATA_KEY}' with other keyword arguments"
        super_kwargs[DATA_KEY] = data

    if kwargs:
        if DATA_KEY not in super_kwargs:
            super_kwargs[DATA_KEY] = kwargs
            kwargs = {}

    _type = self.get_type()
    if _type == _ModelOrDatasetT:  # type: ignore[misc]
        self._raise_type_exception()

    def _validate_any_models_or_datasets(
            iterable_data: Iterable[tuple[str, object]]) -> tuple[dict, bool]:

        prepared_data = {}
        _model_or_dataset_as_input: bool = False

        for key, val in iterable_data:
            if is_model_instance(val):
                _model_or_dataset_as_input = True
                prepared_data[key] = self._validate_value_for_data_file(key, val)
            else:
                prepared_data[key] = val
        return prepared_data, _model_or_dataset_as_input

    model_or_dataset_as_input = False
    if DATA_KEY in super_kwargs:
        input_data = super_kwargs[DATA_KEY]
        for_type_check = input_data.content if is_model_instance(input_data) else input_data
        match for_type_check:
            case Dataset():
                model_or_dataset_as_input = True
                super_kwargs[DATA_KEY] = cast(Dataset, input_data).to_data()
            case _input_data if is_pure_pydantic_model(_input_data):
                super_kwargs[DATA_KEY], model_or_dataset_as_input = (
                    _validate_any_models_or_datasets(_input_data.dict().items()))
            case Mapping():
                super_kwargs[DATA_KEY], model_or_dataset_as_input = (
                    _validate_any_models_or_datasets(cast(Mapping, input_data).items()))
            case Iterable():
                try:
                    super_kwargs[DATA_KEY], model_or_dataset_as_input = (
                        _validate_any_models_or_datasets(self._check_iterable(input_data)))
                except (TypeError, ValueError) as e:
                    raise TypeError(
                        'Data object must be a mapping or an iterable of '
                        '(key, val) pairs',
                        self.__class__) from e

            case _:
                ...

    self._init(super_kwargs, **kwargs)

    try:
        self._primary_validation(super_kwargs)
    except ValidationError:
        if model_or_dataset_as_input:
            self._secondary_validation_from_data(super_kwargs)
        else:
            raise

    if not self.__doc__:
        self._set_standard_field_description()

absorb

absorb(other: Dataset)

Source code in src/omnipy/data/dataset.py

def absorb(self, other: 'Dataset'):
    self.from_data(other.to_data(), update=True)

absorb_and_replace

absorb_and_replace(other: Dataset)

Source code in src/omnipy/data/dataset.py

def absorb_and_replace(self, other: 'Dataset'):
    self.from_data(other.to_data(), update=False)

as_multi_model_dataset

as_multi_model_dataset() -> IsMultiModelDataset[_ModelOrDatasetT]

Source code in src/omnipy/data/dataset.py

def as_multi_model_dataset(self) -> 'IsMultiModelDataset[_ModelOrDatasetT]':
    from omnipy.data.multi import MultiModelDataset

    multi_model_dataset = MultiModelDataset[self.get_type()]()
    for data_file in self:
        multi_model_dataset.data[data_file] = self.data[data_file]
    return multi_model_dataset

browse

browse(
    *,
    width: pyd.NonNegativeInt | None = None,
    height: pyd.NonNegativeInt | None = None,
    tab: pyd.NonNegativeInt = 4,
    indent: pyd.NonNegativeInt = 2,
    printer: PrettyPrinterLib.Literals = "auto",
    syntax: SyntaxLanguageSpec.Literals | str = "auto",
    freedom: pyd.NonNegativeFloat | None = 2.5,
    debug: bool = False,
    ui: UserInterfaceType.Literals = "auto",
    system: DisplayColorSystem.Literals = "auto",
    style: AllColorStyles.Literals | str = "auto",
    dark: Literal = "auto",
    bg: bool = False,
    fonts: tuple = ("Menlo", "DejaVu Sans Mono", "Consolas", "Courier New", "monospace"),
    font_size: pyd.NonNegativeInt | None = 14,
    font_weight: pyd.NonNegativeInt | None = 400,
    line_height: pyd.NonNegativeFloat | None = 1.25,
    h_overflow: HorizontalOverflowMode.Literals = "ellipsis",
    v_overflow: VerticalOverflowMode.Literals = "ellipsis_bottom",
    panel: PanelDesign.Literals = "table",
    title_at_top: bool = True,
    max_title_height: MaxTitleHeight.Literals = -1,
    min_panel_width: pyd.NonNegativeInt = 3,
    min_crop_width: pyd.NonNegativeInt = 33,
    use_min_crop_width: bool = False,
    max_panels_hor: pyd.NonNegativeInt | None = 9,
    max_nesting_depth: pyd.NonNegativeInt | None = 3,
    justify: Justify.Literals = "left",
) -> None

Opens the model or dataset in a browser, if possible.

For models, this is a detailed view of the model's content, and for datasets this is a detailed view of each model contained in the dataset, one model per browser tab.

PARAMETER	DESCRIPTION
width	Width in characters of the output area (None for auto-detect based on available display dimensions). TYPE: NonNegativeInt | None DEFAULT: None
height	Height in lines of the output area (None for auto-detect based on available display dimensions). TYPE: NonNegativeInt | None DEFAULT: None
tab	Number of spaces to use for each tab. TYPE: NonNegativeInt DEFAULT: 4
indent	Number of spaces to use for each indentation level. TYPE: NonNegativeInt DEFAULT: 2
printer	Library to use for pretty printing. TYPE: PrettyPrinterLib.Literals DEFAULT: 'auto'
syntax	Syntax language for code highlighting. Supported lexers are defined in SyntaxLanguageSpec. For non-supported styles, the user can specify a string with the Pygments lexer name. For this to work, the lexer must be registered in the Pygments library. TYPE: SyntaxLanguageSpec.Literals | str DEFAULT: 'auto'
freedom	Parameter that controls the level of freedom for formatted text to follow the geometry of the frame size (=total available area) in a proportional manner. If the proportional freedom is 0 (the lowest), then the output area must not in any case be proportionally wider that the frame (i.e. a 16/9 frame will only produce output that is 16/9 or narrower). Larger values of proportional freedom allow the output to be proportionally wider than the total available frame, to a degree that relates to the size difference between the frame and the content (larger difference gives more freedom). The default value of 2.5 is a good compromise between readability/aesthetics and good use of the screen estate. If None, the freedom is unlimited (i.e. proportionality is not taken into account at all). TYPE: float | None DEFAULT: 2.5
debug	When True, enables additional debugging information in the output, such as the hierarchy of the Model objects. Currently, only Python pretty printers support debug=True. Hence, enabling debug mode will automatically set the printer to the default Python pretty printer if the printer config value is not already set. TYPE: bool DEFAULT: False
ui	Type of user interface for which the output should being prepared. The user interface describes the technical solutions available for interacting with the user, encompassing the support available for displaying output as well as how the user interacts with the library (including the type of interactive interpreter used, if any). TYPE: UserInterfaceType.Literals DEFAULT: 'auto'
system	Color system to use for terminal output. The default is AUTO, which automatically detects the color system based on particular environment variables. If color capabilities are not detected, the output will be in black and white. If the color system of a modern consoles/terminal is not auto-detected (which is the case for e.g. the PyCharm console), the user might want to set the color system manually to ANSI_RGB to force color output. TYPE: ColorSystem.Literals DEFAULT: 'auto'
style	Color style/theme for syntax highlighting and other display elements. Supported styles are defined in AllColorStyles. For non-supported styles, the user can specify a string with the Pygments style name. For this to work, the style must be registered in the Pygments library. If style is AUTO or any of the other RecommendedColorStyles, the style is automatically selected from the RecommendedColorStyles based on the detected user interface, the color system, and whether the background is dark or not. TYPE: AllColorStyles.Literals | str DEFAULT: 'auto'
dark	Whether the background color of the output is dark. This is used to determine the appropriate color scheme for syntax highlighting. The default is AUTO, which automatically tries to detect whether the background is dark. Capability of auto-detection depends on the user interface. TYPE: DarkBackground.Literals DEFAULT: 'auto'
bg	If False, uses transparent background for the output. In the case of terminal output, the background color will be the current background color of the terminal. For HTML output, the background color will be automatically set to pure black or pure white, depending on the luminosity of the foreground color. TYPE: bool DEFAULT: False
fonts	Font families to use in HTML output, in order of preference (empty tuple for browser default). TYPE: Tuple[str, ...] DEFAULT: ('Menlo', 'DejaVu Sans Mono', 'Consolas', 'Courier New', 'monospace')
font_size	Font size in pixels for HTML output (None for browser default). TYPE: NonNegativeInt | None DEFAULT: 14
font_weight	Font weight for HTML output (None for browser default). TYPE: NonNegativeInt | None DEFAULT: 400
line_height	Line height multiplier for HTML output (None for browser default). TYPE: NonNegativeFloat | None DEFAULT: 1.25
h_overflow	How to handle text that exceeds the width. TYPE: HorizontalOverflowMode.Literals DEFAULT: 'ellipsis'
v_overflow	How to handle text that exceeds the height. TYPE: VerticalOverflowMode.Literals DEFAULT: 'ellipsis_bottom'
panel	Visual design of the panel used as container for the output. Only TABLE is currently supported, which displays the output in a table-like grid. TYPE: PanelDesign.Literals DEFAULT: 'table'
title_at_top	Whether panel titles will be displayed over the panel content (True) or below the content (False) TYPE: bool DEFAULT: True
max_title_height	Maximum height of the panel title. If AUTO, the height is determined by the content of the title, up to a maximum of two lines. If ZERO, the title is not displayed at all. If ONE or TWO, the title is displayed with a fixed height of max one or two lines, respectively. TYPE: MaxTitleHeight.Literals DEFAULT: -1
min_panel_width	Minimum width in characters per panel. TYPE: NonNegativeInt DEFAULT: 3
min_crop_width	Minimum cropping width in characters for panels in cases where more than one panel are to be displayed. This is for instance used to calculate the number of models to display in a Dataset peek(). Only applied if use_min_crop_width is set to True. min_crop_width must be equal to or larger than min_panel_width. TYPE: NonNegativeInt DEFAULT: 33
use_min_crop_width	Whether the min_crop_width value should be considered in cases where more than one panel are to be displayed, potentially reducing the number of displayed panels. TYPE: bool DEFAULT: False
max_panels_hor	Maximum number of panels to display horizontally side-by-side at the top level. This value also acts as a ceiling for nested panels; nested panels cannot exceed this limit even if the constant MAX_PANELS_HORIZONTALLY_DEEPLY_NESTED is set to a higher value. If None, there is no limit. TYPE: NonNegativeInt | None DEFAULT: 9
max_nesting_depth	Maximum levels of nested panels to display. If None, there is no limit. TYPE: NonNegativeInt | None DEFAULT: 3
justify	Justification mode for the panel if inside a layout panel. This is only used for the panel content. TYPE: Justify.Literals DEFAULT: 'left'

Source code in src/omnipy/data/_mixins/display.py

def browse(self, **kwargs) -> None:
    # %% Original docstring (managed by expand_docstr_macros.py) %%
    # {{BROWSE_SUMMARY}}
    #
    # {{BROWSE_DESCRIPTION}}
    #
    # {{DISPLAY_METHOD_ARGS}}
    #
    """Opens the model or dataset in a browser, if possible.

    For models, this is a detailed view of the model's content,
    and for datasets this is a detailed view of each model
    contained in the dataset, one model per browser tab.

    Args:
        width (NonNegativeInt | None):
            Width in characters of the output area (None for
            auto-detect based on available display dimensions).
        height (NonNegativeInt | None):
            Height in lines of the output area (None for
            auto-detect based on available display dimensions).
        tab (NonNegativeInt):
            Number of spaces to use for each tab.
        indent (NonNegativeInt):
            Number of spaces to use for each indentation level.
        printer (PrettyPrinterLib.Literals):
            Library to use for pretty printing.
        syntax (SyntaxLanguageSpec.Literals | str):
            Syntax language for code highlighting. Supported
            lexers are defined in SyntaxLanguageSpec. For
            non-supported styles, the user can specify a string
            with the Pygments lexer name. For this to work, the
            lexer must be registered in the Pygments library.
        freedom (float | None):
            Parameter that controls the level of freedom for
            formatted text to follow the geometry of the frame
            size (=total available area) in a proportional manner.
            If the proportional freedom is 0 (the lowest), then
            the output area must not in any case be proportionally
            wider that the frame (i.e. a 16/9 frame will only
            produce output that is 16/9 or narrower). Larger
            values of proportional freedom allow the output to be
            proportionally wider than the total available frame,
            to a degree that relates to the size difference
            between the frame and the content (larger difference
            gives more freedom). The default value of 2.5 is a
            good compromise between readability/aesthetics and
            good use of the screen estate. If None, the freedom is
            unlimited (i.e. proportionality is not taken into
            account at all).
        debug (bool):
            When True, enables additional debugging information in
            the output, such as the hierarchy of the Model
            objects. Currently, only Python pretty printers support
            debug=True. Hence, enabling debug mode will
            automatically set the printer to the default Python
            pretty printer if the `printer` config value is not
            already set.
        ui (UserInterfaceType.Literals):
            Type of user interface for which the output should
            being prepared. The user interface describes the
            technical solutions available for interacting with the
            user, encompassing the support available for
            displaying output as well as how the user interacts
            with the library (including the type of interactive
            interpreter used, if any).
        system (ColorSystem.Literals):
            Color system to use for terminal output. The default
            is `AUTO`, which automatically detects the color
            system based on particular environment variables. If
            color capabilities are not detected, the output will
            be in black and white. If the color system of a modern
            consoles/terminal is not auto-detected (which is the
            case for e.g. the PyCharm console), the user might
            want to set the color system manually to ANSI_RGB to
            force color output.
        style (AllColorStyles.Literals | str):
            Color style/theme for syntax highlighting and other
            display elements. Supported styles are defined in
            AllColorStyles. For non-supported styles, the user can
            specify a string with the Pygments style name. For this to
            work, the style must be registered in the Pygments
            library. If style is `AUTO` or any of the other
            RecommendedColorStyles, the style is automatically
            selected from the RecommendedColorStyles based on the
            detected user interface, the color system, and whether the
            background is dark or not.
        dark (DarkBackground.Literals):
            Whether the background color of the output is dark.
            This is used to determine the appropriate color scheme
            for syntax highlighting. The default is AUTO, which
            automatically tries to detect whether the background
            is dark. Capability of auto-detection depends on the
            user interface.
        bg (bool):
            If False, uses transparent background for the output.
            In the case of terminal output, the background color
            will be the current background color of the terminal.
            For HTML output, the background color will be
            automatically set to pure black or pure white,
            depending on the luminosity of the foreground color.
        fonts (Tuple[str, ...]):
            Font families to use in HTML output, in order of
            preference (empty tuple for browser default).
        font_size (NonNegativeInt | None):
            Font size in pixels for HTML output (None for browser
            default).
        font_weight (NonNegativeInt | None):
            Font weight for HTML output (None for browser
            default).
        line_height (NonNegativeFloat | None):
            Line height multiplier for HTML output (None for
            browser default).
        h_overflow (HorizontalOverflowMode.Literals):
            How to handle text that exceeds the width.
        v_overflow (VerticalOverflowMode.Literals):
            How to handle text that exceeds the height.
        panel (PanelDesign.Literals):
            Visual design of the panel used as container for the
            output. Only `TABLE` is currently supported, which
            displays the output in a table-like grid.
        title_at_top (bool):
            Whether panel titles will be displayed over the panel
            content (True) or below the content (False)
        max_title_height (MaxTitleHeight.Literals):
            Maximum height of the panel title. If `AUTO`, the
            height is determined by the content of the title, up
            to a maximum of two lines. If `ZERO`, the title is not
            displayed at all. If `ONE` or `TWO`, the title is
            displayed with a fixed height of max one or two lines,
            respectively.
        min_panel_width (NonNegativeInt):
            Minimum width in characters per panel.
        min_crop_width (NonNegativeInt):
            Minimum cropping width in characters for panels in
            cases where more than one panel are to be displayed.
            This is for instance used to calculate the number of
            models to display in a Dataset peek(). Only applied if
            `use_min_crop_width` is set to `True`.
            `min_crop_width` must be equal to or larger than
            `min_panel_width`.
        use_min_crop_width (bool):
            Whether the `min_crop_width` value should be
            considered in cases where more than one panel are to
            be displayed, potentially reducing the number of
            displayed panels.
        max_panels_hor (NonNegativeInt | None):
            Maximum number of panels to display horizontally
            side-by-side at the top level. This value also acts as
            a ceiling for nested panels; nested panels cannot
            exceed this limit even if the constant
            `MAX_PANELS_HORIZONTALLY_DEEPLY_NESTED` is set to a
            higher value. If None, there is no limit.
        max_nesting_depth (NonNegativeInt | None):
            Maximum levels of nested panels to display. If None,
            there is no limit.
        justify (Justify.Literals):
            Justification mode for the panel if inside a layout
            panel. This is only used for the panel content.
    """
    self._browse(**kwargs)

clone_dataset_cls classmethod

clone_dataset_cls(
    new_dataset_cls_name: str, model_cls: type[_NewModelT] | None = None
) -> type[Self]

Source code in src/omnipy/data/dataset.py

@classmethod
def clone_dataset_cls(cls,
                      new_dataset_cls_name: str,
                      model_cls: type[_NewModelT] | None = None) -> type[Self]:
    if model_cls:
        generic_dataset_cls = cls.__bases__[0]
        new_base_cls = generic_dataset_cls[model_cls]  # type: ignore[index]
    else:
        new_base_cls = cls

    new_dataset_cls = type(new_dataset_cls_name, (new_base_cls,), {})
    return new_dataset_cls

copy

copy(*, deep: bool = False, **kwargs) -> Self

Source code in src/omnipy/data/dataset.py

def copy(self, *, deep: bool = False, **kwargs) -> Self:
    pydantic_copy = pyd.GenericModel.copy(self, deep=deep, **kwargs)
    if not deep:
        object.__setattr__(pydantic_copy, DATA_KEY, pydantic_copy.__dict__[DATA_KEY].copy())

    return pydantic_copy  # pyright: ignore [reportReturnType]

deepcopy_context

deepcopy_context(
    top_level_entry_func: Callable[[], None], top_level_exit_func: Callable[[], None]
) -> ContextManager[int]

Source code in src/omnipy/data/_data_class_creator.py

def deepcopy_context(
    self,
    top_level_entry_func: Callable[[], None],
    top_level_exit_func: Callable[[], None],
) -> ContextManager[int]:
    return self.__class__.data_class_creator.deepcopy_context(top_level_entry_func,
                                                              top_level_exit_func)

default_repr_to_terminal_str

default_repr_to_terminal_str(ui_type: TerminalOutputUserInterfaceType.Literals) -> str

Source code in src/omnipy/data/_mixins/display.py

def default_repr_to_terminal_str(
    self,
    ui_type: TerminalOutputUserInterfaceType.Literals,
) -> str:
    return self._display_according_to_ui_type(
        ui_type=ui_type,
        return_output_if_str=True,
        output_method=self._default_panel,
    )

dict

dict(**kwargs) -> dict_t[str, Any]

Source code in src/omnipy/data/dataset.py

def dict(self, **kwargs) -> dict_t[str, Any]:
    return super().dict(**kwargs)[DATA_KEY]

do

do(placeholder: F) -> Dataset[_ModelOrDatasetT]

Source code in src/omnipy/data/dataset.py

def do(self, placeholder: F) -> 'Dataset[_ModelOrDatasetT]':
    new_dataset = self.__class__()
    for data_file, val in self.items():
        new_dataset[data_file] = placeholder(val)
    return new_dataset

failed_task_details

failed_task_details() -> dict[str, IsFailedData]

Source code in src/omnipy/data/_mixins/task.py

def failed_task_details(self) -> dict[str, IsFailedData]:
    self_with_data = cast(HasData, self)
    return {  # pyright: ignore [reportReturnType]
        key: val for key, val in self_with_data.data.items() if isinstance(val, FailedData)
    }

from_data

from_data(data: Mapping[str, Any] | Iterable[tuple[str, Any]], update: bool = True) -> None

Source code in src/omnipy/data/multi.py

def from_data(self,
              data: Mapping[str, Any] | Iterable[tuple[str, Any]],
              update: bool = True) -> None:
    super().from_data(data, update)
    for data_file in self:
        self._validate_data_file_according_to_custom_field_model(data_file)
    self._force_full_validation()

from_json

from_json(data: Mapping[str, str] | Iterable[tuple[str, str]], update: bool = True) -> None

Source code in src/omnipy/data/dataset.py

def from_json(self,
              data: Mapping[str, str] | Iterable[tuple[str, str]],
              update: bool = True) -> None:
    def callback_func(type_variant: 'Model | Dataset', content: Any):
        type_variant.from_json(content)

    self._from_dict_with_callback(data, update, callback_func)

full

full(
    *,
    width: pyd.NonNegativeInt | None = None,
    height: pyd.NonNegativeInt | None = None,
    tab: pyd.NonNegativeInt = 4,
    indent: pyd.NonNegativeInt = 2,
    printer: PrettyPrinterLib.Literals = "auto",
    syntax: SyntaxLanguageSpec.Literals | str = "auto",
    freedom: pyd.NonNegativeFloat | None = 2.5,
    debug: bool = False,
    ui: UserInterfaceType.Literals = "auto",
    system: DisplayColorSystem.Literals = "auto",
    style: AllColorStyles.Literals | str = "auto",
    dark: Literal = "auto",
    bg: bool = False,
    fonts: tuple = ("Menlo", "DejaVu Sans Mono", "Consolas", "Courier New", "monospace"),
    font_size: pyd.NonNegativeInt | None = 14,
    font_weight: pyd.NonNegativeInt | None = 400,
    line_height: pyd.NonNegativeFloat | None = 1.25,
    h_overflow: HorizontalOverflowMode.Literals = "ellipsis",
    v_overflow: VerticalOverflowMode.Literals = "ellipsis_bottom",
    panel: PanelDesign.Literals = "table",
    title_at_top: bool = True,
    max_title_height: MaxTitleHeight.Literals = -1,
    min_panel_width: pyd.NonNegativeInt = 3,
    min_crop_width: pyd.NonNegativeInt = 33,
    use_min_crop_width: bool = False,
    max_panels_hor: pyd.NonNegativeInt | None = 9,
    max_nesting_depth: pyd.NonNegativeInt | None = 3,
    justify: Justify.Literals = "left",
) -> Element | None

Display the content of the Model or Dataset in full height.

full() is a shorthand for peek(height=None) for both models and datasets. Both full-height views are automatically limited in width by the available display dimensions.

PARAMETER	DESCRIPTION
width	Width in characters of the output area (None for auto-detect based on available display dimensions). TYPE: NonNegativeInt | None DEFAULT: None
height	Height in lines of the output area (None for auto-detect based on available display dimensions). TYPE: NonNegativeInt | None DEFAULT: None
tab	Number of spaces to use for each tab. TYPE: NonNegativeInt DEFAULT: 4
indent	Number of spaces to use for each indentation level. TYPE: NonNegativeInt DEFAULT: 2
printer	Library to use for pretty printing. TYPE: PrettyPrinterLib.Literals DEFAULT: 'auto'
syntax	Syntax language for code highlighting. Supported lexers are defined in SyntaxLanguageSpec. For non-supported styles, the user can specify a string with the Pygments lexer name. For this to work, the lexer must be registered in the Pygments library. TYPE: SyntaxLanguageSpec.Literals | str DEFAULT: 'auto'
freedom	Parameter that controls the level of freedom for formatted text to follow the geometry of the frame size (=total available area) in a proportional manner. If the proportional freedom is 0 (the lowest), then the output area must not in any case be proportionally wider that the frame (i.e. a 16/9 frame will only produce output that is 16/9 or narrower). Larger values of proportional freedom allow the output to be proportionally wider than the total available frame, to a degree that relates to the size difference between the frame and the content (larger difference gives more freedom). The default value of 2.5 is a good compromise between readability/aesthetics and good use of the screen estate. If None, the freedom is unlimited (i.e. proportionality is not taken into account at all). TYPE: float | None DEFAULT: 2.5
debug	When True, enables additional debugging information in the output, such as the hierarchy of the Model objects. Currently, only Python pretty printers support debug=True. Hence, enabling debug mode will automatically set the printer to the default Python pretty printer if the printer config value is not already set. TYPE: bool DEFAULT: False
ui	Type of user interface for which the output should being prepared. The user interface describes the technical solutions available for interacting with the user, encompassing the support available for displaying output as well as how the user interacts with the library (including the type of interactive interpreter used, if any). TYPE: UserInterfaceType.Literals DEFAULT: 'auto'
system	Color system to use for terminal output. The default is AUTO, which automatically detects the color system based on particular environment variables. If color capabilities are not detected, the output will be in black and white. If the color system of a modern consoles/terminal is not auto-detected (which is the case for e.g. the PyCharm console), the user might want to set the color system manually to ANSI_RGB to force color output. TYPE: ColorSystem.Literals DEFAULT: 'auto'
style	Color style/theme for syntax highlighting and other display elements. Supported styles are defined in AllColorStyles. For non-supported styles, the user can specify a string with the Pygments style name. For this to work, the style must be registered in the Pygments library. If style is AUTO or any of the other RecommendedColorStyles, the style is automatically selected from the RecommendedColorStyles based on the detected user interface, the color system, and whether the background is dark or not. TYPE: AllColorStyles.Literals | str DEFAULT: 'auto'
dark	Whether the background color of the output is dark. This is used to determine the appropriate color scheme for syntax highlighting. The default is AUTO, which automatically tries to detect whether the background is dark. Capability of auto-detection depends on the user interface. TYPE: DarkBackground.Literals DEFAULT: 'auto'
bg	If False, uses transparent background for the output. In the case of terminal output, the background color will be the current background color of the terminal. For HTML output, the background color will be automatically set to pure black or pure white, depending on the luminosity of the foreground color. TYPE: bool DEFAULT: False
fonts	Font families to use in HTML output, in order of preference (empty tuple for browser default). TYPE: Tuple[str, ...] DEFAULT: ('Menlo', 'DejaVu Sans Mono', 'Consolas', 'Courier New', 'monospace')
font_size	Font size in pixels for HTML output (None for browser default). TYPE: NonNegativeInt | None DEFAULT: 14
font_weight	Font weight for HTML output (None for browser default). TYPE: NonNegativeInt | None DEFAULT: 400
line_height	Line height multiplier for HTML output (None for browser default). TYPE: NonNegativeFloat | None DEFAULT: 1.25
h_overflow	How to handle text that exceeds the width. TYPE: HorizontalOverflowMode.Literals DEFAULT: 'ellipsis'
v_overflow	How to handle text that exceeds the height. TYPE: VerticalOverflowMode.Literals DEFAULT: 'ellipsis_bottom'
panel	Visual design of the panel used as container for the output. Only TABLE is currently supported, which displays the output in a table-like grid. TYPE: PanelDesign.Literals DEFAULT: 'table'
title_at_top	Whether panel titles will be displayed over the panel content (True) or below the content (False) TYPE: bool DEFAULT: True
max_title_height	Maximum height of the panel title. If AUTO, the height is determined by the content of the title, up to a maximum of two lines. If ZERO, the title is not displayed at all. If ONE or TWO, the title is displayed with a fixed height of max one or two lines, respectively. TYPE: MaxTitleHeight.Literals DEFAULT: -1
min_panel_width	Minimum width in characters per panel. TYPE: NonNegativeInt DEFAULT: 3
min_crop_width	Minimum cropping width in characters for panels in cases where more than one panel are to be displayed. This is for instance used to calculate the number of models to display in a Dataset peek(). Only applied if use_min_crop_width is set to True. min_crop_width must be equal to or larger than min_panel_width. TYPE: NonNegativeInt DEFAULT: 33
use_min_crop_width	Whether the min_crop_width value should be considered in cases where more than one panel are to be displayed, potentially reducing the number of displayed panels. TYPE: bool DEFAULT: False
max_panels_hor	Maximum number of panels to display horizontally side-by-side at the top level. This value also acts as a ceiling for nested panels; nested panels cannot exceed this limit even if the constant MAX_PANELS_HORIZONTALLY_DEEPLY_NESTED is set to a higher value. If None, there is no limit. TYPE: NonNegativeInt | None DEFAULT: 9
max_nesting_depth	Maximum levels of nested panels to display. If None, there is no limit. TYPE: NonNegativeInt | None DEFAULT: 3
justify	Justification mode for the panel if inside a layout panel. This is only used for the panel content. TYPE: Justify.Literals DEFAULT: 'left'

RETURNS	DESCRIPTION
Element | None	If the UI type is Jupyter running in browser, the method returns a ReactivelyResizingHtml element which is a Jupyter widget to display HTML output in the browser. Otherwise, the method returns None.

Note

Any default argument value is overridden by the corresponding value in the relevant subsection of the UserInterfaceConfig.

Source code in src/omnipy/data/_mixins/display.py

def full(self, **kwargs) -> 'Element | None':
    # %% Original docstring (managed by expand_docstr_macros.py) %%
    # {{FULL_SUMMARY}}
    #
    # {{FULL_DESCRIPTION}}
    #
    # {{DISPLAY_METHOD_ARGS}}
    #
    # {{DISPLAY_METHOD_RETURNS}}
    #
    # {{DISPLAY_METHOD_NOTE}}
    #
    #
    """Display the content of the Model or Dataset in full height.

    `full()` is a shorthand for `peek(height=None)` for both
    models and datasets. Both full-height views are automatically
    limited in width by the available display dimensions.

    Args:
        width (NonNegativeInt | None):
            Width in characters of the output area (None for
            auto-detect based on available display dimensions).
        height (NonNegativeInt | None):
            Height in lines of the output area (None for
            auto-detect based on available display dimensions).
        tab (NonNegativeInt):
            Number of spaces to use for each tab.
        indent (NonNegativeInt):
            Number of spaces to use for each indentation level.
        printer (PrettyPrinterLib.Literals):
            Library to use for pretty printing.
        syntax (SyntaxLanguageSpec.Literals | str):
            Syntax language for code highlighting. Supported
            lexers are defined in SyntaxLanguageSpec. For
            non-supported styles, the user can specify a string
            with the Pygments lexer name. For this to work, the
            lexer must be registered in the Pygments library.
        freedom (float | None):
            Parameter that controls the level of freedom for
            formatted text to follow the geometry of the frame
            size (=total available area) in a proportional manner.
            If the proportional freedom is 0 (the lowest), then
            the output area must not in any case be proportionally
            wider that the frame (i.e. a 16/9 frame will only
            produce output that is 16/9 or narrower). Larger
            values of proportional freedom allow the output to be
            proportionally wider than the total available frame,
            to a degree that relates to the size difference
            between the frame and the content (larger difference
            gives more freedom). The default value of 2.5 is a
            good compromise between readability/aesthetics and
            good use of the screen estate. If None, the freedom is
            unlimited (i.e. proportionality is not taken into
            account at all).
        debug (bool):
            When True, enables additional debugging information in
            the output, such as the hierarchy of the Model
            objects. Currently, only Python pretty printers support
            debug=True. Hence, enabling debug mode will
            automatically set the printer to the default Python
            pretty printer if the `printer` config value is not
            already set.
        ui (UserInterfaceType.Literals):
            Type of user interface for which the output should
            being prepared. The user interface describes the
            technical solutions available for interacting with the
            user, encompassing the support available for
            displaying output as well as how the user interacts
            with the library (including the type of interactive
            interpreter used, if any).
        system (ColorSystem.Literals):
            Color system to use for terminal output. The default
            is `AUTO`, which automatically detects the color
            system based on particular environment variables. If
            color capabilities are not detected, the output will
            be in black and white. If the color system of a modern
            consoles/terminal is not auto-detected (which is the
            case for e.g. the PyCharm console), the user might
            want to set the color system manually to ANSI_RGB to
            force color output.
        style (AllColorStyles.Literals | str):
            Color style/theme for syntax highlighting and other
            display elements. Supported styles are defined in
            AllColorStyles. For non-supported styles, the user can
            specify a string with the Pygments style name. For this to
            work, the style must be registered in the Pygments
            library. If style is `AUTO` or any of the other
            RecommendedColorStyles, the style is automatically
            selected from the RecommendedColorStyles based on the
            detected user interface, the color system, and whether the
            background is dark or not.
        dark (DarkBackground.Literals):
            Whether the background color of the output is dark.
            This is used to determine the appropriate color scheme
            for syntax highlighting. The default is AUTO, which
            automatically tries to detect whether the background
            is dark. Capability of auto-detection depends on the
            user interface.
        bg (bool):
            If False, uses transparent background for the output.
            In the case of terminal output, the background color
            will be the current background color of the terminal.
            For HTML output, the background color will be
            automatically set to pure black or pure white,
            depending on the luminosity of the foreground color.
        fonts (Tuple[str, ...]):
            Font families to use in HTML output, in order of
            preference (empty tuple for browser default).
        font_size (NonNegativeInt | None):
            Font size in pixels for HTML output (None for browser
            default).
        font_weight (NonNegativeInt | None):
            Font weight for HTML output (None for browser
            default).
        line_height (NonNegativeFloat | None):
            Line height multiplier for HTML output (None for
            browser default).
        h_overflow (HorizontalOverflowMode.Literals):
            How to handle text that exceeds the width.
        v_overflow (VerticalOverflowMode.Literals):
            How to handle text that exceeds the height.
        panel (PanelDesign.Literals):
            Visual design of the panel used as container for the
            output. Only `TABLE` is currently supported, which
            displays the output in a table-like grid.
        title_at_top (bool):
            Whether panel titles will be displayed over the panel
            content (True) or below the content (False)
        max_title_height (MaxTitleHeight.Literals):
            Maximum height of the panel title. If `AUTO`, the
            height is determined by the content of the title, up
            to a maximum of two lines. If `ZERO`, the title is not
            displayed at all. If `ONE` or `TWO`, the title is
            displayed with a fixed height of max one or two lines,
            respectively.
        min_panel_width (NonNegativeInt):
            Minimum width in characters per panel.
        min_crop_width (NonNegativeInt):
            Minimum cropping width in characters for panels in
            cases where more than one panel are to be displayed.
            This is for instance used to calculate the number of
            models to display in a Dataset peek(). Only applied if
            `use_min_crop_width` is set to `True`.
            `min_crop_width` must be equal to or larger than
            `min_panel_width`.
        use_min_crop_width (bool):
            Whether the `min_crop_width` value should be
            considered in cases where more than one panel are to
            be displayed, potentially reducing the number of
            displayed panels.
        max_panels_hor (NonNegativeInt | None):
            Maximum number of panels to display horizontally
            side-by-side at the top level. This value also acts as
            a ceiling for nested panels; nested panels cannot
            exceed this limit even if the constant
            `MAX_PANELS_HORIZONTALLY_DEEPLY_NESTED` is set to a
            higher value. If None, there is no limit.
        max_nesting_depth (NonNegativeInt | None):
            Maximum levels of nested panels to display. If None,
            there is no limit.
        justify (Justify.Literals):
            Justification mode for the panel if inside a layout
            panel. This is only used for the panel content.

    Returns:
        If the UI type is Jupyter running in browser, the
        method returns a ReactivelyResizingHtml element which
        is a Jupyter widget to display HTML output in the
        browser. Otherwise, the method returns None.

    Note:
        Any default argument value is overridden by the
        corresponding value in the relevant subsection of the
        UserInterfaceConfig.

    """
    return self._display_according_to_ui_type(
        ui_type=self._extract_ui_type(**kwargs),
        return_output_if_str=False,
        output_method=self._full,
        **kwargs)

get_model

get_model(data_file: str) -> type[Model]

Source code in src/omnipy/data/multi.py

def get_model(self, data_file: str) -> type[Model]:
    if data_file in self._custom_field_models:
        return self._custom_field_models[data_file]
    else:
        return self.get_type()

get_type cached classmethod

get_type() -> type[_ModelOrDatasetT]

Returns the concrete type (Model or Dataset class) used for all data files in the dataset, e.g.: Model[list[int]], or Dataset[Model[dict[str, float]]] for nested datasets. :return: The concrete type (Model or Dataset class) used for all data files in the dataset.

Source code in src/omnipy/data/dataset.py

@classmethod
@functools.cache
def get_type(cls) -> type[_ModelOrDatasetT]:
    """
    Returns the concrete type (Model or Dataset class) used for all
    data files in the dataset, e.g.: `Model[list[int]]`, or
    `Dataset[Model[dict[str, float]]]` for nested datasets.
    :return: The concrete type (Model or Dataset class) used for all
             data files in the dataset.
    """
    # Part of pydantic v1 hack to stop coercing of e.g.
    # [{'a': 'b', 'c': 'd'}] to {'a': 'c'}
    return cls._clean_type(cls._get_data_field().sub_fields[1].type_)  # type: ignore[index]

json

json(
    *,
    width: pyd.NonNegativeInt | None = None,
    height: pyd.NonNegativeInt | None = None,
    tab: pyd.NonNegativeInt = 4,
    indent: pyd.NonNegativeInt = 2,
    printer: PrettyPrinterLib.Literals = "auto",
    syntax: SyntaxLanguageSpec.Literals | str = "auto",
    freedom: pyd.NonNegativeFloat | None = 2.5,
    debug: bool = False,
    ui: UserInterfaceType.Literals = "auto",
    system: DisplayColorSystem.Literals = "auto",
    style: AllColorStyles.Literals | str = "auto",
    dark: Literal = "auto",
    bg: bool = False,
    fonts: tuple = ("Menlo", "DejaVu Sans Mono", "Consolas", "Courier New", "monospace"),
    font_size: pyd.NonNegativeInt | None = 14,
    font_weight: pyd.NonNegativeInt | None = 400,
    line_height: pyd.NonNegativeFloat | None = 1.25,
    h_overflow: HorizontalOverflowMode.Literals = "ellipsis",
    v_overflow: VerticalOverflowMode.Literals = "ellipsis_bottom",
    panel: PanelDesign.Literals = "table",
    title_at_top: bool = True,
    max_title_height: MaxTitleHeight.Literals = -1,
    min_panel_width: pyd.NonNegativeInt = 3,
    min_crop_width: pyd.NonNegativeInt = 33,
    use_min_crop_width: bool = False,
    max_panels_hor: pyd.NonNegativeInt | None = 9,
    max_nesting_depth: pyd.NonNegativeInt | None = 3,
    justify: Justify.Literals = "left",
) -> Element | None

Preview the data content of the Model or Dataset as JSON.

In contrast to e.g. peek(), json() displays the "data content" of the Model or Dataset, i.e. the content as plain Python objects, potentially converted from the internal data structure. This plain data is formatted in JSON (for compactness). Hence json() represents a the basic compatibility layer of all Omnipy Model or Dataset objects. The view is automatically limited by the available display dimensions.

PARAMETER	DESCRIPTION
width	Width in characters of the output area (None for auto-detect based on available display dimensions). TYPE: NonNegativeInt | None DEFAULT: None
height	Height in lines of the output area (None for auto-detect based on available display dimensions). TYPE: NonNegativeInt | None DEFAULT: None
tab	Number of spaces to use for each tab. TYPE: NonNegativeInt DEFAULT: 4
indent	Number of spaces to use for each indentation level. TYPE: NonNegativeInt DEFAULT: 2
printer	Library to use for pretty printing. TYPE: PrettyPrinterLib.Literals DEFAULT: 'auto'
syntax	Syntax language for code highlighting. Supported lexers are defined in SyntaxLanguageSpec. For non-supported styles, the user can specify a string with the Pygments lexer name. For this to work, the lexer must be registered in the Pygments library. TYPE: SyntaxLanguageSpec.Literals | str DEFAULT: 'auto'
freedom	Parameter that controls the level of freedom for formatted text to follow the geometry of the frame size (=total available area) in a proportional manner. If the proportional freedom is 0 (the lowest), then the output area must not in any case be proportionally wider that the frame (i.e. a 16/9 frame will only produce output that is 16/9 or narrower). Larger values of proportional freedom allow the output to be proportionally wider than the total available frame, to a degree that relates to the size difference between the frame and the content (larger difference gives more freedom). The default value of 2.5 is a good compromise between readability/aesthetics and good use of the screen estate. If None, the freedom is unlimited (i.e. proportionality is not taken into account at all). TYPE: float | None DEFAULT: 2.5
debug	When True, enables additional debugging information in the output, such as the hierarchy of the Model objects. Currently, only Python pretty printers support debug=True. Hence, enabling debug mode will automatically set the printer to the default Python pretty printer if the printer config value is not already set. TYPE: bool DEFAULT: False
ui	Type of user interface for which the output should being prepared. The user interface describes the technical solutions available for interacting with the user, encompassing the support available for displaying output as well as how the user interacts with the library (including the type of interactive interpreter used, if any). TYPE: UserInterfaceType.Literals DEFAULT: 'auto'
system	Color system to use for terminal output. The default is AUTO, which automatically detects the color system based on particular environment variables. If color capabilities are not detected, the output will be in black and white. If the color system of a modern consoles/terminal is not auto-detected (which is the case for e.g. the PyCharm console), the user might want to set the color system manually to ANSI_RGB to force color output. TYPE: ColorSystem.Literals DEFAULT: 'auto'
style	Color style/theme for syntax highlighting and other display elements. Supported styles are defined in AllColorStyles. For non-supported styles, the user can specify a string with the Pygments style name. For this to work, the style must be registered in the Pygments library. If style is AUTO or any of the other RecommendedColorStyles, the style is automatically selected from the RecommendedColorStyles based on the detected user interface, the color system, and whether the background is dark or not. TYPE: AllColorStyles.Literals | str DEFAULT: 'auto'
dark	Whether the background color of the output is dark. This is used to determine the appropriate color scheme for syntax highlighting. The default is AUTO, which automatically tries to detect whether the background is dark. Capability of auto-detection depends on the user interface. TYPE: DarkBackground.Literals DEFAULT: 'auto'
bg	If False, uses transparent background for the output. In the case of terminal output, the background color will be the current background color of the terminal. For HTML output, the background color will be automatically set to pure black or pure white, depending on the luminosity of the foreground color. TYPE: bool DEFAULT: False
fonts	Font families to use in HTML output, in order of preference (empty tuple for browser default). TYPE: Tuple[str, ...] DEFAULT: ('Menlo', 'DejaVu Sans Mono', 'Consolas', 'Courier New', 'monospace')
font_size	Font size in pixels for HTML output (None for browser default). TYPE: NonNegativeInt | None DEFAULT: 14
font_weight	Font weight for HTML output (None for browser default). TYPE: NonNegativeInt | None DEFAULT: 400
line_height	Line height multiplier for HTML output (None for browser default). TYPE: NonNegativeFloat | None DEFAULT: 1.25
h_overflow	How to handle text that exceeds the width. TYPE: HorizontalOverflowMode.Literals DEFAULT: 'ellipsis'
v_overflow	How to handle text that exceeds the height. TYPE: VerticalOverflowMode.Literals DEFAULT: 'ellipsis_bottom'
panel	Visual design of the panel used as container for the output. Only TABLE is currently supported, which displays the output in a table-like grid. TYPE: PanelDesign.Literals DEFAULT: 'table'
title_at_top	Whether panel titles will be displayed over the panel content (True) or below the content (False) TYPE: bool DEFAULT: True
max_title_height	Maximum height of the panel title. If AUTO, the height is determined by the content of the title, up to a maximum of two lines. If ZERO, the title is not displayed at all. If ONE or TWO, the title is displayed with a fixed height of max one or two lines, respectively. TYPE: MaxTitleHeight.Literals DEFAULT: -1
min_panel_width	Minimum width in characters per panel. TYPE: NonNegativeInt DEFAULT: 3
min_crop_width	Minimum cropping width in characters for panels in cases where more than one panel are to be displayed. This is for instance used to calculate the number of models to display in a Dataset peek(). Only applied if use_min_crop_width is set to True. min_crop_width must be equal to or larger than min_panel_width. TYPE: NonNegativeInt DEFAULT: 33
use_min_crop_width	Whether the min_crop_width value should be considered in cases where more than one panel are to be displayed, potentially reducing the number of displayed panels. TYPE: bool DEFAULT: False
max_panels_hor	Maximum number of panels to display horizontally side-by-side at the top level. This value also acts as a ceiling for nested panels; nested panels cannot exceed this limit even if the constant MAX_PANELS_HORIZONTALLY_DEEPLY_NESTED is set to a higher value. If None, there is no limit. TYPE: NonNegativeInt | None DEFAULT: 9
max_nesting_depth	Maximum levels of nested panels to display. If None, there is no limit. TYPE: NonNegativeInt | None DEFAULT: 3
justify	Justification mode for the panel if inside a layout panel. This is only used for the panel content. TYPE: Justify.Literals DEFAULT: 'left'

RETURNS	DESCRIPTION
Element | None	If the UI type is Jupyter running in browser, the method returns a ReactivelyResizingHtml element which is a Jupyter widget to display HTML output in the browser. Otherwise, the method returns None.

Note

Any default argument value is overridden by the corresponding value in the relevant subsection of the UserInterfaceConfig.

Source code in src/omnipy/data/_mixins/display.py

def json(self, **kwargs) -> None:
    # %% Original docstring (managed by expand_docstr_macros.py) %%
    # {{JSON_SUMMARY}}
    #
    # {{JSON_DESCRIPTION}}
    #
    # {{DISPLAY_METHOD_ARGS}}
    #
    # {{DISPLAY_METHOD_RETURNS}}
    #
    # {{DISPLAY_METHOD_NOTE}}
    #
    """Preview the data content of the Model or Dataset as JSON.

    In contrast to e.g. `peek()`, `json()` displays the "data
    content" of the Model or Dataset, i.e. the content as plain
    Python objects, potentially converted from the internal data
    structure. This plain data is formatted in JSON (for
    compactness). Hence `json()` represents a the basic
    compatibility layer of all Omnipy Model or Dataset objects.
    The view is automatically limited by the available display
    dimensions.

    Args:
        width (NonNegativeInt | None):
            Width in characters of the output area (None for
            auto-detect based on available display dimensions).
        height (NonNegativeInt | None):
            Height in lines of the output area (None for
            auto-detect based on available display dimensions).
        tab (NonNegativeInt):
            Number of spaces to use for each tab.
        indent (NonNegativeInt):
            Number of spaces to use for each indentation level.
        printer (PrettyPrinterLib.Literals):
            Library to use for pretty printing.
        syntax (SyntaxLanguageSpec.Literals | str):
            Syntax language for code highlighting. Supported
            lexers are defined in SyntaxLanguageSpec. For
            non-supported styles, the user can specify a string
            with the Pygments lexer name. For this to work, the
            lexer must be registered in the Pygments library.
        freedom (float | None):
            Parameter that controls the level of freedom for
            formatted text to follow the geometry of the frame
            size (=total available area) in a proportional manner.
            If the proportional freedom is 0 (the lowest), then
            the output area must not in any case be proportionally
            wider that the frame (i.e. a 16/9 frame will only
            produce output that is 16/9 or narrower). Larger
            values of proportional freedom allow the output to be
            proportionally wider than the total available frame,
            to a degree that relates to the size difference
            between the frame and the content (larger difference
            gives more freedom). The default value of 2.5 is a
            good compromise between readability/aesthetics and
            good use of the screen estate. If None, the freedom is
            unlimited (i.e. proportionality is not taken into
            account at all).
        debug (bool):
            When True, enables additional debugging information in
            the output, such as the hierarchy of the Model
            objects. Currently, only Python pretty printers support
            debug=True. Hence, enabling debug mode will
            automatically set the printer to the default Python
            pretty printer if the `printer` config value is not
            already set.
        ui (UserInterfaceType.Literals):
            Type of user interface for which the output should
            being prepared. The user interface describes the
            technical solutions available for interacting with the
            user, encompassing the support available for
            displaying output as well as how the user interacts
            with the library (including the type of interactive
            interpreter used, if any).
        system (ColorSystem.Literals):
            Color system to use for terminal output. The default
            is `AUTO`, which automatically detects the color
            system based on particular environment variables. If
            color capabilities are not detected, the output will
            be in black and white. If the color system of a modern
            consoles/terminal is not auto-detected (which is the
            case for e.g. the PyCharm console), the user might
            want to set the color system manually to ANSI_RGB to
            force color output.
        style (AllColorStyles.Literals | str):
            Color style/theme for syntax highlighting and other
            display elements. Supported styles are defined in
            AllColorStyles. For non-supported styles, the user can
            specify a string with the Pygments style name. For this to
            work, the style must be registered in the Pygments
            library. If style is `AUTO` or any of the other
            RecommendedColorStyles, the style is automatically
            selected from the RecommendedColorStyles based on the
            detected user interface, the color system, and whether the
            background is dark or not.
        dark (DarkBackground.Literals):
            Whether the background color of the output is dark.
            This is used to determine the appropriate color scheme
            for syntax highlighting. The default is AUTO, which
            automatically tries to detect whether the background
            is dark. Capability of auto-detection depends on the
            user interface.
        bg (bool):
            If False, uses transparent background for the output.
            In the case of terminal output, the background color
            will be the current background color of the terminal.
            For HTML output, the background color will be
            automatically set to pure black or pure white,
            depending on the luminosity of the foreground color.
        fonts (Tuple[str, ...]):
            Font families to use in HTML output, in order of
            preference (empty tuple for browser default).
        font_size (NonNegativeInt | None):
            Font size in pixels for HTML output (None for browser
            default).
        font_weight (NonNegativeInt | None):
            Font weight for HTML output (None for browser
            default).
        line_height (NonNegativeFloat | None):
            Line height multiplier for HTML output (None for
            browser default).
        h_overflow (HorizontalOverflowMode.Literals):
            How to handle text that exceeds the width.
        v_overflow (VerticalOverflowMode.Literals):
            How to handle text that exceeds the height.
        panel (PanelDesign.Literals):
            Visual design of the panel used as container for the
            output. Only `TABLE` is currently supported, which
            displays the output in a table-like grid.
        title_at_top (bool):
            Whether panel titles will be displayed over the panel
            content (True) or below the content (False)
        max_title_height (MaxTitleHeight.Literals):
            Maximum height of the panel title. If `AUTO`, the
            height is determined by the content of the title, up
            to a maximum of two lines. If `ZERO`, the title is not
            displayed at all. If `ONE` or `TWO`, the title is
            displayed with a fixed height of max one or two lines,
            respectively.
        min_panel_width (NonNegativeInt):
            Minimum width in characters per panel.
        min_crop_width (NonNegativeInt):
            Minimum cropping width in characters for panels in
            cases where more than one panel are to be displayed.
            This is for instance used to calculate the number of
            models to display in a Dataset peek(). Only applied if
            `use_min_crop_width` is set to `True`.
            `min_crop_width` must be equal to or larger than
            `min_panel_width`.
        use_min_crop_width (bool):
            Whether the `min_crop_width` value should be
            considered in cases where more than one panel are to
            be displayed, potentially reducing the number of
            displayed panels.
        max_panels_hor (NonNegativeInt | None):
            Maximum number of panels to display horizontally
            side-by-side at the top level. This value also acts as
            a ceiling for nested panels; nested panels cannot
            exceed this limit even if the constant
            `MAX_PANELS_HORIZONTALLY_DEEPLY_NESTED` is set to a
            higher value. If None, there is no limit.
        max_nesting_depth (NonNegativeInt | None):
            Maximum levels of nested panels to display. If None,
            there is no limit.
        justify (Justify.Literals):
            Justification mode for the panel if inside a layout
            panel. This is only used for the panel content.

    Returns:
        If the UI type is Jupyter running in browser, the
        method returns a ReactivelyResizingHtml element which
        is a Jupyter widget to display HTML output in the
        browser. Otherwise, the method returns None.

    Note:
        Any default argument value is overridden by the
        corresponding value in the relevant subsection of the
        UserInterfaceConfig.
    """
    return self._display_according_to_ui_type(
        ui_type=self._extract_ui_type(**kwargs),
        return_output_if_str=False,
        output_method=self._json,
        **kwargs)

list

list(
    *,
    width: pyd.NonNegativeInt | None = None,
    height: pyd.NonNegativeInt | None = None,
    tab: pyd.NonNegativeInt = 4,
    indent: pyd.NonNegativeInt = 2,
    printer: PrettyPrinterLib.Literals = "auto",
    syntax: SyntaxLanguageSpec.Literals | str = "auto",
    freedom: pyd.NonNegativeFloat | None = 2.5,
    debug: bool = False,
    ui: UserInterfaceType.Literals = "auto",
    system: DisplayColorSystem.Literals = "auto",
    style: AllColorStyles.Literals | str = "auto",
    dark: Literal = "auto",
    bg: bool = False,
    fonts: tuple = ("Menlo", "DejaVu Sans Mono", "Consolas", "Courier New", "monospace"),
    font_size: pyd.NonNegativeInt | None = 14,
    font_weight: pyd.NonNegativeInt | None = 400,
    line_height: pyd.NonNegativeFloat | None = 1.25,
    h_overflow: HorizontalOverflowMode.Literals = "ellipsis",
    v_overflow: VerticalOverflowMode.Literals = "ellipsis_bottom",
    panel: PanelDesign.Literals = "table",
    title_at_top: bool = True,
    max_title_height: MaxTitleHeight.Literals = -1,
    min_panel_width: pyd.NonNegativeInt = 3,
    min_crop_width: pyd.NonNegativeInt = 33,
    use_min_crop_width: bool = False,
    max_panels_hor: pyd.NonNegativeInt | None = 9,
    max_nesting_depth: pyd.NonNegativeInt | None = 3,
    justify: Justify.Literals = "left",
) -> Element | None

Displays a summary list of all models in the dataset.

The summary list includes a number of key properties for each model, including data file names, types, lengths, and sizes in memory. The output is automatically limited by the available display dimensions.

PARAMETER	DESCRIPTION
width	Width in characters of the output area (None for auto-detect based on available display dimensions). TYPE: NonNegativeInt | None DEFAULT: None
height	Height in lines of the output area (None for auto-detect based on available display dimensions). TYPE: NonNegativeInt | None DEFAULT: None
tab	Number of spaces to use for each tab. TYPE: NonNegativeInt DEFAULT: 4
indent	Number of spaces to use for each indentation level. TYPE: NonNegativeInt DEFAULT: 2
printer	Library to use for pretty printing. TYPE: PrettyPrinterLib.Literals DEFAULT: 'auto'
syntax	Syntax language for code highlighting. Supported lexers are defined in SyntaxLanguageSpec. For non-supported styles, the user can specify a string with the Pygments lexer name. For this to work, the lexer must be registered in the Pygments library. TYPE: SyntaxLanguageSpec.Literals | str DEFAULT: 'auto'
freedom	Parameter that controls the level of freedom for formatted text to follow the geometry of the frame size (=total available area) in a proportional manner. If the proportional freedom is 0 (the lowest), then the output area must not in any case be proportionally wider that the frame (i.e. a 16/9 frame will only produce output that is 16/9 or narrower). Larger values of proportional freedom allow the output to be proportionally wider than the total available frame, to a degree that relates to the size difference between the frame and the content (larger difference gives more freedom). The default value of 2.5 is a good compromise between readability/aesthetics and good use of the screen estate. If None, the freedom is unlimited (i.e. proportionality is not taken into account at all). TYPE: float | None DEFAULT: 2.5
debug	When True, enables additional debugging information in the output, such as the hierarchy of the Model objects. Currently, only Python pretty printers support debug=True. Hence, enabling debug mode will automatically set the printer to the default Python pretty printer if the printer config value is not already set. TYPE: bool DEFAULT: False
ui	Type of user interface for which the output should being prepared. The user interface describes the technical solutions available for interacting with the user, encompassing the support available for displaying output as well as how the user interacts with the library (including the type of interactive interpreter used, if any). TYPE: UserInterfaceType.Literals DEFAULT: 'auto'
system	Color system to use for terminal output. The default is AUTO, which automatically detects the color system based on particular environment variables. If color capabilities are not detected, the output will be in black and white. If the color system of a modern consoles/terminal is not auto-detected (which is the case for e.g. the PyCharm console), the user might want to set the color system manually to ANSI_RGB to force color output. TYPE: ColorSystem.Literals DEFAULT: 'auto'
style	Color style/theme for syntax highlighting and other display elements. Supported styles are defined in AllColorStyles. For non-supported styles, the user can specify a string with the Pygments style name. For this to work, the style must be registered in the Pygments library. If style is AUTO or any of the other RecommendedColorStyles, the style is automatically selected from the RecommendedColorStyles based on the detected user interface, the color system, and whether the background is dark or not. TYPE: AllColorStyles.Literals | str DEFAULT: 'auto'
dark	Whether the background color of the output is dark. This is used to determine the appropriate color scheme for syntax highlighting. The default is AUTO, which automatically tries to detect whether the background is dark. Capability of auto-detection depends on the user interface. TYPE: DarkBackground.Literals DEFAULT: 'auto'
bg	If False, uses transparent background for the output. In the case of terminal output, the background color will be the current background color of the terminal. For HTML output, the background color will be automatically set to pure black or pure white, depending on the luminosity of the foreground color. TYPE: bool DEFAULT: False
fonts	Font families to use in HTML output, in order of preference (empty tuple for browser default). TYPE: Tuple[str, ...] DEFAULT: ('Menlo', 'DejaVu Sans Mono', 'Consolas', 'Courier New', 'monospace')
font_size	Font size in pixels for HTML output (None for browser default). TYPE: NonNegativeInt | None DEFAULT: 14
font_weight	Font weight for HTML output (None for browser default). TYPE: NonNegativeInt | None DEFAULT: 400
line_height	Line height multiplier for HTML output (None for browser default). TYPE: NonNegativeFloat | None DEFAULT: 1.25
h_overflow	How to handle text that exceeds the width. TYPE: HorizontalOverflowMode.Literals DEFAULT: 'ellipsis'
v_overflow	How to handle text that exceeds the height. TYPE: VerticalOverflowMode.Literals DEFAULT: 'ellipsis_bottom'
panel	Visual design of the panel used as container for the output. Only TABLE is currently supported, which displays the output in a table-like grid. TYPE: PanelDesign.Literals DEFAULT: 'table'
title_at_top	Whether panel titles will be displayed over the panel content (True) or below the content (False) TYPE: bool DEFAULT: True
max_title_height	Maximum height of the panel title. If AUTO, the height is determined by the content of the title, up to a maximum of two lines. If ZERO, the title is not displayed at all. If ONE or TWO, the title is displayed with a fixed height of max one or two lines, respectively. TYPE: MaxTitleHeight.Literals DEFAULT: -1
min_panel_width	Minimum width in characters per panel. TYPE: NonNegativeInt DEFAULT: 3
min_crop_width	Minimum cropping width in characters for panels in cases where more than one panel are to be displayed. This is for instance used to calculate the number of models to display in a Dataset peek(). Only applied if use_min_crop_width is set to True. min_crop_width must be equal to or larger than min_panel_width. TYPE: NonNegativeInt DEFAULT: 33
use_min_crop_width	Whether the min_crop_width value should be considered in cases where more than one panel are to be displayed, potentially reducing the number of displayed panels. TYPE: bool DEFAULT: False
max_panels_hor	Maximum number of panels to display horizontally side-by-side at the top level. This value also acts as a ceiling for nested panels; nested panels cannot exceed this limit even if the constant MAX_PANELS_HORIZONTALLY_DEEPLY_NESTED is set to a higher value. If None, there is no limit. TYPE: NonNegativeInt | None DEFAULT: 9
max_nesting_depth	Maximum levels of nested panels to display. If None, there is no limit. TYPE: NonNegativeInt | None DEFAULT: 3
justify	Justification mode for the panel if inside a layout panel. This is only used for the panel content. TYPE: Justify.Literals DEFAULT: 'left'

RETURNS	DESCRIPTION
Element | None	If the UI type is Jupyter running in browser, the method returns a ReactivelyResizingHtml element which is a Jupyter widget to display HTML output in the browser. Otherwise, the method returns None.

Note

Any default argument value is overridden by the corresponding value in the relevant subsection of the UserInterfaceConfig.

Source code in src/omnipy/data/_mixins/display.py

def list(self, **kwargs) -> 'Element | None':
    # %% Original docstring (managed by expand_docstr_macros.py) %%
    # {{LIST_SUMMARY}}
    #
    # {{LIST_DESCRIPTION}}
    #
    # {{DISPLAY_METHOD_ARGS}}
    #
    # {{DISPLAY_METHOD_RETURNS}}
    #
    # {{DISPLAY_METHOD_NOTE}}
    #
    """Displays a summary list of all models in the dataset.

    The summary list includes a number of key properties for each
    model, including data file names, types, lengths, and sizes in
    memory. The output is automatically limited by the available
    display dimensions.

    Args:
        width (NonNegativeInt | None):
            Width in characters of the output area (None for
            auto-detect based on available display dimensions).
        height (NonNegativeInt | None):
            Height in lines of the output area (None for
            auto-detect based on available display dimensions).
        tab (NonNegativeInt):
            Number of spaces to use for each tab.
        indent (NonNegativeInt):
            Number of spaces to use for each indentation level.
        printer (PrettyPrinterLib.Literals):
            Library to use for pretty printing.
        syntax (SyntaxLanguageSpec.Literals | str):
            Syntax language for code highlighting. Supported
            lexers are defined in SyntaxLanguageSpec. For
            non-supported styles, the user can specify a string
            with the Pygments lexer name. For this to work, the
            lexer must be registered in the Pygments library.
        freedom (float | None):
            Parameter that controls the level of freedom for
            formatted text to follow the geometry of the frame
            size (=total available area) in a proportional manner.
            If the proportional freedom is 0 (the lowest), then
            the output area must not in any case be proportionally
            wider that the frame (i.e. a 16/9 frame will only
            produce output that is 16/9 or narrower). Larger
            values of proportional freedom allow the output to be
            proportionally wider than the total available frame,
            to a degree that relates to the size difference
            between the frame and the content (larger difference
            gives more freedom). The default value of 2.5 is a
            good compromise between readability/aesthetics and
            good use of the screen estate. If None, the freedom is
            unlimited (i.e. proportionality is not taken into
            account at all).
        debug (bool):
            When True, enables additional debugging information in
            the output, such as the hierarchy of the Model
            objects. Currently, only Python pretty printers support
            debug=True. Hence, enabling debug mode will
            automatically set the printer to the default Python
            pretty printer if the `printer` config value is not
            already set.
        ui (UserInterfaceType.Literals):
            Type of user interface for which the output should
            being prepared. The user interface describes the
            technical solutions available for interacting with the
            user, encompassing the support available for
            displaying output as well as how the user interacts
            with the library (including the type of interactive
            interpreter used, if any).
        system (ColorSystem.Literals):
            Color system to use for terminal output. The default
            is `AUTO`, which automatically detects the color
            system based on particular environment variables. If
            color capabilities are not detected, the output will
            be in black and white. If the color system of a modern
            consoles/terminal is not auto-detected (which is the
            case for e.g. the PyCharm console), the user might
            want to set the color system manually to ANSI_RGB to
            force color output.
        style (AllColorStyles.Literals | str):
            Color style/theme for syntax highlighting and other
            display elements. Supported styles are defined in
            AllColorStyles. For non-supported styles, the user can
            specify a string with the Pygments style name. For this to
            work, the style must be registered in the Pygments
            library. If style is `AUTO` or any of the other
            RecommendedColorStyles, the style is automatically
            selected from the RecommendedColorStyles based on the
            detected user interface, the color system, and whether the
            background is dark or not.
        dark (DarkBackground.Literals):
            Whether the background color of the output is dark.
            This is used to determine the appropriate color scheme
            for syntax highlighting. The default is AUTO, which
            automatically tries to detect whether the background
            is dark. Capability of auto-detection depends on the
            user interface.
        bg (bool):
            If False, uses transparent background for the output.
            In the case of terminal output, the background color
            will be the current background color of the terminal.
            For HTML output, the background color will be
            automatically set to pure black or pure white,
            depending on the luminosity of the foreground color.
        fonts (Tuple[str, ...]):
            Font families to use in HTML output, in order of
            preference (empty tuple for browser default).
        font_size (NonNegativeInt | None):
            Font size in pixels for HTML output (None for browser
            default).
        font_weight (NonNegativeInt | None):
            Font weight for HTML output (None for browser
            default).
        line_height (NonNegativeFloat | None):
            Line height multiplier for HTML output (None for
            browser default).
        h_overflow (HorizontalOverflowMode.Literals):
            How to handle text that exceeds the width.
        v_overflow (VerticalOverflowMode.Literals):
            How to handle text that exceeds the height.
        panel (PanelDesign.Literals):
            Visual design of the panel used as container for the
            output. Only `TABLE` is currently supported, which
            displays the output in a table-like grid.
        title_at_top (bool):
            Whether panel titles will be displayed over the panel
            content (True) or below the content (False)
        max_title_height (MaxTitleHeight.Literals):
            Maximum height of the panel title. If `AUTO`, the
            height is determined by the content of the title, up
            to a maximum of two lines. If `ZERO`, the title is not
            displayed at all. If `ONE` or `TWO`, the title is
            displayed with a fixed height of max one or two lines,
            respectively.
        min_panel_width (NonNegativeInt):
            Minimum width in characters per panel.
        min_crop_width (NonNegativeInt):
            Minimum cropping width in characters for panels in
            cases where more than one panel are to be displayed.
            This is for instance used to calculate the number of
            models to display in a Dataset peek(). Only applied if
            `use_min_crop_width` is set to `True`.
            `min_crop_width` must be equal to or larger than
            `min_panel_width`.
        use_min_crop_width (bool):
            Whether the `min_crop_width` value should be
            considered in cases where more than one panel are to
            be displayed, potentially reducing the number of
            displayed panels.
        max_panels_hor (NonNegativeInt | None):
            Maximum number of panels to display horizontally
            side-by-side at the top level. This value also acts as
            a ceiling for nested panels; nested panels cannot
            exceed this limit even if the constant
            `MAX_PANELS_HORIZONTALLY_DEEPLY_NESTED` is set to a
            higher value. If None, there is no limit.
        max_nesting_depth (NonNegativeInt | None):
            Maximum levels of nested panels to display. If None,
            there is no limit.
        justify (Justify.Literals):
            Justification mode for the panel if inside a layout
            panel. This is only used for the panel content.

    Returns:
        If the UI type is Jupyter running in browser, the
        method returns a ReactivelyResizingHtml element which
        is a Jupyter widget to display HTML output in the
        browser. Otherwise, the method returns None.

    Note:
        Any default argument value is overridden by the
        corresponding value in the relevant subsection of the
        UserInterfaceConfig.
    """

    return self._display_according_to_ui_type(
        ui_type=self._extract_ui_type(**kwargs),
        return_output_if_str=False,
        output_method=self._list,
        **kwargs,
    )

load classmethod

load(
    paths_or_urls: IsPathsOrUrlsOneOrMoreOrNone = None,
    by_file_suffix: bool = False,
    as_mime_type: None | str = None,
    **kwargs: IsPathOrUrl,
) -> Self | asyncio.Task[Self]

Source code in src/omnipy/data/dataset.py

@classmethod
def load(
    cls,
    paths_or_urls: IsPathsOrUrlsOneOrMoreOrNone = None,
    by_file_suffix: bool = False,
    as_mime_type: None | str = None,
    **kwargs: IsPathOrUrl,
) -> Self | asyncio.Task[Self]:
    dataset = cls()
    return dataset.load_into(
        paths_or_urls, by_file_suffix=by_file_suffix, as_mime_type=as_mime_type, **kwargs)

load_into

load_into(
    paths_or_urls: IsPathsOrUrlsOneOrMoreOrNone = None,
    by_file_suffix: bool = False,
    as_mime_type: None | str = None,
    **kwargs: IsPathOrUrl,
) -> Self | asyncio.Task[Self]

Source code in src/omnipy/data/dataset.py

def load_into(
    self,
    paths_or_urls: IsPathsOrUrlsOneOrMoreOrNone = None,
    by_file_suffix: bool = False,
    as_mime_type: None | str = None,
    **kwargs: IsPathOrUrl,
) -> Self | asyncio.Task[Self]:
    from omnipy.components.remote.datasets import HttpUrlDataset
    from omnipy.components.remote.models import HttpUrlModel

    if paths_or_urls is None:
        assert len(kwargs) > 0, 'No paths or urls specified'
        paths_or_urls = kwargs
    else:
        assert len(kwargs) == 0, 'No keyword arguments allowed when paths_or_urls is specified'

    match paths_or_urls:
        case HttpUrlDataset():
            return self._load_http_urls(paths_or_urls, as_mime_type=as_mime_type)

        case HttpUrlModel():
            return self._load_http_urls(
                HttpUrlDataset({str(paths_or_urls): paths_or_urls}),
                as_mime_type=as_mime_type,
            )

        case str():
            try:
                http_url_dataset = HttpUrlDataset({paths_or_urls: paths_or_urls})
            except ValidationError:
                return self._load_paths([paths_or_urls], by_file_suffix)
            return self._load_http_urls(http_url_dataset, as_mime_type=as_mime_type)

        case Mapping():
            try:
                http_url_dataset = HttpUrlDataset(paths_or_urls)
            except ValidationError as exp:
                raise NotImplementedError(
                    'Loading files with specified keys is not yet '
                    'implemented, as only tar.gz file import is '
                    'supported until serializers have been refactored.') from exp
            return self._load_http_urls(http_url_dataset, as_mime_type=as_mime_type)

        case Iterable():
            path_or_url_iterable = paths_or_urls
            try:
                http_url_dataset = HttpUrlDataset(
                    zip(path_or_url_iterable, path_or_url_iterable))
            except ValidationError:
                return self._load_paths(path_or_url_iterable, by_file_suffix)
            return self._load_http_urls(http_url_dataset, as_mime_type=as_mime_type)
        case _:
            raise TypeError(f'"paths_or_urls" argument is of incorrect type. Type '
                            f'{type(paths_or_urls)} is not supported.')

peek

peek(
    *,
    width: pyd.NonNegativeInt | None = None,
    height: pyd.NonNegativeInt | None = None,
    tab: pyd.NonNegativeInt = 4,
    indent: pyd.NonNegativeInt = 2,
    printer: PrettyPrinterLib.Literals = "auto",
    syntax: SyntaxLanguageSpec.Literals | str = "auto",
    freedom: pyd.NonNegativeFloat | None = 2.5,
    debug: bool = False,
    ui: UserInterfaceType.Literals = "auto",
    system: DisplayColorSystem.Literals = "auto",
    style: AllColorStyles.Literals | str = "auto",
    dark: Literal = "auto",
    bg: bool = False,
    fonts: tuple = ("Menlo", "DejaVu Sans Mono", "Consolas", "Courier New", "monospace"),
    font_size: pyd.NonNegativeInt | None = 14,
    font_weight: pyd.NonNegativeInt | None = 400,
    line_height: pyd.NonNegativeFloat | None = 1.25,
    h_overflow: HorizontalOverflowMode.Literals = "ellipsis",
    v_overflow: VerticalOverflowMode.Literals = "ellipsis_bottom",
    panel: PanelDesign.Literals = "table",
    title_at_top: bool = True,
    max_title_height: MaxTitleHeight.Literals = -1,
    min_panel_width: pyd.NonNegativeInt = 3,
    min_crop_width: pyd.NonNegativeInt = 33,
    use_min_crop_width: bool = False,
    max_panels_hor: pyd.NonNegativeInt | None = 9,
    max_nesting_depth: pyd.NonNegativeInt | None = 3,
    justify: Justify.Literals = "left",
) -> Element | None

Display a preview of the Model or Dataset content.

For Model instances, peek() displays a preview of the model's content. For Dataset instances, peek() displays a side-by-side view of each model contained in the dataset. Both views are automatically limited by the available display dimensions.

PARAMETER	DESCRIPTION
width	Width in characters of the output area (None for auto-detect based on available display dimensions). TYPE: NonNegativeInt | None DEFAULT: None
height	Height in lines of the output area (None for auto-detect based on available display dimensions). TYPE: NonNegativeInt | None DEFAULT: None
tab	Number of spaces to use for each tab. TYPE: NonNegativeInt DEFAULT: 4
indent	Number of spaces to use for each indentation level. TYPE: NonNegativeInt DEFAULT: 2
printer	Library to use for pretty printing. TYPE: PrettyPrinterLib.Literals DEFAULT: 'auto'
syntax	Syntax language for code highlighting. Supported lexers are defined in SyntaxLanguageSpec. For non-supported styles, the user can specify a string with the Pygments lexer name. For this to work, the lexer must be registered in the Pygments library. TYPE: SyntaxLanguageSpec.Literals | str DEFAULT: 'auto'
freedom	Parameter that controls the level of freedom for formatted text to follow the geometry of the frame size (=total available area) in a proportional manner. If the proportional freedom is 0 (the lowest), then the output area must not in any case be proportionally wider that the frame (i.e. a 16/9 frame will only produce output that is 16/9 or narrower). Larger values of proportional freedom allow the output to be proportionally wider than the total available frame, to a degree that relates to the size difference between the frame and the content (larger difference gives more freedom). The default value of 2.5 is a good compromise between readability/aesthetics and good use of the screen estate. If None, the freedom is unlimited (i.e. proportionality is not taken into account at all). TYPE: float | None DEFAULT: 2.5
debug	When True, enables additional debugging information in the output, such as the hierarchy of the Model objects. Currently, only Python pretty printers support debug=True. Hence, enabling debug mode will automatically set the printer to the default Python pretty printer if the printer config value is not already set. TYPE: bool DEFAULT: False
ui	Type of user interface for which the output should being prepared. The user interface describes the technical solutions available for interacting with the user, encompassing the support available for displaying output as well as how the user interacts with the library (including the type of interactive interpreter used, if any). TYPE: UserInterfaceType.Literals DEFAULT: 'auto'
system	Color system to use for terminal output. The default is AUTO, which automatically detects the color system based on particular environment variables. If color capabilities are not detected, the output will be in black and white. If the color system of a modern consoles/terminal is not auto-detected (which is the case for e.g. the PyCharm console), the user might want to set the color system manually to ANSI_RGB to force color output. TYPE: ColorSystem.Literals DEFAULT: 'auto'
style	Color style/theme for syntax highlighting and other display elements. Supported styles are defined in AllColorStyles. For non-supported styles, the user can specify a string with the Pygments style name. For this to work, the style must be registered in the Pygments library. If style is AUTO or any of the other RecommendedColorStyles, the style is automatically selected from the RecommendedColorStyles based on the detected user interface, the color system, and whether the background is dark or not. TYPE: AllColorStyles.Literals | str DEFAULT: 'auto'
dark	Whether the background color of the output is dark. This is used to determine the appropriate color scheme for syntax highlighting. The default is AUTO, which automatically tries to detect whether the background is dark. Capability of auto-detection depends on the user interface. TYPE: DarkBackground.Literals DEFAULT: 'auto'
bg	If False, uses transparent background for the output. In the case of terminal output, the background color will be the current background color of the terminal. For HTML output, the background color will be automatically set to pure black or pure white, depending on the luminosity of the foreground color. TYPE: bool DEFAULT: False
fonts	Font families to use in HTML output, in order of preference (empty tuple for browser default). TYPE: Tuple[str, ...] DEFAULT: ('Menlo', 'DejaVu Sans Mono', 'Consolas', 'Courier New', 'monospace')
font_size	Font size in pixels for HTML output (None for browser default). TYPE: NonNegativeInt | None DEFAULT: 14
font_weight	Font weight for HTML output (None for browser default). TYPE: NonNegativeInt | None DEFAULT: 400
line_height	Line height multiplier for HTML output (None for browser default). TYPE: NonNegativeFloat | None DEFAULT: 1.25
h_overflow	How to handle text that exceeds the width. TYPE: HorizontalOverflowMode.Literals DEFAULT: 'ellipsis'
v_overflow	How to handle text that exceeds the height. TYPE: VerticalOverflowMode.Literals DEFAULT: 'ellipsis_bottom'
panel	Visual design of the panel used as container for the output. Only TABLE is currently supported, which displays the output in a table-like grid. TYPE: PanelDesign.Literals DEFAULT: 'table'
title_at_top	Whether panel titles will be displayed over the panel content (True) or below the content (False) TYPE: bool DEFAULT: True
max_title_height	Maximum height of the panel title. If AUTO, the height is determined by the content of the title, up to a maximum of two lines. If ZERO, the title is not displayed at all. If ONE or TWO, the title is displayed with a fixed height of max one or two lines, respectively. TYPE: MaxTitleHeight.Literals DEFAULT: -1
min_panel_width	Minimum width in characters per panel. TYPE: NonNegativeInt DEFAULT: 3
min_crop_width	Minimum cropping width in characters for panels in cases where more than one panel are to be displayed. This is for instance used to calculate the number of models to display in a Dataset peek(). Only applied if use_min_crop_width is set to True. min_crop_width must be equal to or larger than min_panel_width. TYPE: NonNegativeInt DEFAULT: 33
use_min_crop_width	Whether the min_crop_width value should be considered in cases where more than one panel are to be displayed, potentially reducing the number of displayed panels. TYPE: bool DEFAULT: False
max_panels_hor	Maximum number of panels to display horizontally side-by-side at the top level. This value also acts as a ceiling for nested panels; nested panels cannot exceed this limit even if the constant MAX_PANELS_HORIZONTALLY_DEEPLY_NESTED is set to a higher value. If None, there is no limit. TYPE: NonNegativeInt | None DEFAULT: 9
max_nesting_depth	Maximum levels of nested panels to display. If None, there is no limit. TYPE: NonNegativeInt | None DEFAULT: 3
justify	Justification mode for the panel if inside a layout panel. This is only used for the panel content. TYPE: Justify.Literals DEFAULT: 'left'

RETURNS	DESCRIPTION
Element | None	If the UI type is Jupyter running in browser, the method returns a ReactivelyResizingHtml element which is a Jupyter widget to display HTML output in the browser. Otherwise, the method returns None.

Note

Any default argument value is overridden by the corresponding value in the relevant subsection of the UserInterfaceConfig.

Source code in src/omnipy/data/_mixins/display.py

def peek(self, **kwargs) -> 'Element | None':
    # %% Original docstring (managed by expand_docstr_macros.py) %%
    # {{PEEK_SUMMARY}}
    #
    # {{PEEK_DESCRIPTION}}
    #
    # {{DISPLAY_METHOD_ARGS}}
    #
    # {{DISPLAY_METHOD_RETURNS}}
    #
    # {{DISPLAY_METHOD_NOTE}}
    #
    """Display a preview of the Model or Dataset content.

    For Model instances, `peek()` displays a preview of the
    model's content. For Dataset instances, `peek()` displays a
    side-by-side view of each model contained in the dataset. Both
    views are automatically limited by the available display
    dimensions.

    Args:
        width (NonNegativeInt | None):
            Width in characters of the output area (None for
            auto-detect based on available display dimensions).
        height (NonNegativeInt | None):
            Height in lines of the output area (None for
            auto-detect based on available display dimensions).
        tab (NonNegativeInt):
            Number of spaces to use for each tab.
        indent (NonNegativeInt):
            Number of spaces to use for each indentation level.
        printer (PrettyPrinterLib.Literals):
            Library to use for pretty printing.
        syntax (SyntaxLanguageSpec.Literals | str):
            Syntax language for code highlighting. Supported
            lexers are defined in SyntaxLanguageSpec. For
            non-supported styles, the user can specify a string
            with the Pygments lexer name. For this to work, the
            lexer must be registered in the Pygments library.
        freedom (float | None):
            Parameter that controls the level of freedom for
            formatted text to follow the geometry of the frame
            size (=total available area) in a proportional manner.
            If the proportional freedom is 0 (the lowest), then
            the output area must not in any case be proportionally
            wider that the frame (i.e. a 16/9 frame will only
            produce output that is 16/9 or narrower). Larger
            values of proportional freedom allow the output to be
            proportionally wider than the total available frame,
            to a degree that relates to the size difference
            between the frame and the content (larger difference
            gives more freedom). The default value of 2.5 is a
            good compromise between readability/aesthetics and
            good use of the screen estate. If None, the freedom is
            unlimited (i.e. proportionality is not taken into
            account at all).
        debug (bool):
            When True, enables additional debugging information in
            the output, such as the hierarchy of the Model
            objects. Currently, only Python pretty printers support
            debug=True. Hence, enabling debug mode will
            automatically set the printer to the default Python
            pretty printer if the `printer` config value is not
            already set.
        ui (UserInterfaceType.Literals):
            Type of user interface for which the output should
            being prepared. The user interface describes the
            technical solutions available for interacting with the
            user, encompassing the support available for
            displaying output as well as how the user interacts
            with the library (including the type of interactive
            interpreter used, if any).
        system (ColorSystem.Literals):
            Color system to use for terminal output. The default
            is `AUTO`, which automatically detects the color
            system based on particular environment variables. If
            color capabilities are not detected, the output will
            be in black and white. If the color system of a modern
            consoles/terminal is not auto-detected (which is the
            case for e.g. the PyCharm console), the user might
            want to set the color system manually to ANSI_RGB to
            force color output.
        style (AllColorStyles.Literals | str):
            Color style/theme for syntax highlighting and other
            display elements. Supported styles are defined in
            AllColorStyles. For non-supported styles, the user can
            specify a string with the Pygments style name. For this to
            work, the style must be registered in the Pygments
            library. If style is `AUTO` or any of the other
            RecommendedColorStyles, the style is automatically
            selected from the RecommendedColorStyles based on the
            detected user interface, the color system, and whether the
            background is dark or not.
        dark (DarkBackground.Literals):
            Whether the background color of the output is dark.
            This is used to determine the appropriate color scheme
            for syntax highlighting. The default is AUTO, which
            automatically tries to detect whether the background
            is dark. Capability of auto-detection depends on the
            user interface.
        bg (bool):
            If False, uses transparent background for the output.
            In the case of terminal output, the background color
            will be the current background color of the terminal.
            For HTML output, the background color will be
            automatically set to pure black or pure white,
            depending on the luminosity of the foreground color.
        fonts (Tuple[str, ...]):
            Font families to use in HTML output, in order of
            preference (empty tuple for browser default).
        font_size (NonNegativeInt | None):
            Font size in pixels for HTML output (None for browser
            default).
        font_weight (NonNegativeInt | None):
            Font weight for HTML output (None for browser
            default).
        line_height (NonNegativeFloat | None):
            Line height multiplier for HTML output (None for
            browser default).
        h_overflow (HorizontalOverflowMode.Literals):
            How to handle text that exceeds the width.
        v_overflow (VerticalOverflowMode.Literals):
            How to handle text that exceeds the height.
        panel (PanelDesign.Literals):
            Visual design of the panel used as container for the
            output. Only `TABLE` is currently supported, which
            displays the output in a table-like grid.
        title_at_top (bool):
            Whether panel titles will be displayed over the panel
            content (True) or below the content (False)
        max_title_height (MaxTitleHeight.Literals):
            Maximum height of the panel title. If `AUTO`, the
            height is determined by the content of the title, up
            to a maximum of two lines. If `ZERO`, the title is not
            displayed at all. If `ONE` or `TWO`, the title is
            displayed with a fixed height of max one or two lines,
            respectively.
        min_panel_width (NonNegativeInt):
            Minimum width in characters per panel.
        min_crop_width (NonNegativeInt):
            Minimum cropping width in characters for panels in
            cases where more than one panel are to be displayed.
            This is for instance used to calculate the number of
            models to display in a Dataset peek(). Only applied if
            `use_min_crop_width` is set to `True`.
            `min_crop_width` must be equal to or larger than
            `min_panel_width`.
        use_min_crop_width (bool):
            Whether the `min_crop_width` value should be
            considered in cases where more than one panel are to
            be displayed, potentially reducing the number of
            displayed panels.
        max_panels_hor (NonNegativeInt | None):
            Maximum number of panels to display horizontally
            side-by-side at the top level. This value also acts as
            a ceiling for nested panels; nested panels cannot
            exceed this limit even if the constant
            `MAX_PANELS_HORIZONTALLY_DEEPLY_NESTED` is set to a
            higher value. If None, there is no limit.
        max_nesting_depth (NonNegativeInt | None):
            Maximum levels of nested panels to display. If None,
            there is no limit.
        justify (Justify.Literals):
            Justification mode for the panel if inside a layout
            panel. This is only used for the panel content.

    Returns:
        If the UI type is Jupyter running in browser, the
        method returns a ReactivelyResizingHtml element which
        is a Jupyter widget to display HTML output in the
        browser. Otherwise, the method returns None.

    Note:
        Any default argument value is overridden by the
        corresponding value in the relevant subsection of the
        UserInterfaceConfig.
    """
    return self._display_according_to_ui_type(
        ui_type=self._extract_ui_type(**kwargs),
        return_output_if_str=False,
        output_method=self._peek,
        **kwargs,
    )

pending_task_details

pending_task_details() -> dict[str, IsPendingData]

Source code in src/omnipy/data/_mixins/task.py

def pending_task_details(self) -> dict[str, IsPendingData]:
    self_with_data = cast(HasData, self)
    return {  # pyright: ignore [reportReturnType]
        key: val for key, val in self_with_data.data.items() if isinstance(val, PendingData)
    }

save

save(path: str)

Source code in src/omnipy/data/dataset.py

def save(self, path: str):
    serializer_registry = self._get_serializer_registry()

    parsed_dataset, serializer = serializer_registry.auto_detect_tar_file_serializer(self)

    if serializer is None:
        print(f'Unable to find a serializer for dataset with data type "{type(self)}". '
              f'Will abort saving...')
    else:
        if not path.endswith('.tar.gz'):
            out_tar_gz_path = f'{path}.tar.gz'

        print(f'Writing dataset as a gzipped tarpack to "{os.path.abspath(out_tar_gz_path)}"')

        with open(out_tar_gz_path, 'wb') as out_tar_gz_file:
            out_tar_gz_file.write(serializer.serialize(parsed_dataset))

        directory = os.path.abspath(out_tar_gz_path[:-7])
        if not os.path.exists(directory):
            os.makedirs(directory)

        tar = tarfile.open(out_tar_gz_path)
        print(f'Extracting content to directory "{os.path.abspath(out_tar_gz_path[:-7])}"')
        tar.extractall(path=directory)
        tar.close()

set_model

set_model(data_file: str, model: type[Model]) -> None

Source code in src/omnipy/data/multi.py

def set_model(self, data_file: str, model: 'type[Model]') -> None:
    try:
        self._custom_field_models[data_file] = model
        if data_file in self.data:
            self._validate_data_file(data_file)
        else:
            self.data[data_file] = model()
    except ValidationError:
        del self._custom_field_models[data_file]
        raise

to

to(model_or_dataset_cls: type[_OtherModelOrDatasetT]) -> _OtherModelOrDatasetT

Source code in src/omnipy/data/dataset.py

def to(self, model_or_dataset_cls: type[_OtherModelOrDatasetT]) -> '_OtherModelOrDatasetT':
    return model_or_dataset_cls(self)

to_data

to_data() -> dict_t[str, Any]

Source code in src/omnipy/data/dataset.py

def to_data(self) -> dict_t[str, Any]:
    return {key: self._check_value(val) for key, val in self.dict(by_alias=True).items()}

to_json

to_json(pretty=True) -> dict_t[str, str]

Source code in src/omnipy/data/dataset.py

def to_json(self, pretty=True) -> dict_t[str, str]:
    result = {}

    for key, val in self.data.items():
        result[key] = val.to_json(pretty=pretty)

    return result

to_json_schema classmethod

to_json_schema(pretty: bool = True) -> str | dict_t[str, str]

Source code in src/omnipy/data/dataset.py

@classmethod
def to_json_schema(cls, pretty: bool = True) -> str | dict_t[str, str]:
    result = {}
    clean_dataset = super(Dataset, Dataset).__class_getitem__(cls.get_type())
    schema = clean_dataset.schema()
    for key, val in schema['properties'][DATA_KEY].items():
        # Remove the first part of the type definition of 'data', added
        # as a hack to stop coercing of e.g. [{'a': 'b', 'c': 'd'}]
        # to {'a': 'c'}
        if key == 'anyOf':
            result['type'] = 'object'
            result['additionalProperties'] = {
                '$ref': '#/definitions/' + pyd.normalize_name(clean_dataset.get_type().__name__)
            }
        else:
            result[key] = val

    result['title'] = clean_dataset.__name__
    result['definitions'] = schema['definitions']

    for model_desc in result['definitions'].values():
        if 'orig_model' in model_desc:
            del model_desc['orig_model']

    if pretty:
        return cls._pretty_print_json(result)
    else:
        return json.dumps(result)

update_forward_refs classmethod

update_forward_refs(
    calling_module: str | None = None, prev_visited_classes: set[type] | None = None, **localns: Any
) -> None

Source code in src/omnipy/data/dataset.py

@classmethod
def update_forward_refs(
    cls,
    calling_module: str | None = None,
    prev_visited_classes: set[type] | None = None,
    **localns: Any,
) -> None:
    from omnipy.data.model import is_model_subclass
    """
    Try to update ForwardRefs on fields based on this Model, globalns and localns.
    """

    if prev_visited_classes is None:
        prev_visited_classes = set()
    elif cls in prev_visited_classes:
        return

    # Merge the namespaces of the Datasets's own module and the
    # calling module to the local namespace for evaluation of forward
    # references, which is necessary for cases where the Dataset is
    # defined in a different module than where it is used, e.g. when
    # the Dataset is defined in a library and used by a user in their
    # own code.
    if calling_module is None:
        calling_module = get_calling_module_name()
    own_module_ns, globalns = \
        build_own_module_and_global_namespace_for_forward_refs(cls, calling_module, **localns)

    prev_type = cls._get_data_field().type_

    super().update_forward_refs(**globalns)

    cls._get_data_field().type_ = evaluate_any_forward_refs_if_possible(prev_type, **globalns)
    cls.__annotations__[DATA_KEY] = evaluate_any_forward_refs_if_possible(
        cls.__annotations__[DATA_KEY], **globalns)

    prev_visited_classes.add(cls)

    # Merge the Dataset's own module namespace into
    # localns before propagating. This is to allow Model classes and
    # pydantic-generated parametrized base classes (which have
    # __module__='omnipy.data.dataset' rather than the defining
    # module) to still resolve forward refs that only exist
    # in the defining module's namespace.

    extra_ns: dict[str, Any] = {}
    extra_ns.update(own_module_ns)
    extra_ns.update(localns)

    # Propagate update_forward_refs to parent Dataset classes but
    # retaining the same calling module. This is needed to ensure the
    # correct context is used to resolve forward references in complex
    # inheritance hierarchies.
    #
    # We explicitly call `update_forward_refs` on immediate parent
    # classes (`__bases__`) instead of relying solely on
    # `super().update_forward_refs()`. This is because `super()`
    # inside this classmethod resolves relative to `Dataset` in the MRO,
    # silently bypassing custom logic on any intermediate `Dataset`
    # subclasses. Explicitly propagating through `__bases__` ensures
    # that class-level setups are correctly applied to all parents
    # exactly once, efficiently preventing redundant updates.
    for base in cls.__bases__:
        if is_dataset_subclass(base) and base is not Dataset:
            base.update_forward_refs(
                calling_module=calling_module,
                prev_visited_classes=prev_visited_classes,
                **extra_ns,
            )

    # As above, but now propagate update_forward_refs to the types of
    # the Dataset (e.g. the Model).
    for type_variant in split_to_union_variants(cls.get_type()):
        if is_dataset_subclass(type_variant) or is_model_subclass(type_variant):
            type_variant.update_forward_refs(
                calling_module=calling_module,
                prev_visited_classes=prev_visited_classes,
                **extra_ns,
            )

    cls.__name__ = remove_forward_ref_notation(cls.__name__)
    cls.__qualname__ = remove_forward_ref_notation(cls.__qualname__)

    cls._clean_type_caches()

validate classmethod

validate(value: Any) -> Self

Hack to allow overwriting of iter method without compromising pydantic validation. Part of the pydantic API and not the Omnipy API.

Source code in src/omnipy/data/dataset.py

@classmethod
def validate(cls, value: Any) -> Self:
    """
    Hack to allow overwriting of __iter__ method without compromising pydantic validation. Part
    of the pydantic API and not the Omnipy API.
    """
    # TODO: Doublecheck if validate() method is still needed for pydantic v2

    # validate_cls_counts[cls.__name__] += 1
    if is_iterable(value) and not isinstance(value, Mapping):
        value = cls._check_iterable(value)

    return super().validate({'data': value})