pydasa 0.4.7__py3-none-any.whl

pydasa/structs/tools/hashing.py

@@ -0,0 +1,53 @@
+# -*- coding: utf-8 -*-
+"""
+Module helpers.py
+===========================================
+
+Module with utility functions for handling memory allocation in the Data Structures of *PyDASA*.
+
+Module with utility functions for handling data in the maps of *PyDASA*. Specifically for Separate Chaining and Linear Probing Hash Tables.
+
+*IMPORTANT:* based on the implementations proposed by the following authors/books:
+
+    #. Algorithms, 4th Edition, Robert Sedgewick and Kevin Wayne.
+    #. Data Structure and Algorithms in Python, M.T. Goodrich, R. Tamassia, M.H. Goldwasser.
+"""
+# python native modules
+from typing import Hashable
+# import math
+
+# import global variables
+from pydasa.structs.types.generics import VLD_IOTYPE_LT
+
+
+def mad_hash(key: Hashable,
+             scale: int,
+             shift: int,
+             prime: int,
+             mcap: int) -> int:
+    """*mad_hash()* function to compress the indices of the Hash tables using the MAD (Multiply-Add-and-Divide) method.
+
+    MAD is defined as: mad_hash(y) = ((a*y + b) % p) % M, where:
+        a (scale) and b (shift) are random integers in the range [0,p-1], with a > 0
+        p (prime) is a prime number greater than M,
+        M (capacity) is the size of the table, prime
+
+    Args:
+        key (Hashable): key to calculate the index in the Hash table, Can be any native data type in Python or user-defined.
+        scale (int): line slope of the compression function.
+        shift (int): offset of the compression function.
+        prime (int): prime number much greater than the capacity of the Hash table.
+        mcap (int): size of the Hash table, it is a prime number to avoid collisions.
+
+    Returns:
+        int: the index of the element in the Hash table.
+    """
+    # TODO data should be hashable?
+    # data types are (dict, list, set, tuple)
+    if isinstance(key, VLD_IOTYPE_LT) or isinstance(key, dict):
+        key = str(key)
+    # getting the hash from the key
+    hkey = hash(key)
+    # calculating the index with the MAD compression function
+    idx = int((abs(scale * hkey + shift) % prime) % mcap)
+    return idx

pydasa/structs/tools/math.py

@@ -0,0 +1,149 @@
+# -*- coding: utf-8 -*-
+"""
+Module math.py
+===========================================
+
+Module with math functions for finding prime numbers and calculating factorials. in *PyDASA*.
+
+Module with math functions for handling data in the for Separate Chaining Hash Table.
+
+*IMPORTANT:* based on the implementations proposed by the following authors/books:
+
+    #. Algorithms, 4th Edition, Robert Sedgewick and Kevin Wayne.
+    #. Data Structure and Algorithms in Python, M.T. Goodrich, R. Tamassia, M.H. Goldwasser.
+
+*NOTE:* code contributed by Sanjit_Prasad in https://www.geeksforgeeks.org/prime-numbers/
+"""
+# python native modules
+import math
+from typing import Union, Optional
+
+
+def is_prime(n: int) -> bool:
+    """*is_prime()* checks if a number is prime or not. Original code from Sanjit_Prasad.
+
+    Args:
+        n (int): number to check if it is prime.
+
+    Returns:
+        bool: True if the number is prime, False otherwise.
+    """
+    # we asume that the number is prime
+    # Corner cases
+    # check if n is 1 or 0
+    prime = True
+    if n < 2:
+        return False
+
+    # checking if n is 2 or 3
+    if n < 4:
+        return prime
+
+    # checking if n is divisible by 2 or 3
+    if n % 2 == 0 or n % 3 == 0:
+        return False
+
+    # checking if n is divisible by 5 to to square root of n
+    for i in range(5, int(math.sqrt(n) + 1), 6):
+        if n % i == 0 or n % (i + 2) == 0:
+            return False
+    # return True if the number is prime
+    return prime
+
+
+def next_prime(n: int) -> int:
+    """*next_prime()* returns the next prime number greater than n.
+
+    Args:
+        n (int): number to check if it is prime.
+
+    Returns:
+        int: the next prime number greater than n.
+    """
+    # base case
+    if n < 2:
+        return 2
+
+    # working with the next odd number
+    prime = n
+    found = False
+
+    # Loop continuously until isPrime returns
+    while not found:
+        prime += 1
+        # True for a prime number greater than n
+        if is_prime(prime) is True:
+            found = True
+    # return the next prime number to n
+    return prime
+
+
+def previous_prime(n: int) -> int:
+    """*previous_prime()* returns the previous prime number less than n.
+
+    Args:
+        n (int): number to check if it is prime.
+
+    Returns:
+        int: the previous prime number less than n.
+    """
+    # base case
+    if n < 2:
+        return 2
+
+    # working with the next odd number
+    prime = n
+    found = False
+
+    # Loop continuously until isPrime returns
+    while not found:
+        prime -= 1
+        # True for a prime number greater than n
+        if is_prime(prime) is True:
+            found = True
+    # return the previous prime number to n
+    return prime
+
+
+def gfactorial(x: Union[int, float],
+               prec: Optional[int] = None) -> Union[int, float]:
+    """*gfactorial()* calculates the factorial of a number, including support for floats less than 1.0.
+
+        - For integers n ≥ 0: Returns n! (n factorial).
+        - For floats x: Returns Γ(x+1) (gamma function).
+
+    Args:
+        x (Union[int, float]): The number to compute the factorial for.
+        prec (Optional[int], optional): precision, or the number of decimal places to round the result to. Defaults to None.
+
+    Raises:
+        ValueError: If x is a negative integer.
+
+    Returns:
+        Union[int, float]: The factorial of x. Returns an integer for integer inputs ≥ 0, and a float for float inputs or integers < 0.
+
+    Examples:
+        >>> gfactorial(5)
+        120
+        >>> gfactorial(0)
+        1
+        >>> gfactorial(0.5)  # Equivalent to Γ(1.5) = 0.5 * Γ(0.5) = 0.5 * √Pi
+        0.8862269254527579
+        >>> gfactorial(-0.5)  # Equivalent to Γ(0.5) = √Pi
+        1.7724538509055159
+    """
+    if isinstance(x, int) and x >= 0:
+        # Standard factorial for non-negative integers
+        result = math.factorial(x)
+    elif isinstance(x, int) and x < 0:
+        # Factorial is not defined for negative integers
+        raise ValueError("Factorial is not defined for negative integers")
+    else:
+        # For floats, use the gamma function: Γ(x+1)
+        result = math.gamma(x + 1)
+
+    # Apply precision if specified
+    if prec is not None:
+        result = round(result, prec)
+
+    return result

pydasa/structs/tools/memory.py

@@ -0,0 +1,54 @@
+# -*- coding: utf-8 -*-
+"""
+Module memory.py
+===========================================
+
+Module with utility functions for handling memory allocation in the Data Structures of *PyDASA*.
+
+*IMPORTANT:* based on the implementations proposed by the following authors/books:
+
+    #. Algorithms, 4th Edition, Robert Sedgewick and Kevin Wayne.
+    #. Data Structure and Algorithms in Python, M.T. Goodrich, R. Tamassia, M.H. Goldwasser.
+"""
+# python native modules
+import sys
+from typing import Type
+
+# dataclases module handles the creation of classes with slots and fields
+import dataclasses
+
+# import global variables
+from pydasa.structs.types.generics import T
+
+
+def mem_slot(cls: Type[T]) -> Type[T]:
+    """*mem_slot()* is a decorator that converts a class into a dataclass with slots.
+
+    Args:
+        cls (Type[T]): class to convert into a dataclass with slots.
+
+    Raises:
+        TypeError: if the cls is not a class type.
+        RuntimeError: if the Python version is less than 3.10.
+
+    Returns:
+        Type[T]: A dataclass with slots.
+    """
+    # TODO check validity of this decorator
+    # TODO integrate with the dataclass decorator
+    if not isinstance(cls, type):
+        raise TypeError(f"Invalid class: {cls}, class must be a type")
+
+    # Check Python version for native slots support
+    if sys.version_info >= (3, 10):
+        # Use native slots support
+        if dataclasses.is_dataclass(cls):
+            # Already a dataclass, need to recreate with slots
+            return dataclasses.dataclass(cls, slots=True)
+        else:
+            return dataclasses.dataclass(cls, slots=True)
+    else:   # type: ignore[unreachable]
+        _msg = "mem_slot requires Python 3.10+ for native support. "
+        _msg += f"Current version: {sys.version_info.major}."
+        _msg += f"{sys.version_info.minor}"
+        raise RuntimeError(_msg)

pydasa/structs/types/functions.py

@@ -0,0 +1,131 @@
+# -*- coding: utf-8 -*-
+# FIXME old code, remove when tests are finished
+"""
+Module default.py
+===========================================
+
+Module for default global variables and comparison functions for use by all *PyDASA* and its Data Structures.
+
+*IMPORTANT:* based on the implementations proposed by the following authors/books:
+
+    #. Algorithms, 4th Edition, Robert Sedgewick and Kevin Wayne.
+    #. Data Structure and Algorithms in Python, M.T. Goodrich, R. Tamassia, M.H. Goldwasser.
+"""
+
+
+# python native modules
+from dataclasses import dataclass
+from typing import Any
+
+# custom modules
+
+# import global variables
+
+# valid data types for the node
+# :data: VLD_DTYPE_LT
+VLD_DTYPE_LT: tuple = (
+    int,
+    float,
+    str,
+    bool,
+    dict,
+    list,
+    tuple,
+    set,
+    dataclass,
+)
+"""
+Native data types in Python that are comparable in the structures.
+"""
+
+
+def dflt_cmp_function_lt(elm1: Any, elm2: Any, key: str) -> int:
+    """*dflt_cmp_function_lt()* Compare two elements of the ADT List (ArrayList, SingleLinked, DoubleLinked). They can be of Python native or user-defined.
+
+    Args:
+        elm1 (Any): First element to compare.
+        elm2 (Any): Second element to compare.
+        key (str): Key for comparing dictionary elements.
+
+    Raises:
+        TypeError: If elements are of different types or not comparable.
+        KeyError: If the key is not found in dictionary elements.
+        TypeError: If elements are not of built-in comparable types.
+
+    Returns:
+        int: -1 if elm1 < elm2, 0 if elm1 == elm2, 1 if elm1 > elm2.
+    """
+
+    val1, val2 = None, None
+    # if elements are of different types, raise error
+    if type(elm1) is not type(elm2):
+        _msg = "Invalid comparison between "
+        _msg += f"{type(elm1)} and {type(elm2)} elements."
+        raise TypeError(_msg)
+
+    # if both elements are dictionaries and a key is provided
+    if key and isinstance(elm1, dict) and isinstance(elm2, dict):
+        val1, val2 = elm1.get(key), elm2.get(key)
+        if val1 is None or val2 is None:
+            _msg = f"Invalid key: {key}, Key not found in one or both elements."
+            raise KeyError(_msg)
+
+    # if both elements are built-in comparable types
+    elif isinstance(elm1, VLD_DTYPE_LT) and isinstance(elm2, VLD_DTYPE_LT):
+        val1, val2 = elm1, elm2
+
+    # otherwise, raise error
+    else:
+        _msg = f"Elements of type {type(elm1)} are not comparable "
+        _msg += f"with elements of type {type(elm2)}."
+        raise TypeError(_msg)
+
+    # Simplified comparison: returns -1, 0, or 1
+    # quivalent to the comparison as if, elif, and else statements
+    return (val1 > val2) - (val1 < val2)
+
+
+def dflt_cmp_function_ht(ekey1: Any, entry2, key: str, ) -> int:
+    """*dflt_cmp_function_ht()* Compare the entries of the ADT Map (Hash Table). can be of Python native or user-defined.
+
+    Args:
+        ekey1 (Any): Key of the first entry (key-value pair) to compare.
+        entry2 (MapEntry): Second entry (key-value pair) to compare.
+        key (str): Key for comparing dictionary elements.
+
+    Raises:
+        TypeError: If the keys are of different types or not comparable.
+        KeyError: If the key is not found in dictionary elements.
+        TypeError: If keys are not of built-in comparable types.
+
+    Returns:
+        int: -1 if ekey1 < ekey2, 0 if ekey1 == ekey2, 1 if ekey1 > ekey2.
+    """
+    # Extract keys from entries
+    ekey2 = entry2.key
+
+    # if keys are of different types, raise error
+    if type(ekey1) is not type(ekey2):
+        _msg = "Invalid comparison between "
+        _msg += f"{type(ekey1)} and {type(ekey2)} elements."
+        raise TypeError(_msg)
+
+    # if both keys are dictionaries and a key is provided
+    if key and isinstance(ekey1, dict) and isinstance(ekey2, dict):
+        val1, val2 = ekey1.get(key), ekey2.get(key)
+        if val1 is None or val2 is None:
+            _msg = f"Invalid key: '{key}', Key not found in one or both dictionary elements"
+            raise KeyError(_msg)
+
+    # if both keys are built-in comparable types
+    elif isinstance(ekey1, VLD_DTYPE_LT) and isinstance(ekey2, VLD_DTYPE_LT):
+        val1, val2 = ekey1, ekey2
+
+    # otherwise, raise error
+    else:
+        _msg = f"Elements of type {type(ekey1)} are not comparable "
+        _msg += f"with elements of type {type(ekey2)}."
+        raise TypeError(_msg)
+
+    # Simplified comparison: returns -1, 0, or 1
+    return (val1 > val2) - (val1 < val2)

pydasa/structs/types/generics.py

@@ -0,0 +1,54 @@
+# -*- coding: utf-8 -*-
+"""
+Module generics.py
+===========================================
+
+Module for default generic dataclass and global constants for use by all *PyDASA* and its Data Structures.
+
+*IMPORTANT:* based on the implementations proposed by the following authors/books:
+
+    #. Algorithms, 4th Edition, Robert Sedgewick and Kevin Wayne.
+    #. Data Structure and Algorithms in Python, M.T. Goodrich, R. Tamassia, M.H. Goldwasser.
+"""
+
+# python native modules
+from typing import TypeVar
+
+# custom modules
+
+# import global variables
+
+# Type for the element stored in the dataclass
+# :data: T: TypeVar
+T = TypeVar("T")
+"""
+Type for creating Generics dataclasses in data structure classes, methods, and attrs.
+
+NOTE: used for type hinting only in generics dataclasses.
+"""
+
+
+# default key for comparing dictionaries
+# :data: DFLT_DICT_KEY
+DFLT_DICT_KEY: str = "_idx"
+"""
+Default field for comparing dictionaries in the structures.
+"""
+
+# allowed input/output types for the ADTs
+# :data: VLD_IOTYPE_LT
+VLD_IOTYPE_LT: tuple = (
+    list,
+    tuple,
+    set,
+)
+"""
+Allowed input/output types for loading and saving data in the ADTs with the *load* and *save* file methods.
+"""
+
+# default big prime number for MAD compression in hash tables
+# :data: DFLT_PRIME
+DFLT_PRIME: int = 109345121
+"""
+Default big prime number for the MAD compression function in hash tables.
+"""