Welcome to darca-space-manager’s documentation!

This package provides a local storage abstraction layer to manage “spaces” — logical directories backed by metadata. It supports creating, listing, deleting, and tracking files and metadata inside each space.

Project Overview

darca-space-manager

A lightweight, fully-tested Python library to manage logical file-based spaces. Ideal for sandboxing, test environments, or dynamic storage orchestration.

🚀 Overview

darca-space-manager provides a simple abstraction over local file storage by organizing content in logical “spaces”. Each space has its own metadata and supports file-level operations such as reading, writing, deleting, and listing — including support for structured content like YAML and JSON.

✨ Features

• Space creation, deletion, existence checks, and metadata tracking

• File read/write/delete operations within a given space

• Automatic handling of .yaml, .yml, and .json for dictionaries

• Strict ASCII validation when reading text

• Custom exceptions for robust error tracing (SpaceFileManagerException, SpaceManagerException)

• Parallel-safe test fixtures (100% test coverage)

• CI/CD pipelines, auto-doc generation, and live documentation via GitHub Pages

📦 Installation

pip install darca-space-manager

Or using Poetry:

poetry add darca-space-manager

🔧 Usage

from darca_space_manager import SpaceManager, SpaceFileManager

sm = SpaceManager()
sfm = SpaceFileManager()

sm.create_space("demo")
sfm.set_file("demo", "example.yaml", {"foo": "bar"})
print(sfm.get_file("demo", "example.yaml"))  # raw text
sm.delete_space("demo")

📚 Documentation

Visit the full documentation:

👉 https://roelkist.github.io/darca-space-manager/

To build locally:

make docs

📂 Project Layout

darca_space_manager/
├── config.py
├── space_executor.py
├── space_file_manager.py
├── space_manager.py
└── __version__.py

🧪 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.

Getting Started

Contents

• Usage Guide
  • Installation
  • Spaces Overview
  • SpaceManager
  • SpaceFileManager
  • Timestamp Retrieval
  • SpaceExecutor
  • Error Handling
  • Environment Configuration
  • Directory Layout
  • Final Notes
• API Reference
  • SpaceManager
  • SpaceManagerException
  • SpaceFileManager
  • SpaceFileManagerException
  • SpaceExecutor
  • SpaceExecutorException

Community & Contribution

Contributing to darca-space-manager

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.