Darca Storage Documentation

darca-storage is an async-first, protocol-based storage abstraction designed to support scoped file operations, credential-aware connectors, and session-context observability.

It is the foundation of higher-level modules like darca-repository, and is suitable for use in both local and cloud-capable environments.

Readme

Darca Storage

Async-first, secure, and extensible storage backend abstraction for the Darca ecosystem.

darca-storage provides a clean interface for reading and writing to structured storage backends — local, cloud, or custom — with support for path confinement, credential injection, and session-aware logic.

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

Features

  • ✅ Async-compatible FileBackend interface

  • 🔐 Scoped access via ScopedFileBackend

  • 🧠 Session-aware StorageClient with observability

  • 🔌 Pluggable storage connectors (e.g., file://)

  • 🔄 Credential and user context propagation

  • 🧪 Easy to test and extend

📦 Installation

pip install darca-storage

Or using Poetry:

poetry add darca-storage

Quick Example

from darca_storage.factory import StorageConnectorFactory

client = await StorageConnectorFactory.from_url("file:///tmp/darca")

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

Security by Default

All paths are resolved via ScopedFileBackend, which:

  • Normalizes and confines all access to a declared base_path

  • Prevents path traversal (e.g., ../../etc/passwd)

  • Raises StorageClientPathViolation if the boundary is violated

Extending

Implement a new backend:

class MyBackend(FileBackend):
    async def read(self, path: str, *, binary=False) -> Union[str, bytes]:
        ...

Implement a new connector:

class MyConnector(StorageConnector):
    async def connect(self) -> FileBackend:
        return ScopedFileBackend(...)

Then register your scheme inside StorageConnectorFactory.

📚 Documentation

Visit the full documentation:

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

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-storage

Thanks for your interest in contributing to darca-space-manager — 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-space-manager.git
cd darca-space-manager
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

Project Information

  • Author: Roel Kist

  • License: MIT

  • Version: 0.0.1

Indices and Tables