{"author":null,"author_email":"\"Seth M. Morton\" ","bugtrack_url":null,"classifiers":["Development Status :: 5 - Production/Stable","Intended Audience :: Developers","Intended Audience :: Financial and Insurance Industry","Intended Audience :: Information Technology","Intended Audience :: Science/Research","Intended Audience :: System Administrators","License :: OSI Approved :: MIT License","Natural Language :: English","Operating System :: OS Independent","Programming Language :: Python :: 3","Programming Language :: Python :: 3.10","Programming Language :: Python :: 3.11","Programming Language :: Python :: 3.12","Programming Language :: Python :: 3.13","Programming Language :: Python :: 3.8","Programming Language :: Python :: 3.9","Topic :: Scientific/Engineering :: Information Analysis","Topic :: Text Processing","Topic :: Text Processing :: Filters","Topic :: Utilities"],"description":"fastnumbers\n===========\n\n.. image:: https://img.shields.io/pypi/v/fastnumbers.svg\n :target: https://pypi.org/project/fastnumbers/\n\n.. image:: https://img.shields.io/pypi/pyversions/fastnumbers.svg\n :target: https://pypi.org/project/fastnumbers/\n\n.. image:: https://img.shields.io/pypi/l/fastnumbers.svg\n :target: https://github.com/SethMMorton/fastnumbers/blob/main/LICENSE\n\n.. image:: https://github.com/SethMMorton/fastnumbers/workflows/Tests/badge.svg\n :target: https://github.com/SethMMorton/fastnumbers/actions\n\n.. image:: https://codecov.io/gh/SethMMorton/fastnumbers/branch/main/graph/badge.svg\n :target: https://codecov.io/gh/SethMMorton/fastnumbers\n\n.. image:: https://img.shields.io/pypi/dw/fastnumbers.svg\n :target: https://pypi.org/project/fastnumbers/\n\nSuper-fast and clean conversions to numbers.\n\n - Source Code: https://github.com/SethMMorton/fastnumbers\n - Downloads: https://pypi.org/project/fastnumbers/\n - Documentation: https://fastnumbers.readthedocs.io/\n - `Quick Start`_\n - `Timing`_\n - `High-level Algorithm`_\n - `How To Run Tests`_\n - `History`_\n\n``fastnumbers`` is a module with the following three objectives (in order\nof decreasing importance as to why the module was created):\n\n #. Provide a set of convenience functions that wrap calls to\n ``int`` and ``float`` and provides easy, concise, powerful, fast\n and flexible error handling.\n #. Provide a set of functions that can be used to rapidly identify if\n an input *could* be converted to *int* or *float*.\n #. Provide drop-in replacements for the Python built-in ``int`` and\n ``float`` that are on par or faster with the Python equivalents\n (see the `Timing`_ section for details). These functions\n should behave *identically* to the Python built-ins except for a few\n specific corner-cases as mentioned in the\n `API documentation for those functions `_.\n\n - **PLEASE** read the quick start for these functions to fully\n understand the caveats before using them.\n\n**What kind of speedups can you expect?** Here are some highlights, but please\nsee the `Timing`_ section for the raw data if you want details.\n\n - Up to 2x faster conversion of strings to integers than the built-in\n ``int()`` function\n - Up to 5x faster conversion of strings to floats than the built-in\n ``float()`` function (possibly greater for very long strings)\n - Up to 10x faster handling of errors during conversion than using\n user-side error handling\n - On top of the above, operations to convert a list of strings\n (with the ``map`` option or ``try_array`` function) is 2x faster\n than the equivalent list comprehension.\n\n**NOTICE**: As of ``fastnumbers`` version 4.0.0, only Python >= 3.7 is\nsupported.\n\n**NOTICE**: As of ``fastnumbers`` version 4.0.0, the functions ``fast_real``,\n``fast_float``, ``fast_int``, ``fast_forceint``, ``isreal``, ``isfloat``,\n``isint``, and ``isintlike`` have been deprecated and are replaced with\n``try_real``, ``try_float``, ``try_int``, ``try_forceint``, ``check_real``,\n``check_float``, ``check_int``, and ``check_intlike``, respectively. These\nnew functions have more flexible APIs and have names that better reflect\nthe intent of the functions. The old functions can still be used (they will\n*never* be removed from ``fastnumbers``), but the new ones should be\npreferred for new development.\n\n**NOTICE**: As of ``fastnumbers`` version 4.0.0, ``query_type`` now sets\n``allow_underscores`` to ``False`` by default instead of ``True``.\n\nQuick Start\n-----------\n\n- `Error-handling Functions`_\n- `Checking Functions`_\n- `Drop-in Replacement Functions`_\n\nThere are three broad categories of functions exposed by ``fastnumbers``.\nThe below quick start will demonstrate each of these categories. The\nquick start is \"by example\", and will show a sample interactive session\nusing the ``fastnumbers`` API.\n\nError-Handling Functions\n++++++++++++++++++++++++\n\n- `Error-handling function API `_\n- `Fast operations on lists and other iterables`_\n- `About the on_fail option`_\n- `About the denoise option`_\n\n``try_float`` will be used to demonstrate the functionality of the\n``try_*`` functions.\n\n.. code-block:: python\n\n >>> from fastnumbers import RAISE, try_float\n >>> # Convert string to a float\n >>> try_float('56.07')\n 56.07\n >>> # Integers are converted to floats\n >>> try_float(54)\n 54.0\n >>>\n >>> # Unconvertable string returned as-is by default\n >>> try_float('bad input')\n 'bad input'\n >>> # Unconvertable strings can trigger a default value\n >>> try_float('bad input', on_fail=0)\n 0\n >>>\n >>> # One can ask inf or nan to be substituted with another value\n >>> try_float('nan')\n nan\n >>> try_float('nan', nan=0.0)\n 0.0\n >>> try_float(float('nan'), nan=0.0)\n 0.0\n >>> try_float('56.07', nan=0.0)\n 56.07\n >>>\n >>> # The default built-in float behavior can be triggered with\n >>> # RAISE given to \"on_fail\".\n >>> try_float('bad input', on_fail=RAISE) #doctest: +IGNORE_EXCEPTION_DETAIL\n Traceback (most recent call last):\n ...\n ValueError: invalid literal for float(): bad input\n >>>\n >>> # A function can be used to return an alternate value for invalid input\n >>> try_float('bad input', on_fail=len)\n 9\n >>> try_float(54, on_fail=len)\n 54.0\n >>>\n >>> # Single unicode characters can be converted.\n >>> try_float('\\u2164') # Roman numeral 5 (V)\n 5.0\n >>> try_float('\\u2466') # 7 enclosed in a circle\n 7.0\n\n``try_int`` behaves the same as ``try_float``, but for integers.\n\n.. code-block:: python\n\n >>> from fastnumbers import try_int\n >>> try_int('1234')\n 1234\n >>> try_int('\\u2466')\n 7\n\n``try_real`` is like ``try_float`` or ``try_int`` depending\non if there is any fractional component of thi return value.\n\n.. code-block:: python\n\n >>> from fastnumbers import try_real\n >>> try_real('56')\n 56\n >>> try_real('56.0')\n 56\n >>> try_real('56.0', coerce=False)\n 56.0\n >>> try_real('56.07')\n 56.07\n >>> try_real(56.07)\n 56.07\n >>> try_real(56.0)\n 56\n >>> try_real(56.0, coerce=False)\n 56.0\n\n``try_forceint`` always returns an integer.\n\n.. code-block:: python\n\n >>> from fastnumbers import try_forceint\n >>> try_forceint('56')\n 56\n >>> try_forceint('56.0')\n 56\n >>> try_forceint('56.07')\n 56\n >>> try_forceint(56.07)\n 56\n\nFast operations on lists and other iterables\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nEach of the ``try_*`` functions have a ``map`` option causes the function\nto accept an iterable of items to convert and returns a list. Using\n``try_float`` as an example, the following are all functionally equivalent.\n\n.. code-block:: python\n\n >>> from fastnumbers import try_float\n >>> iterable = [\"5\", \"4.5\", \"34567.6\", \"32\"]\n >>> try_float(iterable, map=list) == list(map(try_float, iterable))\n True\n >>> try_float(iterable, map=list) == [try_float(x) for x in iterable]\n True\n >>> try_float(iterable, map=list) == list(try_float(iterable, map=True))\n True\n\nThe difference is that the ``map`` option is 2x the speed of the list\ncomprehension method, and 1.5x the speed of the ``map`` method. The reason\nis that it avoids Python function call overhead on each iteration. Note that\n*True* causes the function to return an iterator, and *list* causes it to\nreturn a ``list``. In practice the performance of these are similar\n(see `Timing`_ for raw data).\n\nIf you need to store your output in a ``numpy`` array, you can use\n``try_array`` to do this conversion directly. This function has some\nadditional handling for overflow that is not present in the other\n``fastnumbers`` functions that may come in handy when dealing with\n``numpy`` arrays.\n\n.. code-block:: python\n\n >>> from fastnumbers import try_array\n >>> import numpy as np\n >>> iterable = [\"5\", \"4.5\", \"34567.6\", \"32\"]\n >>> np.array_equal(np.array(try_float(iterable, map=list), dtype=np.float64), try_array(iterable))\n True\n\nYou will see about a 2x speedup of doing this in one step over converting\nto a list then converting that list to an array.\n\nAbout the ``on_fail`` option\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nThe ``on_fail`` option is a way for you to do *anything* in the event that\nthe given input cannot be converted to a number. It can\n\n* return given object as-is if set to ``fastnumbers.INPUT`` (this is the default)\n* raise a ``ValueError`` if set to ``fastnumbers.RAISE``\n* return a default value if given any non-callable object\n* call a function with the given object if given a single-argument callable\n\nBelow are a couple of ideas to get you thinking.\n\n**NOTE**:: There is also an ``on_type_error`` option that behaves the same as\n``on_fail`` except that a) it is triggered when the given object is of an\ninvalid type and b) the default value is ``fastnumbers.RAISE``, not\n``fastnumbers.INPUT``.\n\n.. code-block:: python\n\n >>> from fastnumbers import INPUT, RAISE, try_float\n >>> # You want to convert strings that can be converted to numbers, but\n >>> # leave the rest as strings. Use fastnumbers.INPUT (the default)\n >>> try_float('45.6')\n 45.6\n >>> try_float('invalid input')\n 'invalid input'\n >>> try_float('invalid input', on_fail=INPUT)\n 'invalid input'\n >>>\n >>>\n >>>\n >>> # You want to convert any invalid string to NaN\n >>> try_float('45.6', on_fail=float('nan'))\n 45.6\n >>> try_float('invalid input', on_fail=float('nan'))\n nan\n >>>\n >>>\n >>>\n >>> # Simple callable case, send the input through some function to generate a number.\n >>> try_float('invalid input', on_fail=lambda x: float(x.count('i'))) # count the 'i's\n 3.0\n >>>\n >>>\n >>>\n >>> # Suppose we know that our input could either be a number, or if not\n >>> # then we know we just have to strip off parens to get to the number\n >>> # e.g. the input could be '45' or '(45)'. Also, suppose that if it\n >>> # still cannot be converted to a number we want to raise an exception.\n >>> def strip_parens_and_try_again(x):\n ... return try_float(x.strip('()'), on_fail=RAISE)\n ...\n >>> try_float('45', on_fail=strip_parens_and_try_again)\n 45.0\n >>> try_float('(45)', on_fail=strip_parens_and_try_again)\n 45.0\n >>> try_float('invalid input', on_fail=strip_parens_and_try_again) #doctest: +IGNORE_EXCEPTION_DETAIL\n Traceback (most recent call last):\n ...\n ValueError: invalid literal for float(): invalid input\n >>>\n >>>\n >>>\n >>> # Suppose that whenever an invalid input is given, it needs to be\n >>> # logged and then a default value is returned.\n >>> def log_and_default(x, log_method=print, default=0.0):\n ... log_method(\"The input {!r} is not valid!\".format(x))\n ... return default\n ...\n >>> try_float('45', on_fail=log_and_default)\n 45.0\n >>> try_float('invalid input', on_fail=log_and_default)\n The input 'invalid input' is not valid!\n 0.0\n >>> try_float('invalid input', on_fail=lambda x: log_and_default(x, default=float('nan')))\n The input 'invalid input' is not valid!\n nan\n\nAbout the ``denoise`` option\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nThe ``denoise`` option is available on the ``try_real`` and ``try_forceint`` options.\nTo best understand its usage, consider the following native Python behavior:\n\n.. code-block:: python\n\n >>> int(3.453e21)\n 3452999999999999737856\n >>> int(float(\"3.453e21\"))\n 3452999999999999737856\n >>> # Most users would likely expect this result from decimal.Decimal\n >>> import decimal\n >>> int(decimal.Decimal(\"3.453e21\"))\n 3453000000000000000000\n >>> # But watch out, even decimal.Decimal doesn't help for float input\n >>> import decimal\n >>> int(decimal.Decimal(3.453e21))\n 3452999999999999737856\n\nBecause the conversion of a float to an int goes through the C ``double`` data type which\nhas inherent limitations on accuracy (See\n`this Stack Overflow question for examples `_)\nthe resulting ``int`` result has \"noise\" digits that are not part of the original float\nrepresentation.\n\nFor functions where this makes sense, ``fastnumbers`` provides the ``denoise`` option to\ngive you the results that ``decimal.Decimal`` would give for strings containing floats.\n\n.. code-block:: python\n\n >>> from fastnumbers import try_real\n >>> try_real(3.453e21)\n 3452999999999999737856\n >>> try_real(\"3.453e21\")\n 3452999999999999737856\n >>> try_real(3.453e21, denoise=True)\n 3453000000000000000000\n >>> try_real(\"3.453e21\", denoise=True)\n 3453000000000000000000\n\nTwo things to keep in mind:\n\n1. The ``denoise`` option adds additional overhead to the conversion calculation, so please consider\n the trade-offs between speed and accuracy when determining whether or not to use it. It is\n *significantly* faster than using ``decimal.Decimal``, but much slower than not using it at all.\n2. For string input, ``denoise`` will return results identical to ``decimal.Decimal``. For float\n input, ``denoise`` will return results that are accurate to about 15 digits (C ``double`` can\n only store 16 decimal digits, so this means that only the last possible digit may not be accurate).\n\nChecking Functions\n++++++++++++++++++\n\n- `Checking function API `_\n\n``check_float`` will be used to demonstrate the functionality of the\n``check_*`` functions. There is also the ``query_type`` function.\n\n.. code-block:: python\n\n >>> from fastnumbers import check_float\n >>> from fastnumbers import ALLOWED, DISALLOWED, NUMBER_ONLY, STRING_ONLY\n >>> # Check that a string can be converted to a float\n >>> check_float('56')\n True\n >>> check_float('56', strict=True)\n False\n >>> check_float('56.07')\n True\n >>> check_float('56.07 lb')\n False\n >>>\n >>> # Check if a given number is a float\n >>> check_float(56.07)\n True\n >>> check_float(56)\n False\n >>>\n >>> # Specify if only strings or only numbers are allowed\n >>> check_float(56.07, consider=STRING_ONLY)\n False\n >>> check_float('56.07', consider=NUMBER_ONLY)\n False\n >>>\n >>> # Customize handling for nan or inf (see API for more details)\n >>> check_float('nan')\n False\n >>> check_float('nan', nan=ALLOWED)\n True\n >>> check_float(float('nan'))\n True\n >>> check_float(float('nan'), nan=DISALLOWED)\n False\n\n``check_int`` works the same as ``check_float``, but for integers.\n\n.. code-block:: python\n\n >>> from fastnumbers import check_int\n >>> check_int('56')\n True\n >>> check_int(56)\n True\n >>> check_int('56.0')\n False\n >>> check_int(56.0)\n False\n\n``check_real`` is very permissive - any float or integer is accepted.\n\n.. code-block:: python\n\n >>> from fastnumbers import check_real\n >>> check_real('56.0')\n True\n >>> check_real('56')\n True\n >>> check_real(56.0)\n True\n >>> check_real(56)\n True\n\n``check_intlike`` checks if a number is \"int-like\", if it has no\nfractional component.\n\n.. code-block:: python\n\n >>> from fastnumbers import check_intlike\n >>> check_intlike('56.0')\n True\n >>> check_intlike('56.7')\n False\n >>> check_intlike(56.0)\n True\n >>> check_intlike(56.7)\n False\n\nThe ``query_type`` function can be used if you need to determine if\na value is one of many types, rather than whether or not it is one specific\ntype.\n\n.. code-block:: python\n\n >>> from fastnumbers import query_type\n >>> query_type('56.0')\n \n >>> query_type('56')\n \n >>> query_type(56.0)\n \n >>> query_type(56)\n \n >>> query_type(56.0, coerce=True)\n \n >>> query_type('56.0', allowed_types=(float, int))\n \n >>> query_type('hey')\n \n >>> query_type('hey', allowed_types=(float, int)) # returns None\n\nDrop-in Replacement Functions\n+++++++++++++++++++++++++++++\n\n- `Drop-in replacement function API `_\n\n**PLEASE** do not take it for granted that these functions will provide you\nwith a speedup - they may not. Every platform, compiler, and data-set is\ndifferent, and you should perform a timing test on your system with your data\nto evaluate if you will see a benefit. As you can see from the data linked in\nthe `Timing`_ section, the amount of speedup you will get is particularly\ndata-dependent. *In general* you will see a performance boost for floats (and\nthis boost increases as the size of the float increases), but for integers it\nis largely dependent on the length of the integer. You will likely *not* see\na performance boost if the input are already numbers instead of strings.\n\n**NOTE**: in the below examples, we use ``from fastnumbers import int`` instead\nof ``import fastnumbers``. This is because calling ``fastnumbers.int()`` is a\nbit slower than just ``int()`` because Python has to first find ``fastnumbers``\nin your namespace, then find ``int`` in the ``fastnumbers`` namespace, instead\nof just finding ``int`` in your namespace - this will slow down the function\ncall and defeat the purpose of using ``fastnumbers``. If you do not want to\nactually shadow the built-in ``int`` function, you can do\n``from fastnumbers import int as fn_int`` or something like that.\n\n.. code-block:: python\n\n >>> # Use is identical to the built-in functions\n >>> from fastnumbers import float, int\n >>> float('10')\n 10.0\n >>> int('10')\n 10\n >>> float('bad input') #doctest: +IGNORE_EXCEPTION_DETAIL\n Traceback (most recent call last):\n ...\n ValueError: invalid literal for float(): bad input\n\n``real`` is provided to give a float or int depending\non the fractional component of the input.\n\n.. code-block:: python\n\n >>> from fastnumbers import real\n >>> real('56.0')\n 56\n >>> real('56.7')\n 56.7\n >>> real('56.0', coerce=False)\n 56.0\n\nTiming\n------\n\nJust how much faster is ``fastnumbers`` than a pure python implementation?\nPlease look https://github.com/SethMMorton/fastnumbers/tree/main/profiling.\n\nHigh-Level Algorithm\n--------------------\n\nFor integers, CPython goes to great lengths to ensure that your string input\nis converted to a number *correctly* and *losslessly* (you can prove this to\nyourself by examining the source code for\n`integer conversions `_).\nThis extra effort is only needed for integers that cannot fit into a 64-bit\ninteger data type - for those that can, a naive algorithm of < 10 lines\nof C code is sufficient and significantly faster. ``fastnumbers`` uses a\nheuristic to determine if the input can be safely converted with the much\nfaster naive algorithm, and if so it does so, falling back on\nthe CPython implementation for longer input strings.\nMost real-world numbers pass the heuristic and so you should generally see\nimproved performance with ``fastnumbers`` for integers.\n\nFor floats, ``fastnumbers`` utilizes the ultra-fast\n`fast_float::from_chars `_ function\nto convert strings representing floats into a C ``double`` both quickly *and\nsafely* - the conversion provides the same accuracy as the CPython\n`float conversion function `_\nbut instead of scaling linearly with length of the input string it seems\nto have roughly constant performance. By completely bypassing the CPython\nconverter we get significant performance gains with no penalty, so you\nshould always see improved performance with ``fastnumbers`` for floats.\n\nInstallation\n------------\n\nUse ``pip``!\n\n.. code-block::\n\n $ pip install fastnumbers\n\nHow to Run Tests\n----------------\n\nPlease note that ``fastnumbers`` is NOT set-up to support\n``python setup.py test``.\n\nThe recommended way to run tests is with\n`tox `_.\nSuppose you want to run tests for Python 3.8 - you can run tests by simply\nexecuting the following:\n\n.. code-block:: sh\n\n $ tox run -e py38\n\n``tox`` will create virtual a virtual environment for your tests and install\nall the needed testing requirements for you.\n\nIf you want to run testing on all supported Python versions you can simply execute\n\n.. code-block:: sh\n\n $ tox run\n\nYou can change the how much \"random\" input your tests will try with\n\n.. code-block:: sh\n\n # Run fewer tests with \"random\" input - much faster\n $ tox run -- --hypothesis-profile fast\n\n # Run more tests with \"random\" input - takes much longer but is more thorough\n $ tox run -- --hypothesis-profile thorough\n\nIf you want to run the performce analysis yourself, you can execute\n\n.. code-block:: sh\n\n # This assumes Python 3.9 - adjust for the version you want to profile\n $ tox run -e py39-prof\n\nIf you do not wish to use ``tox``, you can install the testing dependencies with the\n``dev-requirements.txt`` file and then run the tests manually using\n`pytest `_.\n\n.. code-block:: sh\n\n $ pip install -r dev/requirements.txt\n $ pytest\n\nAuthor\n------\n\nSeth M. Morton\n\nHistory\n-------\n\nPlease visit the changelog `on GitHub `_.\n","description_content_type":"text/x-rst","docs_url":null,"download_url":null,"downloads":{"last_day":-1,"last_month":-1,"last_week":-1},"dynamic":null,"home_page":null,"keywords":"conversion, numeric, performance","license":"MIT","license_expression":null,"license_files":null,"maintainer":null,"maintainer_email":null,"name":"fastnumbers","package_url":"https://pypi.org/project/fastnumbers/","platform":null,"project_url":"https://pypi.org/project/fastnumbers/","project_urls":{"Changelog":"https://github.com/SethMMorton/fastnumbers/blob/main/CHANGELOG.md","Documentation":"https://fastnumbers.readthedocs.io/","Homepage":"https://github.com/SethMMorton/fastnumbers","Issues":"https://github.com/SethMMorton/fastnumbers/issues"},"provides_extra":["fast","icu"],"release_url":"https://pypi.org/project/fastnumbers/5.1.1/","requires_dist":["fastnumbers>=2.0.0; extra == \"fast\"","PyICU>=1.0.0; extra == \"icu\""],"requires_python":">=3.8","summary":"Super-fast and clean conversions to numbers.","version":"5.1.1","yanked":false,"yanked_reason":null}

Dependencies of fastnumbers (2).
Dependency	Optional
fastnumbers	true
PyICU	true

Package search

fastnumbers

project_urls

Dependencies

All package metadata

Releases