piethorn 0.1.0

This is a library of useful tools for Python.

PyThorn is a Python utility library that collects several small but reusable tools under one package. It currently includes:

• collection helpers such as character wrappers, ordered mappings, slice composition utilities, and read-only views

• filesystem and import helpers for path-aware file handling and module loading

• lightweight logging and progress counters

• math helpers for boolean gates, skewed random generation, number-word conversion, timing utilities, and decimal-based equation parsing

• runtime argument and callable inspection helpers

Project Status

PyThorn is currently marked as alpha-quality software. The public behavior described here is based on the current implementation and test suite.

Requirements

• Python 3.12 or newer

Installation

Install from PyPI with:

pip install piethorn

Install from the repository root:

pip install .

For editable development work:

pip install -e .

Package Overview

pythorn.collections

Character-oriented types, ordered mappings, slice-composition helpers, and immutable views over existing sequences and mappings.

pythorn.filehandle

Filesystem wrappers for building and editing files, JSON persistence helpers, and importer utilities for project-relative path and module resolution.

pythorn.logging

A simple logger plus counter types for progress reporting and parent-child percentage tracking.

pythorn.math

Logic gate helpers, skewed random values, numeric word conversion, timing formatting, and an equation parser/evaluator based on decimal.Decimal.

pythorn.typing

Runtime argument-definition containers and inspect-based callable analysis helpers.

Quick Examples

Collections

from pythorn.collections.char import CharSequence
from pythorn.collections.mapping import Map
from pythorn.collections.views import SequenceView

sequence = CharSequence(["ab", " ", "C"])
mapping = Map(["left", "right"], [1, 2])
view = SequenceView([1, 2, 3, 4], reverse=True, cut=slice(1, 4))

assert str(sequence) == "ab C"
assert mapping["left"] == 1
assert list(view) == [4, 3, 2]

Equation Evaluation

from decimal import Context
from pythorn.math.equation import Equation

eq = Equation("$value$ + $fallback:2$", Context())
assert eq.calculate({"value": 3}) == 5

Logging And Progress

from pythorn.logging.logger import Logger

logger = Logger(debug_level=1)
logger.info("starting")

counter = logger.count("jobs", step=0.5)
counter.add(2)
counter.tick()

File Utilities

from pythorn.filehandle.filehandling import File

root = File("tmp_project", find_children=False)
child = root.create_child("data/example.txt", "hello")
child.write("second line")

Typing Utilities

from pythorn.typing.analyze import analyze

def sample(a, /, b: int, *args, c=3, **kwargs) -> str:
    return "ok"

info = analyze(sample)
assert info.arguments.positional == ("a",)
assert info.arguments.keyword == ("c",)

Documentation

The full documentation source lives in docs/ and includes:

• getting-started pages

• narrative guides for each subsystem

• a layered API reference split into package, module, class, and function pages

If Sphinx is available in your environment, a typical HTML build looks like:

python -m sphinx -b html docs docs/_build/html

Repository Layout

• pythorn/ contains the package implementation

• tests/ contains the unit tests

• docs/ contains the reStructuredText documentation tree

• pyproject.toml defines the build metadata

Why PyThorn

PyThorn is useful when you want a small grab-bag library of utilities that are more structured than ad-hoc snippets but lighter than pulling in many separate packages for simple tasks.