{"id":16431702,"url":"https://github.com/reala10n/simplejsondb","last_synced_at":"2025-10-27T01:30:25.288Z","repository":{"id":54759233,"uuid":"333777259","full_name":"RealA10N/simplejsondb","owner":"RealA10N","description":"Create a simple JSON database with just one line of code!","archived":false,"fork":false,"pushed_at":"2023-09-10T23:15:16.000Z","size":170,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-08T01:30:40.860Z","etag":null,"topics":["data","database","db","easy","json","python","simple"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RealA10N.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-01-28T14:06:34.000Z","updated_at":"2023-11-25T17:45:41.000Z","dependencies_parsed_at":"2022-08-14T02:00:35.256Z","dependency_job_id":null,"html_url":"https://github.com/RealA10N/simplejsondb","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RealA10N%2Fsimplejsondb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RealA10N%2Fsimplejsondb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RealA10N%2Fsimplejsondb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RealA10N%2Fsimplejsondb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RealA10N","download_url":"https://codeload.github.com/RealA10N/simplejsondb/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238418208,"owners_count":19468865,"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","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","db","easy","json","python","simple"],"created_at":"2024-10-11T08:32:08.932Z","updated_at":"2025-10-27T01:30:24.935Z","avatar_url":"https://github.com/RealA10N.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Simple Json Database](/assets/banner.png)\n\nDo you need a simple, small, and very easy to use local database? You have come\nto the right place! with _simplejsondb_ you can create a simple JSON database with\nonly one line of code, and we will take care of the rest!\n\n- [A basic example](#a-basic-example)\n- [Installation](#installation)\n- [The `Database` object](#the-database-object)\n  - [`Database` constructor](#database-constructor)\n  - [Database.data](#databasedata)\n  - [Database.save(**additional)](#databasesaveadditional)\n  - [Database.load()](#databaseload)\n  - [Database.path](#databasepath)\n  - [Database.folder](#databasefolder)\n- [The `DatabaseFolder` object](#the-databasefolder-object)\n  - [`DatabaseFolder` constructor](#databasefolder-constructor)\n  - [Examples](#examples)\n\n## A basic example\n\n```python\nfrom simplejsondb import Database\n\n# If database named 'translations' doesn't exist yet, creates a new empty dict database\ntranslations = Database('translations.json', default=dict())\n\n# Now, we can treat the database instance as a dictionary!\ntranslations.data['Hello'] = 'Hola'\ntranslations.data['Goodbye'] = 'Adiós'\nprint(translations.data.values())   # dict_values(['Hola', 'Adiós'])\n\n# The database will automatically save the changes when the program exits\n```\n\nAfter running the code above for the first time, a file named `translations.json`\nwill be automatically created under the current working directory. Then, we will\nbe able to use the database inside other scripts, and treat it as a dictionary:\n\n```python\nfrom simplejsondb import Database\n\n# loads the previously saved translations database\ntranslations = Database('translations.json')\n\n# Again, we treat the 'translations' instance as a dictionary\nprint(f\"Hello in Spanish is {translations.data['Hello']}!\")\n# This will output: Hello in Spanish is Hola!\n\n# We can also use the built in dictionary methods\nfor english, spanish in translations.data.items():\n    print(f\"{english} in Spanish is {spanish}!\")\n\n# This will output:\n# Hello in Spanish is Hola!\n# Goodbye in Spanish is Adiós!\n```\n\n## Installation\n\nThe simplest way to install _simplejsondb_ is by using `pip`. Just run the following\ncommand in your terminal:\n\n```console\n$ (sudo) pip install simplejsondb\n```\n\nYou can also clone the [Github repo](https://github.com/RealA10N/simplejsondb),\ndownload the latest release from [Github](https://github.com/RealA10N/simplejsondb/releases)\nor directly from [PyPI](https://pypi.org/project/simplejsondb/#files). Then, unzip\nthe files (if they are zipped), and use the following command to install the package:\n\n```console\n$ (sudo) python setup.py install\n```\n\nIf the command above didn't work, make sure that you have the `setuptools` package\ninstalled using:\n\n```console\n$ (sudo) pip install setuptools\n```\n\n## The `Database` object\n\nEach instance of the `Database` object is represented by a single json file in\nthe local storage.\n\n### `Database` constructor\n\nThe constructor of the `Database` instance. Receives a path to a `JSON` file, and\ntries to load it. If the file doesn't exist, loads the default data that is passed\nusing the `default` argument.\n\n### Arguments \u003c!-- omit in toc --\u003e\n\n- **path (str):** The path to the json database file.\n- **default:** The default data that will be loaded if the file doesn't exist yet.\n    `None` by default.\n- **save_at_exit (bool):** If `True` (default), will automatically dump the database\n    into storage when the program exits.\n\n\n### Database.data\n\nA property that stores the data in the database. Writing and reading data should\nbe done directly using this property.\n\n\n### Database.save(**additional)\n\nBy default, the database is loaded from the local storage when the instance is\ncreated. It is then saved in the memory, until the program exits - and only then\nthe new and updated data is saved back in the local storage. By using the\n`Database.save()` method, you can save the database into the local storage before\nthe program exists, in any given point.\n\n#### Additional arguments \u003c!-- omit in toc --\u003e\n\nThe `save` method supports receiving additional keyword arguments that are directly\npassed into the `json.dump` function. One useful argument can be `indent` that is\na non-negative integer that sets the indention level of the dumped json file. For\nmore information, check out the [json module documentation].\n\n### Database.load()\n\nLoads the data from the `json` file into the instance. Overwrites previous data that was\nsaved under the `.data` property.\n\n### Database.path\n\nA property that contains the path to the database JSON file.\n\n### Database.folder\n\nA property that stores the absolute path to the directory where the database json\nfile lives in.\n\n## The `DatabaseFolder` object\n\nIn larger projects, you may want to separate your database into multiple `json`\nfiles under the same directory. for that, it is possible to use the `DatabaseFolder`\nobject, that lets you easily manage multiple `json` files, without dealing with\ndifferent instances of the `Database` object.\n\n### `DatabaseFolder` constructor\n\nThe constructor receives a path to a directory, and stores the it for later.\n\n#### Arguments \u003c!-- omit in toc --\u003e\n\n- **folder (str):** A path to a folder in the storage in which the database folder\n    will live.\n- **default_factory (callable):** A function that receives a string that represents\n    the name of a database file, and returns the default value for the file.\n    The default value is the following lambda function `lambda _: None` which will\n    return `None` no matter what the name of the file is.\n- **save_at_exit (bool):** If `True` (default), will automatically dump the database\n    into storage when the program exits.\n\n### Examples\n\n```python\nfrom simplejsondb import DatabaseFolder\n\n\n# Create a database under the 'db' folder\n# The default value in the files will be a list\ndb = DatabaseFolder('db', default_factory=lambda _: list())\n\n# Append 'hello' in the 'db/file1.json'\ndb['file1'].append('hello')\n\n# 'db/file2.json' will store a dictionary\ndb['file2'] = dict()\ndb['file2']['hello'] = 'there!'\n\nprint(db['file2'])      # {'hello': 'there!'}\n```\n\n\n[json module documentation]: https://docs.python.org/3/library/json.html#json.dump\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freala10n%2Fsimplejsondb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Freala10n%2Fsimplejsondb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freala10n%2Fsimplejsondb/lists"}