tessl/pypi-fastnumbers

Super-fast and clean conversions to numbers with flexible error handling and high-performance drop-in replacements for Python's built-in number conversion functions.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

fastnumbers

Name: tessl/pypi-fastnumbers
Author: tessl

Super-fast and clean conversions to numbers with flexible error handling and high-performance drop-in replacements for Python's built-in number conversion functions. The library provides three main categories of functionality: error-handling functions for robust conversion with customizable fallback behaviors, checking functions for validating numeric convertibility, and optimized drop-in replacements for Python's built-in int() and float() functions.

Package Information

Package Name: fastnumbers
Language: Python
Installation: pip install fastnumbers
Version: 4.0.1

Core Imports

import fastnumbers

Common usage patterns:

from fastnumbers import try_float, try_int, try_real, try_forceint
from fastnumbers import check_float, check_int, check_real, check_intlike
from fastnumbers import fast_real, fast_float, fast_int, fast_forceint
from fastnumbers import int, float, real, query_type
from fastnumbers import RAISE, INPUT, ALLOWED, DISALLOWED, STRING_ONLY, NUMBER_ONLY
from fastnumbers import __version__

For legacy compatibility:

from fastnumbers import isfloat, isint, isintlike, isreal  # Deprecated

Basic Usage

from fastnumbers import try_float, try_int, check_real, RAISE

# Error-handling conversion with default fallback
result = try_float('123.45')  # Returns 123.45
result = try_float('invalid')  # Returns 'invalid' (input as-is)

# Error-handling conversion with custom fallback
result = try_float('invalid', on_fail=0.0)  # Returns 0.0
result = try_int('42', on_fail=RAISE)  # Raises ValueError if invalid

# High-speed checking before conversion
if check_real('123.45'):
    value = float('123.45')

# Unicode numeric characters supported
result = try_float('\u2164')  # Roman numeral V -> 5.0
result = try_int('\u2466')    # Circled 7 -> 7

Architecture

fastnumbers is implemented in C++ with Python bindings for maximum performance. The library uses a hierarchical approach:

Selector Constants: Control function behavior (RAISE, INPUT, ALLOWED, etc.)
Type System: Extensive use of overloads and generic types for flexible return types
Error Handling: Multiple strategies for handling conversion failures and type errors
Unicode Support: Full support for Unicode numeric characters and various number formats

The architecture leverages optimized C++ algorithms including fast_float for float conversions and heuristic-based integer parsing, making it significantly faster than Python's built-in conversion functions while maintaining compatibility and adding flexibility.

Capabilities

Error-Handling Functions

Robust number conversion functions with customizable error handling, supporting various fallback strategies including returning input as-is, providing default values, calling transformation functions, or raising exceptions.

def try_real(x, *, inf=ALLOWED, nan=ALLOWED, on_fail=INPUT, on_type_error=RAISE, coerce=True, allow_underscores=False): ...
def try_float(x, *, inf=ALLOWED, nan=ALLOWED, on_fail=INPUT, on_type_error=RAISE, allow_underscores=False): ...
def try_int(x, *, on_fail=INPUT, on_type_error=RAISE, base=10, allow_underscores=False): ...
def try_forceint(x, *, on_fail=INPUT, on_type_error=RAISE, allow_underscores=False): ...

Error-Handling Functions

Checking Functions

Validation functions to test whether inputs can be converted to specific numeric types without performing the actual conversion, enabling conditional processing and input validation.

def check_real(x, *, consider=None, inf=NUMBER_ONLY, nan=NUMBER_ONLY, allow_underscores=False) -> bool: ...
def check_float(x, *, consider=None, inf=NUMBER_ONLY, nan=NUMBER_ONLY, strict=False, allow_underscores=False) -> bool: ...
def check_int(x, *, consider=None, base=0, allow_underscores=False) -> bool: ...
def check_intlike(x, *, consider=None, allow_underscores=False) -> bool: ...

Checking Functions

High-Performance Functions

Optimized drop-in replacement functions that provide the same functionality as Python's built-in conversion functions but with significantly better performance and additional features like custom default values and key transformations.

def fast_real(x, default=None, *, raise_on_invalid=False, inf=None, nan=None, on_fail=None, key=None, coerce=True, allow_underscores=True): ...
def fast_float(x, default=None, *, raise_on_invalid=False, inf=None, nan=None, on_fail=None, key=None, allow_underscores=True): ...
def fast_int(x, default=None, *, raise_on_invalid=False, base=None, on_fail=None, key=None, allow_underscores=True): ...
def fast_forceint(x, default=None, *, raise_on_invalid=False, on_fail=None, key=None, allow_underscores=True): ...

High-Performance Functions

Built-in Replacements

Direct drop-in replacements for Python's built-in int(), float(), and additional real() function that behave identically to the originals but with improved performance characteristics.

def int(x=0, base=10): ...
def float(x=0.0): ...
def real(x=0.0, *, coerce=True): ...

Built-in Replacements

Utility Functions

Additional utility functions for type analysis and deprecated functions maintained for backward compatibility.

def query_type(x, *, allow_inf=False, allow_nan=False, coerce=False, allowed_types=None, allow_underscores=False): ...

Utility Functions

Types

Selector Constants

ALLOWED: ALLOWED_T      # Allow inf/nan values
DISALLOWED: DISALLOWED_T  # Disallow inf/nan values  
INPUT: INPUT_T          # Return input as-is on failure
RAISE: RAISE_T          # Raise exception on failure
STRING_ONLY: STRING_ONLY_T  # Consider only string types
NUMBER_ONLY: NUMBER_ONLY_T  # Consider only numeric types

# Type aliases for parameter types
ConsiderType = Union[STRING_ONLY_T, NUMBER_ONLY_T, None]
InfNanCheckType = Union[STRING_ONLY_T, NUMBER_ONLY_T, ALLOWED_T, DISALLOWED_T]

Input Types

from typing import Union, TypeVar
from typing_extensions import Protocol

# Protocol types for duck typing
class HasIndex(Protocol):
    def __index__(self) -> int: ...

class HasInt(Protocol):
    def __int__(self) -> int: ...

class ItWillFloat(Protocol):
    def __float__(self) -> float: ...

# Union of all acceptable input types  
InputType = Union[int, float, str, bytes, bytearray, HasIndex, HasInt, ItWillFloat]
FastInputType = TypeVar("FastInputType", int, float, ItWillFloat, HasIndex, HasInt, str, bytes, bytearray)
AnyInputType = TypeVar("AnyInputType")

Version Information

__version__: str  # Package version string

Error Handling Patterns

All try_* functions support multiple error handling strategies:

INPUT (default): Return the original input unchanged
RAISE: Raise a ValueError with descriptive message
Custom value: Return any specified default value
Callable: Call a function with the input and return its result

The on_type_error parameter handles cases where the input type is completely invalid (default: RAISE), while on_fail handles conversion failures (default: INPUT).