transcrypto 1.0.2__tar.gz

transcrypto-1.0.2/LICENSE

@@ -0,0 +1,177 @@
+
+                                 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

transcrypto-1.0.2/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: transcrypto
+Version: 1.0.2
+Summary: Basic crypto primitives, not intended for actual use, but as a companion to --Criptografia, Métodos e Algoritmos--
+Author-email: Daniel Balparda <balparda@github.com>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/balparda/transcrypto
+Project-URL: PyPI, https://pypi.org/project/transcrypto/
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Utilities
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.13.5
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# TransCrypto
+
+Basic crypto primitives, not intended for actual use, but as a companion to "Criptografia, Métodos e Algoritmos".
+
+Started in July/2025, by Daniel Balparda. Since version 1.0.2 it is PyPI package:
+
+<https://pypi.org/project/transcrypto/>
+
+## License
+
+Copyright 2025 Daniel Balparda <balparda@github.com>
+
+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 here](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.
+
+## Use
+
+### Install
+
+To use in your project just do:
+
+```sh
+pip3 install transcrypto
+```
+
+and then `from transcrypto import transcrypto` for using it.
+
+### TODO
+
+TODO: explain module...
+
+## Development Instructions
+
+### Setup
+
+If you want to develop for this project, first install [Poetry](https://python-poetry.org/docs/cli/), but make sure it is like this:
+
+```sh
+brew uninstall poetry
+python3.11 -m pip install --user pipx
+python3.11 -m pipx ensurepath
+# re-open terminal
+poetry self add poetry-plugin-export@^1.8  # allows export to requirements.txt (see below)
+poetry config virtualenvs.in-project true  # creates venv inside project directory
+poetry config pypi-token.pypi <TOKEN>      # add you personal project token
+```
+
+Now install the project:
+
+```sh
+brew install python@3.13 git
+brew update
+brew upgrade
+brew cleanup -s
+# or on Ubuntu/Debian: sudo apt-get install python3.13-venv git
+
+git clone https://github.com/balparda/transcrypto.git transcrypto
+cd transcrypto
+
+poetry env use python3.13  # creates the venv
+poetry install --sync      # HONOR the project's poetry.lock file, uninstalls stray packages
+poetry env info            # no-op: just to check
+
+poetry run pytest -vvv
+# or any command as:
+poetry run <any-command>
+```
+
+To activate like a regular environment do:
+
+```sh
+poetry env activate
+# will print activation command which you next execute, or you can do:
+source .env/bin/activate                         # if .env is local to the project
+source "$(poetry env info --path)/bin/activate"  # for other paths
+
+pytest
+
+deactivate
+```
+
+### Updating Dependencies
+
+To update `poetry.lock` file to more current versions:
+
+```sh
+poetry update  # ignores current lock, updates, rewrites `poetry.lock` file
+poetry run pytest
+```
+
+To add a new dependency you should:
+
+```sh
+poetry add "pkg>=1.2.3"  # regenerates lock, updates env
+# also: "pkg@^1.2.3" = latest 1.* ; "pkg@~1.2.3" = latest 1.2.* ; "pkg@1.2.3" exact
+poetry export --format requirements.txt --without-hashes --output requirements.txt
+```
+
+If you added a dependency to `pyproject.toml`:
+
+```sh
+poetry run pip3 freeze --all  # lists all dependencies pip knows about
+poetry lock     # re-lock your dependencies, so `poetry.lock` is regenerated
+poetry install  # sync your virtualenv to match the new lock file
+poetry export --format requirements.txt --without-hashes --output requirements.txt
+```
+
+### Creating a New Version
+
+```sh
+# bump the version!
+poetry version minor  # updates 1.6 to 1.7, for example
+# or:
+poetry version patch  # updates 1.6 to 1.6.1
+# or:
+poetry version <version-number>
+# (also updates `pyproject.toml` and `poetry.lock`)
+
+# publish to GIT, including a TAG
+git commit -a -m "release version 1.0.2"
+git tag 1.0.2
+git push
+git push --tags
+
+# prepare package for PyPI
+poetry build
+poetry publish
+```

transcrypto-1.0.2/README.md

@@ -0,0 +1,129 @@
+# TransCrypto
+
+Basic crypto primitives, not intended for actual use, but as a companion to "Criptografia, Métodos e Algoritmos".
+
+Started in July/2025, by Daniel Balparda. Since version 1.0.2 it is PyPI package:
+
+<https://pypi.org/project/transcrypto/>
+
+## License
+
+Copyright 2025 Daniel Balparda <balparda@github.com>
+
+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 here](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.
+
+## Use
+
+### Install
+
+To use in your project just do:
+
+```sh
+pip3 install transcrypto
+```
+
+and then `from transcrypto import transcrypto` for using it.
+
+### TODO
+
+TODO: explain module...
+
+## Development Instructions
+
+### Setup
+
+If you want to develop for this project, first install [Poetry](https://python-poetry.org/docs/cli/), but make sure it is like this:
+
+```sh
+brew uninstall poetry
+python3.11 -m pip install --user pipx
+python3.11 -m pipx ensurepath
+# re-open terminal
+poetry self add poetry-plugin-export@^1.8  # allows export to requirements.txt (see below)
+poetry config virtualenvs.in-project true  # creates venv inside project directory
+poetry config pypi-token.pypi <TOKEN>      # add you personal project token
+```
+
+Now install the project:
+
+```sh
+brew install python@3.13 git
+brew update
+brew upgrade
+brew cleanup -s
+# or on Ubuntu/Debian: sudo apt-get install python3.13-venv git
+
+git clone https://github.com/balparda/transcrypto.git transcrypto
+cd transcrypto
+
+poetry env use python3.13  # creates the venv
+poetry install --sync      # HONOR the project's poetry.lock file, uninstalls stray packages
+poetry env info            # no-op: just to check
+
+poetry run pytest -vvv
+# or any command as:
+poetry run <any-command>
+```
+
+To activate like a regular environment do:
+
+```sh
+poetry env activate
+# will print activation command which you next execute, or you can do:
+source .env/bin/activate                         # if .env is local to the project
+source "$(poetry env info --path)/bin/activate"  # for other paths
+
+pytest
+
+deactivate
+```
+
+### Updating Dependencies
+
+To update `poetry.lock` file to more current versions:
+
+```sh
+poetry update  # ignores current lock, updates, rewrites `poetry.lock` file
+poetry run pytest
+```
+
+To add a new dependency you should:
+
+```sh
+poetry add "pkg>=1.2.3"  # regenerates lock, updates env
+# also: "pkg@^1.2.3" = latest 1.* ; "pkg@~1.2.3" = latest 1.2.* ; "pkg@1.2.3" exact
+poetry export --format requirements.txt --without-hashes --output requirements.txt
+```
+
+If you added a dependency to `pyproject.toml`:
+
+```sh
+poetry run pip3 freeze --all  # lists all dependencies pip knows about
+poetry lock     # re-lock your dependencies, so `poetry.lock` is regenerated
+poetry install  # sync your virtualenv to match the new lock file
+poetry export --format requirements.txt --without-hashes --output requirements.txt
+```
+
+### Creating a New Version
+
+```sh
+# bump the version!
+poetry version minor  # updates 1.6 to 1.7, for example
+# or:
+poetry version patch  # updates 1.6 to 1.6.1
+# or:
+poetry version <version-number>
+# (also updates `pyproject.toml` and `poetry.lock`)
+
+# publish to GIT, including a TAG
+git commit -a -m "release version 1.0.2"
+git tag 1.0.2
+git push
+git push --tags
+
+# prepare package for PyPI
+poetry build
+poetry publish
+```

transcrypto-1.0.2/pyproject.toml

@@ -0,0 +1,57 @@
+# pyproject.toml  (preferred for new projects, PEP 621)
+# Copyright 2025 Daniel Balparda (balparda@github.com)
+# Apache-2.0 license
+
+[build-system]
+requires = ["setuptools>=80", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "transcrypto"
+version = "1.0.2"
+description = "Basic crypto primitives, not intended for actual use, but as a companion to --Criptografia, Métodos e Algoritmos--"
+readme = "README.md"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+authors = [
+  { name = "Daniel Balparda", email = "balparda@github.com" }
+]
+requires-python = ">=3.13.5"  # if version changes, remember to change README.md
+classifiers = [  # see: https://pypi.org/classifiers/
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.13",
+  "Operating System :: OS Independent",
+  "Topic :: Utilities",
+  "Topic :: Security :: Cryptography"
+]
+dependencies = [
+]
+
+[project.urls]
+Homepage = "https://github.com/balparda/transcrypto"
+PyPI = "https://pypi.org/project/transcrypto/"
+
+[tool.setuptools]
+package-dir = {"" = "src"}   # root package namespace lives in src/
+
+[tool.setuptools.packages.find]
+where   = ["src"]           # auto-discover every importable package inside src/
+include = ["transcrypto*"]  # avoid picking up stuff not in "transcrypto"
+
+[tool.setuptools.package-data]
+"transcrypto" = ["py.typed"]
+
+[tool.poetry.requires-plugins]
+poetry-plugin-export = ">=1.8"
+
+[tool.poetry.group.dev.dependencies]
+pylint = "^3.3"
+flake8 = "^7.2"
+pyright = "^1.1"
+pytest = ">=8.4"
+pytest-pythonpath = ">=0.7"
+coverage = ">=7.9"
+tomli = ">=2.2.1"
+
+[pytest]
+pythonpath = ["src"]

transcrypto-1.0.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

transcrypto-1.0.2/src/transcrypto/transcrypto.py

@@ -0,0 +1,294 @@
+#!/usr/bin/env python3
+#
+# Copyright 2025 Daniel Balparda (balparda@github.com) - Apache-2.0 license
+#
+"""Balparda's TransCrypto."""
+
+import math
+# import pdb
+import random
+from typing import Generator, Optional
+
+__author__ = 'balparda@github.com'
+__version__: tuple[int, int, int] = (1, 0, 2)  # v1.0.2, 2025-07-22
+
+
+FIRST_60_PRIMES_SORTED: list[int] = [
+    2, 3, 5, 7, 11, 13, 17, 19, 23, 29,
+    31, 37, 41, 43, 47, 53, 59, 61, 67, 71,
+    73, 79, 83, 89, 97, 101, 103, 107, 109, 113,
+    127, 131, 137, 139, 149, 151, 157, 163, 167, 173,
+    179, 181, 191, 193, 197, 199, 211, 223, 227, 229,
+    233, 239, 241, 251, 257, 263, 269, 271, 277, 281,
+]
+FIRST_60_PRIMES: set[int] = set(FIRST_60_PRIMES_SORTED)
+COMPOSITE_60: int = math.prod(FIRST_60_PRIMES_SORTED)
+PRIME_60: int = FIRST_60_PRIMES_SORTED[-1]  # 281
+
+_MAX_PRIMALITY_SAFETY = 100  # this is an absurd number, just to have a max
+
+
+class Error(Exception):
+  """TransCrypto exception."""
+
+
+def GCD(a: int, b: int, /) -> int:
+  """Greatest Common Divisor for `a` and `b`, positive integers.
+
+  Uses the Euclid method.
+  """
+  # test inputs
+  if a < 0 or b < 0:
+    raise Error(f'negative input: {a=} , {b=}')
+  # algo needs to start with a >= b
+  if a < b:
+    a, b = b, a
+  # euclid
+  while b:
+    r: int = a % b
+    a, b = b, r
+  return a
+
+
+def ExtendedGCD(a: int, b: int, /) -> tuple[int, int, int]:
+  """Greatest Common Divisor Extended for `a` and `b`, positive integers.
+
+  Uses the Euclid method.
+
+  Returns:
+    (gcd, x, y) so that a * x + b * y = gcd
+    x and y may be negative integers or zero but won't be both zero.
+  """
+  # test inputs
+  if a < 0 or b < 0:
+    raise Error(f'negative input: {a=} , {b=}')
+  # algo needs to start with a >= b (but we remember if we did swap)
+  swapped = False
+  if a < b:
+    a, b = b, a
+    swapped = True
+  # trivial case
+  if not b:
+    return (a, 0 if swapped else 1, 1 if swapped else 0)
+  # euclid
+  x1, x2, y1, y2 = 0, 1, 1, 0
+  while b:
+    q, r = divmod(a, b)
+    x, y = x2 - q * x1, y2 - q * y1
+    a, b, x1, x2, y1, y2 = b, r, x, x1, y, y1
+  return (a, y2 if swapped else x2, x2 if swapped else y2)
+
+
+def ModExp(x: int, y: int, m: int, /) -> int:
+  """Modular exponential: returns (x ** y) % m efficiently (can handle huge values)."""
+  # test inputs
+  if x < 0 or y < 0:
+    raise Error(f'negative input: {x=} , {y=}')
+  if m < 1:
+    raise Error(f'invalid module: {m=}')
+  # trivial cases
+  if not x:
+    return 0
+  if not y or x == 1:
+    return 1 % m
+  if y == 1:
+    return x % m
+  # now both x > 1 and y > 1
+  z: int = 1
+  while y:
+    y, odd = divmod(y, 2)
+    if odd:
+      z = (z * x) % m
+    x = (x * x) % m
+  return z
+
+
+def FermatIsPrime(
+    n: int, /, *,
+    safety: int = 10,
+    witnesses: Optional[set[int]] = None) -> bool:
+  """Primality test of `n` by Fermat's algo (n > 0). DO NOT RELY!
+
+  Will execute Fermat's algo for non-trivial `n` (n > 3 and odd).
+  <https://en.wikipedia.org/wiki/Fermat_primality_test>
+
+  This is for didactical uses only, as it is reasonably easy for this algo to fail
+  on simple cases. For example, 8911 will fail for many sets of 10 random witnesses.
+  (See <https://en.wikipedia.org/wiki/Carmichael_number> to understand better.)
+  Miller-Rabin below (MillerRabinIsPrime) has been tuned to be VERY reliable by default.
+
+  Args:
+    n (int): Number to test primality
+    safety (int, optional): Maximum witnesses to use (only if witnesses is not given)
+    witnesses (set[int], optional): If given will use exactly these witnesses, in order
+
+  Returns:
+    False if certainly not prime ; True if (probabilistically) prime
+  """
+  # test inputs and test for trivial cases: 1, 2, 3, divisible by 2
+  if n < 1:
+    raise Error(f'invalid number: {n=}')
+  if n in (2, 3):
+    return True
+  if n == 1 or not n % 2:
+    return False
+  # n is odd and >= 5 so now we generate witnesses (if needed)
+  # degenerate case is: n==5, max_safety==2 => randint(2, 3) => {2, 3}
+  if not witnesses:
+    max_safety: int = min(n // 2, _MAX_PRIMALITY_SAFETY)
+    if safety < 1:
+      raise Error(f'out of bounds safety: 1 <= {safety=} <= {max_safety}')
+    safety = max_safety if safety > max_safety else safety
+    witnesses = set()
+    while len(witnesses) < safety:
+      witnesses.add(random.randint(2, n - 2))
+  # we have our witnesses: do the actual Fermat algo
+  for w in sorted(witnesses):
+    if not 2 <= w <= (n - 2):
+      raise Error(f'out of bounds witness: 2 <= {w=} <= {n - 2}')
+    if ModExp(w, n - 1, n) != 1:
+      # number is proved to be composite
+      return False
+  # we declare the number PROBABLY a prime to the limits of this test
+  return True
+
+
+def _MillerRabinWitnesses(n: int, /) -> set[int]:  # pylint: disable=too-many-return-statements
+  """Generates a reasonable set of Miller-Rabin witnesses for testing primality of `n`.
+
+  For n < 3317044064679887385961981 it is precise. That is more than 2**81. See:
+  <https://en.wikipedia.org/wiki/Miller%E2%80%93Rabin_primality_test#Testing_against_small_sets_of_bases>
+
+  For n >= 3317044064679887385961981 it is probabilistic, but computes an number of witnesses
+  that should make the test fail less than once in 2**80 tries (once in 10^25). For all intent and
+  purposes it "never" fails.
+  """
+  # test inputs
+  if n < 5:
+    raise Error(f'invalid number: {n=}')
+  # for some "smaller" values there is research that shows these sets are always enough
+  if n < 2047:
+    return {2}                               # "safety" 1, but 100% coverage
+  if n < 9080191:
+    return {31, 73}                          # "safety" 2, but 100% coverage
+  if n < 4759123141:
+    return {2, 7, 61}                        # "safety" 3, but 100% coverage
+  if n < 2152302898747:
+    return set(FIRST_60_PRIMES_SORTED[:5])   # "safety" 5, but 100% coverage
+  if n < 341550071728321:
+    return set(FIRST_60_PRIMES_SORTED[:7])   # "safety" 7, but 100% coverage
+  if n < 18446744073709551616:               # 2 ** 64
+    return set(FIRST_60_PRIMES_SORTED[:12])  # "safety" 12, but 100% coverage
+  if n < 3317044064679887385961981:          # > 2 ** 81
+    return set(FIRST_60_PRIMES_SORTED[:13])  # "safety" 13, but 100% coverage
+  # here n should be greater than 2 ** 81, so safety should be 34 or less
+  n_bits: int = n.bit_length()
+  assert n_bits >= 82      # "should never happen"
+  safety: int = int(math.ceil(0.375 + 1.59 / (0.000590 * n_bits))) if n_bits <= 1700 else 2
+  assert 1 < safety <= 34  # "should never happen"
+  return set(FIRST_60_PRIMES_SORTED[:safety])
+
+
+def _MillerRabinSR(n: int, /) -> tuple[int, int]:
+  """Generates (s, r) where (2 ** s) * r == (n - 1) hold true, for odd n > 5.
+
+  It should be always true that: s >= 1 and r >= 1 and r is odd.
+  """
+  # test inputs
+  if n < 5 or not n % 2:
+    raise Error(f'invalid odd number: {n=}')
+  # divide by 2 until we can't anymore
+  s: int = 1
+  r: int = (n - 1) // 2
+  while not r % 2:
+    s += 1
+    r //= 2
+  # make sure everything checks out and return
+  assert 1 <= r <= n and r % 2  # "should never happen"
+  return (s, r)
+
+
+def MillerRabinIsPrime(
+    n: int, /, *,
+    witnesses: Optional[set[int]] = None) -> bool:
+  """Primality test of `n` by Miller-Rabin's algo (n > 0).
+
+  Will execute Miller-Rabin's algo for non-trivial `n` (n > 3 and odd).
+  <https://en.wikipedia.org/wiki/Miller%E2%80%93Rabin_primality_test>
+
+  Args:
+    n (int): Number to test primality
+    witnesses (set[int], optional): If given will use exactly these witnesses, in order
+
+  Returns:
+    False if certainly not prime ; True if (probabilistically) prime
+  """
+  # test inputs and test for trivial cases: 1, 2, 3, divisible by 2
+  if n < 1:
+    raise Error(f'invalid number: {n=}')
+  if n in (2, 3):
+    return True
+  if n == 1 or not n % 2:
+    return False
+  # n is odd and >= 5; find s and r so that (2 ** s) * r == (n - 1)
+  s, r = _MillerRabinSR(n)
+  # do the Miller-Rabin algo
+  n_limits: tuple[int, int] = (1, n - 1)
+  y: int
+  for w in sorted(witnesses if witnesses else _MillerRabinWitnesses(n)):
+    if not 2 <= w <= (n - 2):
+      raise Error(f'out of bounds witness: 2 <= {w=} <= {n - 2}')
+    x: int = ModExp(w, r, n)
+    if x not in n_limits:
+      for _ in range(s):  # s >= 1 so will execute at least once
+        y = (x * x) % n
+        if y == 1 and x not in n_limits:
+          return False  # number is proved to be composite
+        x = y
+      if x != 1:
+        return False    # number is proved to be composite
+  # we declare the number PROBABLY a prime to the limits of this test
+  return True
+
+
+def PrimeGenerator(start: int) -> Generator[int, None, None]:
+  """Generates all primes from `start` until loop is broken. Tuned for huge numbers."""
+  # test inputs and make sure we start at an odd number
+  if start < 0:
+    raise Error(f'invalid number: {start=}')
+  # handle start of sequence manually if needed... because we have here the only EVEN prime...
+  if start <= 2:
+    yield 2
+    start = 3
+  # we now focus on odd numbers only and loop forever
+  n: int = (start if start % 2 else start + 1) - 2  # n >= 1 always
+  while True:
+    n += 2  # next odd number
+    # is number divisible by (one of the) first 60 primes? test should eliminate 80%+ of candidates
+    if n > PRIME_60 and GCD(n, COMPOSITE_60) != 1:
+      continue  # not prime
+    # do the (more expensive) primality test
+    if MillerRabinIsPrime(n):
+      yield n  # found a prime
+
+
+def MersennePrimesGenerator(start: int) -> Generator[tuple[int, int, int], None, None]:
+  """Generates all Mersenne prime (2 ** n - 1) exponents from 2**start until loop is broken.
+
+  <https://en.wikipedia.org/wiki/List_of_Mersenne_primes_and_perfect_numbers>
+
+  Yields:
+    (exponent, mersenne_prime, perfect_number), given some exponent `n` that will be exactly:
+    (n, 2 ** n - 1, (2 ** (n - 1)) * (2 ** n - 1))
+  """
+  # we now loop forever over prime exponents
+  # "The exponents p corresponding to Mersenne primes must themselves be prime."
+  for n in PrimeGenerator(start if start >= 1 else 1):
+    mersenne: int = 2 ** n - 1
+    # is number divisible by (one of the) first 60 primes? test should eliminate 80%+ of candidates
+    if mersenne > PRIME_60 and GCD(mersenne, COMPOSITE_60) != 1:
+      continue  # not prime
+    # do the (more expensive) primality test
+    if MillerRabinIsPrime(mersenne):
+      # found a prime, yield it plus the perfect number associated with it
+      yield (n, mersenne, (2 ** (n - 1)) * mersenne)

transcrypto-1.0.2/src/transcrypto.egg-info/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: transcrypto
+Version: 1.0.2
+Summary: Basic crypto primitives, not intended for actual use, but as a companion to --Criptografia, Métodos e Algoritmos--
+Author-email: Daniel Balparda <balparda@github.com>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/balparda/transcrypto
+Project-URL: PyPI, https://pypi.org/project/transcrypto/
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Utilities
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.13.5
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# TransCrypto
+
+Basic crypto primitives, not intended for actual use, but as a companion to "Criptografia, Métodos e Algoritmos".
+
+Started in July/2025, by Daniel Balparda. Since version 1.0.2 it is PyPI package:
+
+<https://pypi.org/project/transcrypto/>
+
+## License
+
+Copyright 2025 Daniel Balparda <balparda@github.com>
+
+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 here](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.
+
+## Use
+
+### Install
+
+To use in your project just do:
+
+```sh
+pip3 install transcrypto
+```
+
+and then `from transcrypto import transcrypto` for using it.
+
+### TODO
+
+TODO: explain module...
+
+## Development Instructions
+
+### Setup
+
+If you want to develop for this project, first install [Poetry](https://python-poetry.org/docs/cli/), but make sure it is like this:
+
+```sh
+brew uninstall poetry
+python3.11 -m pip install --user pipx
+python3.11 -m pipx ensurepath
+# re-open terminal
+poetry self add poetry-plugin-export@^1.8  # allows export to requirements.txt (see below)
+poetry config virtualenvs.in-project true  # creates venv inside project directory
+poetry config pypi-token.pypi <TOKEN>      # add you personal project token
+```
+
+Now install the project:
+
+```sh
+brew install python@3.13 git
+brew update
+brew upgrade
+brew cleanup -s
+# or on Ubuntu/Debian: sudo apt-get install python3.13-venv git
+
+git clone https://github.com/balparda/transcrypto.git transcrypto
+cd transcrypto
+
+poetry env use python3.13  # creates the venv
+poetry install --sync      # HONOR the project's poetry.lock file, uninstalls stray packages
+poetry env info            # no-op: just to check
+
+poetry run pytest -vvv
+# or any command as:
+poetry run <any-command>
+```
+
+To activate like a regular environment do:
+
+```sh
+poetry env activate
+# will print activation command which you next execute, or you can do:
+source .env/bin/activate                         # if .env is local to the project
+source "$(poetry env info --path)/bin/activate"  # for other paths
+
+pytest
+
+deactivate
+```
+
+### Updating Dependencies
+
+To update `poetry.lock` file to more current versions:
+
+```sh
+poetry update  # ignores current lock, updates, rewrites `poetry.lock` file
+poetry run pytest
+```
+
+To add a new dependency you should:
+
+```sh
+poetry add "pkg>=1.2.3"  # regenerates lock, updates env
+# also: "pkg@^1.2.3" = latest 1.* ; "pkg@~1.2.3" = latest 1.2.* ; "pkg@1.2.3" exact
+poetry export --format requirements.txt --without-hashes --output requirements.txt
+```
+
+If you added a dependency to `pyproject.toml`:
+
+```sh
+poetry run pip3 freeze --all  # lists all dependencies pip knows about
+poetry lock     # re-lock your dependencies, so `poetry.lock` is regenerated
+poetry install  # sync your virtualenv to match the new lock file
+poetry export --format requirements.txt --without-hashes --output requirements.txt
+```
+
+### Creating a New Version
+
+```sh
+# bump the version!
+poetry version minor  # updates 1.6 to 1.7, for example
+# or:
+poetry version patch  # updates 1.6 to 1.6.1
+# or:
+poetry version <version-number>
+# (also updates `pyproject.toml` and `poetry.lock`)
+
+# publish to GIT, including a TAG
+git commit -a -m "release version 1.0.2"
+git tag 1.0.2
+git push
+git push --tags
+
+# prepare package for PyPI
+poetry build
+poetry publish
+```

transcrypto-1.0.2/src/transcrypto.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+pyproject.toml
+src/transcrypto/__init__.py
+src/transcrypto/py.typed
+src/transcrypto/transcrypto.py
+src/transcrypto.egg-info/PKG-INFO
+src/transcrypto.egg-info/SOURCES.txt
+src/transcrypto.egg-info/dependency_links.txt
+src/transcrypto.egg-info/top_level.txt

transcrypto-1.0.2/src/transcrypto.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

transcrypto-1.0.2/src/transcrypto.egg-info/top_level.txt

@@ -0,0 +1 @@
+transcrypto