LOCAL_SIMPLE_DATABASE¶
Table of Contents
Short Overview.¶
local_simple_database is a simple Python package(py>=2.7 or py>=3.4) with the main purpose to help storing and retrieving data from human-readable .txt files with one line of code. All the interactions with files are being made in a processes-threads safe manner.
Long Overview.¶
This package consists of 2 main classes with which user should interact:
- LocalSimpleDatabase
- LocalDictDatabase
One small example¶
Let’s say you want to store file with int variable with name int_times_I_ve_eaten.
Then, using this package, you can do it like this:
from local_simple_database import LocalSimpleDatabase
LSD = LocalSimpleDatabase(path_to_dir_where_to_save_file)
and then just use everywhere in your code LSD[“int_times_I_ve_eaten”] like if it was usual dictionary.
LSD["int_times_I_ve_eaten"] += 1 # To increase value in the file
LSD["int_times_I_ve_eaten"] # To get current value from the file
int_value_I_was_afraid_to_lose = LSD["int_times_I_ve_eaten"]
How to name databases¶
Name of database should satisfy template “type_name”
Examples: int_balls, float_seconds_left, str_my_name, dict_useless_heap
So just by the name you can define the type of database, isn’t it awesome.
Basic usage.¶
1) LocalSimpleDatabase¶
This class is built to handle (saving-retrieving) one value data like integer or float.
For now supported types of databases are:
- [“int”, “float”, “str”, “datetime”] (Probably will be enhanced soon)
- This means that one file with database can handle only type data
Initialization of databases handler¶
from local_simple_database import LocalSimpleDatabase
LSD = LocalSimpleDatabase(
str_path_database_dir=".",
)
Arguments:
- str_path_database_dir:
- If the explicit path is not given or variable is not set at all,then will be used path “./local_database”Folder for database will be created automatically
A few examples of Usage¶
After you’ve initialized LSD object you can use:
1) Integer database¶
If you want to store/access/modify simple int in file:
# Process 1
LSD["int_red_cars_drove"] += 1
LSD["int_red_cars_drove"] += 2
# Oh now, last one was burgundy
LSD["int_red_cars_drove"] -= 1
# Process 2
print("red cars already found", LSD["int_red_cars_drove"])
# If there was no such DataBase yet, than in will be created and 0 value will be returned.
LSD["int_red_cars_drove"] = 5
print("Red cars already found: ", LSD["int_red_cars_drove"])
2) Float database¶
LSD["float_last_price_of_watermelons"] = 7.49
# Too many watermelons this year, need to apply 30% discount
LSD["float_last_price_of_watermelons"] *= 0.7
print(
"Hello my best customer, current price on watermelons is: ",
LSD["float_last_price_of_watermelons"]
)
3) Datetime database¶
import datetime
# Saving datetime in file in ISO format (E.G. 2020-05-16T18:00:41.780534)
LSD["datetime_now"] = datetime.datetime.now()
# Load datetime obj from DataBase
# if DB not found will be retunrs datetime for 1970-01-01
print("Hour was a moment ago: ", LSD["datetime_now"].hour)
# Use DataBase value to find timedelta
int_seconds_gone = (datetime.datetime.now() - LSD["datetime_now"]).seconds
print("Seconds gone: ", int_seconds_gone)
4) Date database¶
Very similar to datetime database, but only date will by saved
import datetime
# Saving datetime in file in ISO format (E.G. 2020-05-16)
LSD["date_now"] = datetime.datetime.now()
# Load datetime obj from DataBase
# if DB not found will be retunrs datetime for 1970-01-01
print("Date today: ", LSD["date_now"])
# Use DataBase value to find timedelta
if datetime.datetime.now().date() == LSD["date_now"]:
int_seconds_gone_today = (datetime.datetime.now() - LSD["date_now"]).seconds
print("Seconds already gone: ", int_seconds_gone_today)
2) LocalDictDatabase¶
This class was built to handle (saving-retrieving) dictionary with data from a file.
Work with such database is a little different from LocalSimpleDatabase so it was necessary to put it in a separate class
Initialization of databases handler¶
from local_simple_database import LocalDictDatabase
LDD = LocalDictDatabase(
str_path_database_dir=".",
default_value=None,
)
Arguments:
- str_path_database_dir:
- If the explicit path is not given or variable is not set at all,then will be used path “./local_database”Folder for databases will be created automatically
- default_value: value to use for any database if key in it is not found.
- LDD[database_name][key] = default_value
A few examples of Usage¶
1) Basic store/access/modify data from a dict database.¶
# Set methods
## Set value for whole LDD:
LDD["dict_very_useful_heap"] = {"Mike": 50, "Stan": 1000000}
## Set keys for one dictionary LDD
## If there is no file with asked dict database then it will be created automatically
LDD["dict_useless_heap"]["random_key"] = 1
LDD["dict_useless_heap"]["random_key"] += 3
LDD["dict_useless_heap"][2] = ["Oh my God, what a list is doing here", "Aaa"]
LDD["dict_useless_heap"][99] = {"Are you serious?": {"You'd better be!": "Bbb"}}
# Get methods
## To get whole dict for LDD, please use:
LDD["dict_useless_heap"].get_value() # Sorry for that, I don't know how to do it without additional method
## To get string representation of whole dict:
print(LDD["dict_useless_heap"])
## To get one key from dict:
int_random_key = LDD["dict_useless_heap"]["random_key"]
2) Set default value:¶
# You can set the default value for all databases OR for only one:
## 1) Set default value for any database when can't find key:
LDD.change_default_value(0)
## 2) Set default value for one database:
LDD["cars"].change_default_value(0)
# They you can use LDD similarly to collections.defaultdict
LDD["cars"]["red"] += 1
# Oh no, that was burgundy once again
LDD["cars"]["red"] -= 1
LDD["cars"]["burgundy"] += 1
Advanced usage (can be skipped, you already know enough to use it)¶
1) class database additional arguments¶
Both 2 main classes (LocalSimpleDatabase, LocalDictDatabase) have additional arguments:
str_datetime_template_for_rolling=””
This variable allows setting rolling save of database results using the DateTime template.If the value is not empty, then saving/retrieving results will be done from deeper folders with names satisfy the evaluation of the DateTime string template.E.G. To save daily results use “%Y%m%d” (Then deeper folder names will be like “20191230”, “20191231”, …)E.G. To save hourly results use “%Y%m%d_%H” (Then deeper folder names will be like “20191230_0”, “20191230_23”, …)float_max_seconds_per_file_operation=0.01
This variable is necessary for multiprocessing safe work.It setting time in which LSD file accessed by process can’t be accessed by any other process.By default, it is set to 10 ms for simple database and 20 ms for dict database.If you use operations which from accessing value till setting new value needs more time, you are more than welcome to increase it.You can set it to 0.0 if you are not using threads-processes and want the maximum speed.
# Full definition of LocalSimpleDatabase
LSD = LocalSimpleDatabase(
str_path_database_dir=".",
float_max_seconds_per_file_operation=0.05,
str_datetime_template_for_rolling=""
)
# Full definition of LocalDictDatabase
LDD = LocalDictDatabase(
str_path_database_dir=".",
default_value=None,
float_max_seconds_per_file_operation=0.05,
str_datetime_template_for_rolling=""
)
2) Rolling example¶
LSD_daily_rolling = LocalSimpleDatabase(
str_path_database_dir=".",
str_datetime_template_for_rolling="%Y%m%d"
)
3) Get values for ALL databases in the directory.¶
To get a dictionary with data in all databases by database name, use:
LSD.get_dict_data_by_db_name()
If you were using rolling, then you can get dictionary with results like {“datetime_1”: dict_all_DBs_date_1, }
LSD.get_dict_every_DB_by_datetime()
If you were using rolling, and interested only in one database. {“datetime_1”: database_value_1, …}
# Please replace *str_database_name* on name of LSD which values you want to get
LSD.get_one_db_data_daily(
str_database_name,
value_to_use_if_db_not_found=None
)