Skip to content

README.md

Latest commit

 

History

History
360 lines (258 loc) · 8.96 KB

README.md

File metadata and controls

360 lines (258 loc) · 8.96 KB

📦 FuncBox

A lightweight Python utility library for common mathematical and algorithmic tasks.


Table of Contents

Install

pip install -U funcbox

Quick Start

from funcbox import *

is_prime(17)                     # True
classify_numbers([2, 3, 4, 5, 6]) # {'primes': [2, 3, 5], 'composites': [4, 6], 'neither': []}
fibonacci(10)                    # 55
get_factors(12)                  # [1, 2, 3, 4, 6]

Functions Overview

Function Description
is_prime Determines whether a given integer is prime
classify_numbers Categorizes integers into prime, composite, and neutral subsets
fibonacci Computes the $n$-th Fibonacci term or sequence
get_factors Computes all proper divisors of an integer
isAnagram Computes if two strings are anagrams of each other optimally
binary_search Searches for a value in a sorted sequence
dijkstra Calculates shortest paths in a graph using Dijkstra's algorithm
primes Generates primes within a range via the Sieve of Eratosthenes

API Reference

✨ is_prime

is_prime(n)

Determines whether a given integer is prime.

Signature

is_prime(n: int) -> bool

Parameters

  • n (int): The integer to evaluate. Must be a plain integer (not a bool or float).

Raises

  • TypeError: Raised if n is not a plain integer.

Returns

  • bool: True if the integer is prime, False otherwise.

Examples

from funcbox import is_prime

print(is_prime(7))   # True
print(is_prime(10))  # False

✨ classify_numbers

classify_numbers(numbers)

Categorizes a sequence of integers into prime, composite, and neutral sets (0, 1, or negative numbers).

Signature

classify_numbers(numbers: list[int]) -> dict[str, list[int]]

Parameters

  • numbers (list[int]): A list of integers to categorize. All elements must be plain integers.

Raises

  • TypeError: Raised if numbers is not a list, or if any element is not a plain integer.

Returns

  • dict: A dictionary containing three lists:
    • 'primes': Integers that are prime.
    • 'composites': Integers that are composite (greater than 1 and not prime).
    • 'neither': Integers that are neither prime nor composite (< 2).

Examples

from funcbox import classify_numbers

print(classify_numbers([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]))
# {'primes': [2, 3, 5, 7], 'composites': [4, 6, 8, 9], 'neither': [0, 1]}

print(classify_numbers([-5, 0, 1, 13, 15]))
# {'primes': [13], 'composites': [15], 'neither': [-5, 0, 1]}

✨ fibonacci

fibonacci(n, output_type="int")

Computes Fibonacci sequence values. Supports retrieving an individual $n$-th term or an array containing the sequence up to the $n$-th element.

Signature

fibonacci(n: int, output_type: str = "int") -> int | list[int]

Parameters

  • n (int): The sequence index (0-indexed) or the total count of elements to generate. Must be a plain integer.
  • output_type (str): Specification for the return format.
    • "int" (default): Returns a single integer corresponding to the $n$-th term.
    • "list": Returns a list consisting of the first n terms.

Returns

  • int if output_type is "int".
  • list[int] if output_type is "list".

Raises

  • TypeError: Raised if n is not a plain integer or output_type is not a string.
  • ValueError: Raised if n is a negative integer or if an unsupported output_type is provided.

Examples

from funcbox import fibonacci

print(fibonacci(0))                    # 0
print(fibonacci(5))                    # 5
print(fibonacci(5, output_type="list")) # [0, 1, 1, 2, 3]

✨ get_factors

get_factors(num)

Computes all proper divisors (factors) of an integer, excluding the number itself.

Signature

get_factors(num: int) -> list[int]

Parameters

  • num (int): The target integer to compute factors for. Must be a plain integer (not a bool or float).

Raises

  • TypeError: Raised if num is not a plain integer.

Returns

  • list[int]: A sorted list of all proper factors.

Examples

from funcbox import get_factors

print(get_factors(12))  # [1, 2, 3, 4, 6]
print(get_factors(7))   # [1]

✨ isAnagram

isAnagram(str1, str2)

Checks if two strings are anagrams of each other.

Signature

isAnagram(str1: str, str2: str) -> bool

Parameters

  • str1 (str): First string to compare.
  • str2 (str): Second string to compare.

Raises

  • TypeError: Raised if str1 or str2 is not a string.

Returns

  • bool: True if the strings are anagrams, False otherwise.

Examples

from funcbox import isAnagram

print(isAnagram("listen", "silent")) # True
print(isAnagram("hello", "world"))   # False

✨ binary_search

binary_search(arr, target)

Searches for a target value in a sorted sequence.

Signature

binary_search(arr: Sequence, target: Any) -> int

Parameters

  • arr (Sequence): A sorted sequence to search through (e.g. list, tuple, range).
  • target (Any): The value to search for.

Returns

  • int: The index of the target if found, -1 otherwise.

Raises

  • TypeError: Raised if arr is not a Sequence.

Examples

from funcbox import binary_search

print(binary_search([1, 3, 5, 7, 9], 7))  # 3
print(binary_search([1, 3, 5, 7, 9], 4))  # -1

✨ dijkstra

dijkstra(graph, start_node, end_node=None)

Calculates the shortest paths from a source node to all other reachable nodes in a weighted graph using Dijkstra's algorithm.

Signature

from typing import Any
dijkstra(graph: dict, start_node: Any, end_node: Any = None) -> dict

Parameters

  • graph (dict): An adjacency list where each node maps to a dict of {neighbor: weight} pairs. All weights must be non-negative numbers and all neighbor keys must be nodes in the graph.
  • start_node: The origin node for pathfinding computation.
  • end_node: Optional terminal node. If provided, the algorithm terminates early once the shortest path to this node is found.

Raises

  • ValueError: Raised if graph is not a dict, any node's adjacency value is not a dict, any neighbor key is not present in the graph, any edge weight is not a number or is negative, start_node is not in the graph, or end_node is specified but not in the graph.

Returns

  • dict: A resultant dictionary comprised of two objects:
    • 'distances': The calculated minimum distances from the start_node to all resolved nodes. Unreachable nodes evaluate to positive infinity (float('inf')).
    • 'paths': Ordered sequences of nodes representing the shortest path from the start_node. Unreachable nodes map to None.

Examples

from funcbox import dijkstra

graph = {
    'A': {'B': 4, 'C': 2},
    'B': {'D': 5, 'E': 1},
    'C': {'B': 1, 'E': 3},
    'D': {'F': 2},
    'E': {'D': 1, 'F': 4},
    'F': {}
}

result = dijkstra(graph, 'A')
print(result['distances'])
print(result['paths'])

result = dijkstra(graph, 'A', 'F')
print(result['distances']['F'])
print(result['paths']['F'])

✨ primes

primes(start=2, limit)

Generates a sequence of prime numbers within a specified bounds utilizing the Sieve of Eratosthenes algorithm.

Signature

primes(start: int = 2, limit: int) -> list[int]

Parameters

  • start (int): The inclusive lower bound for prime generation. Defaults to 2.
  • limit (int): The inclusive upper bound for prime generation.

Returns

  • list[int]: An ordered list of prime numbers from start boundary up to the specified limit.

Raises

  • TypeError: Raised if start or limit is not a plain integer.
  • ValueError: Raised if either limit or start are evaluated to be less than 2.

Examples

from funcbox import primes

print(primes(limit=10))         # [2, 3, 5, 7]
print(primes(start=10, limit=20)) # [11, 13, 17, 19]

Disclaimer

FuncBox provides utility functions for general use. The developer is not responsible for any issues caused by improper use or abuse of the library.

Contributing

Contributions are welcome! Feel free to fork the repository and submit a pull request with your improvements.

License

This project is licensed under the MIT License. See the LICENSE file for more details.