Metadata-Version: 2.1
Name: LiteJsonDb
Version: 3.0.1
Summary: A lightweight JSON-based database system inspired by Firestore (Firebase). It's designed for simplicity and ease of use.
Home-page: https://github.com/codingtuto/json2db-lite/
Author: Coding Team
Author-email: codingteamgroup@gmail.com
License: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Framework :: Setuptools Plugin
Classifier: Environment :: Console
Requires-Python: >=3.7
Description-Content-Type: text/markdown

# LiteJsonDb: Your Go-To Lightweight JSON Database
![illustration](https://telegra.ph/file/374450a4f36c217b3a20b.jpg)
![PyPi downloads](https://img.shields.io/pypi/dm/LiteJsonDb.svg) 
![Supported Python versions](https://img.shields.io/pypi/pyversions/LiteJsonDb.svg)
![PyPi Package Version](https://img.shields.io/pypi/v/LiteJsonDb.svg)

## :eyes: Overview

Hey there! Welcome to **LiteJsonDb**, your friendly, lightweight JSON-based database. Inspired by the simplicity and real-time capabilities of Firestore, LiteJsonDb makes managing your data a breeze. It's packed with features like encryption, backups, and solid error handling—all without the heavy lifting.

## :thinking: Why LiteJsonDb?

Let's face it: sometimes you don't need a complex database setup. Maybe you're building a small project, a quick prototype, or you just want a straightforward way to store and retrieve JSON data. LiteJsonDb is here for those moments. It's simple, efficient, and gets the job done without any fuss.

## :hammer_and_wrench: Features

- **Easy Data Management**: Add, edit, retrieve, and delete data with just a few lines of code.
- **Data Encryption**: Keep your data secure with optional encryption. 
- **Backup and Restore**: Automatic backups to keep your data safe.
- **Subcollections**: Organize your data in neat, nested structures.
- **Friendly Error Handling**: Helpful, colorful error messages to guide you.

> LiteJsonDb makes managing JSON data simple and enjoyable. Whether you're building a small app or just need a lightweight data storage solution, LiteJsonDb has you covered. Enjoy! 

## :man_technologist: Installation

Getting started is super easy. Just install the package via pip and you're good to go:

<pre>
pip install LiteJsonDb
</pre>

## :crystal_ball: Usage

### :white_check_mark: Initial Setup

First things first, import the `JsonDB` class and initialize your database:

<pre>
import LiteJsonDb

# Initialize the database with encryption enabled
db = LiteJsonDb.JsonDB(crypted=True)
</pre>

### :hugging_face: Basic Operations

#### :heavy_plus_sign: Setting Data

Adding data is a breeze. Just use the `set_data` method. If the key already exists, you'll get a friendly reminder to use `edit_data` instead.

<pre>
# Set data
db.set_data("users/1", {"name": "Aliou", "age": 20})
db.set_data("users/2", {"name": "Coder", "age": 25})
</pre>

#### :writing_hand: Editing Data

Need to update data? No problem. Use the `edit_data` method. It merges the new data with the existing data, so nothing gets lost.

<pre>
# Edit data
db.edit_data("users/1", {"name": "Alex"})
</pre>

#### :ballot_box_with_check: Getting Data

Retrieving data is as simple as it gets. Use the `get_data` method.

<pre>
# Get data
print(db.get_data("users/1"))  # Output: {'name': 'Alex', 'age': 20}
print(db.get_data("users/2"))  # Output: {'name': 'Coder', 'age': 25}
</pre>

#### :wastebasket: Removing Data

Need to delete something? The `remove_data` method has you covered.

<pre>
# Remove data
db.remove_data("users/2")
</pre>

#### :package: Full Database Retrieval

Want to see everything? Use the `get_db` method. Set `raw=True` if you want the data in a readable format.

<pre>
# Get the full database
print(db.get_db(raw=True))
</pre>

### :file_folder: Working with Subcollections

## :file_folder: Subcollections

In LiteJsonDb, subcollections are a way to organize your data hierarchically. Think of them as nested structures that allow you to group related data together under a parent key. This feature is especially useful when you want to manage complex data relationships without losing the simplicity of JSON.

### :thinking: What Are Subcollections?

Subcollections are essentially collections within collections. For example, if you have a main collection of users, you might want to organize their posts into separate subcollections. Here’s how you can work with them:

- **Setting Subcollection Data**: Create and populate a subcollection under a specified parent key.
- **Editing Subcollection Data**: Update existing items in a subcollection.
- **Getting Subcollection Data**: Retrieve the data stored within a subcollection.
- **Removing Subcollection Data**: Delete items or entire subcollections.

Using subcollections helps you maintain a clear structure in your data, making it easier to manage and query.

#### :heavy_plus_sign: Setting Subcollection Data

Organize your data with subcollections. Easy peasy.

<pre>
# Set subcollection data
db.set_subcollection("groups", "1", {"name": "Admins"})
</pre>

#### :writing_hand: Editing Subcollection Data

Editing items within a subcollection? No sweat.

<pre>
# Edit subcollection data
db.edit_subcollection("groups", "1", {"description": "Admin group"})
</pre>

#### :ballot_box_with_check: Getting Subcollection Data

Need to retrieve specific subcollections or items? We've got you.

<pre>
# Get subcollection data
print(db.get_subcollection("groups"))

# Get custom item from the subcollection data
print(db.get_subcollection("groups", "1"))
</pre>

#### :wastebasket: Removing Subcollection Data

Removing items from subcollections is just as simple.

<pre>
# Remove subcollection data
db.remove_subcollection("groups", "1")
</pre>

## :bug: Error Handling

LiteJsonDb is all about being helpful. Here are some friendly, colorful error messages to guide you:

- **Key Exists**: If you try to set data with an existing key, it will suggest using `edit_data`.
- **Key Not Found**: If a key does not exist when you try to get or remove data, it will notify you with a tip on how to proceed.
- **File Issues**: If there are file permission problems, it will guide you on how to fix them.

## :open_file_folder: Example Project Structure

Here's how your project might look:

<pre>
project/
│
├── database/
│   ├── db.json
│   ├── db_backup.json
│   └── LiteJsonDb.log
└── your_code.py
</pre>

## Example `main.py`

Let's put it all together with an example `main.py` file:

<pre>
import LiteJsonDb

# Initialize the database with encryption enabled
db = LiteJsonDb.JsonDB(crypted=True)

# Add some initial data
db.set_data("users/1", {"name": "Aliou", "age": 20})
db.set_data("users/2", {"name": "Coder", "age": 25})

# Modify existing data
db.edit_data("users/1", {"name": "Alex"})

# Retrieve and print data
print(db.get_data("users/1"))
print(db.get_data("users/2"))

# Remove data
db.remove_data("users/2")

# Retrieve the full database
print(db.get_db(raw=True))

# Work with subcollections
db.set_subcollection("groups", "1", {"name": "Admins"})
db.edit_subcollection("groups", "1", {"description": "Admin group"})
print(db.get_subcollection("groups"))
db.remove_subcollection("groups", "1")
</pre>

## :hugs: Contributions and Community
We welcome contributions, suggestions, and feedback to make LiteJsonDb even better! If you have ideas for improvements or want to fix a bug, feel free to:

- **Submit a Pull Request (PR)**: Contribute new features or bug fixes by creating a pull request. Your changes will help improve LiteJsonDb for everyone!
- **Report Issues**: If you encounter any bugs or issues, please open an issue in the repository. Provide as much detail as possible so we can address it swiftly.
- **Suggest Features**: Have an idea for a new feature? Let us know! We’re always open to suggestions on how to enhance LiteJsonDb.

> Your feedback and contributions are greatly appreciated and help us keep LiteJsonDb growing and improving.

## :heart: Donations and Support: How You Can Help

Json2DB-Lite is a labor of love, and your support can make a big difference! If you’re enjoying the project and want to show your appreciation, here are a few ways you can help:

### Fork and Star the Repo

One of the best ways to support Json2DB-Lite is to fork the repository and give it a star on GitHub. It’s like a virtual high-five and helps us spread the word about the project. Plus, it shows us that you value the work we’re doing!

### Consider a Donation

If you’re feeling extra generous and want to contribute financially, we’d be incredibly grateful. Donations help us cover costs and keep the project running smoothly. You can support us in the following ways:

- **PayPal**: Send a donation directly to [my PayPal account](https://paypal.me/djibson35). Every little bit helps and is greatly appreciated!
- **Bitcoin**: Prefer cryptocurrency? You can also donate using Bitcoin to the following address: `1Nn15EttfT2dVBisj8bXCnBiXjcqk1ehWR`.

> Your support, whether through a star, a fork, or a donation, helps keep Json2DB-Lite alive and thriving. Thank you for being awesome!

Cheers and happy coding! :rocket:
