| Name | isqrt JSON |
| Version |
1.1.0
JSON |
| download |
| home_page | |
| Summary | Efficient pure-Python implementation of the integer square root function. |
| upload_time | 2023-05-25 22:00:38 |
| maintainer | |
| docs_url | None |
| author | Andrei Lapets |
| requires_python | >=3.7 |
| license | MIT |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
=====
isqrt
=====
Efficient pure-Python implementation of the integer square root function.
|pypi| |actions| |coveralls|
.. |pypi| image:: https://badge.fury.io/py/isqrt.svg
:target: https://badge.fury.io/py/isqrt
:alt: PyPI version and link.
.. |actions| image:: https://github.com/lapets/isqrt/workflows/lint-test-cover/badge.svg
:target: https://github.com/lapets/isqrt/actions/workflows/lint-test-cover.yml
:alt: GitHub Actions status.
.. |coveralls| image:: https://coveralls.io/repos/github/lapets/isqrt/badge.svg?branch=main
:target: https://coveralls.io/github/lapets/isqrt?branch=main
:alt: Coveralls test coverage summary.
Purpose
-------
Given an arbitrarily large non-negative integer ``n``, the `integer square root <https://en.wikipedia.org/wiki/Integer_square_root>`__ function finds the largest integer ``r`` such that ``r**2 <= n`` and ``(r + 1)**2 > n``.
.. |math_isqrt| replace:: ``math.isqrt``
.. _math_isqrt: https://docs.python.org/3/library/math.html#math.isqrt
.. |math_sqrt| replace:: ``math.sqrt``
.. _math_sqrt: https://docs.python.org/3/library/math.html#math.sqrt
**The built-in** |math_isqrt|_ **function was introduced in Python 3.8 and should normally be used instead of the function defined in this library.** To provide the best performance possible while retaining backwards-compatible behavior for this library, the implementation in this library invokes |math_isqrt|_ when it is available. If |math_isqrt|_ is not available, this library attempts to use |math_sqrt|_ and then (if |math_sqrt|_ does not produce the correct result or the input is outside the range supported by |math_sqrt|_) defaults to a pure-Python implementation in which the number of executed Python arithmetic operations is linear in the bit length of the input integer.
Installation and Usage
----------------------
This library is available as a `package on PyPI <https://pypi.org/project/isqrt>`__:
.. code-block:: bash
python -m pip install isqrt
The library can be imported in the usual way:
.. code-block:: python
from isqrt import isqrt
Examples
^^^^^^^^
The exported function ``isqrt`` provides a pure-Python implementation of the `integer square root <https://en.wikipedia.org/wiki/Integer_square_root>`__ algorithm:
.. code-block:: python
>>> isqrt(4)
2
>>> isqrt(16)
4
>>> list(map(isqrt, range(16, 26)))
[4, 4, 4, 4, 4, 4, 4, 4, 4, 5]
>>> isqrt(2**30000) == 2**15000
True
Development
-----------
All installation and development dependencies are fully specified in ``pyproject.toml``. The ``project.optional-dependencies`` object is used to `specify optional requirements <https://peps.python.org/pep-0621>`__ for various development tasks. This makes it possible to specify additional options (such as ``test``, ``lint``, and so on) when performing installation using `pip <https://pypi.org/project/pip>`__:
.. code-block:: bash
python -m pip install .[test,lint]
Testing and Conventions
^^^^^^^^^^^^^^^^^^^^^^^
All unit tests are executed and their coverage is measured when using `pytest <https://docs.pytest.org>`__ (see the ``pyproject.toml`` file for configuration details):
.. code-block:: bash
python -m pip install .[test]
python -m pytest
Alternatively, all unit tests are included in the module itself and can be executed using `doctest <https://docs.python.org/3/library/doctest.html>`__:
.. code-block:: bash
python src/isqrt/isqrt.py -v
Style conventions are enforced using `Pylint <https://pylint.readthedocs.io>`__:
.. code-block:: bash
python -m pip install .[lint]
python -m pylint src/isqrt
Acknowledgments
^^^^^^^^^^^^^^^
The initial version of this function was `posted <http://stackoverflow.com/a/23279113/2738025>`__ on Stack Overflow. A `more efficient version <https://gist.github.com/castle-bravo/e841684d6bad8e0598e31862a7afcfc7>`__ was implemented by Alexander Gosselin. The implementation in this package is adapted directly from these previous implementations.
Contributions
^^^^^^^^^^^^^
In order to contribute to the source code, open an issue or submit a pull request on the `GitHub page <https://github.com/lapets/isqrt>`__ for this library.
Versioning
^^^^^^^^^^
Beginning with version 0.10.0, the version number format for this library and the changes to the library associated with version number increments conform with `Semantic Versioning 2.0.0 <https://semver.org/#semantic-versioning-200>`__.
Publishing
^^^^^^^^^^
This library can be published as a `package on PyPI <https://pypi.org/project/isqrt>`__ by a package maintainer. First, install the dependencies required for packaging and publishing:
.. code-block:: bash
python -m pip install .[publish]
Ensure that the correct version number appears in the ``pyproject.toml`` file. Create and push a tag for this version (replacing ``?.?.?`` with the version number):
.. code-block:: bash
git tag ?.?.?
git push origin ?.?.?
Remove any old build/distribution files. Then, package the source into a distribution archive:
.. code-block:: bash
rm -rf build dist src/*.egg-info
python -m build --sdist --wheel .
Finally, upload the package distribution archive to `PyPI <https://pypi.org>`__:
.. code-block:: bash
python -m twine upload dist/*
Raw data
{
"_id": null,
"home_page": "",
"name": "isqrt",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "",
"author": "Andrei Lapets",
"author_email": "a@lapets.io",
"download_url": "https://files.pythonhosted.org/packages/48/1d/2e0bab86c007667a8ba39146a7265fb11307a8b04dd554347d3bc0cc798b/isqrt-1.1.0.tar.gz",
"platform": null,
"description": "=====\r\nisqrt\r\n=====\r\n\r\nEfficient pure-Python implementation of the integer square root function.\r\n\r\n|pypi| |actions| |coveralls|\r\n\r\n.. |pypi| image:: https://badge.fury.io/py/isqrt.svg\r\n :target: https://badge.fury.io/py/isqrt\r\n :alt: PyPI version and link.\r\n\r\n.. |actions| image:: https://github.com/lapets/isqrt/workflows/lint-test-cover/badge.svg\r\n :target: https://github.com/lapets/isqrt/actions/workflows/lint-test-cover.yml\r\n :alt: GitHub Actions status.\r\n\r\n.. |coveralls| image:: https://coveralls.io/repos/github/lapets/isqrt/badge.svg?branch=main\r\n :target: https://coveralls.io/github/lapets/isqrt?branch=main\r\n :alt: Coveralls test coverage summary.\r\n\r\nPurpose\r\n-------\r\nGiven an arbitrarily large non-negative integer ``n``, the `integer square root <https://en.wikipedia.org/wiki/Integer_square_root>`__ function finds the largest integer ``r`` such that ``r**2 <= n`` and ``(r + 1)**2 > n``.\r\n\r\n.. |math_isqrt| replace:: ``math.isqrt``\r\n.. _math_isqrt: https://docs.python.org/3/library/math.html#math.isqrt\r\n\r\n.. |math_sqrt| replace:: ``math.sqrt``\r\n.. _math_sqrt: https://docs.python.org/3/library/math.html#math.sqrt\r\n\r\n**The built-in** |math_isqrt|_ **function was introduced in Python 3.8 and should normally be used instead of the function defined in this library.** To provide the best performance possible while retaining backwards-compatible behavior for this library, the implementation in this library invokes |math_isqrt|_ when it is available. If |math_isqrt|_ is not available, this library attempts to use |math_sqrt|_ and then (if |math_sqrt|_ does not produce the correct result or the input is outside the range supported by |math_sqrt|_) defaults to a pure-Python implementation in which the number of executed Python arithmetic operations is linear in the bit length of the input integer.\r\n\r\nInstallation and Usage\r\n----------------------\r\nThis library is available as a `package on PyPI <https://pypi.org/project/isqrt>`__:\r\n\r\n.. code-block:: bash\r\n\r\n python -m pip install isqrt\r\n\r\nThe library can be imported in the usual way:\r\n\r\n.. code-block:: python\r\n\r\n from isqrt import isqrt\r\n\r\nExamples\r\n^^^^^^^^\r\nThe exported function ``isqrt`` provides a pure-Python implementation of the `integer square root <https://en.wikipedia.org/wiki/Integer_square_root>`__ algorithm:\r\n\r\n.. code-block:: python\r\n\r\n >>> isqrt(4)\r\n 2\r\n >>> isqrt(16)\r\n 4\r\n >>> list(map(isqrt, range(16, 26)))\r\n [4, 4, 4, 4, 4, 4, 4, 4, 4, 5]\r\n >>> isqrt(2**30000) == 2**15000\r\n True\r\n\r\nDevelopment\r\n-----------\r\nAll installation and development dependencies are fully specified in ``pyproject.toml``. The ``project.optional-dependencies`` object is used to `specify optional requirements <https://peps.python.org/pep-0621>`__ for various development tasks. This makes it possible to specify additional options (such as ``test``, ``lint``, and so on) when performing installation using `pip <https://pypi.org/project/pip>`__:\r\n\r\n.. code-block:: bash\r\n\r\n python -m pip install .[test,lint]\r\n\r\nTesting and Conventions\r\n^^^^^^^^^^^^^^^^^^^^^^^\r\nAll unit tests are executed and their coverage is measured when using `pytest <https://docs.pytest.org>`__ (see the ``pyproject.toml`` file for configuration details):\r\n\r\n.. code-block:: bash\r\n\r\n python -m pip install .[test]\r\n python -m pytest\r\n\r\nAlternatively, all unit tests are included in the module itself and can be executed using `doctest <https://docs.python.org/3/library/doctest.html>`__:\r\n\r\n.. code-block:: bash\r\n\r\n python src/isqrt/isqrt.py -v\r\n\r\nStyle conventions are enforced using `Pylint <https://pylint.readthedocs.io>`__:\r\n\r\n.. code-block:: bash\r\n\r\n python -m pip install .[lint]\r\n python -m pylint src/isqrt\r\n\r\nAcknowledgments\r\n^^^^^^^^^^^^^^^\r\nThe initial version of this function was `posted <http://stackoverflow.com/a/23279113/2738025>`__ on Stack Overflow. A `more efficient version <https://gist.github.com/castle-bravo/e841684d6bad8e0598e31862a7afcfc7>`__ was implemented by Alexander Gosselin. The implementation in this package is adapted directly from these previous implementations.\r\n\r\nContributions\r\n^^^^^^^^^^^^^\r\nIn order to contribute to the source code, open an issue or submit a pull request on the `GitHub page <https://github.com/lapets/isqrt>`__ for this library.\r\n\r\nVersioning\r\n^^^^^^^^^^\r\nBeginning with version 0.10.0, the version number format for this library and the changes to the library associated with version number increments conform with `Semantic Versioning 2.0.0 <https://semver.org/#semantic-versioning-200>`__.\r\n\r\nPublishing\r\n^^^^^^^^^^\r\nThis library can be published as a `package on PyPI <https://pypi.org/project/isqrt>`__ by a package maintainer. First, install the dependencies required for packaging and publishing:\r\n\r\n.. code-block:: bash\r\n\r\n python -m pip install .[publish]\r\n\r\nEnsure that the correct version number appears in the ``pyproject.toml`` file. Create and push a tag for this version (replacing ``?.?.?`` with the version number):\r\n\r\n.. code-block:: bash\r\n\r\n git tag ?.?.?\r\n git push origin ?.?.?\r\n\r\nRemove any old build/distribution files. Then, package the source into a distribution archive:\r\n\r\n.. code-block:: bash\r\n\r\n rm -rf build dist src/*.egg-info\r\n python -m build --sdist --wheel .\r\n\r\nFinally, upload the package distribution archive to `PyPI <https://pypi.org>`__:\r\n\r\n.. code-block:: bash\r\n\r\n python -m twine upload dist/*\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Efficient pure-Python implementation of the integer square root function.",
"version": "1.1.0",
"project_urls": {
"Repository": "https://github.com/lapets/isqrt"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e0c9489ec5c51287d1c8a1ed30ce3ffd7bb5a044041690c98ccb727a946bb721",
"md5": "7a5a994ba0490547979f4ff955bc3318",
"sha256": "1073bee166d41b1a0e475afbc291ae7b3997a6964905203f0f69be376e48ff58"
},
"downloads": -1,
"filename": "isqrt-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7a5a994ba0490547979f4ff955bc3318",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 6035,
"upload_time": "2023-05-25T22:00:36",
"upload_time_iso_8601": "2023-05-25T22:00:36.787241Z",
"url": "https://files.pythonhosted.org/packages/e0/c9/489ec5c51287d1c8a1ed30ce3ffd7bb5a044041690c98ccb727a946bb721/isqrt-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "481d2e0bab86c007667a8ba39146a7265fb11307a8b04dd554347d3bc0cc798b",
"md5": "67288af664b3d23340ba0908c0d8c425",
"sha256": "7d442b7853f7f72932261addc8e958aca172764d02d0ae882fd59d0442db68f7"
},
"downloads": -1,
"filename": "isqrt-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "67288af664b3d23340ba0908c0d8c425",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 5749,
"upload_time": "2023-05-25T22:00:38",
"upload_time_iso_8601": "2023-05-25T22:00:38.404983Z",
"url": "https://files.pythonhosted.org/packages/48/1d/2e0bab86c007667a8ba39146a7265fb11307a8b04dd554347d3bc0cc798b/isqrt-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-25 22:00:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "lapets",
"github_project": "isqrt",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "isqrt"
}
