Metadata-Version: 2.4
Name: gufo_blob
Version: 0.1.0
Summary: Unified object storage interface for local filesystems and cloud backends
Author: Gufo Labs
License-Expression: BSD-3-Clause
Project-URL: Bug Tracker, https://github.com/gufolabs/gufo_blob/issues
Project-URL: Changelog, https://github.com/gufolabs/gufo_blob/blob/master/CHANGELOG.md
Project-URL: Documentation, https://docs.gufolabs.com/gufo_blob/
Project-URL: Homepage, https://github.com/gufolabs/gufo_blob/
Project-URL: Source Code, https://github.com/gufolabs/gufo_blob/
Keywords: blob,object-storage,storage,filesystem,fsspec,cloud-storage,python
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Operating System :: OS Independent
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: gufo-loader>=2.0.1
Provides-Extra: docs
Requires-Dist: mkdocs-gen-files==0.5.0; extra == "docs"
Requires-Dist: mkdocs-literate-nav==0.6.2; extra == "docs"
Requires-Dist: mkdocs-material==9.6.11; extra == "docs"
Requires-Dist: mkdocs-section-index==0.3.10; extra == "docs"
Requires-Dist: mkdocstrings[python]==0.29.1; extra == "docs"
Provides-Extra: ipython
Requires-Dist: ipython==9.6.0; extra == "ipython"
Provides-Extra: lint
Requires-Dist: mypy==2.1.0; extra == "lint"
Requires-Dist: ruff==0.15.20; extra == "lint"
Requires-Dist: types-PyYAML==6.0.12.3; extra == "lint"
Provides-Extra: test
Requires-Dist: PyYAML>=6.0; extra == "test"
Requires-Dist: pytest-benchmark==5.1.0; extra == "test"
Requires-Dist: pytest-cov==7.0.0; extra == "test"
Requires-Dist: pytest==9.1.1; extra == "test"
Requires-Dist: pytest-asyncio==1.4.0; extra == "test"
Dynamic: license-file

# Gufo Blob

*Unified blob storage access with predictable semantics.*

[![PyPi version](https://img.shields.io/pypi/v/gufo_blob.svg)](https://pypi.python.org/pypi/gufo_blob/)
![Downloads](https://img.shields.io/pypi/dw/gufo_blob)
![Python Versions](https://img.shields.io/pypi/pyversions/gufo_blob)
[![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
![Build](https://img.shields.io/github/actions/workflow/status/gufolabs/gufo_blob/py-tests.yml?branch=master)
[![codecov](https://codecov.io/gh/gufolabs/gufo_blob/graph/badge.svg?token=WPQTHR6C59)](https://codecov.io/gh/gufolabs/gufo_blob)
![Sponsors](https://img.shields.io/github/sponsors/gufolabs)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v0.json)](https://github.com/charliermarsh/ruff)

---

**Documentation**: [https://docs.gufolabs.com/gufo_blob/](https://docs.gufolabs.com/gufo_blob/)

**Source Code**: [https://github.com/gufolabs/gufo_blob/](https://github.com/gufolabs/gufo_blob/)

Gufo Blob is a lightweight, typed abstraction layer for working with key-based object storage across different backends. It provides a consistent and predictable API for accessing, resolving, and iterating over data regardless of the underlying storage implementation.

## Examples

### Synchronous API

**put/get/delete**

```python
from gufo.blob.sync import open_blob

with open_blob("/var/data") as blob:
    # Store
    blob.put("myproj/k1", b"data")
    # Get
    v = blob.get("myproj/k1")
    # Delete
    blob.delete("myproj/k1")
```

**dict-like API**

```python
from gufo.blob.sync import open_blob

with open_blob("/var/data") as blob:
    # Save
    blob["myproj/k1"] = b"data"
    # Get
    v = blob["myproj/k1"]
    # Delete
    del blob["myproj/k1"]
```

### Asynchronous API

```python
from gufo.blob.aio import open_blob

async def main():
    async with open_blob("/var/data") as blob:
        # Store
        await blob.put("myproj/k1", b"data")
        # Get
        v = await blob.get("myproj/k1")
        # Delete
        await blob.delete("myproj/k1")
```

## Features

- **Sync and async modes** - Provides API for both sync and async modes of operation.
- **Unified blob abstraction** — consistent API for working with different storage backends
- **Backend-agnostic design** — works with local filesystem and pluggable storage implementations
- **Fully typed API** — strict typing for keys, values, and storage contracts
- **Agent-friendly architecture** — explicit interfaces and uniform backend semantics simplify AI-assisted development
- **Simple object model** — intuitive Blob / BlobBase interface with predictable semantics
- **Lazy operations** — resources are initialized and opened only when required
- **Explicit lifecycle control** — optional open() / close() with context manager support
- **Transparent connection handling** — automatic resource management for connected backends
- **Efficient scanning** — fast iteration over stored keys with minimal overhead
- **Key-based access model** — uniform resolution of objects via string keys
- **Error unification** — all runtime issues reduce to `BlobError` and `KeyError`
- **Deterministic behavior** — consistent resolution and iteration order guarantees where applicable
- **Extensible architecture** — easy to add new storage backends and resolvers
- **Designed for composition** — works naturally inside larger systems and pipelines

## On Gufo Stack

This product is a part of [Gufo Stack][Gufo Stack] - the collaborative effort 
led by [Gufo Labs][Gufo Labs]. Our goal is to create a robust and flexible 
set of tools to create network management software and automate 
routine administration tasks.

To do this, we extract the key technologies that have proven themselves 
in the [NOC][NOC] and bring them as separate packages. Then we work on API,
performance tuning, documentation, and testing. The [NOC][NOC] uses the final result
as the external dependencies.

[Gufo Stack][Gufo Stack] makes the [NOC][NOC] better, and this is our primary task. But other products
can benefit from [Gufo Stack][Gufo Stack] too. So we believe that our effort will make 
the other network management products better.

[Gufo Labs]: https://gufolabs.com/
[Gufo Stack]: https://docs.gufolabs.com/
[NOC]: https://getnoc.com/
