Skip to content

feat: Make vicinity typing generic#75

Merged
Pringled merged 2 commits intomainfrom
fix-typing
Apr 10, 2026
Merged

feat: Make vicinity typing generic#75
Pringled merged 2 commits intomainfrom
fix-typing

Conversation

@Pringled
Copy link
Copy Markdown
Member

@Pringled Pringled commented Apr 9, 2026

Vicinity has always accepted any item type at runtime, but the type for SimilarityItem was hardcoded to list[tuple[str, float]], making query() appear to return string items regardless of what was actually stored. This makes it impossible to use Vicinity with typed item types without resorting to cast() or type: ignore. This PR fixes that by changing the return type to a generic type.

For example, the following now works correctly:

from dataclasses import dataclass                                                         
from vicinity import Vicinity                                                             
import numpy as np                                                                      
                                                                                        
@dataclass                                                                              
class Document:
    title: str
    url: str
                                                                                        
docs = [Document("Cats", "/cats"), Document("Dogs", "/dogs")]                   
vectors = np.random.rand(2, 4).astype(np.float32)                                         
                                                                                        
index: Vicinity[Document] = Vicinity.from_vectors_and_items(vectors, docs)              
query = np.random.rand(1, 4).astype(np.float32)
                                                                                        
hits = index.query(query, k=1)[0]  # list[tuple[Document, float]]
for doc, distance in hits:                                                                
    print(doc.url)  # this would have failed before with a type error since doc was always assumed to be a str

@Pringled Pringled requested a review from stephantul April 9, 2026 07:58
@codecov-commenter
Copy link
Copy Markdown

codecov-commenter commented Apr 9, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.

Files with missing lines Coverage Δ
vicinity/datatypes.py 100.00% <100.00%> (ø)
vicinity/vicinity.py 95.42% <100.00%> (-3.13%) ⬇️
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@Pringled Pringled merged commit 81e2ceb into main Apr 10, 2026
4 checks passed
@Pringled Pringled deleted the fix-typing branch April 10, 2026 07:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants