{"id":15111314,"url":"https://github.com/kawai-senpai/potatodb","last_synced_at":"2025-10-23T04:31:18.780Z","repository":{"id":256372054,"uuid":"855094142","full_name":"Kawai-Senpai/PotatoDB","owner":"Kawai-Senpai","description":"PotatoDB is a lightweight, file-based NoSQL database for Python projects, designed for easy setup and use in small-scale applications. Ideal for developers seeking simple data persistence without the complexity of traditional databases.","archived":false,"fork":false,"pushed_at":"2024-09-10T10:21:46.000Z","size":110,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-06T15:47:17.883Z","etag":null,"topics":["data","database","easy-to-use","file-based","json","key-value","lightweight","nosql","nosql-database","persistence","python","simple"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/potatodb/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Kawai-Senpai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-09-10T09:46:56.000Z","updated_at":"2025-03-20T14:54:17.000Z","dependencies_parsed_at":"2024-09-10T11:26:36.135Z","dependency_job_id":"ad75f31b-79aa-4a70-b1c7-2f10427c95b2","html_url":"https://github.com/Kawai-Senpai/PotatoDB","commit_stats":null,"previous_names":["kawai-senpai/potatodb"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/Kawai-Senpai/PotatoDB","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kawai-Senpai%2FPotatoDB","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kawai-Senpai%2FPotatoDB/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kawai-Senpai%2FPotatoDB/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kawai-Senpai%2FPotatoDB/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Kawai-Senpai","download_url":"https://codeload.github.com/Kawai-Senpai/PotatoDB/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kawai-Senpai%2FPotatoDB/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280562665,"owners_count":26351727,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-23T02:00:06.710Z","response_time":142,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["data","database","easy-to-use","file-based","json","key-value","lightweight","nosql","nosql-database","persistence","python","simple"],"created_at":"2024-09-26T00:03:26.549Z","updated_at":"2025-10-23T04:31:18.474Z","avatar_url":"https://github.com/Kawai-Senpai.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PotatoDB: Lightweight JSON-based Database for Python\n\n![PotatoDB Cover](https://github.com/Kawai-Senpai/PotatoDB/blob/81f8b44b0718fcd396a296933eb72bc1e35e3053/Assets/PotatoDB%20Thumbnail.png)\n\n**PotatoDB** is a lightweight, JSON-based database solution designed for simplicity and ease of use. It allows you to create, insert, query, update, and delete records in a NoSQL fashion, using Python's built-in JSON module to store data persistently on disk developed by [*Ranit Bhowmick*](https://www.linkedin.com/in/ranitbhowmick/) \u0026 [*Sayanti Chatterjee*](https://www.linkedin.com/in/sayantichatterjee/). Whether you need a quick and easy database for small projects, prototypes, or educational purposes, PotatoDB offers a flexible solution without the overhead of traditional databases.\n\n## Features\n\n- **Simple Setup:** No need for external dependencies or database servers. PotatoDB works out of the box with Python's standard library.\n- **JSON-based Storage:** Data is stored in human-readable JSON files, making it easy to inspect and manipulate outside of the application.\n- **In-Memory Operations:** Perform operations like querying, updating, and deleting records in memory for fast performance.\n- **Automatic Persistence:** Data is automatically saved to disk after each operation, ensuring data integrity.\n- **Table-based Structure:** Create multiple tables within a single database instance.\n- **Dynamic Schema:** No predefined schema; records can have varying fields, offering flexibility for evolving data models.\n\n## Table of Contents\n\n1. [Installation](#installation)\n2. [Basic Usage](#basic-usage)\n    - [Creating a Database Instance](#creating-a-database-instance)\n    - [Creating a Table](#creating-a-table)\n    - [Inserting Records](#inserting-records)\n    - [Querying Records](#querying-records)\n    - [Updating Records](#updating-records)\n    - [Deleting Records](#deleting-records)\n3. [Detailed Documentation](#detailed-documentation)\n    - [Class: `PotatoDB`](#class-PotatoDB)\n    - [Methods](#methods)\n        - [`__init__`](#init)\n        - [`create_table`](#create_table)\n        - [`insert`](#insert)\n        - [`query`](#query)\n        - [`update`](#update)\n        - [`delete`](#delete)\n        - [`set_folder`](#set_folder)\n        - [`save`](#save)\n        - [`load`](#load)\n4. [Examples](#examples)\n5. [Advanced Usage](#advanced-usage)\n6. [Limitations](#limitations)\n7. [Future Enhancements](#future-enhancements)\n8. [Contributing](#contributing)\n\n## Installation\n\nPotatoDB is implemented in pure Python and does not require any external dependencies. To start using PotatoDB, simply download the source code and include it in your project or install it via pip.\n\n```bash\npip install potatodb\n```\n\nAlternatively, you can copy the `potatodb.py` file directly into your project directory.\n\n## Basic Usage\n\n### Creating a Database Instance\n\nTo create a new instance of PotatoDB, import the `PotatoDB` class and specify the folder where the data should be stored. If the folder does not exist, it will be created automatically.\n\n```python\nfrom potatodb.db import PotatoDB\n\n# Create a new PotatoDB instance\ndb = PotatoDB(\"example_data\")\n```\n\n### Creating a Table\n\nTo create a new table within the database, use the `create_table` method.\n\n```python\ndb.create_table(\"users\")\n```\n\n### Inserting Records\n\nRecords can be inserted into a table using the `insert` method. The record should be a Python dictionary.\n\n```python\ndb.insert(\"users\", {\"name\": \"Alice\", \"age\": 30})\ndb.insert(\"users\", {\"name\": \"Bob\", \"age\": 25}) \n# The database will automatically save the data to disk after each operation\n```\n\n### Querying Records\n\nTo query records, use the `query` method with a custom query function. The query function should return `True` for records that match the condition and `False` for those that don't.\n\n```python\n# Query all users\nall_users = db.query(\"users\", lambda record: True)\nprint(\"All users:\", all_users)\n\n# Query users older than 30\nusers_above_30 = db.query(\"users\", lambda record: record[\"age\"] \u003e 30)\nprint(\"Users above 30:\", users_above_30)\n```\n\n### Updating Records\n\nTo update records, use the `update` method with a condition function and an update function.\n\n```python\n# Update the age of all users named \"Alice\" to 35\ndb.update(\"users\", lambda record: record[\"name\"] == \"Alice\", lambda record: record.update({\"age\": 35}))\n```\n\n### Deleting Records\n\nTo delete records, use the `delete` method with a condition function.\n\n```python\n# Delete all users named \"Bob\"\ndb.delete(\"users\", lambda record: record[\"name\"] == \"Bob\")\n```\n\n## Detailed Documentation\n\n### Class: `PotatoDB`\n\nThe `PotatoDB` class is the core of the PotatoDB library. It provides methods for creating tables, inserting data, querying, updating, and deleting records, as well as saving and loading data to and from JSON files.\n\n#### `__init__`\n\n```python\ndef __init__(self, folder=\"PotatoDB\"):\n```\n\n- **Description:** Initializes the database instance, setting the folder for storage and loading existing data from JSON files.\n- **Parameters:**\n  - `folder` (str): The folder where the database files will be stored. Defaults to `\"PotatoDB\"`.\n\n#### `create_table`\n\n```python\ndef create_table(self, table_name):\n```\n\n- **Description:** Creates a new table within the database.\n- **Parameters:**\n  - `table_name` (str): The name of the table to be created.\n\n#### `insert`\n\n```python\ndef insert(self, table_name, data):\n```\n\n- **Description:** Inserts a new record into the specified table.\n- **Parameters:**\n  - `table_name` (str): The name of the table where the record will be inserted.\n  - `data` (dict): The record to be inserted, represented as a dictionary.\n- **Returns:** The inserted record.\n\n#### `query`\n\n```python\ndef query(self, table_name, query_func):\n```\n\n- **Description:** Queries data from the specified table using a query function.\n- **Parameters:**\n  - `table_name` (str): The name of the table to query.\n  - `query_func` (function): A function that takes a record as input and returns `True` if the record matches the query, `False` otherwise.\n- **Returns:** A list of records that match the query.\n\n#### `update`\n\n```python\ndef update(self, table_name, condition_func, update_func):\n```\n\n- **Description:** Updates records in the specified table based on a condition.\n- **Parameters:**\n  - `table_name` (str): The name of the table to update.\n  - `condition_func` (function): A function that takes a record as input and returns `True` if the record should be updated.\n  - `update_func` (function): A function that takes a record as input and performs the update.\n- **Returns:** `True` if the update was successful, `False` otherwise.\n\n#### `delete`\n\n```python\ndef delete(self, table_name, condition_func):\n```\n\n- **Description:** Deletes records from the specified table based on a condition.\n- **Parameters:**\n  - `table_name` (str): The name of the table from which records should be deleted.\n  - `condition_func` (function): A function that takes a record as input and returns `True` if the record should be deleted.\n- **Returns:** `True` if the deletion was successful, `False` otherwise.\n\n#### `set_folder`\n\n```python\ndef set_folder(self, folder_name):\n```\n\n- **Description:** Sets the folder where the tables will be saved and loaded.\n- **Parameters:**\n  - `folder_name` (str): The name of the folder.\n\n#### `save`\n\n```python\ndef save(self, table_name=None):\n```\n\n- **Description:** Saves the specified table to a JSON file in the set folder. (This method is called automatically after each operation.)\n- **Parameters:**\n  - `table_name` (str): The name of the table to save. If `None`, all tables are saved.\n\n#### `load`\n\n```python\ndef load(self, table_name=None):\n```\n\n- **Description:** Loads a table from a JSON file in the set folder. (This method is called automatically when the database is initialized.)\n- **Parameters:**\n  - `table_name` (str): The name of the table to load. If `None`, all tables are loaded.\n\n## Examples\n\nHere's a complete example of how to use PotatoDB:\n\n```python\nfrom potatodb.db import PotatoDB\n\n# Create a new LazyDB instance\ndb = PotatoDB(\"example_data\")\n\n# Create a new table called \"users\"\ndb.create_table(\"users\")\n\n# Insert a new record into the \"users\" table\ndb.insert(\"users\", {\"name\": \"Alice\", \"age\": 30})\ndb.insert(\"users\", {\"name\": \"Bob\", \"age\": 25})\n\n# Query all records from the \"users\" table\nall_users = db.query(\"users\", lambda record: True)\nprint(\"All users:\" , all_users)\n\n# Update the age of all users named \"Alice\" to 35\ndb.update(\"users\", lambda record: record[\"name\"] == \"Alice\", lambda record: record.update({\"age\": 35}))\n\n# Query all records above the age of 30 from the \"users\" table\nusers_above_30 = db.query(\"users\", lambda record: record[\"age\"] \u003e 30)\n\n# Print the updated records\nprint(\"Users above 30:\", users_above_30)\n\n# Delete all users named \"Bob\" from the \"users\" table\ndb.delete(\"users\", lambda record: record[\"name\"] == \"Bob\")\n\n# Query all records from the \"users\" table after deletion\nremaining_users = db.query(\"users\", lambda record: True)\n\n# Print the remaining records\nprint(\"Remaining users:\", remaining_users)\n```\n\n## Advanced Usage\n\n### Custom Data Persistence\n\nWhile PotatoDB automatically saves and loads data from JSON files, you can also manually save or load data using custom file paths or formats. This allows you to integrate PotatoDB with other data management systems or customize the storage format.\n\n## Limitations\n\n- **Performance:** PotatoDB is designed for lightweight tasks and may not perform well with large datasets or complex queries.\n- **Concurrency:** PotatoDB is not thread-safe and should be used with caution in multi-threaded environments.\n- **Data Integrity:** Since PotatoDB writes data to JSON files, there is a risk of data corruption if the program crashes during a write operation.\n\n## Future Enhancements\n\n- **Indexing:** Implementing indexing for faster query performance.\n- **Transactions:** Adding support for transactions to ensure data integrity during complex operations.\n- **Data Export/Import:** Adding features to export and import data in different formats, such as CSV or XML.\n\n## Contributing\n\nContributions are welcome! If you find a bug or want to suggest a feature, feel free to open an issue or submit a pull request on GitHub.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkawai-senpai%2Fpotatodb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkawai-senpai%2Fpotatodb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkawai-senpai%2Fpotatodb/lists"}