Metadata-Version: 2.1
Name: quicktions
Version: 1.14
Summary: Fast fractions data type for rational numbers. Cythonized version of 'fractions.Fraction'.
Home-page: https://github.com/scoder/quicktions
Author: Stefan Behnel
Author-email: stefan_ml@behnel.de
Classifier: Development Status :: 6 - Mature
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Cython
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Office/Business :: Financial
Classifier: License :: OSI Approved :: Python Software Foundation License
License-File: LICENSE

Python's ``Fraction`` data type is an excellent way to do exact calculations
with unlimited rational numbers and largely beats ``Decimal`` in terms of
simplicity, accuracy and safety.  Clearly not in terms of speed, though,
given the cdecimal accelerator in Python 3.3+.

``quicktions`` is an adaptation of the original ``fractions`` module
(as included in CPython 3.10) that is compiled and optimised with
`Cython <https://cython.org/>`_ into a fast, native extension module.

Compared to the standard library ``fractions`` module of CPython,
computations in ``quicktions`` are about

- 10x faster in Python 2.7 and 3.4
- 6x faster in Python 3.5
- 3-4x faster in Python 3.10

Compared to the ``fractions`` module in CPython 3.10, instantiation of a
``Fraction`` in ``quicktions`` is also

- 5-15x faster from a floating point string value (e.g. ``Fraction("123.456789")``)
- 3-5x faster from a floating point value (e.g. ``Fraction(123.456789)``)
- 2-4x faster from an integer numerator-denominator pair (e.g. ``Fraction(123, 456)``)

We provide a set of micro-benchmarks here:

https://github.com/scoder/quicktions/tree/master/benchmark

As of quicktions 1.12, the different number types and implementations compare
as follows in CPython 3.10:

.. code-block::

    Average times for all 'create' benchmarks:
    float               :    36.17 us (1.0x)
    Decimal             :   111.71 us (3.1x)
    Fraction            :   111.98 us (3.1x)
    PyFraction          :   398.80 us (11.0x)

    Average times for all 'compute' benchmarks:
    float               :     4.53 us (1.0x)
    Decimal             :    16.62 us (3.7x)
    Fraction            :    72.91 us (16.1x)
    PyFraction          :   251.93 us (55.6x)

While not as fast as the C implemented ``decimal`` module in Python 3,
``quicktions`` is about 15x faster than the Python implemented ``decimal``
module in Python 2.7.

For documentation, see the Python standard library's ``fractions`` module:

https://docs.python.org/3/library/fractions.html

ChangeLog
=========

1.14 (2023-03-19)
-----------------

* Implement ``__format__`` for ``Fraction``, following
  https://github.com/python/cpython/pull/100161

* Implement ``Fraction.is_integer()``, following
  https://github.com/python/cpython/issues/100488

* ``Fraction.limit_denominator()`` is faster, following
  https://github.com/python/cpython/pull/93730

* Internal creation of result Fractions is about 10% faster if the calculated
  numerator/denominator pair is already normalised, following
  https://github.com/python/cpython/pull/101780

* Built using Cython 3.0.0b1.


1.13 (2022-01-11)
-----------------

* Parsing very long numbers from a fraction string was very slow, even slower
  than ``fractions.Fraction``.  The parser is now faster in all cases (and
  still much faster for shorter numbers).

* ``Fraction`` did not implement ``__int__``.
  https://bugs.python.org/issue44547


1.12 (2022-01-07)
-----------------

* Faster and more space friendly pickling and unpickling.
  https://bugs.python.org/issue44154

* Algorithmically faster arithmetic for large denominators, although slower for
  small fraction components.
  https://bugs.python.org/issue43420
  Original patch for CPython by Sergey B. Kirpichev and Raymond Hettinger.

* Make sure ``bool(Fraction)`` always returns a ``bool``.
  https://bugs.python.org/issue39274

* Built using Cython 3.0.0a10.


1.11 (2019-12-19)
-----------------

* Fix ``OverflowError`` when parsing string values with long decimal parts.


1.10 (2019-08-23)
-----------------

* ``hash(fraction)`` is substantially faster in Py3.8+, following an optimisation
  in CPython 3.9 (https://bugs.python.org/issue37863).

* New method ``fraction.as_integer_ratio()``.


1.9 (2018-12-26)
----------------

* Substantially faster normalisation (and therefore instantiation) in Py3.5+.

* ``//`` (floordiv) now follows the expected rounding behaviour when used with
  floats (by converting to float first), and is much faster for integer operations.

* Fix return type of divmod(), where the first item should be an integer.

* Further speed up mod and divmod operations.


1.8 (2018-12-26)
----------------

* Faster mod and divmod calculation.


1.7 (2018-10-16)
----------------

* Faster normalisation and fraction string parsing.

* Add support for Python 3.7.

* Built using Cython 0.29.


1.6 (2018-03-23)
----------------

* Speed up Fraction creation from a string value by 3-5x.

* Built using Cython 0.28.1.


1.5 (2017-10-22)
----------------

* Result of power operator (``**``) was not normalised for negative values.

* Built using Cython 0.27.2.


1.4 (2017-09-16)
----------------

* Rebuilt using Cython 0.26.1 to improve support of Python 3.7.


1.3 (2016-07-24)
----------------

* repair the faster instantiation from Decimal values in Python 3.6

* avoid potential glitch for certain large numbers in normalisation under Python 2.x


1.2 (2016-04-08)
----------------

* change hash function in Python 2.x to match that of ``fractions.Fraction``


1.1 (2016-03-29)
----------------

* faster instantiation from float values

* faster instantiation from Decimal values in Python 3.6


1.0 (2015-09-10)
----------------

* ``Fraction.imag`` property could return non-zero

* parsing strings with long fraction parts could use an incorrect scale


0.7 (2014-10-09)
----------------

* faster instantiation from float and string values

* fix test in Python 2.x


0.6 (2014-10-09)
----------------

* faster normalisation (and thus instantiation)


0.5 (2014-10-06)
----------------

* faster math operations


0.4 (2014-10-06)
----------------

* enable legacy division support in Python 2.x


0.3 (2014-10-05)
----------------

* minor behavioural fixes in corner cases under Python 2.x
  (now passes all test in Py2.7 as well)


0.2 (2014-10-03)
----------------

* cache hash value of Fractions


0.1 (2014-09-24)
----------------

* initial public release
