pic_scanner.gui.models.windows.main.blueprint.columns

Attributes

gui_file_collection

Classes

`GUIFileCollection`	A class to manage a collection of files with a cursor to navigate through them.
`Column`	A class for building a PySimpleGUI Column.
`FileCollection`	A class for managing a collection of files.
`ButtonSchematic`	A metaclass to enhance classes with logging capabilities. Classes that inherit from
`ButtonFactory`	A class to create ButtonSchematic instances.
`GUIElementKeyFactory`	A factory class to create GUIElementKey objects with predefined configurations.
`LeftColumn`	A class that represents the left column of the main window.
`FileColumn`	A class for building a PySimpleGUI Column.

Functions

`get_image_data`() → bytes)	Get image data from a file or a bytes object.
`flag_lock`(instance, flag_name)	Context manager to set and unset a private flag attribute in an instance.

Package Contents

class pic_scanner.gui.models.windows.main.blueprint.columns.GUIFileCollection(collection: pic_scanner.helpers.FileCollection)

Bases: inspy_logger.Loggable

A class to manage a collection of files with a cursor to navigate through them.

Properties:

collection (FileCollection):: The collection of files.
files (list[Path]):: List of file paths from the collection.
cursor (int):: Current position of the cursor in the collection.

Parameters:: collection (pic_scanner.helpers.FileCollection)

cursor

property collection: pic_scanner.helpers.FileCollection

Returns the collection of files.

Returns:: The collection of files.
Return type:: FileCollection

property files: list

Returns the list of file paths from the collection.

Returns:: The list of file paths.
Return type:: list

property needs_reprocessing: bool

Returns whether the collection needs reprocessing.

Returns:: True if the collection needs reprocessing, False otherwise.
Return type:: bool

next() → str

Moves the cursor to the next file in the collection and returns it.

Returns:: The path of the next file.
Return type:: str

prev() → str

Moves the cursor to the previous file in the collection and returns it.

Returns:: The path of the previous file.
Return type:: str

current() → str

Returns the file at the current cursor position.

Returns:: The path of the current file.
Return type:: str

remove_current(): Removes the file at the current cursor position.

set_cursor(index: int)

Sets the cursor to the specified index, adjusting if out of bounds.

Parameters:: index (int) – The position to set the cursor to.
Raises:: IndexError – If the index is out of the valid range.

add_cursor_callback(callback, *args, **kwargs)

Adds a callback to be invoked when the cursor changes.

Parameters:

callback (callable) – The callback function.
*args – Additional positional arguments to pass to the callback.
**kwargs – Additional keyword arguments to pass to the callback.

class pic_scanner.gui.models.windows.main.blueprint.columns.Column(column_key: str, auto_build=False)

A class for building a PySimpleGUI Column.

This class is used to build a PySimpleGUI Column. It is a subclass of the AutoBuildMeta metaclass.

Properties:

auto_build (bool):: A boolean value that determines whether the class should automatically build itself when instantiated. This is set to False by default. This property is read-only.
building (bool):: A boolean value that determines whether the class is currently building itself. This is set to False by default.
column (psg.Column):: The PySimpleGUI Column object. This is built from the layout, and will only have a value if the class is built.
column_key (str):: The key for the column. This is used to identify the column in the layout. It is set to None by default, and after instantiation it is frozen and cannot be changed.
is_built (bool):: A boolean value that determines whether the class has been built.
layout (list):: A list of elements that make up the layout of the class. This is used to build the column, and is set to an empty list by default.

Parameters:: column_key (str)

column_key

property auto_build: bool

Returns the value of the auto_build attribute.

The auto_build attribute is a boolean value that determines whether the class should automatically build itself when instantiated.

Return type:: bool

abstract build()

property building

Returns the value of the `building` attribute.

The building attribute is a boolean value that determines whether the class is currently building itself.

Returns:: The value of the building attribute.
Return type:: bool

property column

Returns the column.

The column is built from the layout, and will only have a value if the class is built; otherwise it will be None.

Returns:: The column.
Return type:: psg.Column

property layout

Returns the layout.

The layout is a list of elements that make up the layout of the class. This is used to build the column, and is set to an empty list by default.

Returns:: The layout.
Return type:: list

property is_built

Returns whether the class has been built.

Returns:: True if the class has been built, False otherwise.
Return type:: bool

class pic_scanner.gui.models.windows.main.blueprint.columns.FileCollection(paths: List[str] = None)

A class for managing a collection of files.

Properties:

paths (list):: A list of file paths.
total_size (int):: The total size of the collection, in bytes.
total_files (int):: The total number of files in the collection.
extensions (dict):: A dictionary of extensions with properties for total size and number of files.
needs_reprocessing (bool):: A flag indicating whether the collection needs reprocessing.

Parameters:: paths (List[str])

get_total_size_in_lowest_unit()

Get the total size of the collection in the lowest unit.

Return type:: tuple[Union[int, float], str]

get_total_extension_size_in_lowest_unit()

Get the total size of a specific extension in the lowest unit.

Parameters:

extension (str)
return_as_string (bool)

Return type:

tuple[Union[int, float], str]

remove_file()

Remove a file from the collection.

Parameters:: path (Union[pathlib.Path, str])

reprocess_files(): Reprocess the files in the collection.

Examples

>>> collection = FileCollection(paths=['/path/to/file1', '/path/to/file2'])
>>> collection.total_size
123456  # Total size of the collection, in bytes.

paths: list

total_size: int

total_files: int

extensions: dict

property needs_reprocessing: bool

Returns whether the collection needs reprocessing.

This property returns a boolean value indicating whether the collection needs reprocessing. If the collection has been modified since the last processing, this property will return True. If the collection has not been modified, it will return False. The property is read-only.

Returns:: True if the collection needs reprocessing, False otherwise.
Return type:: bool

reprocess_files()

Reprocess the files in the collection.

This method reprocesses the files in the collection. It recalculates the total size of the collection, the total number of files, and the total size of each extension in the collection. It populates the total_size, total_files, and extensions attributes of the class. This method is used to update the collection after files have been added or removed.

Note

This method should be called after files have been added or removed from the collection. It will only reprocess the files if the needs_reprocessing attribute is set to True. After reprocessing, the needs_reprocessing attribute will be set to False.

Returns:: None

get_total_size_in_lowest_unit() → tuple[int | float, str]

Get the total size of the collection in the lowest unit with a size greater than or equal to 1.

This method calculates the total size of the collection in the lowest unit with a size greater than or equal to 1. It returns the size and the unit as a tuple. The unit is a string representing the unit of the size.

Returns:: The total size of the collection and the unit.
Return type:: tuple[Union[int, float], str]

get_total_extension_size_in_lowest_unit(extension: str, return_as_string: bool = False) → tuple[int | float, str]

Get the total size of a specific extension in the lowest unit with a size greater than or equal to 1.

Parameters:

extension (str) – The extension to get the size of.
return_as_string (bool) – A flag indicating whether to return the size as a string. If True, the size will be returned as a string with the unit. If False, the size will be returned as a tuple with the size and the unit.

Returns:

The total size of the extension and the unit.

Return type:

tuple[Union[int, float], str]

Raises:

ValueError – If the extension is not found in the collection.

remove_file(path: pathlib.Path | str, **kwargs)

Remove a file from the collection.

This method removes a file from the collection. It takes a file path as an argument and removes the file from the collection. It then reprocesses the files in the collection to update the total size, total number of files, and total size of each extension.

Note

This method does not delete the file from the file system. It only removes the file from the collection, and only if the file is in the collection. If the file is not in the collection, this method will raise a KeyError. After removing the file, the collection will be reprocessed to update the total size, total number of files, and total size of each extension.

Parameters:

path (Union[Path, str]) – The file path to remove.
**kwargs – Additional keyword arguments.

Raises:

KeyError – If the file is not in the collection.

Returns:

None

pic_scanner.gui.models.windows.main.blueprint.columns.get_image_data(file_or_bytes: str | bytes, maxsize: Tuple[int, int] = (1200, 850)) → bytes

Get image data from a file or a bytes object.

This function opens an image file or a bytes object, resizes it to fit within the given maximum size, and returns the image data in PNG format as bytes.

Parameters:

file_or_bytes (Union[str, bytes]) – The path to the image file or a bytes object containing the image data.
maxsize (Tuple[int, int], optional) – The maximum size of the image as a (width, height) tuple. Default is (1200, 850).

Returns:

The image data as a byte-string object in PNG format.

Return type:

bytes

Raises:

FileNotFoundError – If the specified file does not exist.
OSError – If the file cannot be opened and identified as an image file.
ValueError – If the input bytes object cannot be decoded into an image.

pic_scanner.gui.models.windows.main.blueprint.columns.flag_lock(instance, flag_name)

Context manager to set and unset a private flag attribute in an instance.

This context manager ensures that a specified private flag attribute in the given instance is set to True when entering the context and reset to False upon exiting the context. This is useful for indicating that an operation is in progress within a specific scope.

Parameters:

instance (object) – The instance containing the private flag attribute.
flag_name (str) – The name of the flag attribute (without leading underscore).

Raises:

AttributeError – If the instance does not have the specified private flag attribute.

Example usage:: handler = OperationHandler() with flag_lock(handler, ‘flag’):

# Perform some operation pass

This will automatically set handler._flag to True within the context and reset it to False when exiting the context.

class pic_scanner.gui.models.windows.main.blueprint.columns.ButtonSchematic(text: str, auto_build=False, key: str = None, create_disabled=False, create_hidden=False, skip_enforcing_unique_keys=False, key_factory: pic_scanner.gui.models.element_bases.element_key.factories.GUIElementKeyFactory = None, **kwargs)

Bases: pic_scanner.log_engine.Loggable

A metaclass to enhance classes with logging capabilities. Classes that inherit from ‘Loggable’ can instantly access a logger without manually setting it up. This logger is derived from a parent logger, ensuring consistent logging behavior and hierarchy.

Parameters:

text (str)
key (str)
key_factory (pic_scanner.gui.models.element_bases.element_key.factories.GUIElementKeyFactory)

- log_device: The logger device associated with the instance of the class.

instances

built_instances

DEFAULT_SUFFIX = 'button'

suffix

classmethod has_key(key: str, case_sensitive=False, return_instance=False) → bool | ButtonSchematic | None

Checks if the class instances dictionary contains the provided key with optional case sensitivity and instance return.

Parameters:

key (str) – The key to check in the ButtonSchematic.instances dictionary.
case_sensitive (bool) – Whether the key comparison should be case-sensitive. Default is False.
return_instance (bool) – Whether to return the instance corresponding to the key. Default is False.

Returns:

If return_instance is False: True if the key is present in the instances dictionary, False otherwise.
If return_instance is True: The instance corresponding to the key, or None if the key is not found.

Return type:

Union[bool, ‘ButtonSchematic’, None]

Examples

>>> ButtonSchematic.has_key('MY_BUTTON')
False

>>> ButtonSchematic.has_key('MY_BUTTON', case_sensitive=True)
True

>>> ButtonSchematic.has_key('MY_BUTTON', return_instance=True)
None

>>> ButtonSchematic.has_key('MY_BUTTON', case_sensitive=True, return_instance=True)
<ButtonSchematic object at 0x000001>

classmethod get_instance(key: str, default=None, case_sensitive=False) → 'ButtonSchematic' or None

Returns an instance from the class instances dictionary based on the provided key.

Parameters:

key (str) – The key to look up in the ButtonSchematic.instances dictionary.
default – The default value to return if the key is not found. Default is None.
case_sensitive (bool) – Whether the key lookup should be case-sensitive. Default is False.

Returns:

The instance corresponding to the key, or the default value if the key is not found.

Return type:

‘ButtonSchematic’ or None

Examples

>>> ButtonSchematic.get_instance('MY_BUTTON')
None

>>> ButtonSchematic.get_instance('MY_BUTTON', default='DEFAULT')
'DEFAULT'

>>> ButtonSchematic.get_instance('MY_BUTTON', default='DEFAULT', case_sensitive=True)
None

classmethod check_key(key: str, case_sensitive=False) → bool

Check if the key is in the ButtonSchematic.instances dictionary.

Parameters:

key (str) – The key to check in the ButtonSchematics.instances dictionary.
case_sensitive (bool) – Whether the key comparison should be case-sensitive. Default is False.

Returns:

True if the key is in the instances dictionary, False otherwise.

Return type:

bool

Examples

>>> ButtonSchematic.check_key('MY_BUTTON')
False

>>> ButtonSchematic.check_key('MY_BUTTON', case_sensitive=True)
True

build()

Build the button.

Building the button will create the button object and store it in the ButtonSchematic.instances dictionary.

Returns:: None

disable()

Disables the button.

Returns:: None

enable()

Enables the button.

Returns:: None

hide()

Hides the button.

Returns:: None

unhide()

Unhides the button.

Returns:: None

update(**kwargs)

Updates the button.

Returns:: None

property auto_build

Whether the button should be built automatically.

Returns:: True if the button should be built automatically, False otherwise.
Return type:: bool

Examples

>>> button = ButtonSchematic('My Button')
>>> button.auto_build
False

property built

Whether the button has been built.

Returns:: True if the button has been built, False otherwise.
Return type:: bool

property button: Button or None

The PySimpleGUI button object.

Return type:: Button or None

property create_disabled: bool

Whether the button should be created in a disabled state.

Returns:: True if the button should be created in a disabled state, False otherwise.
Return type:: bool

property create_hidden

Whether the button should be created in a hidden state.

Returns:: True if the button should be created in a hidden state, False otherwise.
Return type:: bool

property disabled

Whether the button is disabled.

Returns:: True if the button is disabled, False otherwise.
Return type:: bool

property enabled

Whether the button is enabled.

Returns:: True if the button is enabled, False otherwise.
Return type:: bool

property enforce_unique_keys

Whether to enforce unique keys for buttons.

Returns:: True if unique keys are enforced, False otherwise.
Return type:: bool

property hidden

property key

The key for the button.

Returns:: The key for the button.
Return type:: str

property state

Returns a `Box` object containing the state of the button, including whether it is enabled

and visible.

Returns:: A Box object with the button’s state attributes.
Return type:: Box

Examples

>>> button = ButtonSchematic('My Button')
>>> button.state
{'enabled': False, 'visible': False}

property text: str

The text for display on the button.

Returns:: The text for the button.
Return type:: str

property visible

Whether the button is visible.

Returns:: True if the button is visible, False otherwise.
Return type:: bool

class pic_scanner.gui.models.windows.main.blueprint.columns.ButtonFactory(window_name: str, default_auto_build=False, default_size=None, default_hidden=False, default_disabled=False, key_factory=None)

Bases: pic_scanner.gui.models.element_bases.button.Loggable

A class to create ButtonSchematic instances.

Properties:

instances (dict):: A dictionary of instances of the ButtonFactory.

Parameters:: window_name (str)

__new__()

Create a new instance of the ButtonFactory if one does not already exist.

Parameters:: window_name (str)

__init__()

Initialize the ButtonFactory.

Parameters:: window_name (str)

create_button -> ButtonSchematic: Create a ButtonSchematic with the specified parameters, falling back to factory defaults where necessary.

instances

create_button(text: str, auto_build: bool = None, size: tuple = None, hidden: bool = None, disabled: bool = None, key: str = None)

Create a ButtonSchematic with the specified parameters, falling back to factory defaults where necessary.

Parameters:

text (str) – The text for the button.
auto_build (bool) – Whether the button should be built automatically.
size (tuple) – The size of the button.
hidden (bool) – Whether the button should be hidden.
disabled (bool) – Whether the button should be disabled.
key (str) – The key for the button.

Returns:

The ButtonSchematic instance.

Return type:

ButtonSchematic

class pic_scanner.gui.models.windows.main.blueprint.columns.GUIElementKeyFactory(default_prefix=None, default_suffix=None, default_replacement_char='_', default_part_delimiter='_', default_all_upper=True, default_replace_spaces=True, skip_sample=True)

Bases: pic_scanner.gui.models.element_bases.element_key.Loggable

A factory class to create GUIElementKey objects with predefined configurations.

create_key(key: str, enable_prefix: bool = False, enable_suffix: bool = False, prefix: str = None, suffix: str = None, replace_spaces: bool = None, replacement_char: str = None, part_delimiter: str = None, all_upper: bool = None) → pic_scanner.gui.models.element_bases.element_key.GUIElementKey

Create a GUIElementKey with the specified parameters, falling back to factory defaults where necessary.

Parameters:

key (str) – The base key string.
enable_prefix (bool) – Whether to enable the prefix.
enable_suffix (bool) – Whether to enable the suffix.
prefix (str) – The prefix to use. Defaults to the factory default.
suffix (str) – The suffix to use. Defaults to the factory default.
replace_spaces (bool) – Whether to replace spaces in the key.
replacement_char (str) – The character to replace spaces with. Defaults to the factory default.
part_delimiter (str) – The delimiter for the key parts. Defaults to the factory default.
all_upper (bool) – Whether to convert the key to all upper case. Defaults to the factory default.

Returns:

` The configured GUI element key.

Return type:

GUIElementKey

pic_scanner.gui.models.windows.main.blueprint.columns.gui_file_collection = None

class pic_scanner.gui.models.windows.main.blueprint.columns.LeftColumn(file_collection: pic_scanner.helpers.filesystem.classes.FileCollection, **kwargs)

Bases: pic_scanner.gui.models.element_bases.column.Column

A class that represents the left column of the main window.

Properties:

file_collection (FileCollection):: The collection of files.
file_list_box (psg.Listbox):: The listbox displaying the file names.
file_names (list[str]):: The list of file names.
next_button (psg.Button):: The button to go to the next file.
file_num_display_elem (psg.Text):: The element displaying the current file number.
prev_button (psg.Button):: The button to go to the previous file.
remove_button (psg.Button):: The button to remove the current image.

Parameters:: file_collection (pic_scanner.helpers.filesystem.classes.FileCollection)

instances = []

property button_factory

Gets the button factory.

Returns:: The button factory.
Return type:: ButtonFactory

property file_collection

Gets the file collection.

Returns:: The collection of files.
Return type:: FileCollection

property file_list_box

Gets the file list box.

Returns:: The listbox displaying the file names.
Return type:: psg.Listbox

property file_names

Gets the file names.

Returns:: The list of file names.
Return type:: list[str]

property next_button

Gets the next button.

Returns:: The button to go to the next file.
Return type:: psg.Button

property file_num_display_elem

Gets the file number display element.

Returns:: The element displaying the current file number.
Return type:: psg.Text

property prev_button

Gets the previous button.

Returns:: The button to go to the previous file.
Return type:: psg.Button

property remove_button

Gets the remove button.

Returns:: The button to remove the current image.
Return type:: psg.Button

build()

Builds the left column layout.

Returns:: The column layout.
Return type:: psg.Column

class pic_scanner.gui.models.windows.main.blueprint.columns.FileColumn(file_path, **kwargs)

Bases: pic_scanner.gui.models.element_bases.column.Column

A class for building a PySimpleGUI Column.

This class is used to build a PySimpleGUI Column. It is a subclass of the AutoBuildMeta metaclass.

Properties:

auto_build (bool):: A boolean value that determines whether the class should automatically build itself when instantiated. This is set to False by default. This property is read-only.
building (bool):: A boolean value that determines whether the class is currently building itself. This is set to False by default.
column (psg.Column):: The PySimpleGUI Column object. This is built from the layout, and will only have a value if the class is built.
column_key (str):: The key for the column. This is used to identify the column in the layout. It is set to None by default, and after instantiation it is frozen and cannot be changed.
is_built (bool):: A boolean value that determines whether the class has been built.
layout (list):: A list of elements that make up the layout of the class. This is used to build the column, and is set to an empty list by default.

property building: bool

Returns the value of the building attribute.

The building attribute is a boolean value that determines whether the class is currently building itself.

Returns:: The value of the building attribute.
Return type:: bool

property changing_image: bool

Return type:: bool

property file_name_display_elem: pic_scanner.gui.models.element_bases.column.psg.Text

Return type:: pic_scanner.gui.models.element_bases.column.psg.Text

property file_path: pathlib.Path

A property that returns the file path.

Return type:: Path

property gui_file_collection

property image_elem: pic_scanner.gui.models.element_bases.column.psg.Image

A property that returns the image element.

Returns:: The image element.
Return type:: pic_scanner.gui.models.element_bases.column.psg.Image

build() → pic_scanner.gui.models.element_bases.column.psg.Column

Builds the column.

This method builds the column by creating the layout and column elements and setting the is_built ` attribute to `True.

Returns:: The column.
Return type:: pic_scanner.gui.models.element_bases.column.psg.Column

change_image(new_path: pathlib.Path | str | int) → None

Changes the image displayed in the column.

This method changes the image displayed in the column to the image located at the path and updates the file name display element to show the new file name.

Parameters:: new_path (Path) – The new path to the image.
Return type:: None