tagmap 0.1.18

Fast data structure for managing tags and metadata with efficient queries

TagMap

A data structure for managing tags and metadata with support for efficient intersection and union queries. Implemented in C++ with Python bindings via pybind11.

Overview

TagMap provides a dictionary-like container where each key maps to a set of tags. It supports querying for keys that match specific tag combinations using AND (intersection) and OR (union) operations.

Characteristics

• O(1) average case for single tag operations (add, remove, check)
• O(k·m) for AND queries (k = result size, m = avg tags per key)
• O(n) for OR queries (n = total keys matching any tag)
• Inverted index structure for fast queries
• C++ implementation with Python 3.8+ compatibility

Install

Install from PyPI:

pip install tagmap

Requires Python 3.8 or later. Pre-built wheels available for Linux, macOS, and Windows. For platform-specific instructions, see INSTALLATION.md.

Usage

import tagmap

m = tagmap.TagMap()

# Set tags for keys
m["alice"] = {"dev", "python"}
m["bob"] = {"dev", "cpp"}
m["carol"] = ["design", "python"]

# Query: keys with both "dev" AND "python"
m.query("dev", "python")        # ['alice']

# Query: keys with "python" OR "ops"
m.query_any("python", "ops")    # ['alice', 'carol']

# Check if key has tag
m.has_tag("alice", "python")    # True

# Add or remove tags
m.add_tag("alice", "ml")
m.remove_tag("bob", "dev")

Documentation

• API Reference - Complete method documentation
• Examples - Usage patterns
• Architecture - Implementation details and complexity analysis
• Installation - Setup instructions for all platforms

Examples

Team Skills

team = tagmap.TagMap({
    "alice": ["python", "typescript", "backend"],
    "bob": ["cpp", "rust", "backend"],
    "carol": ["ux", "ui", "design"],
})

team.query("python")             # ['alice']
team.query("backend")            # ['alice', 'bob']
team.query("python", "backend")  # ['alice']

See EXAMPLES.md for additional usage patterns.

Performance

Tag operations (add, remove, check): O(1) average case AND queries (all tags): O(k·m) where k = result size, m = avg tags per key OR queries (any tag): O(n) where n = sum of keys matching each tag

See ARCHITECTURE.md for detailed complexity analysis and benchmarks.

Building from Source

Clone and build:

git clone https://github.com/originalsouth/tagmap.py.git
cd tagmap.py

python -m venv venv
source venv/bin/activate

pip install pybind11 pytest
pip install -e .

Run tests:

pytest test_tagmap.py -v

Requirements: Python 3.8+, C++20 compiler, pybind11. Build uses -Ofast -march=native optimizations.

For detailed build instructions, see INSTALLATION.md.

License

MIT License. See LICENSE for details.

Repository

• GitHub: https://github.com/originalsouth/tagmap.py
• Issues: https://github.com/originalsouth/tagmap.py/issues
• Releases: https://github.com/originalsouth/tagmap.py/releases