# OnchFS Python Client
Python client for the OnchFS (On-Chain File System) protocol on Tezos blockchain.
## Installation
```bash
pip install pyonchfs
```
## Command Line Interface
OnchFS includes a powerful CLI for easy file uploads and downloads:
### Setup
```bash
# Set your Tezos secret key (required for uploads)
export TZ_SK="edsk..." # Your Tezos secret key
```
### Upload Files
```bash
# Upload a single file (uploads as individual file, not wrapped in directory)
onchfs upload myfile.txt
# or
python -m onchfs upload myfile.txt
# Upload a directory with compression
onchfs upload ./my-website --compress
# Upload to mainnet (defaults to ghostnet)
onchfs upload ./docs --network mainnet
# Skip confirmation prompt
onchfs upload ./data --yes
# Quiet mode - only output onchfs:// URL (perfect for scripts)
onchfs upload myfile.txt --yes --quiet # Outputs: onchfs://[file_hash]
onchfs upload ./website --yes --quiet # Outputs: onchfs://[directory_hash]
```
### Download Files
```bash
# Download from hash (automatically detects files vs directories)
onchfs download 6a89c4e7d38f8ffc1ddba97037aa83181b56326bf5e1f5b95070ba7789813832 ./downloaded
# or
python -m onchfs download 6a89c4e7d38f8ffc1ddba97037aa83181b56326bf5e1f5b95070ba7789813832 ./downloaded
# Download from onchfs:// URL
onchfs download onchfs://6a89c4e7d38f8ffc1ddba97037aa83181b56326bf5e1f5b95070ba7789813832 ./downloaded
# Download single file (saves directly to specified path)
onchfs download [file_hash] ./myfile.txt
# Download directory (extracts all files to specified directory)
onchfs download [directory_hash] ./my-website/
# Quiet mode - no output on success
onchfs download 6a89c4e7d38f8ffc1ddba97037aa83181b56326bf5e1f5b95070ba7789813832 ./downloaded --quiet
```
### Automation & Scripting
The quiet mode is perfect for automation and scripting:
```bash
# Capture upload URL in a variable
URL=$(onchfs upload myfile.txt --yes --quiet)
echo "File uploaded to: $URL"
# Use in pipelines
onchfs upload data.json -y -q | xargs -I {} echo "Data available at: {}"
# Batch processing
for file in *.txt; do
url=$(onchfs upload "$file" -y -q)
echo "$file -> $url"
done
```
### CLI Options
```bash
onchfs --help # Show help
python -m onchfs --help # Alternative way
onchfs upload --help # Upload help
onchfs download --help # Download help
# Global options
--network {mainnet,ghostnet,localnet} # Choose network (default: ghostnet)
# Upload options
--compress # Enable compression
--chunk-size SIZE # Set chunk size in bytes (default: 16384)
--yes, -y # Skip confirmation prompt
--quiet, -q # Quiet mode - only output onchfs:// URL
# Download options
--quiet, -q # Quiet mode - no output on success
```
## Python API
### Quick Start
### Download Files
```python
from onchfs import OnchfsClient, Network
client = OnchfsClient(network=Network.MAINNET)
# Download directory
directory_hash = "f8020273fba472a3e87baf6eb0f3929915edabace0fa409a261c4c4fa6684b21"
files = client.download_directory(directory_hash, "downloaded/")
# Get specific file
content = client.get_file(directory_hash, "index.html")
```
### Prepare Files for Upload
```python
from onchfs import OnchfsClient, IFile, OnchfsPrepareOptions
client = OnchfsClient()
# Prepare files
files = [
IFile(path="hello.txt", content=b"Hello, OnchFS!"),
IFile(path="data.json", content=b'{"message": "test"}')
]
directory_inode = client.prepare_files(files)
directory_hash = client.get_directory_hash(directory_inode)
```
### Upload a Whole Directory (Improved API)
```python
import os
from onchfs import OnchfsUploader, Network, OnchfsPrepareOptions
from pytezos import pytezos
# Load Tezos secret key from environment
secret_key = os.getenv('TZ_SK')
if not secret_key:
raise ValueError("TZ_SK environment variable not set")
# Initialize PyTezos client with secret key
pytezos_client = pytezos.using(
key=secret_key,
shell=Network.GHOSTNET.value # or your preferred RPC endpoint
)
# Initialize OnchFS uploader with network (contracts auto-resolved!)
uploader = OnchfsUploader(pytezos_client, Network.GHOSTNET)
# Prepare directory for upload
directory_path = "./my_website" # Path to your directory
directory_inode = uploader.prepare_directory(
directory_path,
options=OnchfsPrepareOptions(compress=True)
)
# Get the directory hash (this is what you'll use to access files)
directory_hash = uploader.get_directory_hash(directory_inode)
print(f"Directory hash: {directory_hash}")
# Estimate upload cost
cost_estimate = uploader.estimate_cost(directory_inode)
print(f"Estimated cost: {cost_estimate}")
# Upload to OnchFS (contract address automatically resolved!)
print("Starting upload...")
result = uploader.upload_directory(directory_inode)
print(f"Upload operation hash: {result.operation_hash}")
print(f"Your files are now accessible at: onchfs://{result.directory_hash}")
```
**Environment Setup:**
```bash
# Set your Tezos secret key
export TZ_SK="edsk..." # Your Tezos secret key
# Run your upload script
python upload_directory.py
```
## API
### OnchfsUploader (Recommended)
```python
from onchfs import OnchfsUploader, Network
from pytezos import pytezos
# Initialize with automatic contract resolution
uploader = OnchfsUploader(pytezos_client, Network.GHOSTNET)
# Upload without specifying contract address
result = uploader.upload_directory(directory_inode)
```
### OnchfsClient
```python
client = OnchfsClient(
network=Network.MAINNET, # MAINNET, GHOSTNET, SHADOWNET, LOCALNET
contract_address=None, # Optional custom contract
pytezos_client=None # Optional PyTezos client
)
```
**Download Methods:**
- `download_directory(hash, target_dir)` - Download all files
- `get_file(hash, filename)` - Get file content
- `get_file_metadata(hash, filename)` - Get file metadata
- `list_directory(hash)` - List directory contents
**Preparation Methods:**
- `prepare_files(files, options=None)` - Prepare files for upload
- `prepare_directory(path, options=None)` - Prepare directory
- `estimate_upload_cost(directory_inode)` - Estimate costs
- `get_directory_hash(directory_inode)` - Get hash
### Types
```python
from onchfs import IFile, OnchfsPrepareOptions
file = IFile(path="example.txt", content=b"content")
options = OnchfsPrepareOptions(chunk_size=16384, compress=True)
```
## Examples
Run the included examples:
```bash
python examples/download_example.py
python examples/prepare_example.py
```
## Contract Addresses
- **Mainnet**: `KT1Ae7dT1gsLw2tRnUMXSCmEyF74KVkM6LUo`
- **Ghostnet**: `KT1FA8AGGcJha6S6MqfBUiibwTaYhK8u7s9Q`
Raw data
{
"_id": null,
"home_page": null,
"name": "pyonchfs",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "\"objkt.com\" <hi@objkt.com>",
"keywords": "tezos, blockchain, onchfs, file-system, storage, ipfs-alternative",
"author": null,
"author_email": "\"objkt.com\" <hi@objkt.com>",
"download_url": "https://files.pythonhosted.org/packages/f0/c2/a06430a139a94d419b0fc2b9eed9044cf71cad6fe953f746b3de75338b48/pyonchfs-0.1.6.tar.gz",
"platform": null,
"description": "# OnchFS Python Client\n\nPython client for the OnchFS (On-Chain File System) protocol on Tezos blockchain.\n\n## Installation\n\n```bash\npip install pyonchfs\n```\n\n## Command Line Interface\n\nOnchFS includes a powerful CLI for easy file uploads and downloads:\n\n### Setup\n\n```bash\n# Set your Tezos secret key (required for uploads)\nexport TZ_SK=\"edsk...\" # Your Tezos secret key\n```\n\n### Upload Files\n\n```bash\n# Upload a single file (uploads as individual file, not wrapped in directory)\nonchfs upload myfile.txt\n# or\npython -m onchfs upload myfile.txt\n\n# Upload a directory with compression\nonchfs upload ./my-website --compress\n\n# Upload to mainnet (defaults to ghostnet)\nonchfs upload ./docs --network mainnet\n\n# Skip confirmation prompt\nonchfs upload ./data --yes\n\n# Quiet mode - only output onchfs:// URL (perfect for scripts)\nonchfs upload myfile.txt --yes --quiet # Outputs: onchfs://[file_hash]\nonchfs upload ./website --yes --quiet # Outputs: onchfs://[directory_hash]\n```\n\n### Download Files\n\n```bash\n# Download from hash (automatically detects files vs directories)\nonchfs download 6a89c4e7d38f8ffc1ddba97037aa83181b56326bf5e1f5b95070ba7789813832 ./downloaded\n# or\npython -m onchfs download 6a89c4e7d38f8ffc1ddba97037aa83181b56326bf5e1f5b95070ba7789813832 ./downloaded\n\n# Download from onchfs:// URL\nonchfs download onchfs://6a89c4e7d38f8ffc1ddba97037aa83181b56326bf5e1f5b95070ba7789813832 ./downloaded\n\n# Download single file (saves directly to specified path)\nonchfs download [file_hash] ./myfile.txt\n\n# Download directory (extracts all files to specified directory)\nonchfs download [directory_hash] ./my-website/\n\n# Quiet mode - no output on success\nonchfs download 6a89c4e7d38f8ffc1ddba97037aa83181b56326bf5e1f5b95070ba7789813832 ./downloaded --quiet\n```\n\n### Automation & Scripting\n\nThe quiet mode is perfect for automation and scripting:\n\n```bash\n# Capture upload URL in a variable\nURL=$(onchfs upload myfile.txt --yes --quiet)\necho \"File uploaded to: $URL\"\n\n# Use in pipelines\nonchfs upload data.json -y -q | xargs -I {} echo \"Data available at: {}\"\n\n# Batch processing\nfor file in *.txt; do\n url=$(onchfs upload \"$file\" -y -q)\n echo \"$file -> $url\"\ndone\n```\n\n### CLI Options\n\n```bash\nonchfs --help # Show help\npython -m onchfs --help # Alternative way\nonchfs upload --help # Upload help\nonchfs download --help # Download help\n\n# Global options\n--network {mainnet,ghostnet,localnet} # Choose network (default: ghostnet)\n\n# Upload options\n--compress # Enable compression\n--chunk-size SIZE # Set chunk size in bytes (default: 16384)\n--yes, -y # Skip confirmation prompt\n--quiet, -q # Quiet mode - only output onchfs:// URL\n\n# Download options\n--quiet, -q # Quiet mode - no output on success\n```\n\n## Python API\n\n### Quick Start\n\n### Download Files\n\n```python\nfrom onchfs import OnchfsClient, Network\n\nclient = OnchfsClient(network=Network.MAINNET)\n\n# Download directory\ndirectory_hash = \"f8020273fba472a3e87baf6eb0f3929915edabace0fa409a261c4c4fa6684b21\"\nfiles = client.download_directory(directory_hash, \"downloaded/\")\n\n# Get specific file\ncontent = client.get_file(directory_hash, \"index.html\")\n```\n\n### Prepare Files for Upload\n\n```python\nfrom onchfs import OnchfsClient, IFile, OnchfsPrepareOptions\n\nclient = OnchfsClient()\n\n# Prepare files\nfiles = [\n IFile(path=\"hello.txt\", content=b\"Hello, OnchFS!\"),\n IFile(path=\"data.json\", content=b'{\"message\": \"test\"}')\n]\n\ndirectory_inode = client.prepare_files(files)\ndirectory_hash = client.get_directory_hash(directory_inode)\n```\n\n### Upload a Whole Directory (Improved API)\n\n```python\nimport os\nfrom onchfs import OnchfsUploader, Network, OnchfsPrepareOptions\nfrom pytezos import pytezos\n\n# Load Tezos secret key from environment\nsecret_key = os.getenv('TZ_SK')\nif not secret_key:\n raise ValueError(\"TZ_SK environment variable not set\")\n\n# Initialize PyTezos client with secret key\npytezos_client = pytezos.using(\n key=secret_key,\n shell=Network.GHOSTNET.value # or your preferred RPC endpoint\n)\n\n# Initialize OnchFS uploader with network (contracts auto-resolved!)\nuploader = OnchfsUploader(pytezos_client, Network.GHOSTNET)\n\n# Prepare directory for upload\ndirectory_path = \"./my_website\" # Path to your directory\ndirectory_inode = uploader.prepare_directory(\n directory_path,\n options=OnchfsPrepareOptions(compress=True)\n)\n\n# Get the directory hash (this is what you'll use to access files)\ndirectory_hash = uploader.get_directory_hash(directory_inode)\nprint(f\"Directory hash: {directory_hash}\")\n\n# Estimate upload cost\ncost_estimate = uploader.estimate_cost(directory_inode)\nprint(f\"Estimated cost: {cost_estimate}\")\n\n# Upload to OnchFS (contract address automatically resolved!)\nprint(\"Starting upload...\")\nresult = uploader.upload_directory(directory_inode)\n\nprint(f\"Upload operation hash: {result.operation_hash}\")\nprint(f\"Your files are now accessible at: onchfs://{result.directory_hash}\")\n```\n\n**Environment Setup:**\n\n```bash\n# Set your Tezos secret key\nexport TZ_SK=\"edsk...\" # Your Tezos secret key\n\n# Run your upload script\npython upload_directory.py\n```\n\n## API\n\n### OnchfsUploader (Recommended)\n\n```python\nfrom onchfs import OnchfsUploader, Network\nfrom pytezos import pytezos\n\n# Initialize with automatic contract resolution\nuploader = OnchfsUploader(pytezos_client, Network.GHOSTNET)\n\n# Upload without specifying contract address\nresult = uploader.upload_directory(directory_inode)\n```\n\n### OnchfsClient\n\n```python\nclient = OnchfsClient(\n network=Network.MAINNET, # MAINNET, GHOSTNET, SHADOWNET, LOCALNET\n contract_address=None, # Optional custom contract\n pytezos_client=None # Optional PyTezos client\n)\n```\n\n**Download Methods:**\n\n- `download_directory(hash, target_dir)` - Download all files\n- `get_file(hash, filename)` - Get file content\n- `get_file_metadata(hash, filename)` - Get file metadata\n- `list_directory(hash)` - List directory contents\n\n**Preparation Methods:**\n\n- `prepare_files(files, options=None)` - Prepare files for upload\n- `prepare_directory(path, options=None)` - Prepare directory\n- `estimate_upload_cost(directory_inode)` - Estimate costs\n- `get_directory_hash(directory_inode)` - Get hash\n\n### Types\n\n```python\nfrom onchfs import IFile, OnchfsPrepareOptions\n\nfile = IFile(path=\"example.txt\", content=b\"content\")\noptions = OnchfsPrepareOptions(chunk_size=16384, compress=True)\n```\n\n## Examples\n\nRun the included examples:\n\n```bash\npython examples/download_example.py\npython examples/prepare_example.py\n```\n\n## Contract Addresses\n\n- **Mainnet**: `KT1Ae7dT1gsLw2tRnUMXSCmEyF74KVkM6LUo`\n- **Ghostnet**: `KT1FA8AGGcJha6S6MqfBUiibwTaYhK8u7s9Q`\n",
"bugtrack_url": null,
"license": null,
"summary": "Python client and CLI for the OnchFS (On-Chain File System) protocol on Tezos blockchain",
"version": "0.1.6",
"project_urls": {
"Bug Tracker": "https://github.com/objkt-com/pyonchfs/issues",
"Documentation": "https://github.com/objkt-com/pyonchfs#readme",
"Homepage": "https://github.com/objkt-com/pyonchfs",
"Repository": "https://github.com/objkt-com/pyonchfs"
},
"split_keywords": [
"tezos",
" blockchain",
" onchfs",
" file-system",
" storage",
" ipfs-alternative"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f6603d199f07ef9582855bd9f2b2a3137a5ae8f8a20e85e270e194f12c2aa749",
"md5": "3334e6febb16ac3596c0c73d876cb072",
"sha256": "ea51fea5f0ff53a264394fd3652af22aca91839909997f4411bf82efceab2859"
},
"downloads": -1,
"filename": "pyonchfs-0.1.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3334e6febb16ac3596c0c73d876cb072",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 26174,
"upload_time": "2025-09-20T09:14:57",
"upload_time_iso_8601": "2025-09-20T09:14:57.322870Z",
"url": "https://files.pythonhosted.org/packages/f6/60/3d199f07ef9582855bd9f2b2a3137a5ae8f8a20e85e270e194f12c2aa749/pyonchfs-0.1.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f0c2a06430a139a94d419b0fc2b9eed9044cf71cad6fe953f746b3de75338b48",
"md5": "6ff55cd6a4c03f7ef517fae70e678757",
"sha256": "7fd91b3f2b78abdd95132181401296c406cd04c2be1a0ce63406b66684b17cbd"
},
"downloads": -1,
"filename": "pyonchfs-0.1.6.tar.gz",
"has_sig": false,
"md5_digest": "6ff55cd6a4c03f7ef517fae70e678757",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 30284,
"upload_time": "2025-09-20T09:14:58",
"upload_time_iso_8601": "2025-09-20T09:14:58.901260Z",
"url": "https://files.pythonhosted.org/packages/f0/c2/a06430a139a94d419b0fc2b9eed9044cf71cad6fe953f746b3de75338b48/pyonchfs-0.1.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-20 09:14:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "objkt-com",
"github_project": "pyonchfs",
"github_not_found": true,
"lcname": "pyonchfs"
}
JSON
