https://github.com/standard-crypto/walrus-python
https://github.com/standard-crypto/walrus-python
Last synced: 8 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/standard-crypto/walrus-python
- Owner: standard-crypto
- License: mit
- Created: 2025-04-07T21:06:35.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-04-09T23:15:57.000Z (9 months ago)
- Last Synced: 2025-05-07T20:18:10.753Z (8 months ago)
- Language: Python
- Size: 31.3 KB
- Stars: 3
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project
- awesome-walrus - Standard Crypto Walrus Python SDK - A Python client for interacting with the Walrus HTTP API. (SDKs)
README
# Walrus Python SDK
The walrus-python SDK provides a Python client for interacting with the [Walrus HTTP API](https://docs.wal.app/usage/web-api.html). [Walrus](https://www.walrus.xyz/) is a decentralized storage system built on the Sui blockchain, allowing you to store and retrieve blobs efficiently.
[](https://pypi.org/project/walrus-python/)
[](https://pypi.org/project/walrus-python/)
## Installation
```commandline
pip install walrus-python
```
## Usage
### Initializing the Client
[List of public aggregators & publishers](https://docs.wal.app/usage/web-api.html#public-services)
```python
from walrus import WalrusClient
publisher_url = "https://publisher.walrus-testnet.walrus.space"
aggregator_url = "https://aggregator.walrus-testnet.walrus.space"
client = WalrusClient(publisher_base_url=publisher_url, aggregator_base_url=aggregator_url)
```
### Uploading a Blob
#### Available Parameters
- `encoding_type` (*Optional[str]*): Specifies the encoding used for the blob.
- `epochs` (*Optional[int], default: 1*): Number of epochs ahead of the current one to store the blob.
- `deletable` (*Optional[bool], default: False*): Determines whether the blob can be deleted later (True) or is permanent (False).
- `send_object_to` (*Optional[str]*): If provided, sends the Blob object to the specified Sui address. Default:
#### From Bytes
```python
blob_data = b"Hello Walrus!"
response = client.put_blob(data=blob_data)
print(response)
```
#### From a File
```python
file_path = "path/to/your/file.txt"
response = client.put_blob_from_file(file_path)
print(response)
```
#### From a Binary Stream
```python
url = "https://example.com/stream"
with requests.get(url, stream=True) as response:
result = client.put_blob_from_stream(response.raw)
print(result)
```
### Retrieving a Blob
#### By Blob ID
```python
blob_id = "your-blob-id"
blob_content = client.get_blob(blob_id)
print(blob_content)
```
#### By Object ID
```python
object_id = "your-object-id"
blob_content = client.get_blob_by_object_id(object_id)
print(blob_content)
```
#### As a File
```python
blob_id = "your-blob-id"
destination_path = "downloaded_blob.jpg"
client.get_blob_as_file(blob_id, destination_path)
print(f"Blob saved to {destination_path}")
```
#### As a Stream
```python
blob_id = "your-blob-id"
stream = client.get_blob_as_stream(blob_id)
with open("streamed_blob.bin", "wb") as f:
f.write(stream.read())
```
#### Retrieving Blob Metadata
```python
blob_id = "your-blob-id"
metadata = client.get_blob_metadata(blob_id)
print(metadata)
```
### Error Handling
WalrusAPIError provides structured error information:
```python
try:
client.get_blob("non-existent-id")
except WalrusAPIError as e:
print(e)
```
### Contributing
Contributions are welcome! Please submit a pull request or open an issue for any suggestions, improvements, or bug reports.