Metadata-Version: 2.1
Name: stupiddb2
Version: 1.0.2
Summary: an incredibly stupid, for fun, json "db"
Home-page: https://github.com/JaffarA/stupiddb
License: GPLv3
Author: Jaffar Almaleki
Author-email: jaffar.almaleki@gmail.com
Requires-Python: >=3.11,<4.0
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Project-URL: Repository, https://github.com/JaffarA/stupiddb
Description-Content-Type: text/markdown

>This project is designed for recreational purposes, and I would advise against using it for critical database requirements unless it's intended for similar small-scale and experimental projects.

### StupidDB

### Why?

I often found myself re-implementing the same dumb db/lock for micro projects, so I decided to make it into a library I can just include as a dependency.

This is the dumbest PoC (not proof-of-concept) db I use for toy development. Not really actually a database, more of a python wrapper for a json file. Really great for things like doing a work secret santa api (all within a single file) 🎅 and... not much else.

Includes two amazingly stupid classes and some not well thought out functions for them:

- `stupiddb2.StupidDB`

    - `insert`
    ```python
    stupiddb2.StupidDB().insert(
        {"name": "alice", "age": "21"}
    )
    ```
    - `retrieve`
    ```python
    result = stupiddb2.StupidDB().retrieve(
        0  # index of the record to retrieve
    )
    print(result)  # {"name": "alice", "age": "21"}
    ```
    - `update`
    ```python
    stupiddb2.StupidDB().update(
        0,  # index of the record to update
        {"name": "alice", "age": "22"}
    )
    ```
    - `remove`
    ```python
    stupiddb2.StupidDB().remove(
        0  # index of the record to remove
    )
    ```

> Bonus 🃏: this is a really dumb lock that uses a json file to store the lock state. It's not a real lock, but it's good enough for my purposes.

- `stupiddb2.StupidLock`

    - `is_locked`
    ```python
    stupiddb2.StupidLock().is_locked()  # False
    ```
    - `acquire_lock`
    ```python
    stupiddb2.StupidLock().acquire_lock()
    stupiddb2.StupidLock().is_locked()  # True
    ```
    - `release_lock`
    ```python
    stupiddb2.StupidLock().release_lock()
    stupiddb2.StupidLock().is_locked()  # False
    ```

### Installing
```bash
pip install stupiddb2  # pip
poetry add stupiddb2  # poetry
```

### Example Usage
```python
from stupiddb2 import StupidDB, StupidLock

db_path = "example_db.json"
lock_path = "example_lock.json"


def register_user(user: dict[str, str]) -> bool:
    # initialize db
    stupid_db = StupidDB(db_path)

    # initialize lock
    lock = StupidLock(lock_path)

    try:
        # acquire lock
        lock.acquire_lock()

        # insert user into db
        stupid_db.insert(user)

        # release lock
        lock.release_lock()
    except Exception as e:
        # handle exception
        # ...something went wrong, the user was not registered
        return False

    return True

alice = {"name": "alice", "age": "21"}
alice_is_registered = register_user(alice)
print(alice_is_registered)  # True
```

# Development

### Command Reference
```bash
just format  # runs black + isort
just lint  # runs mypy + ruff
just test  # runs tests
just coverage  # prints coverage report (run after tests)
```


## Setup

### Install [Just](https://github.com/casey/just)
```bash
brew install just  # if you want to use brew (recommended + easier)
```

### Install [Pyenv](https://github.com/pyenv/pyenv) - (optional but recommended)
```bash
pyenv install 3.11.7
pyenv local 3.11.7
```

### Install [Poetry](https://python-poetry.org/docs/)

## Running the project
```bash
# after installing poetry run the following to install dev dependencies
poetry install --with dev --no-root
# if you're using vscode and want the venv path to python for IDE features
poetry run which python  # copy the output of this command and paste it into your .vscode/settings.json {"python.defaultInterpreterPath": PATH}
just test  # runs tests
```

## FAQ

> Q: Why is this called stupiddb2 and not stupiddb?

`stupiddb` was taken on pypi 😭

If any questions are ever asked, they will be answered here. 🙋

## License

[GPL-3](https://choosealicense.com/licenses/gpl-3.0/)

