Usage Guide

This guide walks through how to use darca-repository to resolve and interact with storage repositories via the StorageClient abstraction.

---

Repository Resolution

Start by retrieving a repository profile from the registry:

from darca_repository.registry.factory import get_repository_registry

registry = get_repository_registry()
profile = registry.get_profile("workspace-main")

---

Connect and Use a Repository

Wrap the profile in a RepositoryInstance and connect to its storage:

from darca_repository.instance import RepositoryInstance

repo = RepositoryInstance(profile)
client = await repo.connect()  # returns a StorageClient

Now you can read/write files using the familiar async interface:

await client.write("data/report.txt", content="Hello Darca!")
content = await client.read("data/report.txt")
print(content)

---

Verify Access

Use test_connection() to check if the repository root is reachable and accessible:

success = await repo.test_connection()
if not success:
    raise RuntimeError("Repository is unavailable.")

---

Credential Injection

You can define credentials in your YAML profile using environment variables:

credentials:
  token: ${DARCA_ACCESS_TOKEN}

At runtime, Repository.get_secret(“token”) will resolve ${DARCA_ACCESS_TOKEN} from the environment:

token = profile.get_secret("token")
assert token == os.getenv("DARCA_ACCESS_TOKEN")

These credentials are automatically injected into the connector and client.

---

Repository Profile Example

name: workspace-main
storage_url: file:///data/workspace
scheme: file
credentials:
  token: ${DARCA_TOKEN}
parameters:
  cache: "false"
tags:
  env: dev
enabled: true
priority: 5

---

Next Steps

• See API Reference for a full reference of modules and classes.

• Explore advanced backends (e.g. cloud connectors) via future plugins.