Metadata-Version: 2.1
Name: local_simple_database
Version: 0.1.0
Summary: Package for easy process variable in file like if it was usual variable in python
Home-page: https://github.com/stas-prokopiev/local_simple_database
Author: stanislav prokopyev
Author-email: stas.prokopiev@gmail.com
License: mit
Description: ========================
        LOCAL_SIMPLE_DATABASE
        ========================
        
        .. image:: https://readthedocs.org/projects/local-simple-database/badge/?version=latest
            :target: https://local-simple-database.readthedocs.io/en/latest/?badge=latest
            :alt: Documentation Status
        
        .. image:: https://travis-ci.org/stas-prokopiev/local_simple_database.svg?branch=master
            :target: https://travis-ci.org/stas-prokopiev/local_simple_database
        
        .. contents:: **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 in just with one line of code. All of this is done in a process-thread safe manner.
        
        
        Long Overview.
        =========================
        
        This package consists of 2 main classes with which user should interact:
        
        #. class_local_simple_database
        #. class_local_dict_database
        
        One small example
        ----------------------
        
        Let's say you want to want store file with int variable with name int_times_I_ve_eaten.
        
        Then you should define handler of databases (E.G. at the top of your python program)
        
        .. code-block:: python
        
            from local_simple_database import class_local_simple_database
            DB = class_local_simple_database("folder_with_all_my_databases")
        
        and then just use everywhere in your code DB["int_times_I_ve_eaten"] like as it was usual dictionary.
        
        .. code-block:: python
        
            DB["int_times_I_ve_eaten"] += 1  # To increase value in the file
            DB["int_times_I_ve_eaten"]  # To get current value from the file
        
        After running this code in the folder with path = "folder_with_all_my_databases" will be created file "folder_with_all_my_databases/int_times_I_ve_eaten.txt" where value of this database will be stored.
        
        As value is stored in a human-readable txt file you can always access it and even after a restart of the computer, it'll still be there.
        
        To get it, just use:
        
        .. code-block:: python
        
            int_value_I_was_afraid_to_lose = DB["int_times_I_ve_eaten"]
        
        
        How to name database-s
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        
        Name of database should satisfy template "type_name" (E.G. 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.
        
        Installation
        ============
        
        * Install via pip:
        
        .. code-block:: bash
        
            pip install local_simple_database
        
        
        Basic usage.
        =========================
        
        1) class_local_simple_database
        --------------------------------------------------------------------------------------------------
        
        This class was built to handle (saving-retrieving) one value data like integers or floats.
        
        For now on supported types of databases are: ["int", "float", "str"] (Probably will be enhanced soon)
        
        - This means that you can use a database with one value inside with types of value: integer, float, string
        
        Initialization of databases handler
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        
        .. code-block:: python
        
            DB = class_local_simple_database(
                str_path_database_dir=".",
            )
        
        Arguments:
        
        1. **str_path_database_dir**: If the explicit path to database-s is not given,
            then will be used path "./local_database"
            Folder for database-s will be created automatically
        
        A few examples of Usage
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        
        The first thing you need to do is to initialize the database in some directory.
        
        To do so you need to replace str_path_database_dir from the code below on folder where you would like to store the file or leave it blank.
        
        .. code-block:: python
        
            from local_simple_database import class_local_simple_database
            DB = class_local_simple_database(str_path_database_dir=".")
        
        1) Integer database
        """"""""""""""""""""""""""""""""""""""""""""""""""""""""""""
        
        *If you want to store/access/modify simple int in file*
        
        .. code-block:: python
        
            # Process 1
            DB["int_red_cars_drove"] += 1
            DB["int_red_cars_drove"] += 2
            # Oh now, last one was burgundy
            DB["int_red_cars_drove"] -= 1
        
            # Process 2
            print("red cars already found", DB["int_red_cars_drove"])
            # If there was no such DataBase yet, than in will be created and 0 value will be returned.
            DB["int_red_cars_drove"] = 0
            print("red cars already found", DB["int_red_cars_drove"])
        
        2) Float database
        """"""""""""""""""""""""""""""""""""""""""""""""""""""""""""
        
        .. code-block:: python
        
            DB["float_last_price_of_watermelon"] = 7.49
            # Too many watermelons this year, need to apply 30% discount
            DB["float_last_price_of_watermelon"] *= 0.7
            print(
                "Hello my best customer, current price on watermelon is: ",
                DB["float_last_price_of_watermelon"]
            )
        
        
        2) class_local_dict_database
        --------------------------------------------------------------------------------------------------
        
        This class was built to handle (saving-retrieving) dictionary of data from a file.
        
        Work with such database-s is a little different from *class_local_simple_database* so it was necessary to put it in a separate class
        
        Initialization of databases handler
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        
        .. code-block:: python
        
            DB = class_local_dict_database(
                str_path_database_dir=".",
                default_value=None,
            )
        
        Arguments:
        
        #. **str_path_database_dir**: If the explicit path to database-s is not given,
            then will be used path "./local_database"
            Folder for database-s will be created automatically
        
        #. **default_value**: value to use if key in DB not found.
        
        A few examples of Usage
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        
        The first thing you need to do is to initialize the database in some directory.
        
        To do so you need to replace str_path_database_dir from the code below on folder where you would like to store a file or leave it blank.
        
        .. code-block:: python
        
            from local_simple_database import class_local_simple_database
            DB = class_local_dict_database(
                str_path_database_dir=".",
                default_value=None,
            )
        
        
        1) Basic Save-Get data from dict database.
        """"""""""""""""""""""""""""""""""""""""""""""""""""""""""""
        
        .. code-block:: python
        
            # Set methods
            # Set value for whole DB:
            DB["dict_very_useful_heap"] = Any dictionary here
        
            ## Set keys for one DB with dict
            DB["dict_useless_heap"]["random_key"] = 1
            DB["dict_useless_heap"]["random_key"] += 3
            DB["dict_useless_heap"][2] = ["Oh my God, what a list is doing here", "Aaa"]
            DB["dict_useless_heap"][99] = {"Are you serious?": {"You'd better be!": "Bbb"}}
        
            # Get methods
            ## To get whole dict for DB use:
            DB["dict_useless_heap"].get_value()  # Sorry for that, I don't know how to get rid of this additional method
        
            ## To get string representation of whole dict:
            str(DB["dict_useless_heap"])
            print(DB["dict_useless_heap"])
        
            ## To get one key from dict:
            int_random_key = DB["dict_useless_heap"]["random_key"]
        
        
        2) Set default value:
        """"""""""""""""""""""""""""""""""""""""""""""""""""""""""""
        
        .. code-block:: python
        
            # You can set the default value for all databases OR for only one
        
            ## 1) Set default value for all database-s:
            DB.change_default_value(0)
        
            ## 2) Set default value for one database:
            DB["cars"].change_default_value(0)
        
            # They you can use DB similarly as collections.defaultdict
            DB["cars"]["red"] += 1
            # Oh no, that was burgundy one
            DB["cars"]["red"] -= 1
            DB["cars"]["burgundy"] += 1
        
        
        
        Advanced usage.
        =========================
        
        1) class database additional arguments
        --------------------------------------------------------------------------------------------------
        
        Both 2 main classes (**class_local_simple_database**, **class_local_dict_database**) have additional arguments:
        
        1) **float_max_seconds_per_file_operation=0.05**
        
            This variable is necessary for multiprocessing safe work.
        
            It set time in which access by process file can't be accessed by any other process.
            By default, it set to 10 ms.
        
            If you use operation 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.
        
        2) **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", ...)
        
        
        .. code-block:: python
        
            # Full definition of class_local_simple_database
            DB = class_local_simple_database(
                str_path_database_dir=".",
                float_max_seconds_per_file_operation=0.05,
                str_datetime_template_for_rolling=""
            )
            # Full definition of class_local_dict_database
            DB = class_local_dict_database(
                str_path_database_dir=".",
                default_value=None,
                float_max_seconds_per_file_operation=0.05,
                str_datetime_template_for_rolling=""
            )
        
        
        2) Get values in ALL databases in the directory.
        --------------------------------------------------------------------------------------------------
        
        To get a dictionary with data in all databases by database name, use:
        
        .. code-block:: python
        
            DB.get_dict_DBs_data_by_DB_name()
        
        If you were using rolling, then you can get dictionary with results like {"datetime_1": dict_all_DBs_data_1, }
        
        .. code-block:: python
        
            DB.get_dict_every_DB_by_datetime()
        
        
        If you were using rolling, and interested only in one database. {"datetime_1": database_value_1, ...}
        
        .. code-block:: python
        
            DB.get_one_DB_data_daily(
                str_db_name,
                value_to_use_if_DB_not_found=None
            )
        
        Links
        =====
        
            * `PYPI <https://pypi.org/project/local_simple_database/>`_
            * `readthedocs <https://local-simple-database.readthedocs.io/en/latest/>`_
            * `GitHub <https://github.com/stas-prokopiev/local_simple_database>`_
        
        Releases
        ========
        
        See `CHANGELOG <https://github.com/stas-prokopiev/local_simple_database/blob/master/CHANGELOG.rst>`_.
        
        Contributing
        ============
        
        - Fork it (<https://github.com/stas-prokopiev/local_simple_database/fork>)
        - Create your feature branch (`git checkout -b feature/fooBar`)
        - Commit your changes (`git commit -am 'Add some fooBar'`)
        - Push to the branch (`git push origin feature/fooBar`)
        - Create a new Pull Request
        
        Contacts
        ========
        
            * Email: stas.prokopiev@gmail.com
        
            * `vk.com <https://vk.com/stas.prokopyev>`_
        
            * `Facebook <https://www.facebook.com/profile.php?id=100009380530321>`_
        
        License
        =======
        
        This project is licensed under the MIT License.
        
Platform: any
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Description-Content-Type: text/x-rst; charset=UTF-8
Provides-Extra: testing
