fastnumbers: Super-fast and clean conversions to numbers

Common errors

• error: command '/usr/bin/clang' failed with exit code 1

  cause Installation fails on macOS (and potentially other Unix-like systems) when trying to compile the C extension, often due to incompatibility between older `fastnumbers` versions and newer Python versions (e.g., Python 3.9+).
  fix Upgrade `fastnumbers` to version 3.1.0 or higher (`pip install --upgrade fastnumbers`). If an upgrade is not possible, consider using a Python environment with version 3.8 or lower.

• TypeError: isinstance() arg 2 must be a type or tuple of types

  cause This error occurs when attempting to use `fastnumbers.int` or `fastnumbers.float` (imported as drop-in replacements for built-ins) in `isinstance()` checks. These are functions, not type objects.
  fix For type checking with `isinstance()`, use Python's built-in types by explicitly importing `builtins` or referencing them directly: `import builtins; isinstance(value, builtins.int)` or `isinstance(value, int)`.

• ValueError: invalid literal for float(): 'some_string'

  cause You are attempting to convert an input string that cannot be parsed as a number, and the `fastnumbers` function is configured to raise a `ValueError` on failure (e.g., `on_fail=RAISE` or `raise_on_invalid=True` in deprecated functions).
  fix Modify the `on_fail` parameter (or `default` for deprecated functions) to handle invalid inputs gracefully. Options include `on_fail=INPUT` (returns original input), `default=0.0` (returns a specific value), or `on_fail=my_custom_handler` (calls a function). Example: `try_float('bad_input', default=0.0)`.

Warnings

• breaking As of fastnumbers version 4.0.0, Python versions older than 3.7 are no longer supported. Ensure your environment uses Python 3.7 or newer.
  Fix: Upgrade your Python interpreter to version 3.7 or later.
• deprecated Functions like `fast_real`, `fast_float`, `fast_int`, `fast_forceint`, `isreal`, `isfloat`, `isint`, and `isintlike` were deprecated in version 4.0.0. While they are still available, new development should use their more flexible replacements: `try_real`, `try_float`, `try_int`, `try_forceint`, `check_real`, `check_float`, `check_int`, and `check_intlike` respectively.
  Fix: Refactor code to use the `try_*` functions for error-handling conversions and `check_*` functions for type checking.
• gotcha Directly calling `fastnumbers.int()` or `fastnumbers.float()` (e.g., `import fastnumbers; fastnumbers.int('5')`) is slower than importing them directly (e.g., `from fastnumbers import int; int('5')`). This is due to Python's internal namespace lookup overhead.
  Fix: Always import the specific functions you intend to use directly, e.g., `from fastnumbers import int` or `from fastnumbers import float`.
• gotcha The `denoise` option, available in some conversion functions, adds additional overhead to the calculation. While it provides `decimal.Decimal`-like accuracy for floats (especially from strings), it is significantly slower than conversions without `denoise`.
  Fix: Evaluate the trade-off between speed and the need for high-precision decimal conversion. Use `denoise` only when precise decimal behavior is critical and the performance impact is acceptable.
• gotcha The `float` and `int` functions provided by `fastnumbers` (e.g., `from fastnumbers import float`) are not class types like Python's built-in `float` and `int`. Therefore, they cannot be used with `isinstance()` (e.g., `isinstance(9.4, fastnumbers.float)` will raise a `TypeError`).
  Fix: When performing `isinstance` checks, use the built-in types explicitly: `import builtins; isinstance(9.4, builtins.float)`.

Install

• pip install fastnumbers Install stable version

Imports

• try_float

  from fastnumbers import try_float

  Recommended for fast float conversion with error handling.
• try_int

  from fastnumbers import try_int

  Recommended for fast integer conversion with error handling.
• float (replacement)
  wrong:

  import fastnumbers; fastnumbers.float('123.45')

  correct:

  from fastnumbers import float

  This provides a faster drop-in replacement for the built-in `float`, but calling `fastnumbers.float()` is slower due to Python's namespace lookup. Note that this is a function, not a class, so `isinstance()` checks will not work directly.
• fast_float (deprecated)
  wrong:

  from fastnumbers import fast_float

  correct:

  from fastnumbers import try_float

  The `fast_float` function was deprecated in v4.0.0; `try_float` is the preferred replacement with a more flexible API.

Quickstart

This quickstart demonstrates the core functionality of `fastnumbers` using `try_float` and `try_int` for robust number conversions. It shows how to handle unconvertible inputs by returning the original input (default), a specified default value, raising a `ValueError`, or executing a custom callback function.

from fastnumbers import try_float, try_int, RAISE, INPUT

# Basic conversion with default error handling (returns input on failure)
print(f"'123.45' -> {try_float('123.45')}")
print(f"'abc' -> {try_float('abc')}")

# Convert to float, returning a default value on failure
print(f"'abc' with default=0.0 -> {try_float('abc', default=0.0)}")

# Convert to int, raising an error on failure
try:
    print(f"'123' -> {try_int('123')}")
    print(f"'45.67' -> {try_int('45.67')}") # Truncates float strings to int
    print(f"'xyz' -> {try_int('xyz', on_fail=RAISE)}")
except ValueError as e:
    print(f"'xyz' with on_fail=RAISE -> {e}")

# Convert to float, using a custom function on failure
def handle_fail(val):
    return f"Failed to convert: {val}"
print(f"'bad_num' with custom handler -> {try_float('bad_num', on_fail=handle_fail)}")