Skip to main content

​
Overview

The Contextbase Python SDK provides the ContextbaseFile class for seamless file handling. It automatically manages MIME type detection, Base64 encoding, and file operations.

​
ContextbaseFile Class

​
Creating Files

​
From File Path

from contextbase import ContextbaseFile

# Simple file creation
file = ContextbaseFile.from_path("document.pdf")
print(f"File: {file.name}")        # "document.pdf"
print(f"Type: {file.mime_type}")   # "application/pdf"  
print(f"Size: {file.get_size()}")  # File size in bytes

​
From String Content

# Create file from text
content = "This is a text document with important information."
file = ContextbaseFile.from_data(content, "notes.txt")

# Specify MIME type explicitly  
file = ContextbaseFile.from_data(
    content="Custom content",
    name="data.custom", 
    mime_type="application/custom"
)

​
From Binary Content

# Read binary file
with open("image.png", "rb") as f:
    binary_data = f.read()

file = ContextbaseFile.from_data(binary_data, "screenshot.png")
print(file.mime_type)  # "image/png" (auto-detected)

​
Direct Constructor

import base64

# Create from base64 content directly
base64_content = base64.b64encode(b"Hello World").decode('utf-8')
file = ContextbaseFile(
    name="hello.txt",
    mime_type="text/plain",
    base64_content=base64_content
)

​
File Operations

​
Access File Properties

file = ContextbaseFile.from_path("document.pdf")

# Basic properties
print(file.name)           # "document.pdf"
print(file.mime_type)      # "application/pdf"
print(file.base64_content) # Base64 encoded content

# Get original content
content = file.get_content()  # Returns bytes
size = file.get_size()        # Size in bytes

# Convert to API format
file_dict = file.to_dict()    # {"name": "...", "mime_type": "...", "base64": "..."}

​
File Comparison

file1 = ContextbaseFile.from_data("content", "test.txt")
file2 = ContextbaseFile.from_data("content", "test.txt")
file3 = ContextbaseFile.from_data("different", "test.txt")

print(file1 == file2)  # True (same content and name)
print(file1 == file3)  # False (different content)

​
Publishing Files

The simplest way to upload files: 
from contextbase import Contextbase

client = Contextbase()

# Upload any file type
response = client.publish_file(
    context_name="documents",
    file_path="report.pdf",
    scopes={"user_id": 123}
)

if response.ok:
    print("✅ File uploaded successfully!")

​
Using publish() with ContextbaseFile

For more control over file handling: 
from contextbase import Contextbase, ContextbaseFile

client = Contextbase()

# Method 1: From path
file = ContextbaseFile.from_path("document.pdf")
response = client.publish(
    context_name="documents",
    file=file
)

# Method 2: From content
content = generate_report_content()  # Your function
file = ContextbaseFile.from_data(content, "report.txt")
response = client.publish(
    context_name="generated_reports", 
    file=file
)

​
Supported File Types

The SDK automatically detects MIME types for common extensions:
CategoryExtensionsMIME Types
Documents.pdf, .doc, .docx, .txt, .mdapplication/pdf, text/plain, etc.
Images.png, .jpg, .jpeg, .gif, .svgimage/png, image/jpeg, etc.
Data.csv, .json, .xml, .yamltext/csv, application/json, etc.
Code.py, .js, .html, .csstext/x-python, text/javascript, etc.
Archives.zip, .tar, .gzapplication/zip, etc.
For unknown extensions:
  • String content: Defaults to text/plain
  • Binary content: Defaults to application/octet-stream

​
Advanced Examples

​
Processing Multiple Files

import os
from pathlib import Path

# Upload all PDFs in a directory
pdf_dir = Path("documents/")
for pdf_file in pdf_dir.glob("*.pdf"):
    response = client.publish_file(
        context_name="pdfs_document_library",
        file_path=pdf_file,
        scopes={"category": "manuals"}
    )
    print(f"Uploaded: {pdf_file.name}")

​
Creating Files Dynamically

import json
from datetime import datetime

# Generate JSON report
report_data = {
    "timestamp": datetime.now().isoformat(),
    "metrics": {"cpu": 75, "memory": 60},
    "status": "healthy"
}

# Convert to file and upload
json_content = json.dumps(report_data, indent=2)
file = ContextbaseFile.from_data(json_content, "system-report.json")

response = client.publish(
    context_name="system_reports",
    file=file,
    scopes={"environment": "production"}
)

​
Handling Large Files

# For large files, use streaming approach
def upload_large_file(file_path):
    try:
        # ContextbaseFile handles large files efficiently
        file = ContextbaseFile.from_path(file_path)
        
        response = client.publish_file(
            context_name="storage",
            file_path=file_path
        )
        
        if response.ok:
            print(f"✅ Large file uploaded: {file.name} ({file.get_size()} bytes)")
        else:
            print(f"❌ Upload failed: {response.error.message}")
            
    except ValueError as e:
        print(f"❌ File error: {e}")

​
Error Handling

from contextbase import ContextbaseFile, ContextbaseError

# Handle file creation errors
try:
    file = ContextbaseFile.from_path("nonexistent.pdf")
except ValueError as e:
    print(f"File error: {e}")  # "File not found"

# Handle directory errors
try:
    file = ContextbaseFile.from_path("/some/directory/")
except ValueError as e:
    print(f"Path error: {e}")  # "Path is not a file"

# Handle upload errors
try:
    response = client.publish_file("context", "file.pdf")
    response.raise_for_status()
except ContextbaseError as e:
    print(f"Upload failed: {e.message}")
except ValueError as e:
    print(f"Validation error: {e}")

​
Best Practices

# Use publish_file() for simple uploads
response = client.publish_file("uploads", "file.pdf")

# Use ContextbaseFile for dynamic content
content = generate_content()
file = ContextbaseFile.from_data(content, "dynamic.txt")
response = client.publish("generated", file=file)

# Always check responses
if response.ok:
    print("Success!")
else:
    print(f"Error: {response.error.message}")

​
❌ Avoid These Patterns

# Don't read files manually
with open("file.pdf", "rb") as f:  # ❌ Unnecessary
    content = f.read()
    # ContextbaseFile.from_path() does this automatically

# Don't encode manually
import base64
encoded = base64.b64encode(content)  # ❌ Done automatically

# Don't guess MIME types
file = ContextbaseFile.from_data(content, "file.pdf", "text/plain")  # ❌ Wrong type