Darca Repository Documentation

Welcome to the official documentation for darca-repository — an async-aware, credential-capable repository abstraction built on top of darca-storage.

It enables logical data spaces to be resolved, validated, and connected with secure access control and extensible backend support.

Note

This project is part of the Darca ecosystem. See https://github.com/roelkist for related modules.

Readme

darca-repository

A session-aware, credential-capable repository abstraction for structured storage backends.

darca-repository enables secure, pluggable resolution of storage spaces into active clients. It builds on darca-storage and provides a registry-driven mechanism to manage logical repositories with rich metadata, credential handling, and async file operations.

Build Status Deploy Status Codecov Black code style License PyPi GitHub Pages

Features

  • ✅ Async-first storage repository resolution

  • 🔐 Credential injection via secrets or environment variables

  • 🔄 Session metadata propagation for observability

  • 🔌 Pluggable registry backends (YAML, SQL-ready)

  • 🔎 Clean interface for probing, connecting, and verifying access

Requirements

  • Python >= 3.9

  • darca-storage

  • pydantic

  • PyYAML (if using YAML-based registries)

📦 Installation

pip install darca-repository

Or using Poetry:

poetry add darca-repository

Quick Usage

from darca_repository.instance import RepositoryInstance
from darca_repository.registry.factory import get_repository_registry

registry = get_repository_registry()
profile = registry.get_profile("my-space")

repo = RepositoryInstance(profile)
client = await repo.connect()

await client.write("hello.txt", content="Hello, Darca!")

Repository Format (YAML)

Example YAML file (workspace-main.yaml):

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

📚 Documentation

Visit the full documentation:

👉 https://roelkist.github.io/darca-repository/

To build locally:

make docs

🧪 Testing

Run all tests using:

make test

Coverage and reports:

  • Generates coverage.svg badge

  • Stores HTML output in htmlcov/

  • Fully parallel test support with xdist

🤝 Contributing

We welcome all contributions!

  • Create a new branch from main

  • Use PRs to submit changes

  • You can also open feature requests or issues using our GitHub templates

See CONTRIBUTING.rst for detailed guidelines.

📄 License

This project is licensed under the MIT License. See LICENSE for details.

Community & Contribution

Contributing to darca-repository

Thanks for your interest in contributing to darca-repository — a project by Roel Kist.

We welcome issues, pull requests, questions, suggestions, and other contributions from the community.

Getting Started

Clone the project and set up the development environment:

git clone https://github.com/roelkist/darca-repository.git
cd darca-repository
make install

This will create a virtual environment and install all dependencies needed for development, testing, and formatting.

Workflow

  • 🔍 Open an issue first for bugs or major features

  • ✅ Fork, branch, and develop your changes

  • 📦 Run tests and checks locally before submitting your PR

  • 📝 Include docstrings and tests for new functionality

Make Targets

make test      # Run full test suite with coverage
make check     # Run linting, formatting, and typing
make format    # Auto-format code (black, ruff)
make clean     # Remove temp files, caches, build artifacts

Testing

Tests are located in the tests/ directory and use pytest.

All code contributions must be accompanied by appropriate tests and aim to maintain 100% coverage:

make test

Code Style

This project enforces strict quality and consistency via:

  • Black - formatting

  • Ruff - linting and import sorting

  • Mypy - type checking

make check     # Run all style and quality checks
make format    # Auto-fix lint and formatting issues

Commit & Pull Request Guidelines

  • Use clear, conventional commit messages

  • Keep PRs small and focused

  • Describe the change and link to any relevant issues

  • Pass all CI checks before review

Maintainer

This project is developed and maintained by:

Roel Kist GitHub: https://github.com/roelkist

License

All contributions are licensed under the MIT License.

Contents

Guide

API Reference

About

  • Author: Roel Kist

  • License: MIT

  • Version: 0.1.0

Indices and Tables