Metadata-Version: 2.4
Name: obj_tag_group
Version: 0.2.0
Summary: A flexible, searchable registry that allows you to attach text tags to almost any Python object.
License-Expression: MIT
Project-URL: Repository, https://github.com/nicholas-lua/obj_tag_group
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# obj_tag_group

A searchable registry that allows you to attach text tags to almost any Python object.

Objects are indexed by their serialized content, allowing for quick filtering of items using regular expression searches on their associated tags.


## Important notes

1. The save/load to file feature of this package uses python's pickle module. **Never load a saved registry file from an untrusted source**, as this can result in arbitrary code execution during deserialization.

2. This package will fail to work on objects that cannot be serialized, such as lambda functions.

3. The tags work by creating a full copy of the object in memory, and will not reflect any future changes made to the object/s.


## Motivation

In Python, categorizing objects is usually done through modifying an object's class to include a tags attribute, or mapping the objects in a dictionary. However, this becomes a problem for unhashable objects such as the native set or dict.

Originally, the intention was simply to allow users to tag and filter unicode characters for easy searching, but was later extended to work on other data types as well, necessitating the support for unhashable types.


## Features

- Add / remove tags to most Python objects, even unhashable ones such as dictionaries and lists, as well as custom classes
- Filter and retrieve objects using regular expression queries
- Save the entire tagged registry to disk and load it back later.


## Installation

```bash
pip install obj_tag_group
```

## Quickstart

```python
from obj_tag_group import Tag_Group

# 1. Initialize the Registry
reg = Tag_Group()

# 2. Create and Tag Objects
test_1 = {1: "Apple", 2: ("Lemon", "Mango")}
test_2 = ["Mango", "Pineapple", "Cabbage"]
test_3 = "Lettuce"
test_4 = ("beef", "ham")

reg.tag_object(test_1, tags = ["dict", "fruit"])
reg.tag_object(test_2, tags = ["list", "fruit", "vegetable"])
reg.tag_object(test_3, tags = ["string", "vegetable"])
reg.tag_object(test_4, tags = ["tuple", "meat"])

# 3. Filter Objects by Tags (Example: find objects with both "fruit" and "vegetable")
results = reg.filter_tags(pattern=r"vegetable|fruit")
print(results)
# Output (not necessarily in the same order): [{1: 'Apple', 2: ('Lemon', 'Mango')}, ['Mango', 'Pineapple', 'Cabbage'], 'Lettuce']

```


## User Guide

### 1. Tagging Objects and Handling Errors
The `tag_object` method accepts arbitrary Python structures. If an object is of a type that cannot be serialized by `pickle` (e.g., live file streams, database connections, or lambda functions), the system will catch the error and throws a `TypeError`.

```python
# Tagging an unhashable dictionary structure
reg.tag_object({"user_id": 101}, tags=["auth", "active"])

# Triggering a serialization safety catch
try:
    reg.tag_object(lambda x: x + 1, tags="function")
except TypeError as e:
    print(e)  # Output: Object of type function cannot be serialized with pickle. [...]

```

### 2. Modifying and Removing Tags

The `untag_object` method changes slightly based on the provided arguments:

1. Remove specific tags: Pass a string or an iterable of strings to strip those explicit tags while leaving the object in the registry. Objects that have no remaining tags will be removed automatically.

2. Completely untrack an object: Omit the tags parameter entirely to wipe the object and all of its associated tags completely out of memory.

```python
# Remove only the "active" tag
reg.untag_object({"user_id": 101}, tags="active")

# Completely stop tracking this object across the entire registry
reg.untag_object({"user_id": 101})
```


### 3. Filtering with Regex Flags

The `filter_tags` method forwards any standard Python regular expression options to the `re` compiler. For example, case-insensitive queries can be implemented using `re.IGNORECASE`.

```python
import re

# Matches "VEGETABLE", "Vegetable", or "vegetable"
results = reg.filter_tags(pattern=r"^VEGETABLE$", flags=re.IGNORECASE)
```

Note on Result Ordering: The list returned by filter_tags() is inherently unordered due to the underlying hash table indexing. If your application relies on a specific sequence, sort the output list manually after retrieval.


### 4. Saving and Loading to Files
The entire `Tag_Group` registry (including all tracked objects, hashes, and tags) can be saved to a file on disk and reloaded to return exactly where you left off. 

* `save_to_file(filename)`: Serializes the current registry state using high-performance pickling.
* `load_from_file(filename)`: A class method that restores your data. If the specified file does not exist yet, it gracefully catches the error and returns a completely fresh, empty `Tag_Group` instance instead of crashing.

```python
# Save your current session state to disk
reg.save_to_file("my_registry.pkl")

# Load your session back into a new variable later (or in a different script)
from obj_tag_group import Tag_Group
loaded_reg = Tag_Group.load_from_file("my_registry.pkl")
```

Security Reminder: As detailed in Important Notes, load_from_file uses pickle to load serialized data. Only load files created by yourself or trusted parties to prevent arbitrary code execution.


## Developer Guide

This guide outlines the internal architecture of `obj_tag_group` and provides setup instructions for modifying the package.


### 1. Internal Architecture & State Management
The library relies on three internal data structures within the `Tag_Group` class to map objects, hashes, and tags:

* `self.unhash = {}`: A standard dictionary mapping a SHA-256 string hash to the raw `pickle` byte stream of the tracked object. This acts as our primary object storage database.
* `self.tags = defaultdict(set)`: A dictionary mapping an object's SHA-256 hash to a Python `set` of string tags assigned to it.
* `self.hashes = defaultdict(set)`: A dictionary mapping a specific string tag back to a `set` of object SHA-256 hashes, enabling faster regular expression pattern filtering.


### 2. Local Environment Setup
To set up a local development environment, clone the repository and install it in editable/development mode:

```bash
# Clone the repository
git clone [https://github.com/YOUR_USERNAME/obj_tag_group.git](https://github.com/YOUR_USERNAME/obj_tag_group.git)
cd obj_tag_group

# Install the package in editable mode with development tools
pip install -e .
```


### 3. Running Tests

We use pytest to maintain codebase reliability. Before finalizing changes, ensure all tests pass cleanly by running the test suite:

```bash
# Install testing dependencies
pip install pytest

# Execute tests
pytest
```
