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

Subpackages

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

Attributes

`PARENT_LOGGER`
`MOD_LOGGER`
`BUTTON_FACTORY`

Classes

`FileCollection`	A class for managing a collection of files.
`LeftColumn`	A class that represents the left column of the main window.
`FileColumn`	A class for building a PySimpleGUI Column.
`BaseBlueprint`	A base class for building blueprints.
`GUIFileCollection`	A class to manage a collection of files with a cursor to navigate through them.
`ButtonFactory`	A class to create ButtonSchematic instances.
`BluePrint`	A base class for building blueprints.

Functions

flag_lock(instance, flag_name)

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

Package Contents

pic_scanner.gui.models.windows.main.blueprint.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.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

class pic_scanner.gui.models.windows.main.blueprint.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.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

class pic_scanner.gui.models.windows.main.blueprint.BaseBlueprint(auto_build: bool = False)

A base class for building blueprints.

This class is used to create blueprints for building GUI elements. A blueprint is a set of instructions that are used to build a GUI element.

Properties:

auto_build (bool):
A boolean value that determines whether the class should automatically build itself when instantiated.

building (bool):
A boolean value that determines whether the class is currently building itself.

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.

Parameters:: auto_build (bool)

build(): An abstract method that builds the class.

property auto_build

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.

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

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

building()

Deletes the building attribute.

This method sets the building attribute to False.

Returns:: None

property is_built

Returns the value of the `is_built` attribute.

The is_built attribute is a boolean value that determines whether the class has been built.

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

property layout

Returns the value of the `layout` attribute.

The layout attribute is a list of elements that make up the layout of the class.

Returns:: The value of the layout attribute.
Return type:: list

abstract build()

An abstract method that builds the class.

This method is called to build the class by creating and must be implemented by subclasses.

Returns:: None

class pic_scanner.gui.models.windows.main.blueprint.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.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

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

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

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

class pic_scanner.gui.models.windows.main.blueprint.BluePrint(file_collection: pic_scanner.helpers.filesystem.classes.FileCollection, pre_built_left_column=None, pre_built_file_column=None, **kwargs)

Bases: pic_scanner.gui.models.element_bases.blueprint.BaseBlueprint, pic_scanner.log_engine.Loggable

A base class for building blueprints.

This class is used to create blueprints for building GUI elements. A blueprint is a set of instructions that are used to build a GUI element.

Properties:

auto_build (bool):
A boolean value that determines whether the class should automatically build itself when instantiated.

building (bool):
A boolean value that determines whether the class is currently building itself.

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.

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

build(): An abstract method that builds the class.

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

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 button_factory

property file_collection

property file_collection_cursor

property file_column

A property that returns the file column.

The file column is the column that displays the image in the GUI representation of the blueprint. This is the right column in the blueprint layout. This property is a RestrictedSetter, and can only be set to an instance of FileColumn. The initial value is None.

Returns:: The file column.
Return type:: FileColumn

property left_column

A property that returns the left column.

Returns:: The left column.
Return type:: LeftColumn

build()

Build the blueprint layout.

Returns:: The layout of the blueprint.
Return type:: list

change_image(new_image)

Change the image in the file column.

This method changes the image in the image element of the file column to the new image provided. The new image must be a path to an image file. This method is used to change the image displayed in the GUI when the user navigates through the images in the file collection. This method is called by the blueprint controller when the user changes the image.

Parameters::

new_image:: The new image to display in the file column.

Returns:: None

current_image()

Get the current image.

This method returns the path to the current image in the file column. This is the image that is currently displayed in the GUI. This method is used by the blueprint controller to determine which image is currently displayed in the GUI. This method is called by the blueprint controller when the user changes the image. The blueprint controller uses this method to determine the current image. The blueprint controller then uses this information to update the current image in the GUI.

Returns:: The path to the current image.
Return type:: str

next_image()

Get the next image.

This method moves the cursor to the next image in the file collection and returns the path to that image. This method is used by the blueprint controller to move the cursor to the next image in the file collection. This method is called by the blueprint controller when the user clicks the ‘Next’ button in the GUI. The blueprint controller uses this method to move the cursor to the next image in the file collection. The blueprint controller then uses this information to update the current image in the GUI.

Returns:: The path to the next image.
Return type:: str

update_image()