transcrypto 1.6.0__tar.gz → 1.8.0__tar.gz

{transcrypto-1.6.0/src/transcrypto.egg-info → transcrypto-1.8.0}/PKG-INFO

@@ -1,20 +1,33 @@
 Metadata-Version: 2.4
 Name: transcrypto
-Version: 1.6.0
+Version: 1.8.0
 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/
+License-File: LICENSE
+Keywords: cryptography,validation,encryption,signing,random-generation,prime-numbers,aes-encryption,decryption,rsa-cryptography,elgamal-encryption,dsa-algorithm,modular-mathematics,rsa,dsa,elgamal,aes,python,poetry,typer,rich,cli
+Author: Daniel Balparda
+Author-email: balparda@github.com
+Requires-Python: >=3.12
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Operating System :: OS Independent
 Classifier: Topic :: Utilities
 Classifier: Topic :: Security :: Cryptography
-Requires-Python: <4.0,>=3.13.5
+Requires-Dist: cryptography (>=46.0)
+Requires-Dist: gmpy2 (>=2.2)
+Requires-Dist: platformdirs (>=4.5)
+Requires-Dist: rich (>=14.3)
+Requires-Dist: scipy (>=1.17)
+Requires-Dist: typer (>=0.21)
+Requires-Dist: zstandard (>=0.25)
+Project-URL: Changelog, https://github.com/balparda/transcrypto/blob/main/CHANGELOG.md
+Project-URL: Homepage, https://github.com/balparda/transcrypto
+Project-URL: Issues, https://github.com/balparda/transcrypto/issues
+Project-URL: PyPI, https://pypi.org/project/transcrypto/
+Project-URL: Repository, https://github.com/balparda/transcrypto
 Description-Content-Type: text/markdown
-License-File: LICENSE
-Dynamic: license-file
 
 # TransCrypto
 
@@ -76,7 +89,7 @@ Started in July/2025, by Daniel Balparda. Since version 1.0.2 it is PyPI package
 
 ## License
 
-Copyright 2025 Daniel Balparda <balparda@github.com>
+Copyright 2026 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).
 
@@ -94,7 +107,6 @@ All that being said, extreme care was taken that this is a good library with a s
 
 ## CLI Apps
 
-- [SafeTrans/`safetrans`](safetrans.md): Safe cryptographic operations;
 - [TransCrypto/`transcrypto`](transcrypto.md): Does all the operations but allows you to shoot yourself in the foot;
 - [Profiler/`profiler`](profiler.md): Measure transcrypto performance.
 
@@ -122,14 +134,18 @@ Known dependencies:
 #### Humanized Sizes (IEC binary)
 
 ```py
-from transcrypto import utils
+from transcrypto import base
 
-utils.HumanizedBytes(512)                 # '512 B'
-utils.HumanizedBytes(2048)                # '2.00 KiB'
-utils.HumanizedBytes(5 * 1024**3)         # '5.00 GiB'
+base.HumanizedBytes(512)                  # '512 B'
+base.HumanizedBytes(2048)                 # '2.000 KiB'
+base.HumanizedBytes(5 * 1024**3)          # '5.000 GiB'
 ```
 
-Converts raw byte counts to binary-prefixed strings (`B`, `KiB`, `MiB`, `GiB`, `TiB`, `PiB`, `EiB`). Values under 1024 bytes are returned as integers with `B`; larger values use two decimals.
+Converts raw byte counts to binary-prefixed strings (`B`, `KiB`, `MiB`, `GiB`, `TiB`, `PiB`, `EiB`).
+
+- For integer inputs `<1024`, returns an integer count with `B` (e.g. `'512 B'`).
+- For float inputs `<1024`, returns 3 decimals with `B` (e.g. `'51.200 B'`).
+- For values `≥1024`, returns 3 decimals.
 
 - standard: 1 KiB = 1024 B, 1 MiB = 1024 KiB, …
 - errors: negative inputs raise `InputError`
@@ -138,43 +154,47 @@ Converts raw byte counts to binary-prefixed strings (`B`, `KiB`, `MiB`, `GiB`, `
 
 ```py
 # Base (unitless)
-utils.HumanizedDecimal(950)               # '950'
-utils.HumanizedDecimal(1500)              # '1.50 k'
+base.HumanizedDecimal(950)                # '950'
+base.HumanizedDecimal(1500)               # '1.500 k'
 
 # With a unit (trimmed and attached)
-utils.HumanizedDecimal(1500, ' Hz ')      # '1.50 kHz'
-utils.HumanizedDecimal(0.123456, 'V')     # '0.1235 V'
+base.HumanizedDecimal(1500, unit=' Hz ')  # '1.500 kHz'
+base.HumanizedDecimal(0.123456, unit='V') # '123.456 mV'
 
 # Large magnitudes
-utils.HumanizedDecimal(3_200_000)         # '3.20 M'
-utils.HumanizedDecimal(7.2e12, 'B/s')     # '7.20 TB/s'
+base.HumanizedDecimal(3_200_000)          # '3.200 M'
+base.HumanizedDecimal(7.2e12, unit='B/s') # '7.200 TB/s'
 ```
 
-Scales by powers of 1000 using SI prefixes (`k`, `M`, `G`, `T`, `P`, `E`). For values `<1000`, integers are shown as-is; small floats show four decimals. For scaled values, two decimals are used and the unit (if provided) is attached without a space (e.g., `kHz`).
+Scales by powers of 1000 using SI prefixes to keep the displayed value in roughly `[1, 1000)` when possible.
+
+- Supported large prefixes: `k`, `M`, `G`, `T`, `P`, `E`
+- Supported small prefixes: `m`, `µ`, `n`, `p`, `f`, `a`
+- Formatting uses 3 decimals for non-integer/unscaled values and for scaled values.
 
 - unit handling: `unit` is stripped; `<1000` values include a space before the unit (`'950 Hz'`)
-- errors: negative or non-finite inputs raise `InputError`
+- errors: non-finite inputs raise `InputError` (negative values are supported and keep a leading `-`)
 
 #### Humanized Durations
 
 ```py
-utils.HumanizedSeconds(0)                 # '0.00 s'
-utils.HumanizedSeconds(0.000004)          # '4.000 µs'
-utils.HumanizedSeconds(0.25)              # '250.000 ms'
-utils.HumanizedSeconds(42)                # '42.00 s'
-utils.HumanizedSeconds(3661)              # '1.02 h'
-utils.HumanizedSeconds(172800)            # '2.00 d'
+base.HumanizedSeconds(0)                  # '0.000 s'
+base.HumanizedSeconds(0.000004)           # '4.000 µs'
+base.HumanizedSeconds(0.25)               # '250.000 ms'
+base.HumanizedSeconds(42)                 # '42.000 s'
+base.HumanizedSeconds(3661)               # '1.017 h'
+base.HumanizedSeconds(172800)             # '2.000 d'
 ```
 
 Chooses an appropriate time unit based on magnitude and formats with fixed precision:
 
 - `< 1 ms`: microseconds with three decimals (`µs`)
 - `< 1 s`: milliseconds with three decimals (`ms`)
-- `< 60 s`: seconds with two decimals (`s`)
-- `< 60 min`: minutes with two decimals (`min`)
-- `< 24 h`: hours with two decimals (`h`)
-- `≥ 24 h`: days with two decimals (`d`)
-- special case: `0 → '0.00 s'`
+- `< 60 s`: seconds with three decimals (`s`)
+- `< 60 min`: minutes with three decimals (`min`)
+- `< 24 h`: hours with three decimals (`h`)
+- `≥ 24 h`: days with three decimals (`d`)
+- special case: `0 → '0.000 s'`
 - errors: negative or non-finite inputs raise `InputError`
 
 #### Execution Timing
@@ -191,7 +211,7 @@ import time
 ```py
 with base.Timer('Block timing'):
     time.sleep(1.2)
-# → logs: "Block timing: 1.20 s" (default via logging.info)
+# → logs: "Block timing: 1.200 s" (default via logging.info)
 ```
 
 Starts timing on entry, stops on exit, and reports elapsed time automatically.
@@ -204,7 +224,7 @@ def slow_function():
     time.sleep(0.8)
 
 slow_function()
-# → logs: "Function timing: 0.80 s"
+# → logs: "Function timing: 0.800 s"
 ```
 
 Wraps a function so that each call is automatically timed.
@@ -215,17 +235,17 @@ Wraps a function so that each call is automatically timed.
 tm = base.Timer('Inline timing', emit_print=True)
 tm.Start()
 time.sleep(0.1)
-tm.Stop()   # prints: "Inline timing: 0.10 s"
+tm.Stop()   # prints: "Inline timing: 0.100 s"
 ```
 
 Manual control over `Start()` and `Stop()` for precise measurement of custom intervals.
 
 ##### Key points
 
-- **Label**: required, shown in output; empty labels raise `InputError`
+- **Label**: optional; if empty, output omits the label prefix
 - **Output**:
   - `emit_log=True` → `logging.info()` (default)
-  - `emit_print=True` → direct `print()`
+  - `emit_print=True` → prints via `rich.console.Console().print()`
   - Both can be enabled
 - **Format**: elapsed time is shown using `HumanizedSeconds()`
 - **Safety**:
@@ -253,7 +273,7 @@ blob = base.Serialize(data)
 blob = base.Serialize(
     data,
     compress=9,               # compression level (-22..22, default=3)
-    key=my_symmetric_key      # must implement SymmetricCrypto
+    key=my_encryptor          # must implement `base.Encryptor` (e.g., `aes.AESKey`)
 )
 
 # Save directly to file
@@ -297,7 +317,7 @@ obj = base.DeSerialize(data=blob)
 obj = base.DeSerialize(file_path='/tmp/data.blob')
 
 # With decryption
-obj = base.DeSerialize(data=blob, key=my_symmetric_key)
+obj = base.DeSerialize(data=blob, key=my_decryptor)
 ```
 
 Deserialization path:
@@ -313,7 +333,8 @@ data/file → (decrypt) → (decompress if Zstd) → unpickle
 
 - Exactly one of `data` or `file_path` must be provided.
 - `file_path` must exist; `data` must be at least 4 bytes.
-- Wrong key or corrupted data can raise `CryptoError`.
+- Wrong key / authentication failure can raise `CryptoError`.
+- Corrupted compressed blobs typically raise `zstandard.ZstdError` during decompression.
 
 #### Cryptographically Secure Randomness
 
@@ -388,8 +409,8 @@ The function is `O(log(min(a, b)))` and handles arbitrarily large integers. To f
 
 ```py
 >>> base.ExtendedGCD(462, 1071)
-(21, -2, 1)
->>> 462 * -2 + 1071 * 1
+(21, 7, -3)
+>>> 462 * 7 + 1071 * (-3)
 21
 ```
 
@@ -535,13 +556,13 @@ Hashes a file from disk in streaming mode. By default uses SHA-256; `digest='sha
 
 #### Symmetric Encryption Interface
 
-`SymmetricCrypto` is an abstract base class that defines the **byte-in / byte-out** contract for symmetric ciphers.
+`base.Encryptor` and `base.Decryptor` are runtime-checkable protocols that define the **byte-in / byte-out** contract for symmetric ciphers.
 
 - **Metadata handling** — if the algorithm uses a `nonce` or `tag`, the implementation must handle it internally (e.g., append it to ciphertext).
 - **AEAD modes** — if supported, `associated_data` must be authenticated; otherwise, a non-`None` value should raise `InputError`.
 
 ```py
-class MyAES(base.SymmetricCrypto):
+class MyAES(base.Encryptor, base.Decryptor):
     def Encrypt(self, plaintext: bytes, *, associated_data=None) -> bytes:
         ...
     def Decrypt(self, ciphertext: bytes, *, associated_data=None) -> bytes:
@@ -555,8 +576,8 @@ Cryptographic objects all derive from the `CryptoKey` class and will all have so
 - Will be safe to log and print, i.e., implement safe `__str__()` and `__repr__()` methods (in actuality `repr` will be exactly the same as `str`). The `__str__()` should always fully print the public parts of the object and obfuscate the private ones. This obfuscation allows for some debugging, if needed, but if the secrets are "too short" then it can be defeated by brute force. For usual crypto defaults the obfuscation is fine. The obfuscation is the fist 4 bytes of the SHA-512 for the value followed by an ellipsis (e.g. `c9626f16…`).
 - It will have a `_DebugDump()` method that **does print secrets** and can be used for **debugging only**.
 - Can be easily serialized to `bytes` by the `blob` property and to base-64 encoded `str` by the `encoded` property.
-- Can be serialized encrypted to `bytes` by the `Blob(key=[SymmetricCrypto])` method and to encrypted base-64 encoded `str` by the `Encoded(key=[SymmetricCrypto])` method.
-- Can be instantiated back as an object from `str` or `bytes` using the `Load(data, key=[SymmetricCrypto] | None)` method. The `Load()` will decide how to build the object and will work universally with all the serialization options discussed above.
+- Can be serialized encrypted to `bytes` by the `Blob(key=[base.Encryptor])` method and to encrypted base-64 encoded `str` by the `Encoded(key=[base.Encryptor])` method.
+- Can be instantiated back as an object from `str` or `bytes` using the `Load(data, key=[base.Decryptor] | None)` method. The `Load()` will decide how to build the object and will work universally with all the serialization options discussed above.
 
 Example:
 
@@ -719,7 +740,7 @@ For real-world deployments, use a high-level library with authenticated encrypti
 from transcrypto import elgamal
 
 # Shared parameters (prime modulus, group base) for a group
-shared = elgamal.ElGamalSharedPublicKey.New(256)
+shared = elgamal.ElGamalSharedPublicKey.NewShared(256)
 print(shared.prime_modulus)
 print(shared.group_base)
 
@@ -771,8 +792,8 @@ This is **raw DSA** over a prime field — **no hashing or padding**. You sign/v
 ```py
 from transcrypto import dsa
 
-# Shared parameters (p, q, g)
-shared = dsa.DSASharedPublicKey.New(p_bits=1024, q_bits=160)
+# Shared parameters (p, q, g) - Safe Sign/Verify requires q > 512 bits
+shared = dsa.DSASharedPublicKey.NewShared(2048, 520)
 print(shared.prime_modulus)  # p
 print(shared.prime_seed)     # q  (q | p-1)
 print(shared.group_base)     # g
@@ -808,11 +829,11 @@ assert pub.RawVerify(msg, sig)
 
 ```py
 # Generate primes (p, q) with q | (p-1); also returns m = (p-1)//q
-p, q, m = dsa.NBitRandomDSAPrimes(p_bits=1024, q_bits=160)
+p, q, m = dsa.NBitRandomDSAPrimes(1024, 160)
 assert (p - 1) % q == 0
 ```
 
-Used internally by `DSASharedPublicKey.New()`.
+Used internally by `DSASharedPublicKey.NewShared()`.
 Search breadth and retry caps are bounded; repeated failures raise `CryptoError`.
 
 #### Public Bidding
@@ -837,14 +858,14 @@ print(bid_pub == bid_pub_expected)
 
 <https://en.wikipedia.org/wiki/Shamir's_secret_sharing>
 
-This is the information-theoretic SSS but with no authentication or binding between share and secret. Malicious share injection is possible! Add MAC or digital signature in hostile settings. Use at least 128-bit modulus for non-toy deployments.
+This is the information-theoretic SSS but with no authentication or binding between share and secret. Malicious share injection is possible! Add MAC or digital signature in hostile settings. Use at least 128-bit modulus for non-toy deployments; `MakeDataShares()` requires > 256 bits.
 
 ```py
 from transcrypto import sss
 
 # Generate parameters: at least 3 of 5 shares needed,
-# coefficients & modulus are 128-bit primes
-priv = sss.ShamirSharedSecretPrivate.New(minimum_shares=3, bit_length=128)
+# coefficients & modulus are 264-bit primes (> 256 bits required for MakeDataShares)
+priv = sss.ShamirSharedSecretPrivate.New(3, 264)
 pub  = sss.ShamirSharedSecretPublic.Copy(priv)   # what you publish
 
 print(f'threshold        : {pub.minimum}')
@@ -874,8 +895,8 @@ A single share object looks like `sss.ShamirSharePrivate(minimum=3, modulus=...,
 # Safe Re-constructing the secret
 secret = b'xyz'
 five_shares = priv.MakeDataShares(secret, 5)
-subset = five_shares[:3]                   # any 3 distinct shares
-recovered = subset[0].RecoverData(subset)  # each share has the encrypted data, so you ask it to join with the others
+subset = five_shares[:3]                        # any 3 distinct shares
+recovered = subset[0].RecoverData(subset[1:])   # each share has the encrypted data, pass other shares
 assert recovered == secret
 
 # Raw Re-constructing the secret
@@ -913,7 +934,7 @@ print(priv.RawVerifyShare(secret, tampered))  # ▶ False
 
 ### Setup
 
-If you want to develop for this project, first install python 3.13 and [Poetry](https://python-poetry.org/docs/cli/), but to get the versions you will need, we suggest you do it like this (*Linux*):
+If you want to develop for this project, first install python 3.12 and [Poetry](https://python-poetry.org/docs/cli/), but to get the versions you will need, we suggest you do it like this (*Linux*):
 
 ```sh
 sudo apt-get update
@@ -922,10 +943,10 @@ sudo apt-get install git python3 python3-pip pipx python3-dev python3-venv build
 
 sudo add-apt-repository ppa:deadsnakes/ppa  # install arbitrary python version
 sudo apt-get update
-sudo apt-get install python3.13
+sudo apt-get install python3.12
 
 sudo apt-get remove python3-poetry
-python3.13 -m pipx ensurepath
+python3.12 -m pipx ensurepath
 # re-open terminal
 pipx install poetry
 poetry --version  # should be >=2.1
@@ -941,11 +962,11 @@ brew update
 brew upgrade
 brew cleanup -s
 
-brew install git python@3.13  # install arbitrary python version
+brew install git python@3.12  # install arbitrary python version
 
 brew uninstall poetry
-python3.13 -m pip install --user pipx
-python3.13 -m pipx ensurepath
+python3.12 -m pip install --user pipx
+python3.12 -m pipx ensurepath
 # re-open terminal
 pipx install poetry
 poetry --version  # should be >=2.1
@@ -960,7 +981,7 @@ Now install the project:
 git clone https://github.com/balparda/transcrypto.git transcrypto
 cd transcrypto
 
-poetry env use python3.13  # creates the venv
+poetry env use python3.12  # creates the venv
 poetry sync                # sync env to project's poetry.lock file
 poetry env info            # no-op: just to check
 
@@ -998,7 +1019,7 @@ If you manually added a dependency to `pyproject.toml` you should ***very carefu
 
 ```sh
 rm -rf .venv .poetry poetry.lock
-poetry env use python3.13
+poetry env use python3.12
 poetry install
 ```
 
@@ -1035,7 +1056,7 @@ poetry publish
 If you changed the CLI interface at all, in any tool, run:
 
 ```sh
-./tools/generate_docs.sh
+make docs
 ```
 
 You can find the 10 top slowest tests by running:
@@ -1069,3 +1090,4 @@ $ deactivate
 ```
 
 Hint: 85%+ is inside `MillerRabinIsPrime()`/`gmpy2.powmod()`...
+