watchdict 0.1.4

A dictionary class with change detection and state persistence

WatchDict

WatchDict is a Python library that provides an enhanced data structure for monitoring dynamic changes in collections, allowing for efficient querying using trie-based search functionality. The WatchDict class enables logging of modifications and supports advanced search capabilities, while also saving all changes in a JSON file that acts as a database.

Features

• WatchDict: Automatically logs and saves changes when items are added, removed, or modified.

• Trie-Based Search: Fast searching for prefixes, suffixes, and exact matches using a trie data structure.

• Flexible Querying: Supports exact matches, substring searches, and numerical comparisons (greater than, less than).

• Persistent Storage: Saves all changes in a JSON file, allowing data to persist between sessions.

• Debug Logging: Easily toggle logging of changes to standard output.

Installation

You can install the WatchDict package using pip:

pip install watchdict 

Usage

Importing the Library

To use WatchDict, import it into your Python script:

from watchdict import WatchDict

Creating a WatchDict

You can create a WatchDict to monitor and manipulate a dictionary of items. Here’s how to do it:

# Initialize a WatchDict with a file path for persistence

watchdict = WatchDict(database='data.json', allow_search=True)



# Set items

watchdict['key1'] = 'value1'  # Output: Set item: key1 = value1

watchdict['key2'] = 'value2'  # Output: Set item: key2 = value2



# Get an item

value = watchdict['key1']  # Output: 'value1'



# Delete an item

del watchdict['key2']  # Output: Deleted item: key2 which had value value2



# Search for values

results = watchdict['$value1$']  # Exact match query

print(results)  # Output: [{'key1': 'value1'}]



# Greater than query

greater_than_results = watchdict['>100']

print(greater_than_results)  # Output: results of greater than 100

between_results = watchdict['>100&<200']

or_opration = watchdict['$hello|*bye']

Persistent Storage

All changes made to the WatchDict are saved in a specified JSON file. When the WatchDict is initialized, it loads existing data from the file, allowing for persistence between sessions.

Logging

To enable logging of changes, set the debug flag to True at the beginning of your script:

debug = True  # Enable logging

To disable logging, set debug to False:

debug = False  # Disable logging

Example Usage

Here's a complete example showcasing the features of WatchDict:

from watchdict import WatchDict



# Enable debug logging

debug = True



# Create and manipulate a WatchDict

watchdict = WatchDict(database='data.json', allow_search=True)

watchdict['key1'] = 'value1'

watchdict['key2'] = 'value2'



# Get an item

print(watchdict['key1'])  # Output: 'value1'



# Delete an item

del watchdict['key2']



# Search for an exact value

print(watchdict['$value1$'])  # Output: [{'key1': 'value1'}]



# Perform a greater than query

# Assume numerical values are stored in the WatchDict

print(watchdict['>100'])  # Output: results for values greater than 100

Query Syntax

You can perform various types of queries on the WatchDict. Here are the supported query formats:

• Exact match: Enclose the word in $ symbols (e.g., $word$)

• Greater than: Start the query with > (e.g., >10)

• Less than: Start the query with < (e.g., <5)

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• This project utilizes a trie data structure for efficient searching. The implementation is based on common patterns for prefix trees.