Python SDK¶

גישה תוכנתית ל-HomeCloud מ-Python 3.

חבילה: homecloud-sdk · ייבוא: from homecloud import HomeCloud

התקנה¶

pip install homecloud-sdk

אם החבילה עדיין לא ב-PyPI בסביבה שלכם:

pip install "git+https://github.com/HomeCloudLab/homecloud-sdk.git"
# or editable checkout:
pip install -e ../homecloud-sdk

יצירת קליינט¶

from homecloud import HomeCloud

# Explicit (recommended for servers)
client = HomeCloud(
    access_key="HCAK...",
    secret_key="...",
)

# Environment: HC_ACCESS_KEY_ID / HC_SECRET_ACCESS_KEY / HC_APEX
client = HomeCloud.from_env()

# Profile file ~/.homecloud/credentials
client = HomeCloud()
client = HomeCloud(profile="ci")

Async¶

from homecloud import AsyncHomeCloud

async with AsyncHomeCloud.from_env() as client:
    await client.so.upload("docs", "./a.txt", key="a.txt")
    await client.mq.send("orders", {"id": 1})

from homecloud_sdk import … עדיין עובד לתאימות; העדיפו from homecloud import ….

Object Storage¶

client.so.upload("docs", "./readme.md", key="readme.md")
client.so.upload(
    "media",
    body=video_bytes,
    key="videos/clip.mp4",
    content_type="video/mp4",
)

meta = client.so.head_object("docs", "readme.md")
client.so.download("docs", "readme.md", "./copy.md")

print(client.so.get_object_uri("docs", "readme.md"))
print(client.so.generate_presigned_url("docs", "readme.md", expires_in=3600))

client.so.list_objects("docs", prefix="readme")
keys = client.so.list_all_objects("docs", prefix="photos/", recursive=True)
client.so.copy("dest-bucket", "a.txt", "folder/a.txt", source_bucket="src-bucket")
client.so.move("dest-bucket", "a.txt", "folder/a.txt", source_bucket="src-bucket")
client.so.delete("docs", "readme.md")

# API אחד: מקומי↔באקט או באקט↔באקט (כמו CLI `so sync`)
client.so.sync("./dist", "so://my-website/", delete=True)
client.so.sync("so://docs/", "./site")
client.so.sync("so://photos/", "so://backup/photos/", delete=True)

עוזרי ניהול (list_buckets, create_bucket) תומכים ב-Access Key (SigV1) — אותן הרשאות אפקטיביות של המשתמש (כולל קבוצות מערכת). homecloud login נדרש בעיקר לסשן קונסול אינטראקטיבי או למקרים מיוחדים (למשל IR ↔ Docker), לא לרשימת באקטים כשיש credentials.

Message Queues¶

client.mq.send("orders", {"id": 1})
client.mq.send("orders", [{"id": 1}, {"id": 2}])  # batch 1–10

messages = client.mq.receive("orders", max_messages=10, wait_seconds=5)
for msg in messages:
    process(msg)
    client.mq.delete("orders", msg["sequence"])

client.mq.receive("orders", max_messages=10, delete=True)  # receive + ack
client.mq.purge("orders")

dlq = client.mq.receive_dlq("orders", max_messages=5)
client.mq.delete_dlq("orders", 7)
client.mq.purge_dlq("orders")

Functions¶

for fn in client.functions.list():
    print(fn["name"], fn.get("status"))

result = client.functions.invoke("hello", {"name": "Ada"})
print(result)

print(client.functions.url("hello"))
client.functions.enable_url("hello")
client.functions.disable_url("hello")

for row in client.functions.logs("hello")["items"]:
    print(row)
# Breaking (0.5.14+): logs() מחזיר {"items", "next_cursor"} — לא רשימה ישירה.
detail = client.functions.get_invocation("hello", invocation_id)

דומיינים (0.5.15+)¶

hosts = client.domains.list_hosts(domain_id)
client.domains.update_record(domain_id, record_id, record_type="A", record="1.2.3.5", host="www")
client.domains.detach(attachment_id)

משימות ודיאגרמות¶

Management plane — JWT של משתמש (login) או Access Key קשור למשתמש SigV1.

items = client.tasks.search("cert @alice &ops due:overdue")
client.tasks.create("Rotate cert", assignees=["alice"], label_names=["ops"])
client.tasks.assign_me("TASK-12", status="in_progress")
client.tasks.comment("TASK-12", "Deployed to staging")
client.tasks.archive("TASK-12", cancel=True)

diagrams = client.diagrams.list()
client.diagrams.create("Production plan", description="Draft")

Mail¶

boxes = client.mail.list_mailboxes()
msgs = client.mail.list_messages(mailbox_id=boxes[0]["id"], limit=20)
detail = client.mail.get_message(msgs[0]["id"])
raw = client.mail.download_attachment(msgs[0]["id"], "0")

Image Registry¶

print(client.ir.list())
client.ir.create("myapp", keep_last=10)
print(client.ir.usage())

Secrets¶

print(client.secrets.list())

שגיאות¶

from homecloud import HomeCloud, NotFoundError, HomeCloudError

try:
    HomeCloud.from_env().so.head_object("docs", "missing.txt")
except NotFoundError as exc:
    print(exc.resource_type, exc.resource)
except HomeCloudError as exc:
    print(exc.status_code, exc)

Type	Typical status
`NotFoundError`	404
`UnauthorizedError`	401
`PermissionDeniedError`	403
`BadRequestError`	400
`ConflictError`	409
`RateLimitError`	429
`ServiceUnavailableError`	502–504
`ApiError`	other HTTP errors

משתני סביבה¶

Variable	Short	Effect
`HOMECLOUD_PROFILE`	`HC_PROFILE`	Active profile
`HOMECLOUD_ACCESS_KEY_ID`	`HC_ACCESS_KEY_ID`	Access key
`HOMECLOUD_SECRET_ACCESS_KEY`	`HC_SECRET_ACCESS_KEY`	Secret
`HOMECLOUD_ACCOUNT_ID`	`HC_ACCOUNT_ID`	Optional account
`HOMECLOUD_APEX`	`HC_APEX`	Platform domain

קובץ אישורים: ~/.homecloud/credentials (JSON מרובה־פרופילים).

קשר ל-CLI¶

homecloud-cli הוא עטיפת Typer/Rich סביב ה-SDK הזה. העדיפו את ה-CLI לפקודות סנכרון ב-shell/CI ואת ה-SDK בתוך קוד אפליקציה.