srxy 1.0.0__py3-none-any.whl

srxy/__init__.py

@@ -0,0 +1,15 @@
+from srxy.core import magic_search, search
+from srxy.dsl import Q
+from srxy.file_search import magic_file_search
+from srxy.models import FieldConfig, MatchType, SearchResult
+
+
+__all__ = [
+	"FieldConfig",
+	"MatchType",
+	"magic_file_search",
+	"magic_search",
+	"Q",
+	"SearchResult",
+	"search",
+]

srxy/cli.py

@@ -0,0 +1,242 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+from srxy.file_search import magic_file_search, suggest_max_file_size
+from srxy.models import FileSearchResult, SkippedFile
+from srxy.utils import format_match_preview
+
+
+_LOCATION_LABELS = {
+	"line": "line",
+	"page": "page",
+	"paragraph": "paragraph",
+	"row": "row",
+	"slide": "slide",
+}
+
+
+def format_location_label(kind: str, number: int) -> str:
+	label = _LOCATION_LABELS.get(kind, kind)
+	return f"{label} {number}"
+
+
+def _match_labels(result: FileSearchResult) -> str:
+	labels: list[str] = []
+	if "name" in result.breakdown and result.breakdown["name"] > 0.0:
+		labels.append("name")
+	if result.lines or result.breakdown.get("content", 0.0) > 0.0:
+		labels.append("content")
+	return ", ".join(labels) if labels else "match"
+
+
+def format_grouped(results: list[FileSearchResult], *, query: str = "") -> str:
+	if not results:
+		return ""
+
+	lines: list[str] = []
+	match_count = len(results)
+	header = f"{match_count} file matched" if match_count == 1 else f"{match_count} files matched"
+	if query:
+		header += f' for "{query}"'
+	lines.append(header)
+
+	for index, result in enumerate(results):
+		if index > 0:
+			lines.append("")
+		path_text = result.path.as_posix()
+		label_text = _match_labels(result)
+		lines.append(f"── {path_text} ──")
+		lines.append(f"   score {result.score:.2f}  ·  matched: {label_text}")
+		for line_match in result.lines:
+			location = format_location_label(line_match.location_kind, line_match.line_number)
+			preview = format_match_preview(line_match.text, query)
+			lines.append(f"   {location}  ·  score {line_match.score:.2f}")
+			lines.append(f"   │ {preview}")
+
+	return "\n".join(lines)
+
+
+def format_flat(results: list[FileSearchResult]) -> str:
+	lines: list[str] = []
+	for result in results:
+		path_text = result.path.as_posix()
+		if result.lines:
+			for line_match in result.lines:
+				lines.append(
+					f"{path_text}:{line_match.location_kind}:{line_match.line_number}:"
+					f"{line_match.score:.2f}:{line_match.text}"
+				)
+		elif "name" in result.breakdown and result.breakdown["name"] > 0.0:
+			lines.append(f"{path_text}:name:0:{result.score:.2f}:{result.path.name}")
+	return "\n".join(lines)
+
+
+def format_json(results: list[FileSearchResult], *, query: str = "") -> str:
+	payload = [
+		{
+			"path": result.path.as_posix(),
+			"score": result.score,
+			"breakdown": result.breakdown,
+			"lines": [
+				{
+					"line_number": line_match.line_number,
+					"location_kind": line_match.location_kind,
+					"location_label": format_location_label(line_match.location_kind, line_match.line_number),
+					"preview": format_match_preview(line_match.text, query),
+					"text": line_match.text,
+					"score": line_match.score,
+				}
+				for line_match in result.lines
+			],
+		}
+		for result in results
+	]
+	return json.dumps(payload, indent=2)
+
+
+def format_skipped_file_warnings(skipped_files: list[SkippedFile], max_file_size: int) -> str:
+	if not skipped_files:
+		return ""
+
+	lines: list[str] = []
+	for skipped in skipped_files:
+		suggested = suggest_max_file_size(skipped.size_bytes)
+		lines.append(
+			f"warning: skipped content search in {skipped.path.as_posix()} "
+			f"({skipped.size_bytes:,} bytes > --max-file-size {max_file_size:,})"
+		)
+		lines.append(f"  hint: rerun with --max-file-size {suggested}")
+	return "\n".join(lines)
+
+
+def build_parser() -> argparse.ArgumentParser:
+	parser = argparse.ArgumentParser(
+		prog="srxy",
+		description="Fuzzy file and content search using composite matchers.",
+	)
+	parser.add_argument("query", help="Search string")
+	parser.add_argument("path", nargs="?", default=".", help="File or directory to search (default: .)")
+	parser.add_argument("--threshold", type=float, default=0.25, help="Minimum match score (default: 0.25)")
+	parser.add_argument(
+		"--max-file-size",
+		type=int,
+		default=1_048_576,
+		help="Skip content search in files larger than this many bytes (default: 1048576)",
+	)
+	parser.add_argument(
+		"--max-line-matches",
+		type=int,
+		default=50,
+		help="Maximum matching lines returned per file (default: 50)",
+	)
+	parser.add_argument(
+		"--format",
+		choices=("grouped", "flat"),
+		default="grouped",
+		help="Output format for human-readable results (default: grouped)",
+	)
+	parser.add_argument("--json", action="store_true", help="Emit machine-readable JSON")
+	parser.add_argument("--semantic", action="store_true", help="Enable semantic matching (SRXY_SEMANTIC=1)")
+
+	mode_group = parser.add_mutually_exclusive_group()
+	mode_group.add_argument("--names-only", action="store_true", help="Search file names only")
+	mode_group.add_argument("--content-only", action="store_true", help="Search file contents only")
+
+	search_group = parser.add_mutually_exclusive_group()
+	search_group.add_argument(
+		"--names", action="store_true", dest="search_names", default=None, help="Search file names"
+	)
+	search_group.add_argument("--no-names", action="store_false", dest="search_names", help="Skip file name search")
+
+	content_group = parser.add_mutually_exclusive_group()
+	content_group.add_argument(
+		"--content", action="store_true", dest="search_contents", default=None, help="Search contents"
+	)
+	content_group.add_argument("--no-content", action="store_false", dest="search_contents", help="Skip content search")
+
+	parser.add_argument(
+		"--include-hidden",
+		action="store_true",
+		help="Search hidden directories and files (default: skip dot-prefixed entries)",
+	)
+	parser.add_argument(
+		"--include-noise",
+		action="store_true",
+		help="Search noise directories like __pycache__ and node_modules (default: skip)",
+	)
+
+	return parser
+
+
+def resolve_search_modes(args: argparse.Namespace) -> tuple[bool, bool]:
+	if args.names_only:
+		return True, False
+	if args.content_only:
+		return False, True
+
+	search_names = True if args.search_names is None else args.search_names
+	search_contents = True if args.search_contents is None else args.search_contents
+	return search_names, search_contents
+
+
+def render_results(
+	results: list[FileSearchResult],
+	*,
+	as_json: bool,
+	output_format: str,
+	query: str = "",
+) -> str:
+	if as_json:
+		return format_json(results, query=query)
+	if output_format == "flat":
+		return format_flat(results)
+	return format_grouped(results, query=query)
+
+
+def main(argv: list[str] | None = None) -> int:
+	parser = build_parser()
+	args = parser.parse_args(argv)
+
+	if args.semantic:
+		os.environ["SRXY_SEMANTIC"] = "1"
+
+	search_names, search_contents = resolve_search_modes(args)
+	skipped_files: list[SkippedFile] = []
+
+	try:
+		results = magic_file_search(
+			args.path,
+			args.query,
+			search_names=search_names,
+			search_contents=search_contents,
+			threshold=args.threshold,
+			max_file_size=args.max_file_size,
+			max_line_matches=args.max_line_matches,
+			skip_hidden_folders=not args.include_hidden,
+			skip_noise_folders=not args.include_noise,
+			skipped_files=skipped_files if search_contents else None,
+		)
+	except FileNotFoundError as error:
+		print(error, file=sys.stderr)
+		return 2
+	except ValueError as error:
+		print(error, file=sys.stderr)
+		return 2
+
+	warnings = format_skipped_file_warnings(skipped_files, args.max_file_size)
+	if warnings:
+		print(warnings, file=sys.stderr)
+
+	output = render_results(results, as_json=args.json, output_format=args.format, query=args.query)
+	if output:
+		print(output)
+
+	return 0 if results else 1
+
+
+if __name__ == "__main__":
+	sys.exit(main())

srxy/core.py

@@ -0,0 +1,150 @@
+from __future__ import annotations
+
+from typing import Any
+
+from srxy.matchers.registry import get_matcher
+from srxy.models import FieldConfig, MatchType, Q, QNodeType, SearchResult
+from srxy.utils import discover_fields, get_field_value, normalize_text
+
+
+_DEFAULT_MAGIC_SEARCH_FIELDS: list[str] = []
+
+
+def _score_field(
+	item: Any,
+	query: str,
+	field: str,
+	match_type: MatchType,
+	composite_weights: dict[MatchType, float] | None,
+) -> tuple[float, Any]:
+	value = normalize_text(get_field_value(item, field))
+	matcher = get_matcher(match_type, composite_weights)
+	if hasattr(matcher, "score_with_breakdown"):
+		score, sub_breakdown = matcher.score_with_breakdown(query, value)
+		if sub_breakdown:
+			return score, sub_breakdown
+		return score, score
+	return matcher.score(query, value), matcher.score(query, value)
+
+
+def _evaluate_leaf(item: Any, query: str, leaf: Q) -> tuple[float, dict[str, Any]]:
+	if leaf.field is None:
+		return 0.0, {}
+
+	score, detail = _score_field(item, query, leaf.field, leaf.match, leaf.composite_weights)
+	return score, {leaf.field: detail}
+
+
+def _evaluate_q(item: Any, query: str, expr: Q) -> tuple[float, dict[str, Any]]:
+	if expr.node_type == QNodeType.LEAF:
+		return _evaluate_leaf(item, query, expr)
+
+	child_results = [_evaluate_q(item, query, child) for child in expr.children]
+	child_scores = [score for score, _ in child_results]
+	breakdown = {}
+	for _, child_breakdown in child_results:
+		breakdown.update(child_breakdown)
+
+	if not child_scores:
+		return 0.0, breakdown
+
+	if expr.node_type == QNodeType.AND:
+		return min(child_scores), breakdown
+	return max(child_scores), breakdown
+
+
+def _evaluate_fields(
+	item: Any,
+	query: str,
+	fields: list[FieldConfig],
+	require_all: bool,
+	threshold: float,
+) -> tuple[float, dict[str, Any], bool]:
+	field_scores: list[tuple[float, float]] = []
+	breakdown: dict[str, Any] = {}
+
+	for field_config in fields:
+		score, detail = _score_field(
+			item,
+			query,
+			field_config.name,
+			field_config.match,
+			field_config.composite_weights,
+		)
+		field_scores.append((score, field_config.weight))
+		breakdown[field_config.name] = detail
+
+	if not field_scores:
+		return 0.0, breakdown, False
+
+	if require_all and any(score <= 0.0 for score, _ in field_scores):
+		return 0.0, breakdown, False
+
+	if require_all and threshold > 0.0 and any(score < threshold for score, _ in field_scores):
+		return 0.0, breakdown, False
+
+	total_weight = sum(weight for _, weight in field_scores)
+	if total_weight == 0.0:
+		return 0.0, breakdown, False
+
+	weighted_score = sum(score * weight for score, weight in field_scores) / total_weight
+	return weighted_score, breakdown, True
+
+
+def search(
+	items: list[Any],
+	query: str,
+	*,
+	fields: list[FieldConfig] | None = None,
+	where: Q | None = None,
+	threshold: float = 0.0,
+	require_all: bool = False,
+) -> list[SearchResult]:
+	if fields is not None and where is not None:
+		raise ValueError("Provide either 'fields' or 'where', not both")
+	if fields is None and where is None:
+		raise ValueError("Provide either 'fields' or 'where'")
+
+	normalized_query = normalize_text(query)
+	if not normalized_query:
+		return []
+
+	results: list[SearchResult] = []
+
+	for item in items:
+		if where is not None:
+			score, breakdown = _evaluate_q(item, normalized_query, where)
+			if score <= 0.0 or score < threshold:
+				continue
+			results.append(SearchResult(item=item, score=score, breakdown=breakdown))
+		elif fields is not None:
+			score, breakdown, include = _evaluate_fields(
+				item,
+				normalized_query,
+				fields,
+				require_all,
+				threshold,
+			)
+			if not include or score <= 0.0 or score < threshold:
+				continue
+			results.append(SearchResult(item=item, score=score, breakdown=breakdown))
+
+	results.sort(key=lambda result: result.score, reverse=True)
+	return results
+
+
+def magic_search(
+	items: list[Any],
+	query: str,
+	*,
+	fields: list[str] = _DEFAULT_MAGIC_SEARCH_FIELDS,
+	threshold: float = 0.25,
+) -> list[SearchResult]:
+	field_names = fields
+	if not field_names:
+		field_names = discover_fields(items)
+	if not field_names:
+		return []
+
+	where = Q.any(*(Q.composite(field) for field in field_names))
+	return search(items, query, where=where, threshold=threshold)

srxy/document_text.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Iterator
+from pathlib import Path
+
+
+DOCUMENT_SUFFIXES = frozenset({".pdf", ".docx", ".xlsx", ".pptx"})
+
+
+def is_document_path(path: Path) -> bool:
+	return path.suffix.lower() in DOCUMENT_SUFFIXES
+
+
+def iter_document_lines(path: Path) -> Iterator[tuple[int, str]]:
+	suffix = path.suffix.lower()
+	extractors: dict[str, Callable[[Path], Iterator[tuple[int, str]]]] = {
+		".pdf": _iter_pdf_lines,
+		".docx": _iter_docx_lines,
+		".xlsx": _iter_xlsx_lines,
+		".pptx": _iter_pptx_lines,
+	}
+	extractor = extractors.get(suffix)
+	if extractor is None:
+		return
+	try:
+		yield from extractor(path)
+	except Exception:
+		return
+
+
+def _iter_pdf_lines(path: Path) -> Iterator[tuple[int, str]]:
+	from pypdf import PdfReader
+
+	reader = PdfReader(path)
+	for page_number, page in enumerate(reader.pages, start=1):
+		text = page.extract_text() or ""
+		text = text.strip()
+		if text:
+			yield page_number, text
+
+
+def _iter_docx_lines(path: Path) -> Iterator[tuple[int, str]]:
+	from docx import Document
+
+	document = Document(str(path))
+	for paragraph_number, paragraph in enumerate(document.paragraphs, start=1):
+		text = paragraph.text.strip()
+		if text:
+			yield paragraph_number, text
+
+
+def _iter_xlsx_lines(path: Path) -> Iterator[tuple[int, str]]:
+	from openpyxl import load_workbook
+
+	workbook = load_workbook(path, read_only=True, data_only=True)
+	try:
+		line_number = 0
+		for sheet in workbook.worksheets:
+			for row in sheet.iter_rows(values_only=True):
+				cells = [str(cell) for cell in row if cell is not None and str(cell).strip()]
+				if not cells:
+					continue
+				line_number += 1
+				yield line_number, f"[{sheet.title}] " + " ".join(cells)
+	finally:
+		workbook.close()
+
+
+def _iter_pptx_lines(path: Path) -> Iterator[tuple[int, str]]:
+	from pptx import Presentation
+
+	presentation = Presentation(str(path))
+	for slide_number, slide in enumerate(presentation.slides, start=1):
+		parts: list[str] = []
+		for shape in slide.shapes:
+			text = shape.text.strip() if hasattr(shape, "text") else ""
+			if text:
+				parts.append(text)
+		if parts:
+			yield slide_number, " ".join(parts)

srxy/dsl.py

@@ -0,0 +1,6 @@
+"""Query DSL — re-exports the Q expression class."""
+
+from srxy.models import Q
+
+
+__all__ = ["Q"]