{"id":7218,"library":"fastnumbers","title":"fastnumbers: Super-fast and clean conversions to numbers","description":"fastnumbers is a Python C extension designed for super-fast and clean conversions of strings and other types to numbers. It provides convenient error handling, functions to check if an input can be converted, and drop-in replacements for built-in `int` and `float` that are often faster. The library is actively maintained, with version 5.1.1 being the latest stable release, and typically follows a regular release cadence as needed for bug fixes and improvements.","status":"active","version":"5.1.1","language":"en","source_language":"en","source_url":"https://github.com/SethMMorton/fastnumbers","tags":["numbers","conversion","performance","float","int","parsing","utility"],"install":[{"cmd":"pip install fastnumbers","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"Recommended for fast float conversion with error handling.","symbol":"try_float","correct":"from fastnumbers import try_float"},{"note":"Recommended for fast integer conversion with error handling.","symbol":"try_int","correct":"from fastnumbers import try_int"},{"note":"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.","wrong":"import fastnumbers; fastnumbers.float('123.45')","symbol":"float (replacement)","correct":"from fastnumbers import float"},{"note":"The `fast_float` function was deprecated in v4.0.0; `try_float` is the preferred replacement with a more flexible API.","wrong":"from fastnumbers import fast_float","symbol":"fast_float (deprecated)","correct":"from fastnumbers import try_float"}],"quickstart":{"code":"from fastnumbers import try_float, try_int, RAISE, INPUT\n\n# Basic conversion with default error handling (returns input on failure)\nprint(f\"'123.45' -> {try_float('123.45')}\")\nprint(f\"'abc' -> {try_float('abc')}\")\n\n# Convert to float, returning a default value on failure\nprint(f\"'abc' with default=0.0 -> {try_float('abc', default=0.0)}\")\n\n# Convert to int, raising an error on failure\ntry:\n    print(f\"'123' -> {try_int('123')}\")\n    print(f\"'45.67' -> {try_int('45.67')}\") # Truncates float strings to int\n    print(f\"'xyz' -> {try_int('xyz', on_fail=RAISE)}\")\nexcept ValueError as e:\n    print(f\"'xyz' with on_fail=RAISE -> {e}\")\n\n# Convert to float, using a custom function on failure\ndef handle_fail(val):\n    return f\"Failed to convert: {val}\"\nprint(f\"'bad_num' with custom handler -> {try_float('bad_num', on_fail=handle_fail)}\")","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python interpreter to version 3.7 or later.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Refactor code to use the `try_*` functions for error-handling conversions and `check_*` functions for type checking.","message":"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.","severity":"deprecated","affected_versions":">=4.0.0"},{"fix":"Always import the specific functions you intend to use directly, e.g., `from fastnumbers import int` or `from fastnumbers import float`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"All versions with `denoise` option"},{"fix":"When performing `isinstance` checks, use the built-in types explicitly: `import builtins; isinstance(9.4, builtins.float)`.","message":"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`).","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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+).","error":"error: command '/usr/bin/clang' failed with exit code 1"},{"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)`.","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.","error":"TypeError: isinstance() arg 2 must be a type or tuple of types"},{"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)`.","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).","error":"ValueError: invalid literal for float(): 'some_string'"}]}