Release v0.17.0 (#108)

* chore: bump version refs to `0.17.0`

* chore(deps): update dependencies

* feat: add `lib` function for computing `k`-th remainders of continued fractions + use this to reimplement `ContinuedFraction.remainder` + add/update doctests and tests + update Sphinx docs

* refactor: refactor exception handling in `lib.convergent` + update doctests and tests

* feat: add `lib` function for generating remainders of continued fractions + use this to reimplement `ContinuedFraction.remainders` property + add/update doctests and tests + update Sphinx docs

* refactor: improve exception handling in `lib.convergent` + update doctests and tests

* docs: tweak docs index page + README

CITATION.cff

@@ -24,6 +24,6 @@ keywords:
   - real numbers
 
 license: MPL-2.0
-version: 0.16.0
-date-released: 2024-06-19
+version: 0.17.0
+date-released: 2024-06-26
 

README.md

@@ -11,15 +11,15 @@
 <img src="https://us-central1-trackgit-analytics.cloudfunctions.net/token/ping/lsudelfvcxb7f1xm6i4l" alt="trackgit-views" />
 </a>
 [![PyPI version](https://img.shields.io/pypi/v/continuedfractions?logo=python&color=41bb13)](https://pypi.org/project/continuedfractions)
-[![Downloads](https://static.pepy.tech/badge/continuedfractions/week)](https://pepy.tech/project/continuedfractions)
+[![Downloads](https://static.pepy.tech/badge/continuedfractions)](https://pepy.tech/project/continuedfractions)
 
 </div>
 
 # continuedfractions
 
 A simple extension of the Python [`fractions`](https://docs.python.org/3/library/fractions.html) standard library for working with [continued fractions](https://en.wikipedia.org/wiki/Continued_fraction) as Python objects.
 
-The [PyPI package](https://pypi.org/project/continuedfractions/) is here. Only standard libraries are used, and the package can be installed on any **Linux**, **Mac OS** or **Windows** system supporting **Python 3.10**, **3.11**, or **3.12**.
+The [PyPI package](https://pypi.org/project/continuedfractions/) is updated as necessary with improvements, features and fixes. Only standard libraries are used, and the package can be installed on any **Linux**, **Mac OS** or **Windows** system supporting **Python 3.10**, **3.11**, or **3.12**.
 ```shell
 pip install continuedfractions
 ```
@@ -30,7 +30,7 @@ See the [project docs](https://continuedfractions.readthedocs.io/en/latest/) for
 
 The `continuedfractions` package is designed for users interested in:
 
-* working with (finite) continued fractions as Python objects, in an intuitive object-oriented way
+* learning about and working with (finite) continued fractions as Python objects, in an intuitive object-oriented way
 * exploring their key properties, such as elements/coefficients, convergents, semiconvergents, remainders, and others
 * operating on them as rationals and instances of the standard library [`fractions.Fraction`](https://docs.python.org/3/library/fractions.html#fractions.Fraction) class
 * making approximations of and experimental computations for irrational numbers

docs/index.rst

@@ -10,7 +10,7 @@ A simple extension of the Python :py:mod:`fractions` standard library for workin
 
 The package is designed for users interested in:
 
-- working with (finite) continued fractions as Python objects, in an intuitive object-oriented way
+- learning about and working with (finite) continued fractions as Python objects, in an intuitive object-oriented way
 - exploring their key properties, such as elements/coefficients, convergents, semiconvergents, remainders, and others
 - operating on them as rationals and instances of the standard library :py:class:`fractions.Fraction` class
 - making approximations of and experimental computations for irrational numbers

docs/sources/contributing.rst

@@ -160,7 +160,7 @@ The CI/CD pipelines are defined in the `CI YML <https://github.com/sr-murthy/con
 Versioning and Releases :fas:`upload`
 =====================================
 
-The `PyPI package <https://pypi.org/project/continuedfractions/>`_ is currently at version ``0.16.0`` - the goal is to use `semantic versioning <https://semver.org/>`_ consistently for all future releases, but some earlier releases do not comply with strict semantic versioning.
+The `PyPI package <https://pypi.org/project/continuedfractions/>`_ is currently at version ``0.17.0`` - the goal is to use `semantic versioning <https://semver.org/>`_ consistently for all future releases, but some earlier releases do not comply with strict semantic versioning.
 
 There is currently no dedicated pipeline for releases - both `GitHub releases <https://github.com/sr-murthy/continuedfractions/releases>`_ and `PyPI packages <https://pypi.org/project/continuedfractions>`_ are published manually, but both have the same version tag.
 

docs/sources/exploring-continued-fractions.rst

@@ -111,7 +111,7 @@ The same formula is also involved in the implementation of the :py:attr:`~contin
    >>> tuple(ContinuedFraction(649, 200).convergents)
    ((0, ContinuedFraction(3, 1)), (1, ContinuedFraction(13, 4)), (2, ContinuedFraction(159, 49)), (3, ContinuedFraction(649, 200)))
 
-Returning a generator of an enumerated sequence of :py:class:`~continuedfractions.continuedfraction.ContinuedFraction` instances allows the user to define an appropriate static data structure to store all the convergents by index, if required, e.g. via a dict:
+The result is an enumerated sequence of :py:class:`~continuedfractions.continuedfraction.ContinuedFraction` instances, which can be converted into a more accessible data structure, such as a dict:
 
 .. code:: python
 
@@ -398,20 +398,19 @@ If :math:`[a_0; a_1,\ldots]` is of finite order then each :math:`R_k` is a ratio
    >>> cf.remainder(0), cf.remainder(1), cf.remainder(2), cf.remainder(3)
    (ContinuedFraction(649, 200), ContinuedFraction(200, 49), ContinuedFraction(49, 4), ContinuedFraction(4, 1))
 
-It is also possible to get all of the remainders at once using the :py:attr:`~continuedfractions.continuedfraction.ContinuedFraction.remainders` property, which returns a generator of an enumerated sequence of the remainders:
+It is also possible to get all of the remainders at once using the :py:attr:`~continuedfractions.continuedfraction.ContinuedFraction.remainders` property, which returns a generator of an enumerated sequence of the remainders in descending order of index:
 
 .. code:: python
 
    >>> tuple(cf.remainders)
-   ((0: ContinuedFraction(649, 200)), (1, ContinuedFraction(200, 49)), (2, ContinuedFraction(49, 4)), (3, ContinuedFraction(4, 1)))
+   ((3, ContinuedFraction(4, 1)), (2, ContinuedFraction(49, 4)), (1, ContinuedFraction(200, 49)), (0, ContinuedFraction(649, 200)))
 
-As with convergents the result is a generator of an enumerated sequence of :py:class:`~continuedfractions.continuedfraction.ContinuedFraction` instances, as it allows the caller to define a more appropriate static data structure to store all the remainders, if required.
+As with convergents the result is a generator of an enumerated sequence of :py:class:`~continuedfractions.continuedfraction.ContinuedFraction` instances, which can be converted into something more accessible, such as a dict:
 
 .. code:: python
 
-   >>> cf_remainders = dict(cf.remainders)
-   >>> cf_remainders[0], cf_remainders[2]
-   (ContinuedFraction(649, 200), ContinuedFraction(49, 4))
+   >>> dict(ContinuedFraction('3.245').remainders)
+   {3: ContinuedFraction(4, 1), 2: ContinuedFraction(49, 4), 1: ContinuedFraction(200, 49), 0: ContinuedFraction(649, 200)}
 
 Using the simple continued fraction of :math:`\frac{649}{200}` we can verify that these remainders are mathematically correct.
 
@@ -431,7 +430,13 @@ Given a (possibly infinite) continued fraction :math:`[a_0; a_1, a_2,\ldots]` th
 
    R_{k - 1} = a_{k - 1} + \frac{1}{R_k}, \hskip{3em} k \geq 1
 
-where :math:`\frac{1}{R_k}` is a symbolic expression for the number represented by the inverted simple continued fraction :math:`[0; a_k, a_{k + 1},\ldots]`.
+where :math:`\frac{1}{R_k}` is a symbolic expression for the number represented by the inverted simple continued fraction :math:`[0; a_k, a_{k + 1},\ldots]`. If the continued fraction :math:`[a_0; a_1, a_2,\ldots]` is finite of order :math:`n` and we let :math:`R_k = \frac{s_k}{t_k}` then the recurrence relation above can be written as:
+
+.. math::
+
+   R_{k - 1} = \frac{s_{k - 1}}{t_{k - 1}} = \frac{a_{k - 1}s_k + t_k}{s_k}, \hskip{3em} k \geq 1
+
+This is used to implement the remainders functionality in the library function :py:func:`~continuedfractions.lib.remainders`.
 
 Khinchin Means & Khinchin's Constant
 ====================================

docs/sources/getting-started.rst

@@ -43,13 +43,15 @@ Each is summarised below. Or you can go straight to the :doc:`API reference <api
 ``continuedfractions.lib``
 --------------------------
 
-This is a library of standalone functions:
+This is a library of standalone functions for (finite, simple) continued fractions.
 
--  :py:meth:`~continuedfractions.lib.continued_fraction_rational` - generates a unique sequence of elements (coefficients) of a (finite, simple) continued fraction of a rational number given as a :py:class:`fractions.Fraction` instance.
+-  :py:meth:`~continuedfractions.lib.continued_fraction_rational` - generates a unique sequence of elements (coefficients) of the continued fraction of a rational number given as a :py:class:`fractions.Fraction` instance.
 -  :py:meth:`~continuedfractions.lib.continued_fraction_real` - generates a finite sequence of elements of a continued fraction of a real number given as a single :py:class:`int`, :py:class:`float`, :py:class:`str`, or :py:class:`decimal.Decimal` value; the results for :py:class:`float` inputs may be approximate and not necessarily unique.
 - :py:meth:`~continuedfractions.lib.fraction_from_elements` - returns a :py:class:`fractions.Fraction` instance of the rational number represented by a continued fraction from a sequence of its elements.
--  :py:meth:`~continuedfractions.lib.convergent` - returns the :math:`k`-th convergent (for a positive integer :math:`k`) from a sequence of elements of a continued fraction; the convergent is returned as a :py:class:`fractions.Fraction` instance.
+-  :py:meth:`~continuedfractions.lib.convergent` - returns the :math:`k`-th convergent of a continued fraction from a sequence of elements as a :py:class:`fractions.Fraction` instance.
 - :py:meth:`~continuedfractions.lib.convergents` - generates a sequence of all convergents of a continued fraction from a sequence of its elements.
+-  :py:meth:`~continuedfractions.lib.remainder` - returns the :math:`k`-th remainder of a continued fraction from a sequence of elements as a :py:class:`fractions.Fraction` instance.
+- :py:meth:`~continuedfractions.lib.remainders` - generates a sequence of all remainders of a continued fraction from a sequence of its elements.
 -  :py:meth:`~continuedfractions.lib.mediant` - returns the :math:`k`-th left or right mediant of two rational numbers, given as :py:class:`fractions.Fraction` values; the mediant is returned as a :py:class:`fractions.Fraction` instance.
 
 .. note::
@@ -61,7 +63,7 @@ This is a library of standalone functions:
 ``continuedfractions.continuedfraction``
 ----------------------------------------
 
-This is a library containing a single main class:
+This is a library containing a single main class that implements (finite, simple) continued fractions.
 
 - :py:class:`~continuedfractions.continuedfraction.ContinuedFraction` - a subclass of :py:class:`fractions.Fraction`, designed to represent (finite, simple) continued fractions as Python objects, which are fully operable as rational numbers.