| Name | splurge-base58 JSON |
| Version |
2025.1.1
JSON |
| download |
| home_page | None |
| Summary | Splurge Base58 Helper |
| upload_time | 2025-08-16 21:32:47 |
| maintainer | None |
| docs_url | None |
| author | Jim Schilling |
| requires_python | >=3.10 |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# splurge-base58
A Python library for Base-58 encoding and decoding operations with both CLI and API interfaces.
## Features
- **Pure Python Implementation**: No external dependencies required
- **Bitcoin-Compatible Alphabet**: Uses the standard Bitcoin Base-58 alphabet
- **CLI Interface**: Command-line tool for quick encoding/decoding operations
- **API Interface**: Python class for programmatic use
- **Input Validation**: Comprehensive validation with meaningful error messages
- **Length Constraints**: Configurable input length limits for security
- **Unicode Support**: Full support for UTF-8 encoded strings
- **Error Handling**: Robust error handling with custom exception types
- **Performance Optimized**: Efficient algorithms for encoding and decoding
## Installation
```bash
pip install splurge-base58
```
## CLI Usage
The CLI provides a simple command-line interface for Base-58 operations.
### Basic Commands
```bash
# Encode a string to Base-58
python -m splurge_base58 encode "Hello, World!"
# Decode a Base-58 string
python -m splurge_base58 decode "JxF12TrwUP45BMd"
```
### Command Syntax
```bash
python -m splurge_base58 <command> <input>
```
**Commands:**
- `encode` - Convert input string to Base-58 encoding
- `decode` - Convert Base-58 string back to original data
**Constraints:**
- `encode`: Maximum input length is 2048 characters
- `decode`: Maximum input length is calculated based on maximum encode length
### Examples
```bash
# Encode various types of data
python -m splurge_base58 encode "Hello, World!"
python -m splurge_base58 encode "1234567890"
python -m splurge_base58 encode "Special chars: !@#$%^&*()"
# Decode Base-58 strings
python -m splurge_base58 decode "JxF12TrwUP45BMd"
python -m splurge_base58 decode "2NEpo7TZRRrLZSi2U"
python -m splurge_base58 decode "11111111111111111111111111111111"
# Error handling examples
python -m splurge_base58 decode "invalid!@#" # Invalid Base-58
python -m splurge_base58 encode "" # Empty input
```
### Error Handling
The CLI provides clear error messages for various scenarios:
- **Invalid Base-58 string**: When decode input contains invalid characters
- **Empty input**: When encode input is empty
- **Input too long**: When input exceeds maximum length constraints
- **Unknown command**: When an invalid command is provided
## API Usage
The `Base58` class provides a comprehensive API for Base-58 operations.
### Basic Usage
```python
from splurge_base58.base58 import Base58, Base58Error
# Encode data
data = "Hello, World!".encode('utf-8')
encoded = Base58.encode(data)
print(encoded) # Output: JxF12TrwUP45BMd
# Decode data
decoded = Base58.decode(encoded)
original = decoded.decode('utf-8')
print(original) # Output: Hello, World!
```
### Class Methods
#### `Base58.encode(data: bytes) -> str`
Encodes binary data to a Base-58 string.
```python
# Encode string data
text = "Hello, World!"
data = text.encode('utf-8')
encoded = Base58.encode(data)
# Encode binary data
binary_data = b'\x00\x01\x02\x03'
encoded = Base58.encode(binary_data)
# Encode hash data
import hashlib
hash_data = hashlib.sha256(b"test").digest()
encoded = Base58.encode(hash_data)
```
#### `Base58.decode(base58_data: str) -> bytes`
Decodes a Base-58 string back to binary data.
```python
# Decode to string
encoded = "JxF12TrwUP45BMd"
decoded = Base58.decode(encoded)
text = decoded.decode('utf-8')
# Decode binary data
encoded = "11111111111111111111111111111111"
decoded = Base58.decode(encoded)
print(decoded.hex()) # Output: 00000000000000000000000000000000
```
#### `Base58.is_valid(base58_data: str) -> bool`
Validates if a string is valid Base-58.
```python
# Valid Base-58 strings
Base58.is_valid("JxF12TrwUP45BMd") # True
Base58.is_valid("11111111111111111111111111111111") # True
# Invalid Base-58 strings
Base58.is_valid("invalid!@#") # False
Base58.is_valid("") # False
```
### Error Handling
The API uses custom exception types for different error scenarios:
```python
from splurge_base58.base58 import Base58, Base58Error, Base58TypeError, Base58ValidationError
try:
# Encode with invalid input type
Base58.encode("not bytes") # Raises Base58TypeError
# Encode empty data
Base58.encode(b"") # Raises Base58ValidationError
# Decode invalid Base-58
Base58.decode("invalid!@#") # Raises Base58ValidationError
except Base58TypeError as e:
print(f"Type error: {e}")
except Base58ValidationError as e:
print(f"Validation error: {e}")
except Base58Error as e:
print(f"Base-58 error: {e}")
```
### Practical Examples
#### Encoding JSON Data
```python
import json
from splurge_base58.base58 import Base58
# Encode JSON payload
data = {
"user_id": 12345,
"timestamp": "2024-01-15T10:30:00Z",
"action": "login"
}
json_string = json.dumps(data)
json_bytes = json_string.encode('utf-8')
encoded = Base58.encode(json_bytes)
# Decode and verify
decoded = Base58.decode(encoded)
decoded_json = decoded.decode('utf-8')
restored_data = json.loads(decoded_json)
```
#### Encoding File Data
```python
from splurge_base58.base58 import Base58
# Encode file header (example: PNG header)
file_header = b'\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR\x00\x00\x00\x01\x00\x00\x00\x01'
encoded = Base58.encode(file_header)
# Decode file data
decoded = Base58.decode(encoded)
print(decoded.hex()) # Output: 89504e470d0a1a0a0000000d494844520000000100000001
```
#### Encoding Hash Values
```python
import hashlib
from splurge_base58.base58 import Base58
# Encode SHA-256 hash
password = "password123"
hash_data = hashlib.sha256(password.encode('utf-8')).digest()
encoded = Base58.encode(hash_data)
# Decode hash
decoded = Base58.decode(encoded)
print(decoded.hex()) # Output: 240be01fab5649d2beb87e2d6a5574d
```
### Performance Considerations
The implementation is optimized for performance:
- **Efficient algorithms**: Uses optimized conversion methods
- **Memory efficient**: Minimal memory overhead during operations
- **Fast validation**: Quick validation of Base-58 strings
For large datasets, consider processing data in chunks if needed.
## Examples
See the `examples/` directory for complete working examples:
- `cli_usage.py` - CLI end-to-end workflow examples
- `api_usage.py` - API end-to-end workflow examples
Run the examples:
```bash
# CLI examples
python examples/cli_usage.py
# API examples
python examples/api_usage.py
```
## License
This project is licensed under the MIT License - see the LICENSE file for details.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## Changelog
#### [2025.1.1] - 2025-01-15
- Added comprehensive changelog section to README.md
- Improved test suite organization and reliability
- Enhanced single character decoding test logic with round-trip verification
- Reorganized imports in test files for better code structure
- Improved exception handling test coverage
#### [2025.1.0] - 2025-08-16
- Initial Commit
Raw data
{
"_id": null,
"home_page": null,
"name": "splurge-base58",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": null,
"author": "Jim Schilling",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/ce/80/449ab00b9338a8f70f94bc00cbe4e58ef2b6cf33cef4258603676f201d2c/splurge_base58-2025.1.1.tar.gz",
"platform": null,
"description": "# splurge-base58\r\n\r\nA Python library for Base-58 encoding and decoding operations with both CLI and API interfaces.\r\n\r\n## Features\r\n\r\n- **Pure Python Implementation**: No external dependencies required\r\n- **Bitcoin-Compatible Alphabet**: Uses the standard Bitcoin Base-58 alphabet\r\n- **CLI Interface**: Command-line tool for quick encoding/decoding operations\r\n- **API Interface**: Python class for programmatic use\r\n- **Input Validation**: Comprehensive validation with meaningful error messages\r\n- **Length Constraints**: Configurable input length limits for security\r\n- **Unicode Support**: Full support for UTF-8 encoded strings\r\n- **Error Handling**: Robust error handling with custom exception types\r\n- **Performance Optimized**: Efficient algorithms for encoding and decoding\r\n\r\n## Installation\r\n\r\n```bash\r\npip install splurge-base58\r\n```\r\n\r\n## CLI Usage\r\n\r\nThe CLI provides a simple command-line interface for Base-58 operations.\r\n\r\n### Basic Commands\r\n\r\n```bash\r\n# Encode a string to Base-58\r\npython -m splurge_base58 encode \"Hello, World!\"\r\n\r\n# Decode a Base-58 string\r\npython -m splurge_base58 decode \"JxF12TrwUP45BMd\"\r\n```\r\n\r\n### Command Syntax\r\n\r\n```bash\r\npython -m splurge_base58 <command> <input>\r\n```\r\n\r\n**Commands:**\r\n- `encode` - Convert input string to Base-58 encoding\r\n- `decode` - Convert Base-58 string back to original data\r\n\r\n**Constraints:**\r\n- `encode`: Maximum input length is 2048 characters\r\n- `decode`: Maximum input length is calculated based on maximum encode length\r\n\r\n### Examples\r\n\r\n```bash\r\n# Encode various types of data\r\npython -m splurge_base58 encode \"Hello, World!\"\r\npython -m splurge_base58 encode \"1234567890\"\r\npython -m splurge_base58 encode \"Special chars: !@#$%^&*()\"\r\n\r\n# Decode Base-58 strings\r\npython -m splurge_base58 decode \"JxF12TrwUP45BMd\"\r\npython -m splurge_base58 decode \"2NEpo7TZRRrLZSi2U\"\r\npython -m splurge_base58 decode \"11111111111111111111111111111111\"\r\n\r\n# Error handling examples\r\npython -m splurge_base58 decode \"invalid!@#\" # Invalid Base-58\r\npython -m splurge_base58 encode \"\" # Empty input\r\n```\r\n\r\n### Error Handling\r\n\r\nThe CLI provides clear error messages for various scenarios:\r\n\r\n- **Invalid Base-58 string**: When decode input contains invalid characters\r\n- **Empty input**: When encode input is empty\r\n- **Input too long**: When input exceeds maximum length constraints\r\n- **Unknown command**: When an invalid command is provided\r\n\r\n## API Usage\r\n\r\nThe `Base58` class provides a comprehensive API for Base-58 operations.\r\n\r\n### Basic Usage\r\n\r\n```python\r\nfrom splurge_base58.base58 import Base58, Base58Error\r\n\r\n# Encode data\r\ndata = \"Hello, World!\".encode('utf-8')\r\nencoded = Base58.encode(data)\r\nprint(encoded) # Output: JxF12TrwUP45BMd\r\n\r\n# Decode data\r\ndecoded = Base58.decode(encoded)\r\noriginal = decoded.decode('utf-8')\r\nprint(original) # Output: Hello, World!\r\n```\r\n\r\n### Class Methods\r\n\r\n#### `Base58.encode(data: bytes) -> str`\r\n\r\nEncodes binary data to a Base-58 string.\r\n\r\n```python\r\n# Encode string data\r\ntext = \"Hello, World!\"\r\ndata = text.encode('utf-8')\r\nencoded = Base58.encode(data)\r\n\r\n# Encode binary data\r\nbinary_data = b'\\x00\\x01\\x02\\x03'\r\nencoded = Base58.encode(binary_data)\r\n\r\n# Encode hash data\r\nimport hashlib\r\nhash_data = hashlib.sha256(b\"test\").digest()\r\nencoded = Base58.encode(hash_data)\r\n```\r\n\r\n#### `Base58.decode(base58_data: str) -> bytes`\r\n\r\nDecodes a Base-58 string back to binary data.\r\n\r\n```python\r\n# Decode to string\r\nencoded = \"JxF12TrwUP45BMd\"\r\ndecoded = Base58.decode(encoded)\r\ntext = decoded.decode('utf-8')\r\n\r\n# Decode binary data\r\nencoded = \"11111111111111111111111111111111\"\r\ndecoded = Base58.decode(encoded)\r\nprint(decoded.hex()) # Output: 00000000000000000000000000000000\r\n```\r\n\r\n#### `Base58.is_valid(base58_data: str) -> bool`\r\n\r\nValidates if a string is valid Base-58.\r\n\r\n```python\r\n# Valid Base-58 strings\r\nBase58.is_valid(\"JxF12TrwUP45BMd\") # True\r\nBase58.is_valid(\"11111111111111111111111111111111\") # True\r\n\r\n# Invalid Base-58 strings\r\nBase58.is_valid(\"invalid!@#\") # False\r\nBase58.is_valid(\"\") # False\r\n```\r\n\r\n### Error Handling\r\n\r\nThe API uses custom exception types for different error scenarios:\r\n\r\n```python\r\nfrom splurge_base58.base58 import Base58, Base58Error, Base58TypeError, Base58ValidationError\r\n\r\ntry:\r\n # Encode with invalid input type\r\n Base58.encode(\"not bytes\") # Raises Base58TypeError\r\n \r\n # Encode empty data\r\n Base58.encode(b\"\") # Raises Base58ValidationError\r\n \r\n # Decode invalid Base-58\r\n Base58.decode(\"invalid!@#\") # Raises Base58ValidationError\r\n \r\nexcept Base58TypeError as e:\r\n print(f\"Type error: {e}\")\r\nexcept Base58ValidationError as e:\r\n print(f\"Validation error: {e}\")\r\nexcept Base58Error as e:\r\n print(f\"Base-58 error: {e}\")\r\n```\r\n\r\n### Practical Examples\r\n\r\n#### Encoding JSON Data\r\n\r\n```python\r\nimport json\r\nfrom splurge_base58.base58 import Base58\r\n\r\n# Encode JSON payload\r\ndata = {\r\n \"user_id\": 12345,\r\n \"timestamp\": \"2024-01-15T10:30:00Z\",\r\n \"action\": \"login\"\r\n}\r\n\r\njson_string = json.dumps(data)\r\njson_bytes = json_string.encode('utf-8')\r\nencoded = Base58.encode(json_bytes)\r\n\r\n# Decode and verify\r\ndecoded = Base58.decode(encoded)\r\ndecoded_json = decoded.decode('utf-8')\r\nrestored_data = json.loads(decoded_json)\r\n```\r\n\r\n#### Encoding File Data\r\n\r\n```python\r\nfrom splurge_base58.base58 import Base58\r\n\r\n# Encode file header (example: PNG header)\r\nfile_header = b'\\x89PNG\\r\\n\\x1a\\n\\x00\\x00\\x00\\rIHDR\\x00\\x00\\x00\\x01\\x00\\x00\\x00\\x01'\r\nencoded = Base58.encode(file_header)\r\n\r\n# Decode file data\r\ndecoded = Base58.decode(encoded)\r\nprint(decoded.hex()) # Output: 89504e470d0a1a0a0000000d494844520000000100000001\r\n```\r\n\r\n#### Encoding Hash Values\r\n\r\n```python\r\nimport hashlib\r\nfrom splurge_base58.base58 import Base58\r\n\r\n# Encode SHA-256 hash\r\npassword = \"password123\"\r\nhash_data = hashlib.sha256(password.encode('utf-8')).digest()\r\nencoded = Base58.encode(hash_data)\r\n\r\n# Decode hash\r\ndecoded = Base58.decode(encoded)\r\nprint(decoded.hex()) # Output: 240be01fab5649d2beb87e2d6a5574d\r\n```\r\n\r\n### Performance Considerations\r\n\r\nThe implementation is optimized for performance:\r\n\r\n- **Efficient algorithms**: Uses optimized conversion methods\r\n- **Memory efficient**: Minimal memory overhead during operations\r\n- **Fast validation**: Quick validation of Base-58 strings\r\n\r\nFor large datasets, consider processing data in chunks if needed.\r\n\r\n## Examples\r\n\r\nSee the `examples/` directory for complete working examples:\r\n\r\n- `cli_usage.py` - CLI end-to-end workflow examples\r\n- `api_usage.py` - API end-to-end workflow examples\r\n\r\nRun the examples:\r\n\r\n```bash\r\n# CLI examples\r\npython examples/cli_usage.py\r\n\r\n# API examples\r\npython examples/api_usage.py\r\n```\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License - see the LICENSE file for details.\r\n\r\n## Contributing\r\n\r\nContributions are welcome! Please feel free to submit a Pull Request.\r\n\r\n## Changelog\r\n\r\n#### [2025.1.1] - 2025-01-15\r\n- Added comprehensive changelog section to README.md\r\n- Improved test suite organization and reliability\r\n- Enhanced single character decoding test logic with round-trip verification\r\n- Reorganized imports in test files for better code structure\r\n- Improved exception handling test coverage\r\n\r\n#### [2025.1.0] - 2025-08-16\r\n- Initial Commit\r\n",
"bugtrack_url": null,
"license": null,
"summary": "Splurge Base58 Helper",
"version": "2025.1.1",
"project_urls": {
"Documentation": "https://github.com/jim-schilling/splurge-base58#readme",
"Homepage": "https://github.com/jim-schilling/splurge-base58",
"Issues": "https://github.com/jim-schilling/splurge-base58/issues",
"Repository": "https://github.com/jim-schilling/splurge-base58.git"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "95f55ec30d2bc6f32eec86dcbce3a13019e4a1afee53232d13273ab97b8bbb67",
"md5": "45b32b784161b884f9238bf52513501c",
"sha256": "f2a6b5228f50560aea33f2a973bee4c961361540c3408e373eff634922fd040e"
},
"downloads": -1,
"filename": "splurge_base58-2025.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "45b32b784161b884f9238bf52513501c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 8272,
"upload_time": "2025-08-16T21:32:46",
"upload_time_iso_8601": "2025-08-16T21:32:46.078913Z",
"url": "https://files.pythonhosted.org/packages/95/f5/5ec30d2bc6f32eec86dcbce3a13019e4a1afee53232d13273ab97b8bbb67/splurge_base58-2025.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ce80449ab00b9338a8f70f94bc00cbe4e58ef2b6cf33cef4258603676f201d2c",
"md5": "ef1b10912efba08cb8068b0faf90cc14",
"sha256": "d45c3970c07f9f521afc36311181c55cb582f37877215ff3ed02fa0099db7cc0"
},
"downloads": -1,
"filename": "splurge_base58-2025.1.1.tar.gz",
"has_sig": false,
"md5_digest": "ef1b10912efba08cb8068b0faf90cc14",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 19918,
"upload_time": "2025-08-16T21:32:47",
"upload_time_iso_8601": "2025-08-16T21:32:47.180638Z",
"url": "https://files.pythonhosted.org/packages/ce/80/449ab00b9338a8f70f94bc00cbe4e58ef2b6cf33cef4258603676f201d2c/splurge_base58-2025.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-16 21:32:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jim-schilling",
"github_project": "splurge-base58#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "splurge-base58"
}
