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

Overview

Eval results

Files

Checking Functions

Name: tessl/pypi-fastnumbers
Author: tessl

Validation functions that test whether inputs can be converted to specific numeric types without performing the actual conversion. These functions are optimized for speed and enable conditional processing, input validation, and type checking workflows.

Capabilities

Real Number Checking

Tests whether input can be converted to either an integer or float, providing the most general numeric validation.

def check_real(
    x,
    *,
    consider=None,
    inf=NUMBER_ONLY,
    nan=NUMBER_ONLY,
    allow_underscores=False
) -> bool:
    """
    Check if input can be converted to int or float.

    Parameters:
    - x: Input to check (any type)
    - consider: Restrict checking to STRING_ONLY, NUMBER_ONLY, or None (both)
    - inf: How to handle infinity (NUMBER_ONLY, STRING_ONLY, ALLOWED, DISALLOWED)
    - nan: How to handle NaN (NUMBER_ONLY, STRING_ONLY, ALLOWED, DISALLOWED)
    - allow_underscores: Allow underscores in numeric strings (default: False)

    Returns:
    - bool: True if convertible to int or float, False otherwise
    """

Usage Examples

from fastnumbers import check_real, STRING_ONLY, NUMBER_ONLY, ALLOWED, DISALLOWED

# Basic checking
check_real('123')      # True
check_real('123.45')   # True
check_real(42)         # True
check_real(3.14)       # True
check_real('invalid')  # False
check_real([1, 2, 3])  # False

# Type filtering
check_real('123', consider=STRING_ONLY)   # True
check_real(123, consider=STRING_ONLY)     # False
check_real('123', consider=NUMBER_ONLY)   # False
check_real(123, consider=NUMBER_ONLY)     # True

# Special value handling
check_real('inf')                      # False (NUMBER_ONLY default)
check_real('inf', inf=ALLOWED)         # True
check_real(float('inf'))               # True (numeric inf)
check_real('inf', inf=STRING_ONLY)     # True
check_real(float('inf'), inf=STRING_ONLY)  # False

# Unicode and formatting
check_real('\u2164')      # True (Roman numeral V)
check_real('1_000', allow_underscores=True)  # True
check_real('1_000')       # False (underscores not allowed by default)

Float Checking

Tests whether input can be specifically converted to a float, with optional strict mode for more precise validation.

def check_float(
    x,
    *,
    consider=None,
    inf=NUMBER_ONLY,
    nan=NUMBER_ONLY,
    strict=False,
    allow_underscores=False
) -> bool:
    """
    Check if input can be converted to float.

    Parameters:
    - x: Input to check (any type)
    - consider: Restrict checking to STRING_ONLY, NUMBER_ONLY, or None (both)
    - inf: How to handle infinity (NUMBER_ONLY, STRING_ONLY, ALLOWED, DISALLOWED)
    - nan: How to handle NaN (NUMBER_ONLY, STRING_ONLY, ALLOWED, DISALLOWED)
    - strict: Enable strict float checking (default: False)
    - allow_underscores: Allow underscores in numeric strings (default: False)

    Returns:
    - bool: True if convertible to float, False otherwise
    """

Usage Examples

from fastnumbers import check_float

# Basic checking
check_float('123.45')    # True
check_float('123')       # True (int strings can become floats)
check_float(42)          # True (ints can become floats)
check_float('1e5')       # True (scientific notation)
check_float('invalid')   # False

# Strict mode
check_float('123', strict=False)    # True
check_float('123', strict=True)     # False (not a "true" float)
check_float('123.0', strict=True)   # True

# Special formatting
check_float('1.23e-4')     # True
check_float('.5')          # True
check_float('5.')          # True
check_float('  42.0  ')    # True (whitespace ignored)

Integer Checking

Tests whether input can be converted to an integer, with support for different number bases.

def check_int(
    x,
    *,
    consider=None,
    base=0,
    allow_underscores=False
) -> bool:
    """
    Check if input can be converted to int.

    Parameters:
    - x: Input to check (any type)
    - consider: Restrict checking to STRING_ONLY, NUMBER_ONLY, or None (both)
    - base: Number base for checking (0 for auto-detect, 2-36, default: 0)
    - allow_underscores: Allow underscores in numeric strings (default: False)

    Returns:
    - bool: True if convertible to int, False otherwise
    """

Usage Examples

from fastnumbers import check_int

# Basic checking
check_int('123')       # True
check_int(456)         # True
check_int('123.45')    # False (has decimal part)
check_int(78.0)        # True (whole number float)
check_int(78.5)        # False (fractional part)

# Base checking
check_int('ff', base=16)      # True (hex)
check_int('1010', base=2)     # True (binary)
check_int('123', base=8)      # True (octal)
check_int('gg', base=16)      # False (invalid hex)

# Auto-detection (base=0)
check_int('0xff')      # True (hex prefix)
check_int('0b1010')    # True (binary prefix)
check_int('0o123')     # True (octal prefix)

# Type filtering
check_int('123', consider=STRING_ONLY)   # True
check_int(123, consider=STRING_ONLY)     # False

Integer-like Checking

Tests whether input represents an integer-like value (whole numbers), even if stored as float or string.

def check_intlike(
    x,
    *,
    consider=None,
    allow_underscores=False
) -> bool:
    """
    Check if input represents an integer-like value.

    Parameters:
    - x: Input to check (any type)
    - consider: Restrict checking to STRING_ONLY, NUMBER_ONLY, or None (both)
    - allow_underscores: Allow underscores in numeric strings (default: False)

    Returns:
    - bool: True if represents whole number, False otherwise
    """

Usage Examples

from fastnumbers import check_intlike

# Basic checking
check_intlike('123')      # True
check_intlike('123.0')    # True (whole number)
check_intlike('123.45')   # False (has fractional part)
check_intlike(456)        # True
check_intlike(456.0)      # True (whole number float)
check_intlike(456.7)      # False (has fractional part)

# Edge cases
check_intlike('0')        # True
check_intlike('-123')     # True
check_intlike('+456')     # True
check_intlike('1e2')      # True (100.0)
check_intlike('1e-1')     # False (0.1)

# Formatting
check_intlike('  123  ')  # True (whitespace ignored)
check_intlike('1_000', allow_underscores=True)  # True

Consider Parameter Options

The consider parameter allows filtering by input type:

None (default): Check both string and numeric inputs
STRING_ONLY: Only validate string inputs, return False for numbers
NUMBER_ONLY: Only validate numeric inputs, return False for strings

from fastnumbers import check_real, STRING_ONLY, NUMBER_ONLY

# Mixed checking (default)
check_real('123')    # True
check_real(123)      # True

# String-only checking
check_real('123', consider=STRING_ONLY)    # True
check_real(123, consider=STRING_ONLY)      # False

# Number-only checking  
check_real('123', consider=NUMBER_ONLY)    # False
check_real(123, consider=NUMBER_ONLY)      # True

Special Value Handling

The inf and nan parameters control how infinity and NaN values are treated:

NUMBER_ONLY (default): Allow numeric inf/nan, reject string inf/nan
STRING_ONLY: Allow string inf/nan, reject numeric inf/nan
ALLOWED: Allow both string and numeric inf/nan
DISALLOWED: Reject all inf/nan values

from fastnumbers import check_float, ALLOWED, DISALLOWED, STRING_ONLY

# Default behavior (NUMBER_ONLY)
check_float(float('inf'))    # True
check_float('inf')           # False

# Allow all inf/nan
check_float('inf', inf=ALLOWED)        # True
check_float(float('inf'), inf=ALLOWED) # True

# Disallow all inf/nan
check_float(float('inf'), inf=DISALLOWED)  # False
check_float('inf', inf=DISALLOWED)         # False

# String inf/nan only
check_float('inf', inf=STRING_ONLY)        # True
check_float(float('inf'), inf=STRING_ONLY) # False

Deprecated Functions

The following functions are maintained for backward compatibility but are deprecated in favor of the newer check_* equivalents:

isreal (Deprecated)

def isreal(
    x,
    *,
    str_only=False,
    num_only=False,
    allow_inf=False,
    allow_nan=False,
    allow_underscores=True
) -> bool:
    """
    DEPRECATED: Use check_real() instead.
    
    Check if input can be converted to int or float.
    
    Parameters:
    - x: Input to check (any type)
    - str_only: Only check string inputs (default: False)
    - num_only: Only check numeric inputs (default: False)
    - allow_inf: Allow infinity values (default: False)
    - allow_nan: Allow NaN values (default: False)
    - allow_underscores: Allow underscores in numeric strings (default: True)
    
    Returns:
    - bool: True if convertible to int or float, False otherwise
    """

isfloat (Deprecated)

def isfloat(
    x,
    *,
    str_only=False,
    num_only=False,
    allow_inf=False,
    allow_nan=False,
    allow_underscores=True
) -> bool:
    """
    DEPRECATED: Use check_float() instead.
    
    Check if input can be converted to float.
    
    Parameters:
    - x: Input to check (any type)
    - str_only: Only check string inputs (default: False)
    - num_only: Only check numeric inputs (default: False)
    - allow_inf: Allow infinity values (default: False)
    - allow_nan: Allow NaN values (default: False)
    - allow_underscores: Allow underscores in numeric strings (default: True)
    
    Returns:
    - bool: True if convertible to float, False otherwise
    """

isint (Deprecated)

def isint(
    x,
    *,
    str_only=False,
    num_only=False,
    base=0,
    allow_underscores=True
) -> bool:
    """
    DEPRECATED: Use check_int() instead.
    
    Check if input can be converted to int.
    
    Parameters:
    - x: Input to check (any type)
    - str_only: Only check string inputs (default: False)
    - num_only: Only check numeric inputs (default: False)
    - base: Number base for checking (0 for auto-detect, 2-36, default: 0)
    - allow_underscores: Allow underscores in numeric strings (default: True)
    
    Returns:
    - bool: True if convertible to int, False otherwise
    """

isintlike (Deprecated)

def isintlike(
    x,
    *,
    str_only=False,
    num_only=False,
    allow_underscores=True
) -> bool:
    """
    DEPRECATED: Use check_intlike() instead.
    
    Check if input represents an integer-like value.
    
    Parameters:
    - x: Input to check (any type)
    - str_only: Only check string inputs (default: False)
    - num_only: Only check numeric inputs (default: False)
    - allow_underscores: Allow underscores in numeric strings (default: True)
    
    Returns:
    - bool: True if represents whole number, False otherwise
    """

Performance Characteristics

These checking functions are highly optimized and significantly faster than attempting conversion and catching exceptions. They use the same underlying C++ implementation as conversion functions but skip the actual conversion step, making them ideal for: