boring-math-number-theory 2.0.0__tar.gz

boring_math_number_theory-2.0.0/.gitignore

@@ -0,0 +1,7 @@
+# Minimal version - only add to when necessary
+**/__pycache__/
+dist/
+**/.dmypy.json
+**/.mypy_cache/
+**/.pytest_cache/
+**/.ruff_cache

boring_math_number_theory-2.0.0/CHANGELOG.md

@@ -0,0 +1,221 @@
+# CHANGELOG
+
+PyPI boring-math-number-theory project.
+
+## Semantic Versioning
+
+Strict 3 digit semantic versioning.
+
+- **MAJOR** version incremented for incompatible API changes
+- **MINOR** version incremented for backward compatible added functionality
+- **PATCH** version incremented for backward compatible bug fixes
+
+See [Semantic Versioning 2.0.0](https://semver.org).
+
+## Releases and other important milestones
+
+### Update - 2025-10-09
+
+Created new repo for boring-math-number-theory instead of
+renaming boring-math-integer-math and re-purposing it.
+Will archive the boring-math-integer-math GitHub repo.
+The PyPI repo will be archived after the next coordinated
+release.
+
+### Update - 2025-10-08
+
+Broke out combinatorics library (all two functions)
+to its own GitHub repo: boring-math-combinatorics
+
+Eventually boring-math-integer-math will be renamed
+to boring-math-number-theory.
+
+Both are part of my Boring Math hobby projects.
+
+### Version 1.0.2 - PyPI release date 2025-08-04
+
+Bad circulararray requirement in pyproject.toml
+
+### Version 1.0.0 - PyPI release date 2025-08-04
+
+After some flaying and several releases I finally got things settled
+down with a 0.8.2 release. I updated docstrings to reflect a name
+change, integer_math.num_theory -> integer_math.number_theory and
+never made the change! Everything worked but the docstring had wrong
+info. After making the changes and running pytest tests, I realized
+I made an API breaking change. Sorry...
+
+### Version 0.7.1 - PyPI release date 2025-07-14
+
+- Fixed munged CHANGELOG and Documentation links for PyPI
+
+### Version 0.7.0 - PyPI release date 2025-07-14
+
+- First version to use pythonic_fp namespace
+- no longer using dtools namespace packages
+
+### Version 0.5.1 - PyPI release date 2025-04-TBD
+
+- Made compatible with latest release dltools
+  - dtools.circular-array   3.12.0
+  - dtools.fp               1.6.0
+  - dtools.queues           0.27.0
+  - dtools.tuples           0.27.0
+
+### Version 0.5.0 - PyPI release date 2025-01-17
+
+- First PyPI release as bm.integer-math
+- new doc location is
+  [here](https://grscheller.github.io/boring-math-docs/)
+
+### Version 0.4.7 - PyPI release date 2024-11-18
+
+- Some minor additions
+- consistency changes across all grscheller namespace PyPI repos
+
+### Version 0.4.6 - PyPI release date 2024-10-20
+
+- removed docs from repo
+- docs for all grscheller namespace projects maintained
+  [here](https://grscheller.github.io/grscheller-pypi-namespace-docs/)
+
+### Version 0.4.4.5 - commit date 2024-09-08
+
+- preparing to add more composite number tests
+  - primality tests based on Wilson's theorem
+    - becomes too slow when calculation starts using BigInts
+  - added number theory symbols functions
+    - implemented: `legendre_symbol(a, p)`
+    - implemented: `jacobi_symbol(a, n)`
+
+### Version 0.4.4.4 - commit date 2024-09-08
+
+- re-implemented function primes
+  - no longer using sieve of Eratosthenes algorithm
+  - now using Wilson's theorem and incremental factorial generation
+
+### Version 0.4.4 - PyPI release date 2024-09-01
+
+- removed MathJax expressions
+  - not worth the increased maintenance
+  - can get almost the same results using `expresions` and unicode
+
+### Version 0.4.3.1 - commit date 2024-08-17
+
+- MathJax expressions used to render non-code mathematical expressions
+  - pdoc accepts MathJax expressions with --math option
+    - `$ pdoc --math -o . grscheller.boring_math`
+
+### Version 0.4.3 - PyPI release date 2024-08-17
+
+- updated to use grscheller.circular-array 3.4.1
+  - this version of CA compares first with identity before trying equality
+    - like Python builtins do
+- now using pdoc instead of pdoc3 for documentation
+- replaced github markdown with std markdown
+
+### Version 0.4.0 - PyPI release date 2024-07-12
+
+- updated to use grscheller.circular-array 3.3.1
+- minimum Python version now 3.12
+- target Python version now 3.13
+
+### Version 0.3.1 - PyPI release date 2024-03-09
+
+- reflecting grscheller.circular-array PyPI dependency change
+  - dependencies = ["grscheller.circular-array >= 0.2.0, < 2.1"]
+
+### Version 0.3.0 - PyPI release date 2024-03-02
+
+- decided it a good time for a PyPI release
+  - want to use some of the newer features in new endeavors
+  - vastly improved documentation over last PyPI release
+
+### Version 0.2.2.0 - commit date 2024-02-28
+
+- renamed integer_math.mkCoprime to integer_math.coprime
+  - did it now before PyPI v0.3.0
+- realized pdoc uses Markdown as its preferred markup language
+  - some differences
+    - incorporates some GitHub Markdown additions
+    - will format google-style & numpydoc style comments
+    - lists are one dimensional, not hierarchical
+
+### Version 0.2.0.0 - commit date 2024-02-21
+
+- All implementations going forward for integer_math module will use
+  just integer based algorithms. I can't really compete with C based
+  code from the Python standard library. The algorithms will then be
+  of use if ported to a platform without floating point arithmetic.
+- added two new functions to the integer_math module
+  - iSqrt() finds the int square root of an int
+    - does same thing as math.isqrt()
+  - isSqr() return true if integer argument is a perfect square
+
+### Version 0.1.3 - PyPI release date 2024-02-20
+
+- Forgot to update pyproject.toml dependencies
+  - dependencies = ["grscheller.circular-array >= 0.1.1, < 1.1"]
+
+### Version 0.1.2 - PyPI release date 2024-01-30
+
+- now needs CircularArray v0.1.2
+  - integer_math comb uses new foldL method of CircularArray
+  - CircularArray was split out of grscheller.datastructures
+- test suite written
+
+### Version 0.1.1 - PyPI release date 2024-01-20
+
+- fixed some negative value edge cases
+  - lcm(0,0) now gives 0 instead of a divide by zero exception
+    - some authors leave lcm(0, 0) as undefined
+    - lcm(0, 0) = 0 does make sense
+      - since `a * 0 = 0` for all `a >= 0`
+      - 0 is the smallest non-negative integer a such that `a * 0 = 0`
+      - most math theorems remain true for this case
+- README.md improvements
+
+### Version 0.1.0 - PyPI release date 2024-01-17
+
+- initial PyPI grscheller.boring-math release
+- updated pyproject.toml to align with grscheller.datastructures
+
+### Version 0.0.9 - commit date 2024-01-14
+
+- changed project's name from boring_math to boring-math
+- both GitHub repo and future PyPI repo
+- more in alignment with what I see on PyPI
+- project is grscheller.boring-math
+- package is still grscheller.boring_math
+
+### Version 0.0.8 - commit date 2024-01-14
+
+- working on pyproject.toml infrastructure for PyPI releases
+- will use Flit as the packaging/publishing tool
+- replaced bin/ scripts with `boring_math.integer_math_cli` entry-points
+
+### Version 0.0.4 - commit date 2024-01-10
+
+- first coding changes in years!
+- gh-pages configured
+
+### Version 0.0.0.3 - commit date 2023-12-06
+
+- added pyproject.toml
+
+### Version 0.0.0.2 - commit date 2023-12-06
+
+- got package working again
+  - did not understand iterators that well when I first wrote this package
+- replaced my `take` with `itertools.islice`
+- generated docs from docstrings with pdoc3
+
+### Version 0.0.0.1 - commit date 2023-12-06
+
+- fixed Markdown issues with first commit
+- Added .gitignore file to anticipate pytest & __pycache__ directories
+
+### Version 0.0.0.0 - commit date 2023-12-06
+
+- first commit of source code with with the old pipfile build
+  infrastructure removed.

boring_math_number_theory-2.0.0/LICENSE

@@ -0,0 +1,176 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

boring_math_number_theory-2.0.0/PKG-INFO

@@ -0,0 +1,52 @@
+Metadata-Version: 2.4
+Name: boring-math-number-theory
+Version: 2.0.0
+Summary: Number Theory Library
+Keywords: gcd,lcm,number-theory,primes
+Author-email: "Geoffrey R. Scheller" <geoffrey@scheller.com>
+Requires-Python: >=3.13
+Description-Content-Type: text/x-rst
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+License-File: LICENSE
+Requires-Dist: pythonic-fp-circulararray>=6.0.0
+Requires-Dist: pythonic-fp-iterables>=5.1.2
+Requires-Dist: pytest>=8.4.1 ; extra == "test"
+Project-URL: Changelog, https://github.com/grscheller/boring-math-number-theory/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://grscheller.github.io/boring-math/number_theory/development/build/html
+Project-URL: Homepage, https://grscheller.github.io/boring-math
+Project-URL: Source, https://github.com/grscheller/boring-math-number-theory
+Provides-Extra: test
+
+Boring Math - Number Theory
+===========================
+
+PyPI project
+`boring-math-number-theory
+<https://pypi.org/project/boring-math-number-theory>`_.
+
+Python module implementing a number theory library.
+
+This PyPI project is part of the
+`Boring Math
+<https://grscheller.github.io/boring-math>`_ projects.
+
+Documentation
+-------------
+
+Documentation for this project is hosted on
+`GitHub Pages
+<https://grscheller.github.io/boring-math/number-theory/development/build/html>`_.
+
+Copyright and License
+---------------------
+
+Copyright (c) 2023-2025 Geoffrey R. Scheller. Licensed under the Apache
+License, Version 2.0. See the LICENSE file for details.
+

boring_math_number_theory-2.0.0/README.rst

@@ -0,0 +1,25 @@
+Boring Math - Number Theory
+===========================
+
+PyPI project
+`boring-math-number-theory
+<https://pypi.org/project/boring-math-number-theory>`_.
+
+Python module implementing a number theory library.
+
+This PyPI project is part of the
+`Boring Math
+<https://grscheller.github.io/boring-math>`_ projects.
+
+Documentation
+-------------
+
+Documentation for this project is hosted on
+`GitHub Pages
+<https://grscheller.github.io/boring-math/number-theory/development/build/html>`_.
+
+Copyright and License
+---------------------
+
+Copyright (c) 2023-2025 Geoffrey R. Scheller. Licensed under the Apache
+License, Version 2.0. See the LICENSE file for details.

boring_math_number_theory-2.0.0/pyproject.toml

@@ -0,0 +1,82 @@
+[project]
+name = "boring-math-number-theory"
+version = "2.0.0"
+readme = "README.rst"
+requires-python = ">=3.13"
+license = { file = "LICENSE" }
+authors = [{ name = "Geoffrey R. Scheller", email = "geoffrey@scheller.com" }]
+keywords = [
+  "gcd",
+  "lcm",
+  "number-theory",
+  "primes",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Framework :: Pytest",
+  "Intended Audience :: Education",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: Apache Software License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+dependencies = [
+  "pythonic-fp-circulararray>=6.0.0",
+  "pythonic-fp-iterables>=5.1.2",
+]
+dynamic = ["description"]
+
+[project.urls]
+Changelog = "https://github.com/grscheller/boring-math-number-theory/blob/main/CHANGELOG.md"
+Documentation = "https://grscheller.github.io/boring-math/number_theory/development/build/html"
+Homepage = "https://grscheller.github.io/boring-math"
+Source = "https://github.com/grscheller/boring-math-number-theory"
+
+[project.optional-dependencies]
+test = [
+  "pytest>=8.4.1",
+]
+
+[build-system]
+requires = ["flit_core>=3.12,<4"]
+build-backend = "flit_core.buildapi"
+
+[tool.flit.module]
+name = "boring_math.number_theory"
+
+[tool.mypy]
+enable_incomplete_feature = "NewGenericSyntax"
+explicit_package_bases = true
+implicit_reexport = false
+local_partial_types = true
+namespace_packages = true
+warn_redundant_casts = true
+warn_return_any = true
+warn_unused_configs = true
+
+[tool.pylsp-mypy]
+enabled = true
+live-mode = true
+dmypy = false
+strict = true
+report_progress = true
+
+[tool.pytest.ini_options]
+addopts = "-ra"
+consider_namespace_packages = true
+testpaths = ["tests/"]
+
+[tool.ruff]
+target-version = "py313"
+
+[tool.ruff.lint.flake8-quotes]
+docstring-quotes = "double"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["C901"]
+"**/*.py" = ["E741"]
+
+[tool.ruff.format]
+quote-style = "single"
+docstring-code-line-length = 72

boring_math_number_theory-2.0.0/src/boring_math/number_theory/__init__.py

@@ -0,0 +1,272 @@
+# Copyright 2016-2025 Geoffrey R. Scheller
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Number Theory Library
+
+Collection of integer related functions useful in number theory.
+
+"""
+
+from collections.abc import Iterator
+from typing import Final
+from pythonic_fp.circulararray.auto import CA
+from pythonic_fp.iterables.folding import fold_left
+
+__all__ = [
+    'gcd',
+    'lcm',
+    'coprime',
+    'iSqrt',
+    'isSqr',
+    'is_prime',
+    'legendre_symbol',
+    'jacobi_symbol',
+    'primes',
+    'primes_capped',
+    'primes_wilson',
+]
+
+
+def gcd(m: int, n: int, /) -> int:
+    """Uses Euclidean algorithm to compute the gcd of two integers.
+
+    .. note::
+        - mathematically the gcd of 0 and 0 does not exist
+        - taking ``gcd(0, 0) = 1`` is a better choice than ``math.gcd(0, 0) = 0``
+
+            - eliminates lcm & coprime functions having to edge case test
+            - also ``gcd(0, 0)`` returning 1 instead of 0 more mathematically justified
+
+    :param m: first int for gcd calculation
+    :param n: second int for gcd calculation
+    :returns: gcd of the absolute values of ``m`` and ``n``
+
+    """
+    if 0 == m == n:
+        return 1
+    m, n = abs(m), abs(n)
+    while n > 0:
+        m, n = n, m % n
+    return m
+
+
+def lcm(m: int, n: int, /) -> int:
+    """Find the least common multiple (lcm) of two integers.
+
+    :param m: first int for lcm calculation
+    :param n: second int for lcm calculation
+    :returns: lcm of the absolute values of ``m`` and ``n``
+
+    """
+    m //= gcd(m, n)
+    return abs(m * n)
+
+
+def coprime(m: int, n: int, /) -> tuple[int, int]:
+    """Makes 2 integers coprime by dividing out their common factors.
+
+    :param m: first int for coprime calculation
+    :param n: second int for coprime calculation
+    :returns: coprimed values with original signs, ``(0, 0)`` when ``n = m = 0``
+
+    """
+    common = gcd(m, n)
+    return m // common, n // common
+
+
+def iSqrt(n: int, /) -> int:
+    """Integer square root of a non-negative integer.
+
+    :param n: integer whose integer square root is to be found
+    :returns: the unique ``m`` such that ``m*m <= n < (m+1)*(m+1)``
+    :raises ValueError: if ``n < 0``
+
+    """
+    if n < 0:
+        msg = 'iSqrt(n): n must be non-negative'
+        raise ValueError(msg)
+    high = n
+    low = 1
+    while high > low:
+        high = (high + low) // 2
+        low = n // high
+    return high
+
+
+def isSqr(n: int, /) -> bool:
+    """Determine if argument is a perfect square.
+
+    :param n: integer to check
+    :returns: true only if integer argument is a perfect square
+
+    """
+    return False if n < 0 else n == iSqrt(n) ** 2
+
+
+def legendre_symbol(a: int, p: int) -> int:
+    """Calculate the Legendre Symbol ``(a/p)`` where p is an odd prime.
+
+    .. note::
+
+        See https://en.wikipedia.org/wiki/Legendre_symbol
+
+    :param a: any integer
+    :param p: any prime ``p > 2``, does not check that ``p`` is actually prime
+    :returns: the Legendre Symbol ``(a/p) ∈ {-1, 0, 1}``
+    :raises ValueError: if ``abs(p) < 3``
+
+    """
+    p = abs(p)
+    if p < 3:
+        msg = 'p must be a prime greater than 2'
+        raise ValueError(msg)
+    a = a % p
+
+    if a == 0:
+        return 0
+    else:
+        for x in range(1, p):
+            if x * x % p == a:
+                return 1
+        return -1
+
+
+def jacobi_symbol(a: int, n: int) -> int:
+    """Calculate the Jacobi Symbol ``(a/n)``.
+
+    .. note::
+
+        See https://en.wikipedia.org/wiki/Jacobi_symbol
+
+    :param a: any integer
+    :param n: any positive odd integer
+    :returns: the Jacobi Symbol ``(a/p) ∈ {-1, 0, 1}``
+    :raises ValueError: if ``n`` is not a positive odd integer
+
+    """
+    if n <= 0 or n % 2 == 0:
+        msg = 'n must be a positive odd integer'
+        raise ValueError(msg)
+
+    a = a % n
+    t = 1
+    while a != 0:
+        while a % 2 == 0:
+            a = a // 2
+            r = n % 8
+            if r == 3 or r == 5:
+                t = -t
+        n, a = a, n
+        if n % 4 == 3 and a % 4 == 3:
+            t = -t
+        a = a % n
+
+    if n == 1:
+        return t
+    else:
+        return 0
+
+
+def primes_wilson(start: int = 2) -> Iterator[int]:
+    """Prime number generation using Wilson's Theorem.
+
+    .. note::
+
+        Wilson's Theorem:
+        ``∀(n>1)``, ``n`` is prime if and only if ``(n-1)! % n ≡ -1``
+
+    :param start: first value to check, defaults to 2
+    :returns: an infinite iterator of prime numbers
+
+    """
+    if start < 2:
+        n = 2
+        fact = 1
+    else:
+        n = start
+        fact = CA(range(2, n)).foldl(lambda j, k: j * k, 1)
+    while True:
+        if fact % n == n - 1:
+            yield n
+        fact *= n
+        n += 1
+
+
+def primes_capped(start: int, end: int) -> Iterator[int]:
+    """Yield all primes ```p``` where ``start <= p <= end``.
+
+    :param start: first value to check
+    :param start: last value to check
+    :returns: an iterator of all primes ``p`` where ``start <= p <= end``.
+
+    """
+    for ii in primes_wilson(start):
+        if ii < end:
+            yield ii
+        elif ii == end:
+            yield ii
+            break
+        else:
+            break
+
+
+def primes(start: int = 2, end: int | None = None) -> Iterator[int]:
+    """Yield all primes ``p`` where ``start <= p <= end``.
+
+    .. warning::
+
+        If ``end`` is not given, returned iterator is infinite.
+
+    :param start: first value to check, defaults to 2
+    :returns: an iterator of all primes ``p`` where ``start <= p <= end``
+
+    """
+    if end is None:
+        return primes_wilson(start)
+    else:
+        return primes_capped(start, end)
+
+
+def is_prime(n: int, /) -> bool:
+    """Test if argument is a prime number, uses Wilson's Theorem.
+
+    :param n: integer to check if prime
+    :returns: true only if ``n`` is prime
+
+    """
+    _factors:Final[int]=2*3*5*7*11*13*17
+
+    if (n := abs(n)) < 2:
+        return False
+
+    if n >= _factors:
+        if gcd(n, _factors) > 1:
+            return False
+
+    if n < _factors:
+        return (
+            fold_left(
+                range(2, n),
+                lambda j, k: j * k,
+                1,
+            ) % n == n - 1
+        )
+    else:
+        return (
+            fold_left(
+                range(_factors, n),
+                lambda j, k: j * k,
+                _factors,
+            ) % n == n - 1
+        )

boring_math_number_theory-2.0.0/tests/test_number_theory.py

@@ -0,0 +1,128 @@
+# Copyright 2023-2024 Geoffrey R. Scheller
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from boring_math.number_theory import gcd, lcm, coprime
+from boring_math.number_theory import is_prime, primes, primes_wilson
+from boring_math.number_theory import legendre_symbol, jacobi_symbol
+
+class Test_simple_ones:
+    def test_gcd(self)-> None:
+        assert gcd(0, 0) == 1   # mathematically does not exist
+        assert gcd(1, 1) == 1
+        assert gcd(1, 5) == 1
+        assert gcd(5, 1) == 1
+        assert gcd(0, 5) == 5
+        assert gcd(21, 0) == 21 
+        assert gcd(2, 5) == 1
+        assert gcd(5, 2) == 1
+        assert gcd(15, 35) == 5
+        assert gcd(35, 15) == 5
+        assert gcd(2*3*5*7, 3*5*7*11) == 3*5*7
+        assert gcd(123454321, 11111) == 11111
+        assert gcd(123454321, 1111) == 1
+
+    def test_lcm(self) -> None:
+        assert lcm(5, 0) == 0
+        assert lcm(0, 11) == 0
+        assert lcm(0, 0) == 0
+        assert lcm(3, 5) == 15
+        assert lcm(2*3*25*7, 3*5*11) == 2*3*25*7*11
+
+    def test_mkCoprime(self) -> None:
+        assert coprime(0, 0) == (0, 0)
+        assert coprime(5, 0) == (1, 0)
+        assert coprime(0, 4) == (0, 1)
+        assert coprime(1, 4) == (1, 4)
+        assert coprime(6, 15) == (2, 5)
+        assert coprime(2*3*4*5, 3*4*5*11) == (2, 11)
+
+    def test_primes(self) -> None:
+        assert len(list(primes(10, 5))) == 0
+        assert len(list(primes(11, 5))) == 0
+        assert len(list(primes(end=11))) == 5
+        assert len(list(primes(end=12))) == 5
+        assert len(list(primes(start=5, end=11))) == 3
+        assert len(list(primes(start=4, end=12))) == 3
+
+        cnt = 0
+        primeList: list[int] = []
+        for kk in primes_wilson(36):
+            cnt += 1
+            if cnt > 5:
+                assert False
+            primeList.append(kk)
+            if kk >= 53:
+                break
+        assert primeList == [37, 41, 43, 47, 53]
+
+        cnt = 0
+        primeList = []
+        for kk in primes(36):
+            cnt += 1
+            if cnt > 5:
+                assert False
+            primeList.append(kk)
+            if kk >= 53:
+                break
+        assert primeList == [37, 41, 43, 47, 53]
+
+        generated = list(primes(10, 50))
+        assert generated == [11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47]
+        generated = list(primes(10, 8))
+        assert generated == []
+        generated = list(primes(0, 3))
+        assert generated == [2, 3]
+        generated = list(primes(-5, 4))
+        assert generated == [2, 3]
+
+    def test_is_prime(self) -> None:
+        assert not is_prime(0)
+        assert not is_prime(1)
+        assert is_prime(2)
+        assert is_prime(3)
+        assert not is_prime(4)
+        assert is_prime(5)
+        assert not is_prime(6)
+        assert is_prime(7)
+        assert not is_prime(100)
+        assert is_prime(101)
+        assert not is_prime(111)
+        assert not is_prime(11111)
+
+    def test_symbols(self) -> None:
+        legendre3 = [0, 1, -1, 0, 1, -1, 0, 1, -1]
+        for ii in range(0, 9):
+            assert legendre_symbol(ii, 3) == jacobi_symbol(ii, 3) == legendre3[ii]
+
+        legendre5 = [0, 1, -1, -1, 1, 0, 1, -1, -1, 1]
+        for ii in range(0, 10):
+            assert legendre_symbol(ii, 5) == jacobi_symbol(ii, 5) == legendre5[ii]
+
+        legendre127 = [0, 1, 1, -1, 1, -1, -1, -1,  1,  1, -1, 1, -1,  1, -1,
+                       1, 1, 1,  1, 1, -1,  1,  1, -1, -1,  1, 1, -1, -1, -1, 1]
+        for ii in range(0, 31):
+            assert legendre_symbol(ii, 127) == jacobi_symbol(ii, 127) == legendre127[ii]
+
+        jacobi1 = [1] * 100
+        for ii in range(0, 100):
+            assert jacobi_symbol(ii, 1) == jacobi1[ii] == 1
+
+        jacobi7 =[0, 1, 1, -1, 1, -1, -1, 0, 1, 1, -1, 1, -1, -1]
+        for ii in range(0, 14):
+            assert jacobi_symbol(ii, 7) == jacobi7[ii]
+
+        jacobi15 = [0, 1, 1, 0, 1, 0, 0, -1, 1, 0, 0, -1, 0, -1, -1,
+                    0, 1, 1, 0, 1, 0, 0, -1, 1, 0, 0, -1, 0, -1, -1]
+        for ii in range(0, 30):
+            assert jacobi_symbol(ii, 15) == jacobi15[ii]