csignum-fast 1.1.5

High-performance universal sign function for Python

csignum-fast

A versatile, high-performance C++ implementation of the universal sign function for Python.

Released on January 1, 2026 ❄️ New Year Edition.

This is Version 1.1.5. Versions 1.1.1+ correct links and typos in documentation, and metadata for Github, after a major internal refactor in v1.1.0.

Key Features

1. Uniform Results: Always returns only -1, 0, or 1 as an int for valid numeric comparisons.
2. Correct Edge Case Handling:
   • sign(+0.0) and sign(-0.0) return 0.
   • sign(inf) returns 1, sign(-inf) returns -1.
   • For any NaN (float NaN, Decimal NaN, etc.), it returns math.nan (float).
3. Comprehensive Duck Typing: Delegates comparisons to the argument's class. Works seamlessly with:
   • Built-in int (including arbitrary-precision), bool, and float.
   • fractions.Fraction and decimal.Decimal.
   • Any existing and future objects that support rich comparisons with numbers.
4. Informative Error Handling for Easy Debugging: Provides clear, descriptive TypeError messages when passed non-numeric, non-scalar, or incomparable arguments.
5. ⚡ High Performance: Branch-optimized C++20 core.
6. ✅ Thoroughly Tested: Tested on 92 cases including different types, edge cases, new custom class, and inappropriate arguments. Also tested memory leaks and benchmarking against v1.0.2.
7. ✨ Pre-processing Engine: Use the preprocess keyword argument to transform input before calculation or trigger an "Early Exit" (recursion permitted).
8. 🛡️ Exception safety: The if_exc keyword argument allows you to define a fallback value (like None, math.nan, or -2) instead of crashing on invalid types.

Installation

pip install csignum-fast

Standard Usage

from signum import sign # Obligatory for all examples

print(sign(-10**100))       # -1
print(sign(3.14))           #  1
print(sign(float('-nan')))  # math.nan

from decimal import Decimal
print(sign(Decimal("0.0"))) #  0

Advanced Usage (New features since v1.1.0)

☢️ Attention: Contract Programming!

For productivity reasons, keyword argument values are not checked by the sign function. It is your responsibility to:

• Pass a callable with one argument for preprocess (must return None or a tuple).
• Pass a tuple for if_exc.
• All calculations implied by these arguments do not result in additional exceptions or faults.

Passing incorrect values to these parameters may lead to undefined behavior or faults.

⚡ Custom Pre-processing with preprocess

With preprocess keyword argument, you can pass a callable to transform the input. Default: preprocess=None (no preprocessing).

The callable will be called with the positional argument of sign. It should support a special return protocol:

• Return None: sign proceed with usual calculation.
• Return (value,): sign proceed with calculation using value as an argument. Why a tuple? Use (None,) to return None as a value (usually raises TypeError).
• Return (any, result): Early Exit. Immediately return result as the final answer of sign. any is ignored.

from signum import sign # Obligatory for all examples

# Convert str to float; uses lambda as callable
sign('5.0', preprocess=lambda a: (float(a),)) # Returns 1 instead of `TypeError` exception

# Treat small number as zero through argument replacement only
EPS = 1e-9
sign(-.187e-17, preprocess=lambda a: (0 if abs(a) < EPS else a,)) # Returns 0 (instead of -1)

# Treat small number as zero through argument or result replacement; uses variable as callable
ppf1 = lambda x: (x, 0) if abs(x) < EPS else (x,)
sign(-.187e-17, preprocess=ppf1) # Returns 0 (instead of -1)

# Extract number from string, replace only string argument; supplies function as callable
import re
numeric_finder = re.compile(r"[-+]?(?:\d+\.\d*|\.\d+|\d+)(?:[eE][-+]?\d+)?")

def n_extract(s):
    if isinstance(s, str):
        match = numeric_finder.search(s)
        return (float(match.group()),) if match else None
    return None

sign("☠️15 men on the dead man's chest☠️", preprocess=n_extract) # Returns sign(15) == 1

# Do you want sign(complex) instead of `TypeError` exception?
def c_prep(z):
    if z == 0 or not isinstance(z, complex): return None
    # complex z != 0
    return (0, z/abs(z))

sign(-1+1j, preprocess=c_prep) # Returns (-0.7071067811865475+0.7071067811865475j)

# numpy flavor: float result for float or Decimal argument; uses recursive call of sign
from decimal import Decimal
ppf2 = lambda a: (a, float(sign(a))) if isinstance(a, (float, Decimal)) else None
sign(-5.0, preprocess=ppf2) # Returns -1.0 (instead of -1)

🛡️ Exception Safety with if_exc

With this keyword, you can avoid try-except blocks. If sign() encounters an incompatible type, it will return your fallback value instead of raising a TypeError. if_exc should be a tuple that permits you to pass None as the fallback value through if_exc=(None,). (Default if_exc=None is totally different).

from signum import sign # Obligatory for all examples

sign("not a number", if_exc=(-2,)) # Returns -2 instead of `TypeError` exception

You can use both keyword arguments at once

With preprocess, you replace arguments (or results) in specific cases, while if_exc prevents exceptions for all that remains.

📊 Performance & Quality Assurance

Benchmark Results

Versions 1.1.0+ maintain near-zero overhead (+0.8% latency) despite adding logic for new arguments. See details in the "Benchmarking" section in README for tests.

Reliability

• Memory Safety: Verified with long-run leak tests (0 bytes leaked over 4M iterations).
• Test Coverage: 92 validation cases (up from 51 in v1.0.2).

License

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

Author

Alexandru Colesnicov: GitHub Profile