Easy to use 👋 fast & lightweight ☄️ secure 🔐 JSON based database for python! 🐍.
Project description
Datagoose
Datagoose is an easy to use JSON based database for python.
With Datagoose:
- Best performance. Datagoose is a lightweight database.
- Methods that makes your job easier.
- Regex supports.
- You must enable
USE_REGEX
option.
- You must enable
- Safe to use.
- Auto or manual save, for who wants better performance.
- Easy to use database. Created for everyone.
- Rich options. includes hash keys, database path, regexp and more.
- Auto backup
- Can be dumped, also can load a data from JSON file.
<Datagoose>.load()
<Datagoose>.dump()
Update (1.6.0)
- Added
PIN
option for encryption.- If you used
1.5.0
encryption, use PIN2
or dump your database and make a new one.
- If you used
- Added
.replace
,.replace_one
methods. - Added 3 new event.
- Added
ENCRYPTED
option for auto-backup. - Removed
.save_with_indent
method.
Download
You can download with pip install -U datagoose
(PyPi Page) or, you can use with source code.
Note: Current stable version is 1.6.1
. You can download stable version with pip install datagoose==1.6.1
(PyPi).
Quick Documentation
Before Start
You should know these things before using datagoose;
-
Datagoose keeps data in memory, not in a file.
- You can save with
<Datagoose>.save()
for remember the database next time. - Also now you can enable
AUTO_SAVE
option for auto-saving.
- You can save with
-
Datagoose is not a professional database.
Performance
Test Result (Auto-Save Enabled):
- 100 Data with insert many:
-
Starting Insert... Inserting Finished in 0:00:00.007002
-
- 1,000 Data with insert many:
-
Starting Insert... Inserting Finished in 0:00:00.032004
-
- 10,000 Data with insert many:
-
Starting Insert... Inserting Finished in 0:00:00.278020
-
- 100,000 Data with insert many:
-
Starting Insert... Inserting Finished in 0:00:02.808687
-
- 1,000,000 Data with insert many:
-
Starting Insert... Inserting Finished in 0:00:31.908481
-
Methods
Quick Start
[] - Optinal
[argument_name:argument_type:argument_default_value] - Optinal Argument Name | Optional Argument Type | Optional Argument Default Value
{} - Normal
{argument_name:argument_type} - Argument Name | Argument Type
* - Args
from datagoose import Datagoose
database = Datagoose("example")
Options
# Options must be a dict. lets get informations about current options.
# PATH:
# Type: String
# Description: Custom path for JSON file.
# Note: please add path like: "databases/datagoose" not "./databases/datagoose/"
# Default: datagoose_files
# AUTO_SAVE:
# Type: Bool
# Description: When enabled, auto-saves the database when an action performed.
# Default: False
# HASHING:
# Type: List
# Description: Key list for replace data with sha256 hash when inserted.
# Default: []
# SAFE_MODE:
# Type: Bool
# Description: Enable/Disable safe mode. do not recommending to disable this option. if you know what are you doing, then good luck.
# Default: True
# USE_REGEX:
# Type: Bool
# Description: Enable/Disable regex option.
# Default: False
# ENCRYPTED:
# Type: Bool
# Description: Enable/Disable encrypting data.
# Default: False
# PIN:
# Type: Int
# Description: Decryption key for encryption. you should not expose this key.
# Default: 2
# Example:
database = Datagoose("example", {
"AUTO_SAVE": True,
"USE_REGEX": True,
"ENCRYPTED": True,
"PIN": 69 * 420,
"HASHING": [
"PASSWORD"
]
})
# <Datagoose>.read() -> Returns the entire data
# Return Type: List
# Example(s):
full_database = database.read()
# <Datagoose>.info -> Returns database info
# Return Type: Dict
# Example(s):
print(database.info)
# <Datagoose>.length -> Returns total data count
# Return Type: Integer
# Example(s):
print(database.length)
# <Datagoose>.uptime -> Returns database uptime
# Return Type: datetime.timedelta
# Example(s):
print(database.uptime)
# <Datagoose>.save() -> Saves the database
# Return Type: Bool
# Example(s):
database.save()
# <Datagoose>.clear() -> Clears the entire database
# Return Type: Bool
# Example(s):
database.clear()
Inserting Data
# <Datagoose>.insert_one({data:dict}) -> Insert one data to database
# Return Type: Dict
# Argument: data
# Description: The data will be inserted into database.
# Example(s):
database.insert_one({
"name": "John",
"lastname": "Doe",
"age": 25,
"city": "New York",
"country": "USA",
"job": "Doctor"
})
# <Datagoose>.insert_many(*{data:dict}) -> Insert many data to database
# Return Type: Bool
# Args:
# Description: The data(s) will be inserted into database.
# Example(s):
database.insert_many({
"user": 1,
"nickname": "normal_guy_100"
}, {
"user": 2,
"nickname": "user_555"
})
Note: Datagoose adds unique hash ("_id") to every document that inserted. Make sure do not add same "_id" to documents.
# Example
database.insert_one({ "_id": 1, "name": "an_user" })
database.insert_one({ "_id": 1, "name": "another_user" })
# This example will not give an error. But when you use delete or update, datagoose may confuse while find the object.
Finding Data
# <Datagoose>.find({data:dict}) -> Find data from database
# Return Type: Generator? (Dict Yield)
# Argument: data
# Description: The data will find from database.
# Example(s):
found = database.find({
"age": 25
}) # -> {'name': 'test', 'age': 25}, {'name': 'test2', 'age': 25} ...
for result in found:
print(result)
# <Datagoose>.query({check:function}) -> Query data from database with function. *New in 1.4.1*
# Return Type: Generator? (Dict Yield)
# Argument: check
# Description: Functions for check, must return bool.
# Example(s):
for i in database.query(lambda data: 'POINT' in data and data['POINT'] >= 1337):
print(i)
# <Datagoose>.find_one({data:dict}) -> Find one data from database
# Return Type: Dict
# Argument: data
# Description: The data will find from database.
# Example(s):
result = database.find_one({
"user_id": 295818619
})
print(result["nickname"])
Updating Data
# <Datagoose>.update({data:dict}, {new_data:dict}) -> Update data from database
# Return Type: List
# Argument: data
# Description: The data will find from database.
# Argument: new_data
# Description: The data will be changed with found data.
# Example(s):
database.update({
"age": 25
}, {
"age": 26
}) # Now every data has 'age' and 'age' key value is 25, changed with 'age' = 26
# <Datagoose>.update_one({data:dict}, {new_data:dict}) -> Update one data from database
# Return Type: Dict
# Argument: data
# Description: The data will find from database.
# Argument: new_data
# Description: The data will be changed with found data.
# Example(s):
database.update_one({
"user_id": 2486718956
}, {
"banned": True,
"ban_time": "30d"
}) # Now only one data updated.
Note: When you add new key and value to new_data dictionary, it will insert into data.
# Example
database.insert_one({ "_id": 1, "name": "an_user" })
database.update_one({
"_id": 1
}, {
"total_kill": 16
})
# Now our data is:
{
"_id": 1,
"name": "an_user",
"total_kill": 16
}
Replace Data
# <Datagoose>.replace({data:dict}, {new_data:dict}) -> Replace data from database
# Return Type: List
# Argument: data
# Description: The data will find from database.
# Argument: new_data
# Description: The data will be replaced with found data.
# Example(s):
database.replace({
"age": 25
}, {
"thing": True,
"age": 26
}) # Now every data has 'age' and 'age' key value is 25, changed with new data.
# <Datagoose>.replace_one({data:dict}, {new_data:dict}) -> Replace one data from database
# Return Type: Dict
# Argument: data
# Description: The data will find from database.
# Argument: new_data
# Description: The data will be replaced with found data.
# Example(s):
database.replace_one({
"user_id": 2486718956
}, {
"banned": True,
"ban_time": "30d",
"user_id": 2486718956
}) # Now only one data replaced.
Note: The difference between update and replace, replace changes the entire data with new one. update only updates the key that given.
Deleting Data
# <Datagoose>.delete({data:dict}) -> Delete data from database
# Return Type: List
# Argument: data
# Description: The data will be deleted from database.
# Example(s):
database.delete({
"total_hours": 1
}) # Now datagoose deleted all data contains key 'total_hours' and key value is 1
# <Datagoose>.delete_one({data:dict}) -> Delete one data from database
# Return Type: Dict
# Argument: data
# Description: The data will be deleted from database.
# Example(s):
database.delete_one({
"user_id": 6811
})
Count & Exists
# <Datagoose>.count({data:dict}) -> Count all data contains data argument
# Return Type: Integer
# Argument: data
# Description: The data will count.
# Example(s):
database.count({
"name": "John",
"age": 40
}) # -> 6157
# <Datagoose>.exists({data:dict}) -> Checks data exists
# Return Type: Bool
# Argument: data
# Description: The data will be checked.
# Example(s):
result = database.exists({
"name": "a_guy_11"
})
if result:
database.delete_one({ "name": "a_guy_11" })
Note: "has" is an alias for exists.
# Example
result = database.has({
"name": "a_guy_11"
})
if result:
database.delete_one({ "name": "a_guy_11" })
# is same with:
result = database.exists({
"name": "a_guy_11"
})
if result:
database.delete_one({ "name": "a_guy_11" })
Using Regex
# Quick example for using regex in datagoose.
# You must enable USE_REGEX option for using regex in datagoose.
for i in db.find({"ANSWER": r"yes|y"}):
print(i)
Load & Dump
# <Datagoose>.dump({location:str}, [encoding:str:utf-8]) -> Dumps the database to JSON file.
# Return Type: None
# Argument: location
# Description: The location that will dump.
# Argument: encoding
# Description: Encoding while write.
# Example(s):
database.dump("./dump.json")
# <Datagoose>.load({location:str}, [encoding:str:utf-8], [overwrite:bool:True]) -> Load database from JSON file.
# Return Type: Dict
# Argument: location
# Description: The location that will dump.
# Argument: encoding
# Description: Encoding while write.
# Argument: overwrite
# Description: If True, it will delete old data and paste loaded one. Else, it will extend data with loaded JSON.
# Example(s):
# 1.
database.load("./old_database.json", overwrite=False)
# 2.
database.load("./old_database.json")
Note: for .load(), the JSON will loaded must have 'database' key and value must be a list. Also in list, values must be dict.
Note: "export" is an aliases for .dump().
# Example
database.export("./dump.json", indent=4)
# is same with:
database.dump("./dump.json", indent=4)
Copying Data
# <Datagoose>.copy({data:dict}, [repeat:int:1]) -> Copy data to database
# Return Type: Bool
# Argument: data
# Description: The data will be copied to database.
# Argument: repeat
# Description: Repeat number for copy. Must be between 1 - 100000
# Example(s):
database.copy({
"total_hours": 1
}) # Now datagoose copied all data contains these informations.
# <Datagoose>.repeat_one({data:dict}) -> Copy one data to database
# Return Type: Dict
# Argument: data
# Description: The data will be copied to database.
# Example(s):
database.copy_one({
"user_id": 6811
})
Collecting Garbage Data
# <Datagoose>.collect_garbage() -> Returns all garbage data in database
# Return Type: Generator
# Example(s):
getgc = database.collect_garbage()
for garbage in getgc:
print("Found Garbage Data: ", garbage)
# <Datagoose>.clear_garbage() -> Clear all garbage data in database
# Return Type: Bool
# Example(s):
database.clear_garbage()
Sorting Database
# <Datagoose>.sort_for_key({key:str}, [reverse:bool:False]) -> Sort database for key.
# Return Type: List
# Argument: key
# Description: The key for sort.
# Argument: reverse
# Description: Reverse the result.
# Example(s):
point_list = database.sort_for_key("point", reverse=True)
winner = point_list[0]
print(f"Congrats, {winner['name']}. You won the game!")
# <Datagoose>.find_and_sort({data:dict}, {key:str}, [reverse:bool:False]) -> Find and sort database for key.
# Return Type: List
# Argument: data
# Description: The data for find.
# Argument: key
# Description: The key for sort.
# Argument: reverse
# Description: Reverse the result.
# Example(s):
finished = database.find_and_sort({"finished": True}, "time", reverse=True)
winner = finished[0]
print(f"Congrats, {winner['name']}. You won the game!")
Note: .sort_for_key() not changes the database, just returns sorted version of database.
Auto-Backup
# <Datagoose>.start_backup([options:dict:{}]) -> Starts backup for every x second. Raises error when already started.
# Return Type: None
# Argument: options
# Description: Options for auto-backup
# Example(s):
database.start_backup({
"TIME": 60, # Second for repeat time. Minimum 30 second, Maximum 31,557,600 (1 year) second.
"PATH": "database/backups", # Path for backup files.
"ENCRYPTED": True # Encryption for database.
})
# <Datagoose>.stop_backup() -> Stops backup loop. Will not effect if already stopped.
# Return Type: Bool
# Example(s):
database.stop_backup()
# <Datagoose>.is_backup_open -> Returns backup status.
# Return Type: Bool
# Example(s):
if not database.is_backup_open:
print("Backup Disabled.")
Using Events
# You can use an event with .on(event_name, function).
# Example:
database.on("before_insert", lambda v: print("Starting to insert data: {0}".format(v)))
# Or:
def before_insert_function(value):
# ...
print("Starting to insert value: {0}".format(value))
database.on("before_insert", before_insert_function)
Event List
All events and quick descriptions;
{
"before_insert": lambda value: None, # Runs before insert.
"should_insert": lambda value: True, # Check method for should value insert.
"after_insert": lambda value: None, # Runs after insert.
"before_update": lambda now, changes: None, # Runs before update.
"should_update": lambda now, changes: True, # Check method for should data update.
"after_update": lambda now, old: None, # Runs after update.
"before_replace": lambda now, new: None, # Runs before replace.
"should_replace": lambda now, new: True, # Check method for should data replace.
"after_replace": lambda now, old: None, # Runs after replace.
"before_delete": lambda value: None, # Runs before delete.
"should_delete": lambda value: True, # Check method for should data delete.
"after_delete": lambda value: None, # Runs after delete.
"before_copy": lambda value: None, # Runs before copy.
"should_copy": lambda value: True, # Check method for should data copy.
"after_copy": lambda value: None, # Runs after copy.
"before_save": lambda: None, # Runs before save.
"after_save": lambda: None, # Runs after save.
"before_export": lambda: None, # Runs before using .dump() (export)
"after_export": lambda: None, # Runs after using .dump() (export)
"before_import": lambda: None, # Runs before using .load() (import)
"after_import": lambda: None, # Runs after using .load() (import)
"backup_start": lambda: None, # Runs when auto-backup starts.
"backup": lambda: None, # Runs when backup data.
"backup_finish": lambda: None, # Runs when auto-backup finish
"before_garbage_clear": lambda: None, # Runs before garbage clear.
"after_garbage_clear": lambda: None # Runs after garbage clear.
}
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
File details
Details for the file datagoose-1.6.1.tar.gz
.
File metadata
- Download URL: datagoose-1.6.1.tar.gz
- Upload date:
- Size: 16.3 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.4.1 importlib_metadata/4.4.0 pkginfo/1.7.0 requests/2.25.1 requests-toolbelt/0.9.1 tqdm/4.61.0 CPython/3.9.5
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 74d4193ab6507d3aa0c59a420ef2d9dbad09b2b568939e6b6ae2514b72d98390 |
|
MD5 | 722cbb4a568f490475c3b3199e822ab8 |
|
BLAKE2b-256 | e0b5fb43890c9e7ba60ea46fa89d6218af6706bfa817b48f2f32424ed7d2e92b |