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
Construction
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
Caller Checks
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:
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)
5.2 Command Line (automatic exit-code mapping)
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)
6. Authoring Conventions (for contributors)
- 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.
- Error-code prefix enforced:
err() validates the PPYC_ERR_ prefix and raises PPYC_ERR if it does not match.
- docstrings must have a "Returns" section: describe the normal return value, as well as the 3-tuple on error and the possible error codes.
raise ValueError must not be used: for parameter validation use return err(...); for internal contradictions use raise PPYC_ERR(...).
- 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.