ymlstash

A simple ORM-like utility for operating on local YAML files via Python dataclasses.

In the context of this library, a stash is a diretory in the filesystem that holds many .yml files that all adhere to the same structure.

ymlstash simplifies the management of such a basic database of files.

Install

Package is published on PyPI - https://pypi.org/project/ymlstash/

Install from pip or your favorite package manager:

$ pip install ymlstash

Usage

Start by defining your model as a dataclass:

from dataclasses import dataclass
from typing import ClassVar

@dataclass
class User:
    name: str
    age: int
    active: bool
    key: ClassVar[str] = "name"

Primary Keys

Each model must include a primary key that will be used as the entry filename to uniquely access each record.

The recommended way do to this is with the special key field which is used to denote that name should be used as the primary key field. If an object has name: "foo", it will be saved as foo.yml in the stash root directory.

Actions

Instantiate a new object:

user = User(name="yuval", age=42, active=True)

Save it to file:

from ymlstash import YmlStash

stash = YmlStash(User, "path/to/db")  # path can either be a string or Path() object
stash.save(user)

This will create a yuval.yml file in the stash root directory.

If the key field is not present on the dataclass, an explicit key must be passed:

stash.save(obj, key="custom-key")

Load from file:

user = stash.load("yuval")

List all keys existing in stash:

keys = stash.list_keys()

Delete a key:

stash.delete("foo")

Check for key existence:

stash.exists("foo")

Drop all files (careful, this deletes everything):

stash.drop()

License

MIT

yuvadm / ymlstash