tagmap 0.1.15

Fast data structure for managing tags and metadata with efficient queries

TagMap

A fast, efficient data structure for managing tags and metadata in Python, built with C++ and pybind11.

Overview

TagMap is a specialized dictionary-like data structure optimized for managing multiple tags per key. It supports efficient queries for keys with specific tag combinations.

Features

• ⚡ Fast tag-based queries with intersection (all-of) and union (any-of) operations
• 📦 Efficient tag addition and removal
• 🔍 Multiple query methods for flexible data retrieval
• ⚙️ Built on high-performance C++ implementation
• 📊 Perfect for metadata management, feature flags, and classification systems

Quick Start

Installation

pip install tagmap

Or with uv:

uv pip install tagmap

Basic Usage

import tagmap

# Create a TagMap
m = tagmap.TagMap()

# Add entries with tags
m["alice"] = {"dev", "python"}
m["bob"] = {"dev", "cpp"}
m["carol"] = ["design", "python"]

# Query all entries with both "dev" and "python"
results = m.query("dev", "python")
# Result: ['alice']

# Query entries with either "python" OR "ops"
results = m.query_any("python", "ops")
# Result: ['alice', 'carol']

# Check if an entry has a tag
has_tag = m.has_tag("alice", "python")
# Result: True

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

Documentation

• Installation Guide - Detailed setup instructions for all platforms
• API Reference - Complete API documentation with method signatures
• Usage Examples - Real-world usage patterns and examples
• Architecture Guide - Internal design and performance characteristics
• Contributing Guide - How to contribute to the project

Common Use Cases

Team Skills Management

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

# Find all Python developers
python_devs = team.query("python")

# Find all backend developers
backend_devs = team.query("backend")

# Find people with backend + Python skills
full_stack = team.query("python", "backend")

Content Classification

articles = tagmap.TagMap({
    "post_1": ["python", "tutorial", "beginner"],
    "post_2": ["python", "advanced"],
    "post_3": ["javascript", "tutorial"],
})

# Find beginner Python tutorials
beginners = articles.query("python", "tutorial", "beginner")

# Find tutorials for learning (any level)
tutorials = articles.query_any("tutorial")

Feature Deployment Tracking

features = tagmap.TagMap({
    "auth_v2": ["production", "staging"],
    "new_dashboard": ["staging", "beta"],
    "payment": ["production"],
})

# What's in production?
prod = features.query("production")

# What's available for testing?
testing = features.query_any("staging", "beta")

# How many features are in both staging and beta?
count = features.count(["staging", "beta"])

Performance

TagMap is designed for high-performance queries on tagged data:

• Query operations: O(n) where n is the number of results
• Tag operations: O(1) average time for add/remove/check
• Memory efficient: Optimized inverted index for fast queries
• Scales well: Handles thousands of entries with hundreds of tags

See ARCHITECTURE.md for detailed performance characteristics.

Building from Source

For development or to use the latest features:

# Clone the repository
git clone https://github.com/originalsouth/tagmap.py.git
cd tagmap.py

# Create virtual environment
python -m venv venv
source venv/bin/activate

# Install dependencies
pip install pybind11 pytest

# Build and install
pip install -e .

# Or use the Makefile
make

# Run tests
pytest test_tagmap.py -v

Requires:

• Python 3.8+
• C++20 compatible compiler
• pybind11

Build Methods

Both pip install -e . and make use identical compiler optimizations:

• Optimization: -Ofast (aggressive speed optimization)
• CPU-specific: -march=native (optimize for your CPU)
• Link-time optimization: -flto=auto
• Result: Equivalent performance from both methods

See INSTALLATION.md for platform-specific build instructions.

Examples

Check EXAMPLES.md for comprehensive examples including:

• Team member skills tracking
• Blog post categorization
• Feature deployment tracking
• Document classification
• Dynamic tag management
• Bulk operations
• Analytics and reporting

Contributing

We welcome contributions! Please see CONTRIBUTING.md for:

• Development setup
• Code style guidelines
• Testing requirements
• Pull request process
• Reporting issues

License

TagMap is licensed under the MIT License. See LICENSE file for details.

Authors

• originalsouth - Initial implementation

Changelog

See GitHub Releases for version history and release notes.

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions