API Reference

This page contains the auto-generated API reference for all public classes and functions in the sexagesimal-calculator library.

The `Sexagesimal` Class

Represents an immutable sexagesimal (base-60) number.

This class provides a robust way to handle sexagesimal numbers, which are common in historical mathematics and astronomy. It supports standard arithmetic operations while ensuring that all calculations are performed natively in base-60.

Instances of this class are immutable. All arithmetic operations return a new Sexagesimal instance.

Parameters:

Name	Type	Description	Default
`value`	`Union[str, int, float, Sexagesimal]`	The value to initialize the number with. - If str: Can be a decimal ('1.5') or sexagesimal ('01;30'). - If int or float: Will be converted from decimal. - If Sexagesimal: A new instance is created from the provided one.	required

Attributes:

Name	Type	Description
`is_negative`	`bool`	True if the number is negative.
`integer_part`	`Tuple[int, ...]`	A tuple representing the integer places of the number. For 123;45 (2,3;45), this would be (2, 3).
`fractional_part`	`Tuple[int, ...]`	A tuple representing the fractional places of the number. For 123;45, this would be (45,).

Raises:

Type	Description
`InvalidFormatError`	If the input string is not in a valid decimal or sexagesimal format, or if any sexagesimal part is >= 60.

Examples:

>>> a = Sexagesimal("04;10,30")
>>> b = Sexagesimal(1.5)  # Creates Sexagesimal("01;30")
>>> print(a + b)
05;40,30

init

__init__(value: Union[str, int, float])

Initialize a Sexagesimal instance from a variety of inputs.

Summary

Construct an immutable sexagesimal (base-60) value from:

an existing Sexagesimal (copied),
a sexagesimal string like "01;30,15",
a decimal string like "1.5",
an int or float (treated as decimal). Decimal inputs are converted to sexagesimal; sexagesimal strings are parsed and validated; normalization (removal of extraneous zeros) is applied before the internal canonical representation is stored.

Parameters:

Name	Type	Description	Default
`value`	`Union[str, int, float, Sexagesimal]`	Sexagesimal: instance to copy. str: decimal ("1.5") or sexagesimal ("01;30,15" or "1;30"). int \| float: treated as a decimal number and converted.	required

Raises:

Type	Description
`InvalidFormatError`	If the input string is not a valid decimal or sexagesimal format, or if parsing fails.
`InvalidFormatError`	If any parsed sexagesimal digit is outside the valid range [0, BASE-1] (BASE == 60 in this module).

Notes

The constructor always stores a normalized, immutable SexagesimalParts container obtained via arithmetic.normalize_parts.
A Sexagesimal passed to the constructor is copied by reusing its internal parts object (no re-parsing).
Decimal-to-sexagesimal conversion uses the module conversion utilities with a reasonable default precision for fractional expansion.

str

__str__() -> str

Return the canonical sexagesimal string representation.

Produces a normalized string in the form "[sign]DD[,DD...];FF[,FF...]" where: - each degree or fractional place is zero-padded to two digits, - the integer and fractional parts are separated by ';', - individual places are separated by ','. Zero is always represented as "00;00" (no negative sign). Negative values are prefixed with a leading '-' character.

Returns:

Name	Type	Description
`str`	`str`	Canonical sexagesimal string for this instance, e.g. "05;30,15" or "-01;00".

pow

__pow__(n: int) -> Sexagesimal

pow Calculates the power of a Sexagesimal number to an integer n.

This method supports positive, negative, and zero integer n, leveraging the existing multiplication and division methods of the class.

For positive n, it uses repeated multiplication.
For a zero n, it returns 1 (Sexagesimal('01;00')).
For negative n, it calculates the reciprocal of the positive power.

Parameters:

Name	Type	Description	Default
`n`	`int`	The integer n to raise the number to.	required

Returns:

Name	Type	Description
`Sexagesimal`	`Sexagesimal`	The result of the power operation.

Raises:

Type	Description
`TypeError`	If the n is not an integer.
`ZeroDivisionError`	If the base is zero and the n is negative.

to_decimal

to_decimal(precision: int = 50) -> Decimal

Convert the Sexagesimal number to a high-precision Decimal.

Summary

Produce a Decimal representation of this sexagesimal value by summing integer-place digits weighted by BASEk (k = 0,1,2,...) and fractional-place digits as digit/BASEk (k = 1,2,...). The global Decimal context precision is set to precision for the duration of the computation.

Parameters:

Name	Type	Description	Default
`precision`	`int`	Number of significant digits to use in the Decimal context (localcontext().prec). Must be a positive integer. Defaults to 50.	`50`

Returns:

Name	Type	Description
`Decimal`	`Decimal`	A Decimal equal to the numeric value of this Sexagesimal. The returned Decimal carries the same sign as the instance; canonical zero is returned as a non-negative Decimal.

Notes

This function mutates the module Decimal context via localcontext().prec. Callers that rely on a different global Decimal precision should restore it after calling this method if necessary.
All accumulation uses Decimal arithmetic to avoid floating-point rounding; the result is as exact as allowed by the requested precision.

round

round(precision: int = 0) -> Sexagesimal

Round the sexagesimal number to the specified fractional-place precision.

Summary

Truncate the fractional part to precision base-60 places and perform round-half-up based on the next (precision-th) fractional digit (round up when that digit >= BASE//2). Carries produced by rounding propagate through fractional places into the integer places as needed, and the final result is normalized. Zero is canonicalized as non-negative.

Parameters:

Name	Type	Description	Default
`precision`	`int`	Number of fractional base-60 places to keep. 0 means rounding to the integer part. Must be a non-negative integer. Defaults to 0.	`0`

Raises:

Type	Description
`TypeError`	If `precision` is not an int.
`ValueError`	If `precision` is negative.

Returns:

Name	Type	Description
`Sexagesimal`	`Sexagesimal`	A new Sexagesimal instance rounded to the requested precision.

Notes

If precision is greater than or equal to the current fractional length, the original instance is returned (no change).
Carry propagation may extend the integer part (creating a new high-order digit) and normalization removes any extraneous zeros.

Explanation Functions

sexagesimal_calculator.explain

CalculationGrid `dataclass`

Stores the raw data needed to render an arithmetic grid.

ExplanationStep `dataclass`

Represents one step or detail in the narrative.

VerboseResult `dataclass`

A container for the final result and the rich explanation steps.

str

__str__() -> str

Renders the explanation to a plain, uncolored string.

__rich_console__

__rich_console__(
    console: Console, options: ConsoleOptions
) -> RenderResult

Allows the object to be printed directly by a rich.console.Console.

print

print()

Prints the rich, colored explanation directly to the console.

explain_multiplication

explain_multiplication(
    a: Sexagesimal, b: Sexagesimal
) -> VerboseResult

Explain long multiplication of two sexagesimal values and produce a verbose narrative.

Summary

Perform a pedagogical, step-by-step long multiplication of two Sexagesimal instances. The explanation breaks each operand into integer and fractional base-60 digits, computes intermediate row products (digit-by-digit with carries), arranges a summation grid with proper shifts, reduces the accumulated digits into integer and fractional parts, and reports the canonical normalized result.

Parameters:

Name	Type	Description	Default
`a`	`Sexagesimal`	Left multiplicand.	required
`b`	`Sexagesimal`	Right multiplicand.	required

Returns:

Name	Type	Description
`VerboseResult`	`VerboseResult`	A container with the canonical Sexagesimal product in `result`, a short `title`, and a `steps` list combining ExplanationStep entries and a CalculationGrid showing intermediate rows and the final column-wise sum.

Notes

The narrative includes decomposition, per-digit multiplication (with carry), the shifted intermediate rows, column-wise summation and carry propagation, splitting the full digit array into integer/fractional parts, and final normalization.
The function uses the robust Sexagesimal.mul implementation to produce the authoritative final result after demonstrating the manual algorithm.

explain_addition

explain_addition(
    a: Sexagesimal, b: Sexagesimal
) -> VerboseResult

Explain addition of two sexagesimal values and produce a verbose narrative.

Summary

Produce a step-by-step, pedagogical explanation of adding two Sexagesimal instances. The explanation documents sign handling (delegating to subtraction for mixed signs), alignment of integer and fractional digits, per-column addition with carry propagation from fractional to integer places, construction of a calculation grid showing the aligned operands and result, and the final canonical, normalized sum.

Parameters:

Name	Type	Description	Default
`a`	`Sexagesimal`	Left addend.	required
`b`	`Sexagesimal`	Right addend.	required

Returns:

Name	Type	Description
`VerboseResult`	`VerboseResult`	A container holding: - result (Sexagesimal): the canonical sum (produced by the library's arithmetic to guarantee normalization), - title (str): a short descriptive title, - steps (List[Union[ExplanationStep, CalculationGrid]]): a sequence of narrative steps and a CalculationGrid illustrating the work.

Notes

When operands have opposite signs the narrative records the transformation (e.g. A + (-B) -> A - B) and delegates to explain_subtraction to show the borrowing behavior; the combined explanation is returned.
Fractional parts are right-padded and integer parts are left-padded for alignment prior to column-wise processing. Carries from fractional addition propagate into integer columns and may produce a new high-order digit.
The function both demonstrates the manual algorithm (for teaching) and uses the authoritative Sexagesimal addition (a + b) to produce the final, normalized result included in the VerboseResult.

explain_subtraction

explain_subtraction(
    a: Sexagesimal, b: Sexagesimal
) -> VerboseResult

Explain subtraction of two sexagesimal values and produce a verbose narrative.

Summary

Produce a pedagogical, step-by-step explanation of computing A - B for Sexagesimal operands. The explanation documents sign handling (delegating to addition when signs differ), magnitude comparison, the borrow algorithm across fractional and integer base-60 places, construction of a calculation grid showing aligned operands and the result, and the canonical normalized final value.

Parameters:

Name	Type	Description	Default
`a`	`Sexagesimal`	Minuend.	required
`b`	`Sexagesimal`	Subtrahend.	required

Returns:

Name	Type	Description
`VerboseResult`	`VerboseResult`	A container with: - result (Sexagesimal): canonical difference (produced by the library's arithmetic to guarantee normalization), - title (str): a short descriptive title, - steps (List[Union[ExplanationStep, CalculationGrid]]): narrative steps and a CalculationGrid illustrating the borrowing and column-wise work.

Notes

When operands have opposite signs the function records the transformation (e.g. -A - +B -> -(A + B), +A - -B -> A + B) and delegates to the addition explainer; the returned VerboseResult combines both narratives and the correctly signed final result.
For magnitude subtraction the algorithm pads fractional parts on the right and integer parts on the left for alignment, subtracts right-to-left, propagating borrows from fractional into integer places as necessary.
The calculation grid shows the padded operand rows and the raw digitwise result; the authoritative final Sexagesimal value is produced by the library subtraction (a - b) to ensure normalization and canonical zero/sign.

explain_division

explain_division(
    a: Sexagesimal, b: Sexagesimal
) -> VerboseResult

Explain division of two sexagesimal values using exact rational arithmetic.

Summary

Demonstrate a clear, step-by-step strategy for dividing two Sexagesimal instances by converting them to exact Rational numbers, performing the division exactly, and then converting the quotient back into a sexagesimal expansion (showing a limited number of fractional-place extraction steps for pedagogy). The function also documents the handling of division by zero and presents a human-friendly narrative describing the conversion and extraction process.

Parameters:

Name	Type	Description	Default
`a`	`Sexagesimal`	Numerator.	required
`b`	`Sexagesimal`	Denominator.	required

Returns:

Name	Type	Description
`VerboseResult`	`VerboseResult`	A container with: - result (Sexagesimal): the canonical quotient (produced by the library's division to ensure normalization and correct sign), - title (str): a short descriptive title, - steps (List[ExplanationStep]): a sequence of narrative steps that explain conversion to Rational, the exact division, and the process of recovering sexagesimal integer and fractional digits.

Notes

Division is performed via exact Rational arithmetic (to avoid rounding errors). The sexagesimal expansion of the quotient may be terminating or repeating; the explainer shows the first few fractional extraction steps (for demonstration) while the authoritative final Sexagesimal result is obtained from the library's division operator.
If the denominator is zero the function records an error step and returns a placeholder VerboseResult (no numeric result can be produced).
The conversion back to sexagesimal is performed by extracting the integer part and repeatedly multiplying the fractional remainder by BASE (60) to obtain successive base-60 digits; this process is shown only up to a short demonstration depth in the narrative.

Utility Functions

sexagesimal_calculator.utils

increment_table

increment_table(
    initial: Union[str, int, float],
    increment: Union[str, int, float],
    rows: int = 10,
    mod: int = 0,
) -> List[str]

Generates a table of incrementing sexagesimal values.

API Reference

The Sexagesimal Class

__init__

__str__

__pow__

to_decimal

round

Explanation Functions

sexagesimal_calculator.explain

CalculationGrid dataclass

ExplanationStep dataclass

VerboseResult dataclass

__str__

__rich_console__

print

explain_multiplication

explain_addition

explain_subtraction

explain_division

Utility Functions

sexagesimal_calculator.utils

increment_table

The `Sexagesimal` Class

init

str

pow

CalculationGrid `dataclass`

ExplanationStep `dataclass`

VerboseResult `dataclass`

str