quicktools-atom 0.2.0__tar.gz → 0.4.0__tar.gz

quicktools_atom-0.4.0/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: quicktools-atom
+Version: 0.4.0
+Summary: Math and string utilities with a bundled CLI, by AtomDev Studios
+Author-email: Samuel Peprah <windscribe.samuel@gmail.com>
+Project-URL: Homepage, https://github.com/Samuel-Peprah-cmd/quicktools
+Project-URL: Repository, https://github.com/Samuel-Peprah-cmd/quicktools
+Project-URL: Documentation, https://samuel-peprah-cmd.github.io/quicktools/
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: Pillow
+Requires-Dist: python-docx
+Requires-Dist: pypdf
+Requires-Dist: openpyxl
+Requires-Dist: reportlab
+Requires-Dist: PyYAML
+Requires-Dist: pdf2docx
+Requires-Dist: docx2pdf
+
+\# quicktools
+
+
+
+A small toolkit with math and string utilities, plus a bundled CLI.
+
+
+
+\## Install
+
+
+
+&#x20;   pip install quicktools-atom
+
+
+
+\## Usage
+
+
+
+&#x20;   from quicktools import mathtools, strtools
+
+
+
+&#x20;   mathtools.is\_prime(97)
+
+&#x20;   strtools.slugify("Hello World")
+
+
+
+\## CLI
+
+
+
+&#x20;   quicktools is-prime 97
+
+&#x20;   quicktools stats 1 2 3 4 5
+
+&#x20;   quicktools slugify "Hello World"
+

quicktools_atom-0.4.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "quicktools-atom"
+version = "0.4.0"
+description = "Math and string utilities with a bundled CLI, by AtomDev Studios"
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [
+    { name = "Samuel Peprah", email = "windscribe.samuel@gmail.com" }
+]
+dependencies = [
+    "Pillow",
+    "python-docx",
+    "pypdf",
+    "openpyxl",
+    "reportlab",
+    "PyYAML",
+    "pdf2docx",
+    "docx2pdf",
+]
+
+[project.urls]
+Homepage = "https://github.com/Samuel-Peprah-cmd/quicktools"
+Repository = "https://github.com/Samuel-Peprah-cmd/quicktools"
+Documentation = "https://samuel-peprah-cmd.github.io/quicktools/"
+
+[project.scripts]
+quicktools = "quicktools.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

quicktools_atom-0.4.0/src/quicktools/__init__.py

@@ -0,0 +1,88 @@
+"""
+<p align="center">
+  <img src="assets/AtomDev_Studios.png" alt="AtomDev Studios" width="320" style="border-radius: 8px;">
+</p>
+
+# quicktools
+
+A math and string-manipulation toolkit covering linear algebra, calculus,
+number theory, combinatorics, and text processing — built by **Samuel Peprah**
+under **AtomDev Studios**.
+
+---
+
+## About Samuel Peprah
+
+<p align="center">
+  <img src="assets/sam.png" alt="Samuel Peprah" width="160" style="border-radius: 50%; object-fit: cover;">
+</p>
+
+Samuel Peprah is a software developer, web application developer, and
+Occupational Therapy student at the University of Ghana. Alongside his
+healthcare education, he is also studying Computer Science at the University
+of the People, combining knowledge from both fields to develop practical
+technology solutions.
+
+His interests span full-stack web development, software engineering,
+automation, artificial intelligence, cybersecurity, and health technology.
+He enjoys building scalable applications that solve real-world problems and
+continuously explores new technologies to improve his skills.
+
+Samuel has developed educational platforms, business management systems,
+attendance systems, healthcare applications, and AI-powered solutions. He is
+passionate about creating software that is modern, efficient, secure, and
+user-friendly.
+
+## About AtomDev Studios
+
+AtomDev Studios is the personal software development brand founded by Samuel
+Peprah. The studio specializes in designing and developing modern websites,
+web applications, business management systems, educational platforms, and
+custom software solutions for individuals, startups, schools, and
+organizations.
+
+The mission of AtomDev Studios is to transform ideas into reliable, scalable,
+and innovative digital products that solve real-world problems while
+delivering exceptional user experiences.
+
+### Areas of Expertise
+
+- Full-Stack Web Development
+- Custom Web Applications
+- REST API Development
+- Database Design & Management
+- Educational Technology Platforms
+- Healthcare Technology Solutions
+- AI Integration & Automation
+- UI/UX Design
+- Cloud Deployment & Hosting
+- Website Maintenance & Support
+
+### Technologies
+
+Python • Flask • JavaScript • HTML • CSS • Tailwind CSS • Bootstrap •
+PostgreSQL • SQLite • Git • GitHub • Cloudflare • Docker
+
+### Connect
+
+- LinkedIn: [samuel-peprah-a63598347](https://www.linkedin.com/in/samuel-peprah-a63598347)
+- X (Twitter): [@legend_consult](https://x.com/legend_consult)
+- TikTok: [@legendinlearning](https://www.tiktok.com/@legendinlearning)
+- Instagram: [@ksapeprah](https://www.instagram.com/ksapeprah)
+- GitHub: [Samuel-Peprah-cmd](https://github.com/Samuel-Peprah-cmd)
+
+> "Building innovative software solutions that bridge technology with real-world impact."
+
+---
+
+## Modules
+
+- `mathtools` — primes, GCD/LCM, mean, median, standard deviation
+- `strtools` — palindromes, slugify, edit distance, anagrams, ciphers
+- `linalg` — matrix operations, determinants, inverses, linear systems
+- `calculus` — derivatives, integrals, Taylor series, Newton's method
+- `numbertheory` — extended GCD, modular inverse, sieve, prime factorization
+- `combinatorics` — permutations, combinations, Catalan numbers, Fibonacci
+"""
+
+__version__ = "0.2.0"

{quicktools_atom-0.2.0 → quicktools_atom-0.4.0}/src/quicktools/calculus.py

@@ -62,4 +62,54 @@ def newtons_method(f: Callable[[float], float], x0: float, tol: float = 1e-10, m
         if dfx == 0:
             raise ZeroDivisionError("Derivative is zero; Newton's method failed")
         x = x - fx / dfx
-    return x
+    return x
+
+def bisection_method(f, a: float, b: float, tol: float = 1e-10, max_iter: int = 200) -> float:
+    """Find a root of f within [a, b] using the bisection method. Requires f(a) and f(b) to have opposite signs."""
+    if f(a) * f(b) > 0:
+        raise ValueError("f(a) and f(b) must have opposite signs")
+    for _ in range(max_iter):
+        mid = (a + b) / 2
+        if abs(f(mid)) < tol or (b - a) / 2 < tol:
+            return mid
+        if f(a) * f(mid) < 0:
+            b = mid
+        else:
+            a = mid
+    return (a + b) / 2
+
+
+def secant_method(f, x0: float, x1: float, tol: float = 1e-10, max_iter: int = 200) -> float:
+    """Find a root of f near x0 and x1 using the secant method (no derivative required)."""
+    for _ in range(max_iter):
+        fx0, fx1 = f(x0), f(x1)
+        if fx1 - fx0 == 0:
+            raise ZeroDivisionError("Secant method failed: division by zero")
+        x2 = x1 - fx1 * (x1 - x0) / (fx1 - fx0)
+        if abs(x2 - x1) < tol:
+            return x2
+        x0, x1 = x1, x2
+    return x1
+
+
+def partial_derivative(f, point: list[float], index: int, h: float = 1e-6) -> float:
+    """Approximate the partial derivative of a multivariable function f at `point`,
+    with respect to the variable at position `index`."""
+    point_plus = list(point)
+    point_minus = list(point)
+    point_plus[index] += h
+    point_minus[index] -= h
+    return (f(*point_plus) - f(*point_minus)) / (2 * h)
+
+
+def arc_length(f, a: float, b: float, n: int = 1000) -> float:
+    """Approximate the arc length of y = f(x) from x=a to x=b."""
+    def integrand(x: float) -> float:
+        return math.sqrt(1 + derivative(f, x) ** 2)
+    return integral_simpson(integrand, a, b, n)
+
+
+def limit_approximation(f, x: float, h: float = 1e-6) -> float:
+    """Approximate the limit of f(t) as t approaches x, by averaging values just before and after x
+    (useful for functions undefined exactly at x, e.g. removable discontinuities)."""
+    return (f(x - h) + f(x + h)) / 2

quicktools_atom-0.4.0/src/quicktools/combinatorics.py

@@ -0,0 +1,88 @@
+"""Combinatorics: permutations, combinations, and counting sequences."""
+import math
+
+
+def permutations_count(n: int, r: int) -> int:
+    """Number of ways to arrange r items out of n, order matters: nPr."""
+    if r > n or r < 0:
+        return 0
+    return math.factorial(n) // math.factorial(n - r)
+
+
+def combinations_count(n: int, r: int) -> int:
+    """Number of ways to choose r items out of n, order doesn't matter: nCr."""
+    if r > n or r < 0:
+        return 0
+    return math.factorial(n) // (math.factorial(r) * math.factorial(n - r))
+
+
+def catalan_number(n: int) -> int:
+    """The nth Catalan number — counts things like valid bracket sequences and binary tree shapes."""
+    return combinations_count(2 * n, n) // (n + 1)
+
+
+def fibonacci(n: int) -> int:
+    """The nth Fibonacci number (0-indexed: fibonacci(0) == 0)."""
+    if n < 0:
+        raise ValueError("n must be non-negative")
+    a, b = 0, 1
+    for _ in range(n):
+        a, b = b, a + b
+    return a
+
+
+def binomial_expansion_coeffs(n: int) -> list[int]:
+    """Coefficients of (x + y)^n, i.e. row n of Pascal's triangle."""
+    return [combinations_count(n, k) for k in range(n + 1)]
+
+def multinomial_coefficient(n: int, ks: list[int]) -> int:
+    """Number of ways to divide n items into groups of sizes ks (which must sum to n)."""
+    if sum(ks) != n:
+        raise ValueError("The group sizes must sum to n")
+    result = math.factorial(n)
+    for k in ks:
+        result //= math.factorial(k)
+    return result
+
+
+def stirling_second_kind(n: int, k: int) -> int:
+    """Number of ways to partition a set of n objects into k non-empty subsets."""
+    if k == 0:
+        return 1 if n == 0 else 0
+    if k > n or n < 0:
+        return 0
+    if k == n:
+        return 1
+    total = 0
+    for j in range(k + 1):
+        sign = (-1) ** (k - j)
+        total += sign * combinations_count(k, j) * (j ** n)
+    return total // math.factorial(k)
+
+
+def derangements_count(n: int) -> int:
+    """Number of permutations of n items where no item ends up in its original position."""
+    if n == 0:
+        return 1
+    if n == 1:
+        return 0
+    a, b = 1, 0
+    for i in range(2, n + 1):
+        a, b = b, (i - 1) * (a + b)
+    return b
+
+
+def integer_partitions_count(n: int) -> int:
+    """Number of ways to write n as a sum of positive integers, order not mattering."""
+    if n < 0:
+        return 0
+    partitions = [1] + [0] * n
+    for k in range(1, n + 1):
+        for i in range(k, n + 1):
+            partitions[i] += partitions[i - k]
+    return partitions[n]
+
+
+def combinations_with_replacement_count(n: int, r: int) -> int:
+    """Number of ways to choose r items from n types, with repetition allowed and order not mattering."""
+    return combinations_count(n + r - 1, r)

quicktools_atom-0.4.0/src/quicktools/doctools.py

@@ -0,0 +1,89 @@
+"""Word document utilities: reading, creating, editing .docx files, and converting to/from PDF."""
+from docx import Document
+
+
+def read_docx_text(path: str) -> str:
+    """Extract and return all paragraph text from a .docx file."""
+    doc = Document(path)
+    return "\n".join(p.text for p in doc.paragraphs)
+
+
+def create_docx_from_text(text: str, output_path: str) -> None:
+    """Create a new .docx file, adding each line of text as a separate paragraph."""
+    doc = Document()
+    for line in text.split("\n"):
+        doc.add_paragraph(line)
+    doc.save(output_path)
+
+
+def get_docx_word_count(path: str) -> int:
+    """Count the total number of words across all paragraphs in a .docx file."""
+    doc = Document(path)
+    return sum(len(p.text.split()) for p in doc.paragraphs)
+
+
+def get_docx_paragraph_count(path: str) -> int:
+    """Count the number of paragraphs in a .docx file."""
+    return len(Document(path).paragraphs)
+
+
+def replace_text_in_docx(path: str, old: str, new: str, output_path: str) -> None:
+    """Replace all occurrences of `old` with `new` across every paragraph, saving to output_path."""
+    doc = Document(path)
+    for p in doc.paragraphs:
+        if old in p.text:
+            for run in p.runs:
+                if old in run.text:
+                    run.text = run.text.replace(old, new)
+    doc.save(output_path)
+
+
+def extract_docx_tables(path: str) -> list[list[list[str]]]:
+    """Extract every table in a .docx file as a list of tables, each a list of rows, each a list of cell strings."""
+    doc = Document(path)
+    all_tables = []
+    for table in doc.tables:
+        rows = []
+        for row in table.rows:
+            rows.append([cell.text for cell in row.cells])
+        all_tables.append(rows)
+    return all_tables
+
+
+def merge_docx_files(paths: list[str], output_path: str) -> None:
+    """Merge multiple .docx files into one, concatenating their paragraphs in order."""
+    combined = Document()
+    for i, path in enumerate(paths):
+        doc = Document(path)
+        for p in doc.paragraphs:
+            combined.add_paragraph(p.text)
+        if i < len(paths) - 1:
+            combined.add_page_break()
+    combined.save(output_path)
+
+
+def docx_to_pdf(path: str, output_path: str) -> None:
+    """Convert a .docx file to PDF. Requires Microsoft Word to be installed (Windows/macOS) and
+    the optional 'docx2pdf' package (pip install docx2pdf)."""
+    try:
+        from docx2pdf import convert
+    except ImportError:
+        raise ImportError(
+            "docx_to_pdf() requires docx2pdf. Install it with: pip install docx2pdf\n"
+            "Note: it also requires Microsoft Word to be installed on this machine."
+        )
+    convert(path, output_path)
+
+
+def pdf_to_docx(path: str, output_path: str) -> None:
+    """Convert a PDF file to .docx, preserving text layout where possible.
+    Requires the optional 'pdf2docx' package (pip install pdf2docx)."""
+    try:
+        from pdf2docx import Converter
+    except ImportError:
+        raise ImportError(
+            "pdf_to_docx() requires pdf2docx. Install it with: pip install pdf2docx"
+        )
+    cv = Converter(path)
+    cv.convert(output_path)
+    cv.close()

quicktools_atom-0.4.0/src/quicktools/filetools.py

@@ -0,0 +1,103 @@
+"""File utilities: reading, writing, hashing, zipping, and inspecting files of any type."""
+import os
+import json
+import hashlib
+import zipfile
+import mimetypes
+import shutil
+
+
+def get_file_info(path: str) -> dict:
+    """Return basic metadata about a file: size, extension, mime type, last modified time."""
+    stat = os.stat(path)
+    mime_type, _ = mimetypes.guess_type(path)
+    return {
+        "size_bytes": stat.st_size,
+        "extension": os.path.splitext(path)[1],
+        "mime_type": mime_type or "unknown",
+        "modified_time": stat.st_mtime,
+    }
+
+
+def read_text_file(path: str, encoding: str = "utf-8") -> str:
+    """Read and return the full contents of a text file."""
+    with open(path, "r", encoding=encoding) as f:
+        return f.read()
+
+
+def write_text_file(path: str, content: str, encoding: str = "utf-8") -> None:
+    """Write text content to a file, overwriting it if it exists."""
+    with open(path, "w", encoding=encoding) as f:
+        f.write(content)
+
+
+def read_json_file(path: str) -> object:
+    """Read and parse a JSON file, returning the resulting Python object."""
+    with open(path, "r", encoding="utf-8") as f:
+        return json.load(f)
+
+
+def write_json_file(path: str, data: object, indent: int = 2) -> None:
+    """Write a Python object to a file as formatted JSON."""
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=indent)
+
+
+def read_yaml_file(path: str) -> object:
+    """Read and parse a YAML file, returning the resulting Python object."""
+    import yaml
+    with open(path, "r", encoding="utf-8") as f:
+        return yaml.safe_load(f)
+
+
+def write_yaml_file(path: str, data: object) -> None:
+    """Write a Python object to a file as YAML."""
+    import yaml
+    with open(path, "w", encoding="utf-8") as f:
+        yaml.safe_dump(data, f)
+
+
+def compute_file_hash(path: str, algorithm: str = "sha256") -> str:
+    """Compute the hex digest hash of a file's contents (works for any file type)."""
+    h = hashlib.new(algorithm)
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(8192), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def zip_files(file_paths: list[str], output_zip_path: str) -> None:
+    """Compress a list of files into a single .zip archive."""
+    with zipfile.ZipFile(output_zip_path, "w", zipfile.ZIP_DEFLATED) as zf:
+        for path in file_paths:
+            zf.write(path, arcname=os.path.basename(path))
+
+
+def unzip_file(zip_path: str, output_dir: str) -> list[str]:
+    """Extract a .zip archive into output_dir, returning the list of extracted file names."""
+    with zipfile.ZipFile(zip_path, "r") as zf:
+        zf.extractall(output_dir)
+        return zf.namelist()
+
+
+def list_files_in_directory(directory: str, extension: str | None = None) -> list[str]:
+    """List all files in a directory, optionally filtered by extension (e.g. '.txt')."""
+    files = os.listdir(directory)
+    if extension:
+        files = [f for f in files if f.endswith(extension)]
+    return files
+
+
+def get_file_extension(path: str) -> str:
+    """Return the file extension of a path, including the leading dot (e.g. '.pdf')."""
+    return os.path.splitext(path)[1]
+
+
+def copy_file(src: str, dst: str) -> None:
+    """Copy a file from src to dst."""
+    shutil.copy2(src, dst)
+
+
+def delete_file(path: str) -> None:
+    """Delete a file. Raises FileNotFoundError if it doesn't exist."""
+    os.remove(path)

quicktools_atom-0.4.0/src/quicktools/imagetools.py

@@ -0,0 +1,128 @@
+"""Image utilities: format conversion, resizing, editing, and image-to-PDF, powered by Pillow.
+
+Supports conversion between PNG, JPEG/JPG, BMP, GIF, WEBP, TIFF, and more —
+the output format is inferred automatically from the output file's extension.
+"""
+from PIL import Image, ImageOps, ImageDraw, ImageFont
+
+
+def convert_image(input_path: str, output_path: str) -> None:
+    """Convert an image from one format to another (e.g. PNG -> JPEG, JPEG -> WEBP).
+    The target format is inferred from output_path's file extension."""
+    img = Image.open(input_path)
+    # JPEG doesn't support transparency (RGBA); flatten onto white if needed.
+    if output_path.lower().endswith((".jpg", ".jpeg")) and img.mode in ("RGBA", "P"):
+        img = img.convert("RGB")
+    img.save(output_path)
+
+
+def resize_image(input_path: str, output_path: str, width: int, height: int) -> None:
+    """Resize an image to the given width and height."""
+    img = Image.open(input_path)
+    resized = img.resize((width, height))
+    resized.save(output_path)
+
+
+def rotate_image(input_path: str, output_path: str, degrees: float) -> None:
+    """Rotate an image by the given number of degrees (counter-clockwise), expanding the canvas as needed."""
+    img = Image.open(input_path)
+    rotated = img.rotate(degrees, expand=True)
+    rotated.save(output_path)
+
+
+def flip_image(input_path: str, output_path: str, direction: str = "horizontal") -> None:
+    """Flip an image. direction is 'horizontal' or 'vertical'."""
+    img = Image.open(input_path)
+    if direction == "horizontal":
+        flipped = ImageOps.mirror(img)
+    elif direction == "vertical":
+        flipped = ImageOps.flip(img)
+    else:
+        raise ValueError("direction must be 'horizontal' or 'vertical'")
+    flipped.save(output_path)
+
+
+def grayscale_image(input_path: str, output_path: str) -> None:
+    """Convert an image to grayscale."""
+    img = Image.open(input_path).convert("L")
+    img.save(output_path)
+
+
+def crop_image(input_path: str, output_path: str, left: int, top: int, right: int, bottom: int) -> None:
+    """Crop an image to the box defined by (left, top, right, bottom) pixel coordinates."""
+    img = Image.open(input_path)
+    cropped = img.crop((left, top, right, bottom))
+    cropped.save(output_path)
+
+
+def get_image_info(path: str) -> dict:
+    """Return basic information about an image: format, dimensions, and color mode."""
+    img = Image.open(path)
+    return {"format": img.format, "size": img.size, "mode": img.mode}
+
+
+def create_thumbnail(input_path: str, output_path: str, max_size: int = 128) -> None:
+    """Create a thumbnail no larger than max_size x max_size, preserving aspect ratio."""
+    img = Image.open(input_path)
+    img.thumbnail((max_size, max_size))
+    img.save(output_path)
+
+
+def compress_image(input_path: str, output_path: str, quality: int = 70) -> None:
+    """Save a (typically JPEG) image at a reduced quality level to shrink file size."""
+    img = Image.open(input_path)
+    if img.mode in ("RGBA", "P"):
+        img = img.convert("RGB")
+    img.save(output_path, quality=quality, optimize=True)
+
+
+def merge_images_horizontally(paths: list[str], output_path: str) -> None:
+    """Combine multiple images side by side into a single image."""
+    images = [Image.open(p) for p in paths]
+    total_width = sum(img.width for img in images)
+    max_height = max(img.height for img in images)
+    combined = Image.new("RGB", (total_width, max_height), "white")
+    x_offset = 0
+    for img in images:
+        combined.paste(img, (x_offset, 0))
+        x_offset += img.width
+    combined.save(output_path)
+
+
+def merge_images_vertically(paths: list[str], output_path: str) -> None:
+    """Stack multiple images on top of each other into a single image."""
+    images = [Image.open(p) for p in paths]
+    max_width = max(img.width for img in images)
+    total_height = sum(img.height for img in images)
+    combined = Image.new("RGB", (max_width, total_height), "white")
+    y_offset = 0
+    for img in images:
+        combined.paste(img, (0, y_offset))
+        y_offset += img.height
+    combined.save(output_path)
+
+
+def add_text_watermark(input_path: str, output_path: str, text: str) -> None:
+    """Overlay a text watermark in the bottom-right corner of an image."""
+    img = Image.open(input_path).convert("RGBA")
+    overlay = Image.new("RGBA", img.size, (255, 255, 255, 0))
+    draw = ImageDraw.Draw(overlay)
+    try:
+        font = ImageFont.load_default()
+    except Exception:
+        font = None
+    bbox = draw.textbbox((0, 0), text, font=font)
+    text_w, text_h = bbox[2] - bbox[0], bbox[3] - bbox[1]
+    position = (img.width - text_w - 10, img.height - text_h - 10)
+    draw.text(position, text, fill=(255, 255, 255, 180), font=font)
+    watermarked = Image.alpha_composite(img, overlay).convert("RGB")
+    watermarked.save(output_path)
+
+
+def images_to_pdf(image_paths: list[str], output_pdf_path: str) -> None:
+    """Combine one or more images into a single multi-page PDF file."""
+    images = [Image.open(p).convert("RGB") for p in image_paths]
+    if not images:
+        raise ValueError("At least one image path is required")
+    first, rest = images[0], images[1:]
+    first.save(output_pdf_path, save_all=True, append_images=rest)