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. 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.

Direct Functions

• truedivmod(__x: int | float, __y: int | float): Always returns an even result, even if floats are used.
• encode_float(floating_point: float) -> bytes: Encodes a floating point number.
• decode_float(bytes_like: bytes) -> float: Decodes a floating point number encoded by encode_float.
• encode_int(num: int, overwrite_signed: bool = False) -> bytes: Encodes a general integer.
• encode_positive_int(num: int) -> bytes: Encodes an always positive integer.
• encode_possible_negative_int(num: int) -> bytes: Encode a possibly negative integer.
• decode_int(bytes_like: bytes, signed: bool = False) -> int: Decode a general integer.
• decode_positive_int(bytes_like: bytes) -> int: Decode an always positive integer.
• decode_possible_negative_int(bytes_like: bytes) -> int: Decode a possibly negative integer.
• encode(to_encode: _Union[int, str]) -> bytes: Encode multiple datatypes.
• decode(bytes_like: bytes, return_int: bool = False) -> _Union[int, str]: Decode multiple datatypes.
• bits(bytes_like: _typing.Union[bytes, bytearray], return_str: bool = False) -> _Union[list, str]: Get the raw bit representation of any byteslike object.
• nice_bits(bytes_like: _typing.Union[bytes, bytearray], spaced: bool = False, wrap_count: int = 0, to_chars: bool = False, edge_space: bool = False) -> str: Like bits but with nice extra features.
• minmax(min_val, max_val, to_reduce): Gets the min max of a value.
• isEven(x: _Union[int, float, str]) -> bool: Performs an efficient isEven calculation on various datatypes.
• isOdd(x: _Union[int, float, str]) -> bool: Performs an efficient isOdd calculation on various datatypes.
• isEvenInt(x: int) -> bool: Performs an efficient isEven calulation on integers.
• isOddInt(x: int) -> bool: Performs an efficient isOdd calulation on integers.
• isEvenFloat(x: _Union[float, str]) -> _typing.Tuple[bool, bool]: Performs an isEven check on both parts of a floating point number.
• isOddFloat(x: _Union[float, str]) -> _typing.Tuple[bool, bool]: Performs an isOdd check on both parts of a floating point number.
• isEvenString(x: str) -> bool: Performs an efficient isEven caluclation on a string.
• isOddString(x: str) -> bool: Performs an efficient isOdd caluclation on a string.
• nice_number(number: int, seperator: str = "."): Makes large numbers easier to understand at a glance. [DEPRECATED;SLOW]
• nn(number: int, seperator: str = "."): Makes large numbers easier to understand at a glance. Uses the :, formatter to get fast speeds.
• local_nn(number: int): Makes larger numbers easier to understand at a glance using the local number formatting. Uses the locale module.
• what_func(func: _typing.Callable, type_names: bool = False, return_def: bool = False) -> _typing.Optional[str]: Makes it easy to understand function parameters from the commandline.
• what_class(cls: _typing.Type, type_names: bool = False, return_def: bool = False) -> _typing.Optional[str]: Makes it easy to understand class parameters from the commandline.
• bytes_to_human_readable_binary_iec(size: int) -> str: Formats a bit size to the iec format.
• bytes_to_human_readable_decimal_si(size: int) -> str: Formats a bit size to the si format.
• bits_to_human_readable(size: float) -> str: Convert bits to a human-readable string using SI units.
• iterbytes(bytes_like: _typing.Union[bytes, bytearray]): Iterates over a byteslike object. It iterates like normal and re-encodes the chars.
• set_bits(bytes_like: _typing.Union[bytes, bytearray], start_position: int, bits: str, byte_order: _typing.Literal["big", "little"] = "big", return_bytearray: bool = False, auto_expand: bool = False): Sets the bits at any position in a byteslike object.
• bytes_length(data: _typing.Union[int, float, str]) -> int: Returns the byteslength of various datatypes.
• bit_length(data: _typing.Union[int, float, str]) -> int: Returns the bitlength of various datatypes.
• Bits: Makes it easy to work with bits as it externally shows the inputted byteslike object, but the string represenation is in bits. [UNDER CONSTRUCTION]
• UniversalBits: Takes in various datatypes, converts them to bytes and does the same like Bits, but externally it shows the inputted datatype instead of a byteslike object. [UNDER CONSTRUCTION]
• unnest_iterable(iterable, max_depth: int = 4): Unnests an iterable in order using recursion.
• cutoff_iterable(iterable: _Union[list, tuple, dict, set], max_elements_start: int = 4, max_elements_end: int = 0, show_hidden_elements_num: bool = False, return_lst: bool = False): Makes it easy to view long lists.
• cutoff_string(string: str, max_chars_start: int = 4, max_chars_end: int = 0, show_hidden_chars_num: bool = False): Makes it easy to view long strings.
• beautify_json(data_dict): Beautifies json (a dictionary).
• update_dict_if_absent(original_dict, new_data): Updates the original dict with the new dicts value, only if that key isn't present yet in the original.

database

--. UNDER CONSTRUCTION .--

faker_pro

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

FakerPro

A pro version of the default Faker class.

Methods

• All default Faker methods
• generate_person(): Generates a random person and returns them as a dictionary. Families are occationally generated for more divers data.
• gender_relational_name(gender: Literal["male", "female", "other"], include_last_name=False): Creates a name that fits the gender inputted.
• email_relational_name(first_name, last_name): Generates a random email that fits the name of a person.
• generate_family(family_name=None): Creates a new family and returns it as a list of normal person dictionaries.

Usage

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

from aplustools.data.faker_pro import FakerPro

# Create an instance of TestDataGenerator
fake_pro = FakerPro("en-US")

# Generate multiple random people, some of which may belong to families
print("Generating random people:")
for _ in range(10):
    person = fake_pro.generate_person()
    print(person)

# Generate a specific family
family_name = "Smith"
family = fake_pro.generate_family(family_name)
print(f"\nGenerated family {family_name}:")
for member in family:
    print(member)

# Generate gender relational names with and without last names
male_name_with_last = fake_pro.gender_relational_name('male', include_last_name=True)
female_name_without_last = fake_pro.gender_relational_name('female', include_last_name=False)
print(f"\nMale name with last name: {male_name_with_last}")
print(f"Female name without last name: {female_name_without_last}")

# Generate email relational to name
email = fake_pro.email_relational_name("John", "Doe")
print(f"\nRelational email: {email}")

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.