# Error System Manual (PPYC_ERR) > As of purepycrypto v3.2.0, the library uses a **unified error system**. > This document is the authoritative reference for error codes and handling. --- ## 1. Design Principles The library strictly divides errors into two categories, semantically clear and never mixed: | Type | Handling | Applicable scenarios | |------|----------|----------------------| | **Fatal error** | **Raise `PPYC_ERR`** | The program can no longer run safely: internal invariant broken (library bug), fatal environment problem, unable to construct an object during initialization | | **Non-fatal error** | **Return a 3-tuple** `(error_code, error_message, suggestion)` | Expected failures: invalid input, failed validation, authentication failure, missing file, parse failure | **Core idea**: expected failures **should not** be expressed with exceptions — the caller can handle them gracefully by checking the return value; whereas a genuine crash should let the exception bubble up to expose the problem. --- ## 2. Fatal Error: `PPYC_ERR` ```python from purepycrypto import PPYC_ERR, PPYC_ERR_INTERNAL try: ... except PPYC_ERR as e: print(e.code) # 'PPYC_ERR_INTERNAL' print(e.message) # human-readable reason print(e.suggestion) # human-readable fix suggestion print(str(e)) # '[PPYC_ERR_INTERNAL] reason Suggestion: ...' ``` ### Construction ```python raise PPYC_ERR(code, message, suggestion="") # or the convenience function from purepycrypto import raise_ppyc raise_ppyc(PPYC_ERR_INTERNAL, "state machine inconsistent", "please file an issue") ``` ### Attributes | Attribute | Type | Description | |-----------|------|-------------| | `code` | `str` | error code, in the form `PPYC_ERR_xxx` | | `message` | `str` | reason description | | `suggestion` | `str` | fix suggestion (may be empty) | | `as_tuple()` | method | returns `(code, message, suggestion)` | ### Legacy Exception Name Compatibility The following historical exception names remain available; all are **subclasses** of `PPYC_ERR` and carry `code/message/suggestion`: | Legacy name | Default code | |-------------|--------------| | `CryptoError` | `PPYC_ERR_INTERNAL` | | `DecryptionError` | `PPYC_ERR_AUTH_FAILED` | | `Ed25519Error` | `PPYC_ERR_INVALID_ARG` | | `PPYCError` | (alias of `PPYC_ERR`) | --- ## 3. Non-Fatal Errors: 3-Tuple Return ```python from purepycrypto import err, ok, is_ok, is_err, OK_TUPLE # error return err(PPYC_ERR_INVALID_KEY_LEN, "AES key must be 16/24/32 bytes", "pass a correct length") # -> ('PPYC_ERR_INVALID_KEY_LEN', 'AES key must be 16/24/32 bytes', 'pass a correct length') # success (validation-style API) return OK_TUPLE # (None, None, None) ``` ### Caller Checks ```python result = some_api(...) # method 1: generic check (works for any API) if is_err(result): code, msg, hint = result print(code, msg, hint) # method 2: using aes.gcm_decrypt as an example (returns plaintext bytes on success, a tuple on failure) out = aes.gcm_decrypt(nonce, ct, tag, aad) if isinstance(out, tuple) and out[0] is not None: code, msg, hint = out ... # handle the error else: plaintext = out ``` ### Helper Functions | Function | Description | |----------|-------------| | `err(code, message, suggestion="")` | construct an error tuple (validates the `PPYC_ERR_` prefix) | | `ok(value)` | semantically marks "success"; equivalent to returning `value` directly | | `OK_TUPLE` | `(None, None, None)`, the success return of validation-style APIs | | `is_ok(result)` | determines success (`None` or `(None,None,None)` or an ordinary value) | | `is_err(result)` | determines whether it is an error tuple (`(PPYC_ERR_xxx, msg, hint)`) | | `PPYCResult` | type alias `Tuple[Optional[str], Optional[str], Optional[str]]` | --- ## 4. Complete Error-Code Table Import methods: ```python from purepycrypto import PPYC_ERR_INVALID_KEY_LEN # import a single one directly from purepycrypto import ALL_ERROR_CODES # all (tuple) ``` ### 4.1 General | Error code | Meaning | |------------|---------| | `PPYC_ERR_UNKNOWN` | uncategorized error | | `PPYC_ERR_INTERNAL` | internal inconsistency (should raise `PPYC_ERR`) | | `PPYC_ERR_UNSUPPORTED` | unsupported feature / value | | `PPYC_ERR_NOT_IMPLEMENTED` | not yet implemented | ### 4.2 Argument Validation | Error code | Meaning | |------------|---------| | `PPYC_ERR_INVALID_ARG` | invalid argument (general) | | `PPYC_ERR_INVALID_TYPE` | invalid type (e.g. not bytes) | | `PPYC_ERR_INVALID_LENGTH` | invalid length (general) | | `PPYC_ERR_INVALID_HEX` | invalid hexadecimal format | | `PPYC_ERR_OUT_OF_RANGE` | value out of range | | `PPYC_ERR_MESSAGE_TOO_LONG` | message too long (exceeds the encoding limit) | | `PPYC_ERR_INPUT_TOO_LARGE` | input exceeds the algorithm limit | ### 4.3 Key / nonce / IV | Error code | Meaning | |------------|---------| | `PPYC_ERR_INVALID_KEY` | invalid key (general) | | `PPYC_ERR_INVALID_KEY_LEN` | invalid key length | | `PPYC_ERR_INVALID_NONCE` | invalid nonce | | `PPYC_ERR_INVALID_NONCE_LEN` | invalid nonce length | | `PPYC_ERR_INVALID_IV` | invalid IV | | `PPYC_ERR_INVALID_IV_LEN` | invalid IV length | | `PPYC_ERR_INVALID_SALT` | invalid salt | ### 4.4 Authentication / Decryption | Error code | Meaning | |------------|---------| | `PPYC_ERR_AUTH_FAILED` | authentication failure (AEAD tag / signature verification fails) | | `PPYC_ERR_DECRYPT_FAILED` | decryption failure | | `PPYC_ERR_INVALID_PADDING` | invalid padding (PKCS#7 etc.) | | `PPYC_ERR_INVALID_SIGNATURE` | invalid signature / verification fails | | `PPYC_ERR_INVALID_TAG` | invalid authentication tag | ### 4.5 Encoding / Parsing | Error code | Meaning | |------------|---------| | `PPYC_ERR_INVALID_ENCODING` | invalid encoding format (DER / PEM) | | `PPYC_ERR_PARSE_FAILED` | parse failure | | `PPYC_ERR_INVALID_POINT` | invalid curve point (decoding / low order) | | `PPYC_ERR_INVALID_KEY_MATERIAL` | invalid key material | ### 4.6 File / IO | Error code | Meaning | |------------|---------| | `PPYC_ERR_FILE_NOT_FOUND` | file not found | | `PPYC_ERR_IO` | read/write failure | | `PPYC_ERR_PERMISSION` | insufficient permission | ### 4.7 Environment / Dependencies | Error code | Meaning | |------------|---------| | `PPYC_ERR_NO_MULTIPROCESS` | multiprocessing unavailable | | `PPYC_ERR_ENV` | runtime environment problem | ### 4.8 Algorithm / Parameter Domain | Error code | Meaning | |------------|---------| | `PPYC_ERR_INVALID_PARAM` | invalid algorithm parameter | | `PPYC_ERR_INVALID_KDF_PARAM` | invalid KDF parameter (t/m/p/N/r/iterations/dklen) | | `PPYC_ERR_INVALID_RSA_BITS` | invalid RSA bit size | | `PPYC_ERR_INVALID_ALGO` | invalid algorithm name | | `PPYC_ERR_INVALID_MODE` | invalid mode (ECB/CBC/GCM…) | | `PPYC_ERR_INVALID_OPERATION` | invalid operation (enc/dec…) | ### 4.9 CLI / TUI | Error code | Meaning | |------------|---------| | `PPYC_ERR_CLI_USAGE` | command-line usage error | | `PPYC_ERR_CLI_INPUT` | invalid interactive input | | `PPYC_ERR_EOF` | input stream ended (pipe / redirect) | --- ## 5. Real Examples ### 5.1 Library Call (checking the return value) ```python from purepycrypto import AES, is_err, PPYC_ERR_AUTH_FAILED aes = AES(key) result = aes.gcm_encrypt(nonce, plaintext, aad) if is_err(result): print("encryption parameter error:", result) else: ct, tag = result ``` ### 5.2 Command Line (automatic exit-code mapping) ```bash $ purepycrypto hash --algo nope --text abc --hex [✗] PPYC_ERR_INVALID_ALGO: unknown algorithm: nope Suggestion: available: sha256 / sha512 / blake2b $ echo $? # 2 (PPYC_ERR uniformly returns 2) ``` CLI exit code conventions: | Exit code | Meaning | |-----------|---------| | `0` | success | | `1` | other (e.g. argparse usage error, verification FAIL) | | `2` | `PPYC_ERR` (fatal error) | | `3` | file not found | | `4` | argument error (ValueError / TypeError) | ### 5.3 TUI (graceful EOF handling) ```bash $ echo "" | purepycrypto ... Select > [✗] PPYC_ERR_EOF: 输入流已结束(EOF) 建议: 交互式 TUI 需要终端输入;脚本化请用命令行模式 purepycrypto <子命令> ``` --- ## 6. Authoring Conventions (for contributors) 1. **Single source of error definitions**: the library defines error codes and exception classes only in `purepycrypto/_ppyc_error.py`; all other modules use `from ._ppyc_error import ...` and must not invent error-code string literals. 2. **Error-code prefix enforced**: `err()` validates the `PPYC_ERR_` prefix and raises `PPYC_ERR` if it does not match. 3. **docstrings must have a "Returns" section**: describe the normal return value, as well as the 3-tuple on error and the possible error codes. 4. **`raise ValueError` must not be used**: for parameter validation use `return err(...)`; for internal contradictions use `raise PPYC_ERR(...)`. 5. **Authentication failures go through tuples**: AEAD tag verification and signature verification failures → `return err(PPYC_ERR_AUTH_FAILED, ...)`. --- *This manual is released together with `purepycrypto`. Error-code constants are in `purepycrypto/_ppyc_error.py`.*