Dynamic programming (#17)

* Rebased 'feature/dynamic' onto 'devel'

* Added factorial function

Added factorial getter function implementation and tests.
Added typed marker file for the "calc" package.

* Added dynamic package

Implemented fibonacci number getter function (dynamic programming).
Added corresponding test cases for huge numbers to demonstrate enhancements.

* Added grid traveler problem

* Updated function signatures

* Updated memoize decorator documentation

* Updated imports

* Fixed pylint issues

* Added can sum target function

Implemented function to check, if it's available to get the target number.
Added test cases as well.
Only tabulation approach implemented.

* Updated memoize decorator docstring

* Added can sum target function

Implemented memoized function and test cases.

* Refactored "can_get_target" function

* Updated tabulation functions

Implemented function to get the best sequence to get target number.
Added test cases as well.
This algorithm has no limitations on available numbers usage.

* Added some comments to dynamic functions

* Added partition list function boilerplate

Prepared some test cases, including edge cases tests.
TDD - test are expected failed (no pytest marks).

* Revert "Added partition list function boilerplate"

This reverts commit 8a49e9b.

Author: shorodilov

pyproject.toml

@@ -33,7 +33,9 @@ classifiers = [
 ]
 packages = [
     { include = "bisearch", from = "src" },
+    { include = "calc", from = "src" },
     { include = "conv_store", from = "src" },
+    { include = "dynamic", from = "src" },
     { include = "sequences", from = "src" },
     { include = "sorting", from = "src" },
     { include = "primes", from = "src" },

src/calc/__init__.py

@@ -0,0 +1,13 @@
+"""
+Various calculation challenges
+==============================
+
+"""
+
+from calc.func import *
+
+__all__ = [
+    "get_factorial",
+    "get_fibonacci_number",
+    "get_sum_of_strings",
+]

src/calc/func.py

@@ -0,0 +1,123 @@
+"""
+Calculation functions implementations
+
+"""
+
+
+def get_factorial(number: int, /) -> int:
+    """Return the factorial value for a given number
+
+    :param number:
+    :type number: int
+
+    :return: the factorial value
+    :rtype: int
+
+    In mathematics the factorial is the product of all positive integers
+    less than or equal to given number.
+    E.g. 5! = 5 * 4! = 5 * 4 * 3 * 2 * 1 = 120.
+    The value of 0! = 1 according to the convention of an empty product.
+
+    Usage examples:
+
+    >>> assert get_factorial(0) == 1
+    >>> assert get_factorial(5) == 120
+
+    """
+
+    if number <= 1:
+        return 1
+
+    return number * get_factorial(number - 1)
+
+
+def get_fibonacci_number(idx: int, /) -> int:
+    """Return a Fibonacci's sequence number at a specified index
+
+    :param idx: a Fibonacci sequence index starting from 0
+    :type idx: int
+
+    :return: a sequence's member
+    :rtype: int
+
+    The Fibonacci number is a number from the Fibonacci sequence, in which
+    each number is the sum of the two preceding ones. This sequence commonly
+    starts from 0 and 1: 0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144...
+
+    Usage examples:
+
+    >>> assert get_fibonacci_number(0) == 0
+    >>> assert get_fibonacci_number(1) == 1
+    >>> assert get_fibonacci_number(2) == 1
+    >>> assert get_fibonacci_number(3) == 2
+    >>> assert get_fibonacci_number(4) == 3
+
+    """
+
+    if idx <= 0:
+        return 0
+
+    if 0 < idx < 3:  # the same as ``idx == 1 or idx == 2``
+        return 1
+
+    return get_fibonacci_number(idx - 1) + get_fibonacci_number(idx - 2)
+
+
+def get_sum_of_strings(number_1: str, number_2: str, /) -> str:
+    """Return the sum of two numbers of string type as string
+
+    :param number_1: first number
+    :type number_1: str
+    :param number_2: second number
+    :type number_2: str
+
+    :return: the sum of two numbers
+    :rtype: str
+
+    Valid input is a string of any length containing numeric characters from
+    0 to 9. Empty strings are allowed as well and should be considered as 0.
+
+    Usage examples:
+
+    >>> assert get_sum_of_strings("123", "456") == "579"
+    >>> assert get_sum_of_strings("099", "001") == "100"
+    >>> assert get_sum_of_strings("", "10") == "10"
+    >>> assert get_sum_of_strings("", "") == "0"
+
+    """
+
+    # remove leading zeros
+    for digit in number_1:
+        if digit != "0":
+            break
+        number_1 = number_1[1::]
+    for digit in number_2:
+        if digit != "0":
+            break
+        number_2 = number_2[1::]
+
+    if not number_1 or not number_2:
+        return number_1 or number_2 or "0"
+
+    result: str = ""
+    size: int = max(len(number_1), len(number_2))
+
+    # reverse numbers
+    number_1, number_2 = number_1[::-1], number_2[::-1]
+
+    # make strings of the same lengths
+    while len(number_1) < size:
+        number_1 += "0"
+    while len(number_2) < size:
+        number_2 += "0"
+
+    carry: int = 0
+    for digit_1, digit_2 in zip(number_1, number_2):
+        sum_of_digits = int(digit_1) + int(digit_2) + carry
+        result += str(sum_of_digits % 10)
+        carry = sum_of_digits // 10
+
+    if carry:
+        result += str(carry)
+
+    return result[::-1]

src/calc/py.typed

@@ -0,0 +1,115 @@
+"""
+Dynamic programming memoization functions
+
+"""
+
+import functools
+from typing import Any, Callable, Dict, List, Optional, Tuple
+
+from calc.func import get_fibonacci_number as fib_classic
+
+
+def memoize(func: Callable) -> Callable:
+    """Memoization decorator implementation
+
+    :param func: a function to decorate with memoization technique
+
+    :return: the decorated function
+
+    The memoization technique helps to reduce the number of recursive
+    calls by caching the results already calculated for some inputs.
+
+    Current implementation caches the inputs as tuples containing args,
+    so it has limitations for "un-hashable" inputs, that can not be
+    stored in a cache dictionary.
+
+    """
+
+    cache: Dict[Tuple[Any], int] = {}
+
+    @functools.wraps(func)
+    def wrapper(*args):
+        if args not in cache:
+            cache[args] = func(*args)
+
+        return cache[args]
+
+    return wrapper
+
+
+@memoize
+@functools.wraps(fib_classic, ("__annotations__", "__doc__"))
+def get_fibonacci_number(idx):  # pylint: disable=C0116
+    if idx <= 0:
+        return 0
+    if idx < 3:
+        return 1
+
+    return get_fibonacci_number(idx - 1) + get_fibonacci_number(idx - 2)
+
+
+@memoize
+def get_grid_travels(height: int, width: int, /) -> int:
+    """Calculate the number of available route for a specified grid size
+
+    :param height: grid height
+    :param width: grid width
+
+    :return: the number of available routes
+    :rtype: int
+
+    The traveler starts the journey in the top-left corner of the grid
+    and trying to reach the opposite grid corner (bottom-right).
+    The only moves available are **move right** and **move down**.
+    The task is to calculate the number of all available routes to do
+    this.
+
+    """
+
+    if height <= 0 or width <= 0:
+        return 0
+
+    if height == 1 or width == 1:
+        return 1
+
+    return (get_grid_travels(height - 1, width)
+            + get_grid_travels(height, width - 1))
+
+
+def can_get_target(target: int, numbers: List[int],
+                   cache: Optional[Dict[int, bool]] = None) -> bool:
+    """Check if the target value can be generated using given numbers
+
+    :param target: the desired number
+    :type target: int
+    :param numbers: the sequence of numbers available for usage
+    :type numbers: list[int]
+    :param cache: optional dictionary that stores already calculated results
+    :type cache: dict[int, bool]
+
+    :return: the check result
+    :rtype: bool
+
+    Numbers from the list can be used as many times as needed.
+
+    """
+
+    # check base cases
+    if target < 0:
+        return False
+
+    if not target:
+        return True
+
+    # check cached values
+    cache = cache or {}
+    if target in cache:
+        return cache[target]
+
+    # perform calculation
+    for number in numbers:
+        cache[target] = can_get_target(target - number, numbers, cache)
+        if cache[target]:
+            return True
+
+    return False