atomicshop 2.11.47__py3-none-any.whl → 3.10.5__py3-none-any.whl

atomicshop/basics/booleans.py

@@ -1,38 +1,35 @@
-def check_3_booleans_when_only_1_can_be_true(boolean1: tuple, boolean2: tuple, boolean3: tuple) -> None:
+def is_only_1_true_in_list(
+        booleans_list_of_tuples: list[tuple],
+        raise_if_all_false: bool = True
+) -> None:
     """
-    Example:
-        check_3_booleans_when_only_1_can_be_true(
-            (self.config['section']['default_usage'], 'default_usage'),
-            (self.config['section']['create_usage'], 'create_usage'),
-            (self.config['section']['custom_usage'], 'custom_usage'))
-    :param boolean1: tuple, (value, string name of the setting you want to print to the user to be aware of).
-    :param boolean2: tuple, (value, string name of the setting you want to print to the user to be aware of).
-    :param boolean3: tuple, (value, string name of the setting you want to print to the user to be aware of).
-    :return:
+    Check if only one boolean can be 'True' from a list of booleans
+    :param booleans_list_of_tuples: list of tuples, Structure:
+        [(value, string name of the setting you want to print to the user to be aware of), ...]
+    :param raise_if_all_false: bool, If True, exception will be raised if all booleans are False.
+    :return: None
     """
 
-    check_if_3_booleans_are_false(boolean1, boolean2, boolean3)
-    check_if_2_booleans_are_true(boolean1, boolean2)
-    check_if_2_booleans_are_true(boolean1, boolean3)
-    check_if_2_booleans_are_true(boolean2, boolean3)
+    # Filter to get all the `True` conditions and their associated names
+    true_conditions = [name for value, name in booleans_list_of_tuples if value]
 
+    # Count the number of True values
+    true_count = len(true_conditions)
 
-def check_if_3_booleans_are_false(boolean1: tuple, boolean2: tuple, boolean3: tuple):
-    if not boolean1[0] and not boolean2[0] and not boolean3[0]:
-        message = f"All the boolean settings in config ini file were set to 'False',\n" \
-                  f"You need at least one 'True':\n" \
-                  f"{boolean1[1]}={boolean1[0]}\n" \
-                  f"{boolean2[1]}={boolean2[0]}\n" \
-                  f"{boolean3[1]}={boolean3[0]}"
-        raise ValueError(message)
-
-
-def check_if_2_booleans_are_true(boolean1: tuple, boolean2: tuple) -> None:
-    if boolean1[0] and boolean2[0]:
-        message = f"Only one configuration can be 'True':\n" \
-                  f"{boolean1[1]}={boolean1[0]}\n" \
-                  f"{boolean2[1]}={boolean2[0]}\n"
-        raise ValueError(message)
+    if true_count == 1:
+        # Only one value is True, which is acceptable
+        # print(f"Only one condition is True: {true_conditions[0]}.")
+        pass
+    elif true_count > 1:
+        # More than one value is True, raise an exception
+        raise ValueError(f"Multiple conditions are True: {', '.join(true_conditions)}.")
+    elif true_count == 0 and raise_if_all_false:
+        # None of the values are True, and the user does not want to ignore this case
+        raise ValueError("No conditions are True, and raise_if_all_false is set to True.")
+    else:
+        # If no True values and no_raise_if_all_false is True, just pass silently
+        # print("No conditions are True (but raise_if_all_false is set to False).")
+        pass
 
 
 def convert_string_to_bool(string: str) -> bool:

atomicshop/basics/bytes_arrays.py

@@ -1,3 +1,7 @@
+from typing import Union
+import string
+
+
 def get_single_byte_from_byte_string(byte_string, index: int):
     """
     Function extracts single byte as byte from byte string object.
@@ -53,6 +57,30 @@ def convert_sequence_of_bytes_to_sequence_of_strings(byte_sequence: bytes) -> li
     return result
 
 
+def convert_sequence_of_bytes_to_exact_string(
+        byte_sequence: bytes,
+        add_space_between_bytes: bool = False,
+) -> str:
+    """
+    Convert sequence of bytes to exact string.
+    Example: b'\xc0\x00' -> 'c000'
+
+    :param byte_sequence: bytes, sequence of bytes.
+    :param add_space_between_bytes: bool, add space between bytes.
+        Example: b'\xc0\x00' -> 'c0 00'
+    :return: string.
+    """
+
+    # Convert to hex string and format
+    byte_list: list = []
+    for byte in byte_sequence:
+        byte_list.append(f'{byte:02x}')
+
+    result = ''.join(byte_list)
+
+    return result
+
+
 def find_position(target: bytes, file_path: str = None, file_bytes: bytes = None, chunk_size: int = None, starting_position: int = 0) -> int:
     """
     Find position of the target bytes string in the file.
@@ -155,3 +183,18 @@ def read_bytes_from_position(
         # Read the specified number of bytes.
         data = file.read(num_bytes)
     return data
+
+
+def convert_bytes_to_printable_string_only(
+        byte_sequence: Union[bytes, bytearray],
+        non_printable_character: str = '.'
+) -> str:
+    """
+    Convert bytes to printable string. If byte is not printable, replace it with 'non_printable_character'.
+    :param byte_sequence: bytes or bytearray, sequence of bytes.
+    :param non_printable_character: string, character to replace non-printable characters.
+    :return:
+    """
+
+    printable = set(string.printable)
+    return ''.join(chr(byte) if chr(byte) in printable else non_printable_character for byte in byte_sequence)

atomicshop/basics/classes.py

@@ -1,12 +1,160 @@
 import os
 import sys
 import ast
-import importlib
 from pathlib import Path
+import pkgutil
+import importlib
+import inspect
 
 from ..file_io.file_io import read_file
 
 
+"""
+Using logger in the class only once during the import of the module.
+ 
+class ParserParent:
+    # Initializing the logger in the "class variable" section will leave the instance of the logger initiated
+    # and the rest of the instances of the class will use the same logger.
+    # It is not in the "__init__" section, so it's not going to be initiated again.
+    # The name of the logger using "__name__" variable, which is the full name of the module package.
+    # Example: classes.parsers.parser_1_reference_general
+
+    # The code outside the functions will be executed during import of the module. When initializing a class
+    # in the script these lines will not be called again, only the "init" function.
+    logger = create_custom_logger()
+
+    def __init__(self, class_client_message: ClientMessage):
+        self.class_client_message: ClientMessage = class_client_message
+
+    # Usage: self.logger.info("Message")
+"""
+
+
+"""
+Using Base class for easier interfacing on subclasses.
+
+recognition/recognition_base.py:
+    from abc import abstractmethod
+    
+    
+    class Recognizer:
+        @abstractmethod
+        def recognize_vendor(self, file_path: str) -> str:
+            pass
+    
+        @abstractmethod
+        def recognize_family(self, bytes_list: list[str]]) -> str:
+            pass
+
+
+recognition/super_vendor.py:
+    from .recognition_base import Recognizer
+    
+    class SupervendorRecognizer(Recognizer):
+        def recognize_vendor(self, file_path: str) -> str:
+            classification_string: str = <Some logic to classify the SuperVendor>
+            return classification_string
+    
+        def recognize_family(self, bytes_list: list[str]]) -> str:
+            family_classification_string: str = <Some logic to classify the family of the SuperVendor>
+            return family_classification_string
+            
+
+main_script.py:
+    from . import recognition
+    from .recognition.recognition_base import Recognizer
+    
+    # Get the list of all the recognizers in the recognition package.
+    recognizers_list: list = classes.get_list_of_classes_in_module(
+        imported_package=recognition, imported_base_class=Recognizer)
+    
+    # Get the list of all the vendors from the file.
+    vendors_list: list = list()
+    for recognizer in recognizers_list:
+        recognizer_instance = recognizer()
+        vendor_name: str = recognizer_instance.recognize_vendor(file_object=file_path)
+        if vendor_name:
+            vendors_list.append((vendor_name, recognizer_instance))
+    
+    # Get the families of the vendors.
+    for vendor_name, recognizer_instance in vendors_list:
+        family_name: str = recognizer_instance.recognize_family(bytes_list=file_bytes_list)
+        print(f"Vendor: {vendor_name}, Family: {family_name}")
+"""
+
+def get_list_of_classes_in_module(
+        imported_package,
+        imported_base_class
+) -> list:
+    """
+    Function that returns a list of classes that are subclasses of the imported_base_class from the imported_package.
+
+    Example:
+        # Package structure:
+        # unpackers
+        # ├── __init__.py
+        # ├── unpacker_base.py
+        # ├── unpacker_1.py
+        # ├── unpacker_2.py
+        # ├── unpacker_3.py
+        # └── ... (other unpacker modules)
+
+        # unpacker_base.py:
+        from abc import abstractmethod
+        class Unpacker:
+            @abstractmethod
+            def unpack(self, file_path):
+                pass
+
+        # unpacker_1.py:
+        from unpackers.unpacker_base import Unpacker
+        class Unpacker1(Unpacker):
+            def unpack(self, file_path):
+                print(f"Unpacking file with Unpacker1: {file_path}")
+
+        # main_script.py:
+        # Import the base class
+        from unpackers.unpacker_base import Unpacker
+        # Import the package
+        import unpackers
+        # Get the list of classes
+        unpacker_classes = get_list_of_classes_in_module(imported_package=unpackers, imported_base_class=Unpacker)
+
+        # Initialize the classes
+        for unpacker_class in unpacker_classes:
+            unpacker_instance = unpacker_class()
+            unpacker_instance.unpack("file_path")
+        ----------------------------
+        # You can also initialize the list of classes dynamically and after that execute methods.
+        # Example:
+        unpacker_classes = get_list_of_classes_in_module(imported_package=unpackers, imported_base_class=Unpacker)
+
+        instance_list: list = []
+        for unpacker_class in unpacker_classes:
+            instance_list.append(unpacker_class())
+
+        for instance in instance_list:
+            instance.unpack("file_path")
+
+    :param imported_package:
+    :param imported_base_class:
+    :return:
+    """
+    unpacker_classes = []
+
+    # Iterate over all modules in the 'imported_package' package
+    for loader, module_name, is_pkg in pkgutil.iter_modules(imported_package.__path__):
+        # Import the module
+        module = importlib.import_module(f"{imported_package.__name__}.{module_name}")
+
+        # Inspect module members to find Unpacker subclasses
+        for name, obj in inspect.getmembers(module, inspect.isclass):
+            if issubclass(obj, imported_base_class) and obj is not imported_base_class:
+                unpacker_classes.append(obj)
+
+    return unpacker_classes
+
+
 def create_empty_class():
     """
     Function creates empty class, you can add parameters to it dynamically.

atomicshop/basics/dicts.py

@@ -24,6 +24,18 @@ def get_first_key_and_value_dict(input_dict: dict) -> dict:
     return {first_key: input_dict[first_key]}
 
 
+def get_last_added_key_value(input_dict: dict) -> dict:
+    """
+    The function will return the last added key and value in a dictionary.
+
+    :param input_dict: dict, the dictionary to get the last added key and value.
+    :return: dict, the last added key and value in the dictionary.
+    """
+
+    last_key = list(input_dict.keys())[-1]
+    return {last_key: input_dict[last_key]}
+
+
 def remove_keys(input_dict: dict, key_list: list) -> None:
     """
     The function will remove a key from dictionary without raising an exception if it doesn't exist.

atomicshop/basics/enums.py

@@ -32,10 +32,10 @@ def __comparison_usage_example(
         main folder.
 
     Usage:
-        from atomicshop.filesystem import get_file_paths_from_directory, ComparisonOperator
+        from atomicshop.filesystem import get_paths_from_directory, ComparisonOperator
 
         # Get full paths of all the 'engine_config.ini' files.
-        engine_config_path_list = get_file_paths_from_directory(
+        engine_config_path_list = get_paths_from_directory(
             directory_fullpath=some_directory_path,
             file_name_check_tuple=(config_file_name, ComparisonOperator.EQ))
     """

atomicshop/basics/exceptions.py

@@ -1,4 +1,3 @@
-# v1.0.3 - 28.03.2023 17:20
 import sys
 
 from .threads import current_thread_id
@@ -15,3 +14,8 @@ def print_exception() -> None:
     exc_type, exc_value, exc_traceback = sys.exc_info()
 
     print(f"{error_log_prefix} Thread {thread_id}: * Details: {exc_type}, {exc_value}")
+
+
+def get_exception_type_string(exception: Exception) -> str:
+    """ Get exception type string """
+    return type(exception).__name__

atomicshop/basics/list_of_classes.py

@@ -0,0 +1,29 @@
+from operator import attrgetter
+
+
+def sort_by_attributes(
+        list_instance: list,
+        attribute_list: list,
+        reverse: bool = False,
+        case_insensitive: bool = False
+):
+    """
+    Sort a list of objects by their attributes.
+
+    :param list_instance: list of objects.
+    :param attribute_list: list of attributes (strings). The sorting will be done by the attributes in the list.
+        In the appearing order in the list.
+    :param reverse: bool, sort in reverse order.
+    :param case_insensitive: bool, sorting will be case-insensitive.
+    """
+
+    for attribute in attribute_list:
+        if case_insensitive:
+            list_instance = sorted(
+                list_instance, key=lambda obj: getattr(obj, attribute).lower(), reverse=reverse
+            )
+        else:
+            list_instance = sorted(
+                list_instance, key=attrgetter(attribute), reverse=reverse
+            )
+    return list_instance

atomicshop/basics/list_of_dicts.py

@@ -1,5 +1,5 @@
 from operator import itemgetter
-from json import dumps, loads
+import json
 
 from . import dicts, strings
 
@@ -100,7 +100,13 @@ def merge_to_dict(list_of_dicts: list) -> dict:
     return result_dict
 
 
-def is_value_exist_in_key(list_of_dicts: list, key: str, value_to_match: str, prefix_suffix: bool = False) -> bool:
+def is_value_exist_in_key(
+        list_of_dicts: list,
+        key: str,
+        value_to_match: str,
+        value_case_insensitive: bool = False,
+        prefix_suffix: bool = False
+) -> bool:
     """
     The function will check if a value exists in a key in a list of dicts.
 
@@ -113,6 +119,7 @@ def is_value_exist_in_key(list_of_dicts: list, key: str, value_to_match: str, pr
     :param key: str, the key to check in each entry (dict) in the list.
     :param value_to_match: str, the value to find in the key.
         This values is a pattern, so it can be a part of the value and can contain wildcards as "*" character.
+    :param value_case_insensitive: bool, if True the value will be matched case insensitive.
     :param prefix_suffix: bool, related to how pattern of 'value_to_find' is matched against the value in the key.
         Check the 'strings.match_pattern_against_string' function for more information.
     :return: bool, True if the value exists in the key in any entry in the list of dicts, False if not.
@@ -121,7 +128,9 @@ def is_value_exist_in_key(list_of_dicts: list, key: str, value_to_match: str, pr
     for dictionary in list_of_dicts:
         try:
             # if value_to_find in dictionary.get(key, None):
-            if strings.match_pattern_against_string(value_to_match, dictionary.get(key, None), prefix_suffix):
+            if strings.match_pattern_against_string(
+                    value_to_match, dictionary.get(key, None), case_insensitive=value_case_insensitive,
+                    prefix_suffix=prefix_suffix):
                 return True
         # If the key is not present in the dict 'TypeError' will be raised, since 'None' doesn't have the 'in' operator.
         except TypeError:
@@ -141,7 +150,7 @@ def convert_to_set(list_of_dicts, sort_keys: bool = False) -> set:
     :return: set.
     """
 
-    return set(dumps(x, sort_keys=sort_keys) for x in list_of_dicts)
+    return set(json.dumps(x, sort_keys=sort_keys) for x in list_of_dicts)
 
 
 def convert_from_set(set_object: set) -> list:
@@ -152,4 +161,59 @@ def convert_from_set(set_object: set) -> list:
     :return: list of dicts.
     """
 
-    return [loads(x) for x in set_object]
+    return [json.loads(x) for x in set_object]
+
+
+def summarize_entries(list_instance: list, list_of_keys_to_remove: list = None) -> list:
+    """
+    The function will summarize entries in a list of dicts.
+
+    :param list_instance: list of dicts, the entries to summarize.
+    :param list_of_keys_to_remove: list, the keys to remove from each entry before summarizing.
+    :return: list, of the summarized entries, each entry without the keys in 'list_of_keys_to_remove',
+        including the count of the entry.
+
+    --------------------------------------
+
+    Example:
+    list_instance = [
+        {'time': '2021-08-01 00:00:00', 'name': 'name1', 'cmdline': 'cmdline1', 'domain': 'domain1'},
+        {'time': '2021-08-01 00:00:00', 'name': 'name2', 'cmdline': 'cmdline2', 'domain': 'domain2'},
+        {'time': '2021-08-01 00:00:00', 'name': 'name1', 'cmdline': 'cmdline1', 'domain': 'domain1'}
+    ]
+
+    list_of_keys_to_remove = ['time', 'cmdline']
+
+    summarize_entries(list_instance, list_of_keys_to_remove)
+
+    Output:
+    [
+        {'name': 'name1', 'domain': 'domain1', 'count': 2},
+        {'name': 'name2', 'domain': 'domain2', 'count': 1}
+    ]
+    """
+
+    summed_entries: dict = dict()
+    for entry in list_instance:
+        # Copy the entry to new dict, since we're going to remove a key.
+        line_copied = entry.copy()
+
+        # Remove the keys in the 'list_of_keys_to_remove'.
+        if list_of_keys_to_remove:
+            for key in list_of_keys_to_remove:
+                _ = line_copied.pop(key, None)
+
+        line_json_string = json.dumps(line_copied)
+        if line_json_string not in summed_entries:
+            summed_entries[line_json_string] = 1
+        else:
+            summed_entries[line_json_string] += 1
+
+    result_list: list = []
+    for json_string_record, count in summed_entries.items():
+        record = json.loads(json_string_record)
+        result_list.append(
+            {**record, 'count': count}
+        )
+
+    return result_list

atomicshop/basics/lists.py

@@ -1,3 +1,6 @@
+import copy
+
+
 def remove_duplicates(list_instance: list):
     # One of the fastest methods.
     seen = set()
@@ -109,3 +112,14 @@ def get_the_most_frequent_element_from_list(list_instance: list[str]) -> str:
     """
 
     return max(set(list_instance), key=list_instance.count)
+
+
+def copy_list_of_mutable_objects(list_instance: list) -> list:
+    """
+    This function will copy the list of mutable objects. Meaning that all the mutable objects inside will be copied
+    as well.
+    :param list_instance: list.
+    :return: list.
+    """
+
+    return copy.deepcopy(list_instance)