data

The data module in aplustools is a versatile component that primarily focuses on simplifying the management and handling of various data-related tasks in your applications. A key function in this module is the install_dependencies method, which ensures that essential libraries and packages are installed, streamlining the setup process for the module's comprehensive features. This functionality is particularly beneficial for automatically setting up the environment, allowing you to utilize the module's capabilities without manual configuration hassles. Whether you're dealing with database interactions, data generation, or other data-centric processes, this module equips you with the necessary tools to efficiently manage these tasks.

database

The database module provides a simplified interface for interacting with databases. It encapsulates database connections, table creation, data insertion, and data retrieval into a convenient object-oriented interface.

Classes

DBManager

DBManager serves as an interface for managing SQLite databases.

Methods

• __init__(self, path: str): Initializes a DBManager instance by connecting to the SQLite database specified by the path.
• create_table(self, table_name: str, columns: list): Creates a table with the specified table_name and columns if it doesn't already exist.
• update_info(self, info: list, table: str, columns: list): Inserts a new row of info into the specified table using the specified columns. The length of info must match the number of columns.
• get_info(self, table: str, columns: list) -> list: Retrieves data from the specified table and columns, returning the results as a list of tuples.
• close(self): Commits any pending transactions and closes the database connection.

Usage

The following example demonstrates how to use the DBManager class to interact with an SQLite database:

from aplustools.data.database import DBManager

# Create a new DBManager instance, connecting to my_db.db
my_db = DBManager("./my_db.db")

# Create a new table named my_table with three columns
my_db.create_table("my_table", ["column1", "column2", "column3"])

# Insert a new row of data into my_table
my_db.update_info(["info1", "info3"], "my_table", ["column1", "column2"])

# Retrieve and print data from my_table
print(my_db.get_info("my_table", ["column3"]))

# Close the database connection
my_db.close()

In this example:

1. A DBManager instance named my_db is created, connecting to an SQLite database file named my_db.db.
2. A new table named my_table is created with three columns: column1, column2, and column3.
3. A new row of data is inserted into my_table, with info1 and info3 populating column1 and column2, respectively.
4. Data is retrieved from my_table, specifically from column3, and printed to the console.
5. The database connection is closed using the close method.

faker

This module provides a convenient way to generate test data for various fields such as names, emails, passwords, phone numbers, addresses, and birth dates. It uses randomized selections to create plausible yet fictitious data points.

Classes

Identity

A dataclass representing a user's identity with multiple attributes.

Attributes

• name: User's first name.
• last_name: User's last name.
• email: User's email address.
• password: User's password.
• phone_number: User's phone number.
• address: User's physical address.
• birth_date: User's birth date.

TestDataGenerator

A class designed for generating random test data.

Methods

• generate_random_name(): Generates a random name combining a first name and a last name.
• generate_random_email(): Creates a random email address.
• generate_random_password(length=10): Generates a random password of a specified length.
• generate_random_phone_number(): Creates a random phone number in a common format.
• generate_random_address(): Generates a random physical address.
• generate_random_birth_date(): Creates a random birth date.
• generate_random_identity(): Compiles a complete identity using all the above methods.
• insert_test_data(num_accounts=10, num_events=5): Inserts a specified number of test accounts and events into a system (currently placeholder).

Usage

The following example demonstrates how to use the TestDataGenerator class to generate random test data for different purposes:

from aplustools.data.faker import TestDataGenerator

# Create an instance of TestDataGenerator
test_data = TestDataGenerator()

# Generate a random identity
random_identity = test_data.generate_random_identity()
print(f"Random Identity: {random_identity}")

# Generate individual pieces of data
print(f"Random Name: {test_data.generate_random_name()}")
print(f"Random Email: {test_data.generate_random_email()}")
print(f"Random Password: {test_data.generate_random_password()}")
print(f"Random Phone Number: {test_data.generate_random_phone_number()}")
print(f"Random Address: {test_data.generate_random_address()}")
print(f"Random Birth Date: {test_data.generate_random_birth_date()}")

imagetools

This advanced module is designed for extensive image manipulation, handling both offline and online images. It supports various operations such as downloading, processing, transforming, and saving images.

Classes

ImageManager

A versatile manager for handling multiple image objects.

Methods

• init(base_location: Optional[str], use_async: bool): Sets up the Image Manager with options for storage location and asynchronous operations.
• add_image(image_class, ★args, ★★kwargs) -> int: Adds an image to the manager, returning its index.
• remove_image(index: int): Removes an image based on its index.
• **execute_func(index: int, function, *args, kwargs): Executes a function on a specific image.
• Other methods for bulk operations on images, asynchronous additions, and removals.

OfflineImage

Handles image operations for locally stored or byte-based images.

Methods

• init(data: Optional[Union[str, bytes]], path: Optional[str], _use_async: bool, base_location: Optional[str], original_name: Optional[str]): Initializes with either raw data or a file path.
• load_image_from_data(): Converts stored data into a Pillow image object.
• save_image_to_disk(file_path: Optional[str]): Saves the current image to disk.
• resize_image(new_size: Tuple[int, int], resample): Resizes the image to the given size.
• rotate_image(degrees: float, expand: bool): Rotates the image by the specified degree.
• crop_image(crop_rectangle: Tuple[int, int, int, int]): Crops the image.
• convert_to_grayscale(): Converts the image to grayscale.
• apply_filter(filter_type): Applies a specified filter to the image.
• And more, including saving in different formats, base64 conversions, etc.

OnlineImage

Extends OfflineImage with functionalities for handling web-based images.

Methods

• init(current_url: Optional[str], base_location: str, one_time: bool, _use_async: bool): Initialized with an online image URL.
• download_image(): Downloads the image from the specified URL.
• download_logo_image(): Specific method for downloading logo images.

SVGCompatibleImage

Specialized for handling SVG images and converting them to raster formats.

Methods

• init(file_path_or_url, resolution: Optional[int], output_size: Optional[Tuple[int, int]], magick_path: Optional[str], _use_async: bool, base_location: Optional[str], keep_online_svg: bool): Handles SVG images, offering conversion and manipulation options.
• load_image(): Loads the image, with special handling for SVG files.
• _convert_svg_to_raster(): Converts SVG to a raster format, such as PNG.
• Additional methods specific to SVG handling.

Usage

The module can be used to manage a variety of image processing tasks, from simple resizing and rotation to complex operations involving online image retrieval and SVG handling. Users can add images to the ImageManager, apply transformations, and save them to disk. Each subclass (OfflineImage, OnlineImage, SVGCompatibleImage) comes with specific methods catering to different image formats and sources.

from aplustools.data.imagetools import ImageManager, OfflineImage, OnlineImage, SVGCompatibleImage
import os

# Initialize ImageManager
image_manager = ImageManager(base_location="./images")

# Adding an online image
image_manager.add_image(OnlineImage, current_url="http://example.com/image.jpg")

# Adding an offline image
image_manager.add_image(OfflineImage, path="local_image.jpg")

# Manipulating images
image_manager.execute_func(0, "resize_image", new_size=(100, 100))  # Resize first image
image_manager.execute_func(1, "rotate_image", degrees=45)            # Rotate second image

# Saving images to disk
image_manager.execute_func(0, "save_image_to_disk", file_path="resized_image.jpg")
image_manager.execute_func(1, "save_image_to_disk", file_path="rotated_image.jpg")

# Handling SVG images
svg_image_processor = SVGCompatibleImage("image.svg", resolution=300, output_size=(667, 800))
svg_image_processor.save_image_to_disk(file_path="converted_image.png")

advanced_imagetools Module

This module enhances image manipulation capabilities using OpenCV, offering sophisticated image processing, transformation, and saving functionalities.

Classes

ImageManager

Manages a collection of image objects, with both synchronous and asynchronous operations.

Methods

• init(base_location: Optional[str], use_async: bool): Sets up the Image Manager, specifying storage location and asynchronous operation mode.
• add_image(image_class, ★args, ★★kwargs) -> int: Adds a new image to the manager.
• remove_image(index: int): Removes an image by its index.
• **execute_func(index: int, function, *args, kwargs): Executes a specific function on an image.
• Additional methods for bulk additions/removals and asynchronous handling.

OfflineImage

Focused on handling local or byte-based images with advanced transformations.

Methods

• init(data: Optional[Union[str, bytes]], path: Optional[str], _use_async: bool, base_location: Optional[str], original_name: Optional[str]): Initializes with data or file path.
• load_image_from_data(): Loads the image data into an OpenCV image.
• resize_image(new_size: Tuple[int, int]): Resizes the image.
• rotate_image(degrees: float): Rotates the image by a given angle.
• crop_image(crop_rectangle: Tuple[int, int, int, int]): Crops the image.
• update_image_data(img): Updates the stored image data after transformation.
• save_image_to_disk(file_path: Optional[str]): Saves the image to the specified file path.
• convert_to_grayscale(): Converts the image to grayscale.
• apply_blur(ksize: Tuple[int, int]): Applies Gaussian blur to the image.
• Other methods including custom resize operations.

OnlineImage

Extends OfflineImage for online image handling.

Methods

• init(current_url: Optional[str], base_location: str, one_time: bool, _use_async: bool): Initializes with an online image URL.
• download_image(): Downloads an image from a given URL.

SVGCompatibleImage

Handles SVG images, allowing for conversion to raster images and modifications.

Methods

• init(file_path_or_url, resolution: Optional[int], output_size: Optional[Tuple[int, int]], magick_path: Optional[str], _use_async: bool, base_location: Optional[str], keep_online_svg: bool): Initializes with file path or URL and other parameters for handling SVG files.
• load_image(): Loads SVG and converts it to a raster format.
• Additional methods for SVG specific processing.

Utility Functions

• reduce_color_depth(image: np.ndarray, bits_per_channel: int): Reduces color depth of the image.
• remove_icc_profile(image_path: str, image_output_path: str): Removes the ICC profile from the image.
• process_and_save_as_heic(image_path: str, output_dir_path: str): Processes and saves an image as HEIC format.

Usage

This module is suitable for more advanced image processing tasks that require OpenCV's functionality. It allows for sophisticated operations such as color depth reduction, image format conversion, and handling of different image formats like HEIC and SVG.

from aplustools.data.advanced_imagetools import ImageManager, OfflineImage, OnlineImage, SVGCompatibleImage, process_and_save_as_heic

# Initialize ImageManager
image_manager = ImageManager(base_location="./images", use_async=True)

# Add an online image to the manager
image_manager.add_image(OnlineImage, current_url="http://example.com/image.jpg", one_time=True)

# Add an offline image to the manager
image_manager.add_image(OfflineImage, path="local_image.jpg")

# Example of processing an offline image
offline_image = OfflineImage(data=base64_image_str)  # Assuming 'base64_image_str' is defined
offline_image.resize_image_custom((800, 600), cv2.INTER_LANCZOS4)
offline_image.rotate_image(45)
offline_image.crop_image((50, 50, 750, 550))
offline_image.convert_to_grayscale()
offline_image.apply_blur((5, 5))

# Save the processed image to disk
offline_image.save_image_to_disk("./processed_image.png")

# Example of using SVGCompatibleImage
svg_image_processor = SVGCompatibleImage("https://example.com/image.svg", 300, (667, 800), keep_online_svg=True)
svg_image_processor.save_image_to_disk("./converted_image.png")

# Process and save an image as HEIC format
process_and_save_as_heic("./source_image.jpg", "./output_directory")

# Perform operations on images managed by ImageManager
image_manager.execute_func(0, "convert_to_grayscale")  # Apply grayscale conversion to the first image
image_manager.execute_func(1, "apply_blur", ksize=(5, 5))  # Apply blur to the second image

# Save changes made to images in ImageManager
image_manager.execute_func(0, "save_image_to_disk", file_path="./images/first_image.png")
image_manager.execute_func(1, "save_image_to_disk", file_path="./images/second_image.png")

updaters

This module provides tools for managing software updates and version comparisons, particularly useful for applications requiring automated updates from a GitHub repository.

Classes

VersionNumber

Handles version comparison operations using semantic versioning.

Methods

• init(number: str): Initializes with a version number string.
• Comparison operations: __eq__, __ne__, __lt__, __le__, __gt__, __ge__ for comparing with other version numbers.

GithubUpdater

Manages the update process by connecting to a GitHub repository and handling update operations.

Methods

• init(author: str, repo_name: str, version: Literal["exe", "py"]): Initializes with details of the GitHub repository.
• get_latest_release_title_version() -> Union[None, str]: Retrieves the latest release version from the GitHub repository.
• get_latest_tag_version() -> Union[None, str]: Retrieves the latest tag version from the GitHub repository.
• receive_update_status() -> UpdateStatusGenerator: Returns a generator for receiving update status.
• update(path: str, zip_path: str, repo_version: str, implementation: Literal["gui", "cmd", "none"], host: str, port: int, non_blocking: bool, wait_for_connection: bool) -> Union[Tuple[bool, None, int], Tuple[bool, Exception, int], threading.Thread]: Initiates the update process.

Utility Functions

• local_test(): Demonstrates how to use the GithubUpdater class to perform an update.

Usage

This module is particularly useful for applications that require automated updates and version management. Using GithubUpdater, applications can check for the latest versions on GitHub, download updates, and apply them. The VersionNumber class offers a convenient way to handle and compare semantic version numbers.

Example

# Create an instance of GithubUpdater
updater = GithubUpdater("YourGitHubUsername", "YourRepositoryName", "py")

# Check for the latest version
latest_version = updater.get_latest_tag_version()

# Compare with the current version
current_version = "1.0.0"  # Example current version
if VersionNumber(latest_version) > current_version:
    # Perform the update
    print("Update available. Starting update process.")
    update_thread = updater.update("/path/to/update", "/path/to/zip", latest_version, "none", "localhost", 5000, True, True)
    update_thread.start()
    for progress in updater.receive_update_status():
        print(f"Update progress: {progress}%")
    update_thread.join()
else:
    print("No update necessary.")

In this example, the GithubUpdater checks for the latest version on a specified GitHub repository. If the latest version is greater than the current version, it starts the update process, downloads the update, and reports the progress.