michraz 0.1.0__py3-none-any.whl

michraz/__init__.py

@@ -0,0 +1,34 @@
+"""michraz: one clean interface to Israeli public tenders.
+
+from michraz import Michraz
+
+with Michraz() as m:
+    for tender in m.search(keyword="גינון", open_only=True):
+        print(tender.deadline, tender.title)
+"""
+
+from michraz._version import __version__
+from michraz.client import Michraz
+from michraz.errors import MichrazError, SourceFormatError, SourceUnavailableError
+from michraz.export import to_csv, to_dataframe, to_dicts
+from michraz.models import Document, Tender
+from michraz.sources import BeerShevaExtra, BeerShevaSource, RmiExtra, RmiSource, Source, SourceName
+
+__all__ = [
+    "BeerShevaExtra",
+    "BeerShevaSource",
+    "Document",
+    "Michraz",
+    "MichrazError",
+    "RmiExtra",
+    "RmiSource",
+    "Source",
+    "SourceName",
+    "SourceFormatError",
+    "SourceUnavailableError",
+    "Tender",
+    "__version__",
+    "to_csv",
+    "to_dataframe",
+    "to_dicts",
+]

michraz/__main__.py

@@ -0,0 +1,3 @@
+from michraz.cli import main
+
+raise SystemExit(main())

michraz/_closeable.py

@@ -0,0 +1,25 @@
+"""Context-manager behaviour shared by every object that owns a connection pool."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from types import TracebackType
+from typing import TypeVar
+
+_T = TypeVar("_T", bound="Closeable")
+
+
+class Closeable(ABC):
+    """An object with a :meth:`close` method that can be used in a ``with`` block."""
+
+    @abstractmethod
+    def close(self) -> None:
+        """Releases the resources this object owns."""
+
+    def __enter__(self: _T) -> _T:
+        return self
+
+    def __exit__(
+        self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None
+    ) -> None:
+        self.close()

michraz/_dates.py

@@ -0,0 +1,68 @@
+"""Date parsing helpers. Every datetime michraz produces is timezone-aware."""
+
+from __future__ import annotations
+
+import re
+from datetime import datetime
+from zoneinfo import ZoneInfo
+
+TIMEZONE_NAME = "Asia/Jerusalem"
+JERUSALEM = ZoneInfo(TIMEZONE_NAME)
+
+LOCAL_FORMAT = "%d/%m/%Y %H:%M:%S"
+
+UTC_DESIGNATOR = "Z"
+UTC_OFFSET = "+00:00"
+
+_FRACTION = re.compile(r"\.(\d+)")
+MICROSECOND_DIGITS = 6
+
+
+def _pad_fraction(match: re.Match[str]) -> str:
+    # Python 3.10 only accepts fractions of exactly 3 or 6 digits; the RMI API sends 2 ("57.55").
+    return "." + match.group(1)[:MICROSECOND_DIGITS].ljust(MICROSECOND_DIGITS, "0")
+
+
+def parse_iso(value: str | None) -> datetime | None:
+    """Parses an ISO 8601 timestamp and converts it to Asia/Jerusalem.
+
+    Args:
+        value: Timestamp such as ``"2026-12-28T12:00:00+02:00"``. A value without an offset is taken as
+            Asia/Jerusalem local time.
+
+    Returns:
+        An aware datetime, or None if ``value`` is None or blank.
+
+    Raises:
+        ValueError: If ``value`` is not a valid ISO 8601 timestamp.
+    """
+    if value is None or not value.strip():
+        return None
+    text = _FRACTION.sub(_pad_fraction, value.strip().replace(UTC_DESIGNATOR, UTC_OFFSET))
+    parsed = datetime.fromisoformat(text)
+    if parsed.tzinfo is None:
+        return parsed.replace(tzinfo=JERUSALEM)
+    return parsed.astimezone(JERUSALEM)
+
+
+def parse_local(value: str | None, fmt: str = LOCAL_FORMAT) -> datetime | None:
+    """Parses a local Israeli timestamp such as ``"10/11/2026 12:00:00"``.
+
+    Args:
+        value: Text to parse.
+        fmt: ``strptime`` format. Defaults to ``dd/mm/yyyy HH:MM:SS``.
+
+    Returns:
+        An aware datetime in Asia/Jerusalem, or None if ``value`` is None or blank.
+
+    Raises:
+        ValueError: If ``value`` does not match ``fmt``.
+    """
+    if value is None or not value.strip():
+        return None
+    return datetime.strptime(value.strip(), fmt).replace(tzinfo=JERUSALEM)
+
+
+def now() -> datetime:
+    """Returns the current time in Asia/Jerusalem."""
+    return datetime.now(JERUSALEM)

michraz/_enums.py

@@ -0,0 +1,14 @@
+"""Enum base used across the package."""
+
+from enum import Enum
+
+
+class StrEnum(str, Enum):
+    """A string enum whose members equal, hash and print as their values.
+
+    ``StrEnum.MEMBER == "value"`` is true and members work as dictionary keys next to plain strings, so code
+    that still passes the raw string keeps working. ``enum.StrEnum`` exists only from Python 3.11.
+    """
+
+    def __str__(self) -> str:
+        return str(self.value)

michraz/_http.py

@@ -0,0 +1,253 @@
+"""Polite HTTP client shared by every source.
+
+Government services are not built for heavy traffic, so this client sends an honest User-Agent, waits between
+requests to the same host, caches successful responses on disk and backs off when a server asks it to.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import os
+import tempfile
+import time
+from collections.abc import Callable, Mapping
+from datetime import datetime, timedelta, timezone
+from email.utils import parsedate_to_datetime
+from http import HTTPStatus
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from michraz._closeable import Closeable
+from michraz._enums import StrEnum
+from michraz._version import __version__
+from michraz.errors import SourceFormatError, SourceUnavailableError
+
+logger = logging.getLogger(__name__)
+
+PROJECT_URL = "https://github.com/Zikithezikit/michraz"
+USER_AGENT = f"michraz/{__version__} (+{PROJECT_URL})"
+HEADER_USER_AGENT = "User-Agent"
+HEADER_ACCEPT = "Accept"
+HEADER_RETRY_AFTER = "Retry-After"
+JSON_MEDIA_TYPE = "application/json"
+
+_CACHE_FETCHED_AT = "fetched_at"
+_CACHE_DATA = "data"
+CACHE_FILE_SUFFIX = ".json"
+CACHE_TMP_SUFFIX = ".tmp"
+DEFAULT_CACHE_DIR = Path(os.environ.get("XDG_CACHE_HOME") or Path.home() / ".cache") / "michraz"
+DEFAULT_CACHE_TTL = timedelta(hours=1)
+DEFAULT_MIN_INTERVAL = 1.0
+MIN_INTERVAL_FLOOR = 0.5
+MAX_RETRIES = 2
+BACKOFF_BASE = 1.0
+MAX_RETRY_AFTER = 60.0
+TIMEOUT = httpx.Timeout(30.0, connect=10.0)
+SAMPLE_CHARS = 200
+
+
+class HttpMethod(StrEnum):
+    """The HTTP methods michraz uses. Both only read data."""
+
+    GET = "GET"
+    POST = "POST"
+
+
+# 429 and every 5xx are worth retrying; any other error status is final.
+_REDIRECT_STATUS_START = HTTPStatus.MULTIPLE_CHOICES
+_SERVER_ERROR_START = HTTPStatus.INTERNAL_SERVER_ERROR
+
+
+def _truncate(text: str) -> str:
+    return text if len(text) <= SAMPLE_CHARS else text[:SAMPLE_CHARS] + "..."
+
+
+def _retry_after(header: str | None, wall_clock: Callable[[], float]) -> float | None:
+    """Parses a Retry-After header given in seconds or as an HTTP date."""
+    if not header:
+        return None
+    try:
+        return max(0.0, float(header))
+    except ValueError:
+        pass
+    try:
+        when = parsedate_to_datetime(header)
+    except (TypeError, ValueError):
+        return None
+    if when.tzinfo is None:
+        when = when.replace(tzinfo=timezone.utc)
+    return max(0.0, when.timestamp() - wall_clock())
+
+
+class _DiskCache:
+    """JSON files on disk, one per request, valid for ``ttl``."""
+
+    def __init__(self, directory: Path, ttl: timedelta, wall_clock: Callable[[], float]) -> None:
+        self.directory = directory
+        self.ttl = ttl
+        self._wall_clock = wall_clock
+
+    def _path(self, key: str) -> Path:
+        return self.directory / f"{key}{CACHE_FILE_SUFFIX}"
+
+    def read(self, key: str) -> tuple[float, Any] | None:
+        """Returns ``(fetched_at, data)`` regardless of age, or None if absent or unreadable."""
+        try:
+            entry = json.loads(self._path(key).read_text(encoding="utf-8"))
+            return float(entry[_CACHE_FETCHED_AT]), entry[_CACHE_DATA]
+        except (OSError, ValueError, KeyError, TypeError):
+            return None
+
+    def fresh(self, key: str) -> tuple[float, Any] | None:
+        entry = self.read(key)
+        if entry is None or self._wall_clock() - entry[0] >= self.ttl.total_seconds():
+            return None
+        return entry
+
+    def write(self, key: str, data: Any) -> None:
+        payload = json.dumps({_CACHE_FETCHED_AT: self._wall_clock(), _CACHE_DATA: data}, ensure_ascii=False)
+        try:
+            self.directory.mkdir(parents=True, exist_ok=True)
+            with tempfile.NamedTemporaryFile(
+                "w", encoding="utf-8", dir=self.directory, suffix=CACHE_TMP_SUFFIX, delete=False
+            ) as handle:
+                handle.write(payload)
+            os.replace(handle.name, self._path(key))
+        except OSError as exc:  # a cache that cannot be written must never break a search
+            logger.debug("could not write cache entry: %s", exc)
+
+
+def _request_key(method: HttpMethod, url: str, payload: Any) -> str:
+    body = json.dumps(payload, sort_keys=True, ensure_ascii=False) if payload is not None else ""
+    return hashlib.sha256(f"{method}\n{url}\n{body}".encode()).hexdigest()
+
+
+class HttpClient(Closeable):
+    """Rate-limited, caching JSON client with bounded retries.
+
+    Args:
+        cache_dir: Directory for cached responses. None disables the cache.
+        cache_ttl: How long a cached response stays valid.
+        min_interval: Minimum seconds between requests to the same host. Must be at least 0.5.
+        client: An ``httpx.Client`` to use. By default one is created and owned by this object.
+        clock: Monotonic clock in seconds. Replace it in tests.
+        sleep: Sleep function. Replace it in tests so they do not wait.
+        wall_clock: Wall-clock time in seconds since the epoch, used for cache age.
+
+    Raises:
+        ValueError: If ``min_interval`` is below 0.5 seconds.
+    """
+
+    def __init__(
+        self,
+        *,
+        cache_dir: str | os.PathLike[str] | None = DEFAULT_CACHE_DIR,
+        cache_ttl: timedelta = DEFAULT_CACHE_TTL,
+        min_interval: float = DEFAULT_MIN_INTERVAL,
+        client: httpx.Client | None = None,
+        clock: Callable[[], float] = time.monotonic,
+        sleep: Callable[[float], None] = time.sleep,
+        wall_clock: Callable[[], float] = time.time,
+    ) -> None:
+        if min_interval < MIN_INTERVAL_FLOOR:
+            raise ValueError(f"min_interval must be at least {MIN_INTERVAL_FLOOR} seconds")
+        self.min_interval = min_interval
+        self._clock = clock
+        self._sleep = sleep
+        self._wall_clock = wall_clock
+        self._owns_client = client is None
+        self._client = client or httpx.Client(
+            headers={HEADER_USER_AGENT: USER_AGENT, HEADER_ACCEPT: JSON_MEDIA_TYPE}, timeout=TIMEOUT
+        )
+        self._cache = _DiskCache(Path(cache_dir).expanduser(), cache_ttl, wall_clock) if cache_dir else None
+        self._last_request: dict[str, float] = {}
+
+    def close(self) -> None:
+        """Closes the underlying connection pool if this object created it."""
+        if self._owns_client:
+            self._client.close()
+
+    def get_json(self, source: str, url: str, params: Mapping[str, Any] | None = None) -> Any:
+        """Fetches ``url`` with GET and returns the decoded JSON body.
+
+        Args:
+            source: Name of the calling source, used in error messages.
+            url: Absolute URL.
+            params: Query parameters.
+
+        Raises:
+            SourceUnavailableError: If the host cannot be reached or answers with an error status.
+            SourceFormatError: If the body is not JSON.
+        """
+        return self._json(source, HttpMethod.GET, self._full_url(url, params), None)
+
+    def post_json(self, source: str, url: str, payload: Any) -> Any:
+        """Sends ``payload`` as JSON with POST and returns the decoded JSON body.
+
+        Raises:
+            SourceUnavailableError: If the host cannot be reached or answers with an error status.
+            SourceFormatError: If the body is not JSON.
+        """
+        return self._json(source, HttpMethod.POST, url, payload)
+
+    def cached_at(
+        self, method: HttpMethod, url: str, params: Mapping[str, Any] | None = None, payload: Any = None
+    ) -> datetime | None:
+        """Returns when a request was last fetched into the cache, even if the entry has expired."""
+        if self._cache is None:
+            return None
+        entry = self._cache.read(_request_key(method, self._full_url(url, params), payload))
+        return datetime.fromtimestamp(entry[0], tz=timezone.utc) if entry else None
+
+    @staticmethod
+    def _full_url(url: str, params: Mapping[str, Any] | None) -> str:
+        return str(httpx.URL(url, params=params)) if params else url
+
+    def _json(self, source: str, method: HttpMethod, url: str, payload: Any) -> Any:
+        key = _request_key(method, url, payload)
+        if self._cache and (hit := self._cache.fresh(key)) is not None:
+            logger.debug("cache hit for %s", url)
+            return hit[1]
+        response = self._send(source, method, url, payload)
+        try:
+            data = response.json()
+        except ValueError as exc:
+            raise SourceFormatError(source, f"response is not JSON: {_truncate(response.text)!r}") from exc
+        if self._cache:
+            self._cache.write(key, data)
+        return data
+
+    def _throttle(self, host: str) -> None:
+        last = self._last_request.get(host)
+        if last is not None:
+            wait = last + self.min_interval - self._clock()
+            if wait > 0:
+                self._sleep(wait)
+        self._last_request[host] = self._clock()
+
+    def _send(self, source: str, method: HttpMethod, url: str, payload: Any) -> httpx.Response:
+        host = httpx.URL(url).host
+        for attempt in range(MAX_RETRIES + 1):
+            self._throttle(host)
+            try:
+                response = self._client.request(method.value, url, json=payload)
+            except httpx.HTTPError as exc:
+                raise SourceUnavailableError(source, f"request to {host} failed: {exc}") from exc
+            status = response.status_code
+            retryable = status == HTTPStatus.TOO_MANY_REQUESTS or status >= _SERVER_ERROR_START
+            if not retryable or attempt == MAX_RETRIES:
+                break
+            delay = _retry_after(response.headers.get(HEADER_RETRY_AFTER), self._wall_clock)
+            if delay is None:
+                delay = BACKOFF_BASE * 2**attempt
+            if delay > MAX_RETRY_AFTER:
+                raise SourceUnavailableError(source, f"{host} asked to wait {delay:.0f}s (HTTP {status}); giving up")
+            logger.warning("%s answered HTTP %d, retrying in %.1fs", host, status, delay)
+            self._sleep(delay)
+        if status >= _REDIRECT_STATUS_START:
+            raise SourceUnavailableError(source, f"HTTP {status} from {url}")
+        return response

michraz/_version.py

@@ -0,0 +1,10 @@
+"""Package version, read from the installed distribution metadata."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+DISTRIBUTION_NAME = "michraz"
+
+try:
+    __version__ = version(DISTRIBUTION_NAME)
+except PackageNotFoundError:  # running from a source tree that was never installed
+    __version__ = "0+unknown"

michraz/cli.py

@@ -0,0 +1,146 @@
+"""Command-line interface: ``michraz search`` and ``michraz sources``."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+import sys
+from collections.abc import Sequence
+from datetime import datetime
+from enum import IntEnum
+
+from michraz import _dates
+from michraz._enums import StrEnum
+from michraz._http import DEFAULT_CACHE_DIR
+from michraz._version import __version__
+from michraz.client import Michraz
+from michraz.errors import MichrazError
+from michraz.export import to_csv, to_dicts
+from michraz.models import Tender
+from michraz.sources import BaseSource, SourceName
+
+PROGRAM = "michraz"
+DATE_FORMAT = "%Y-%m-%d %H:%M"
+STATE_OPEN = "open"
+STATE_CLOSED = "closed"
+TABLE_HEADER = ("SOURCE", "NUMBER", "DEADLINE", "STATE")
+TITLE_HEADER = "TITLE"
+
+
+class Command(StrEnum):
+    """Subcommands of the ``michraz`` program."""
+
+    SEARCH = "search"
+    SOURCES = "sources"
+
+
+class ExitCode(IntEnum):
+    """Process exit codes. argparse itself exits with 2 on a usage error."""
+
+    OK = 0
+    ERROR = 1
+
+
+NO_DATE = "-"
+MIN_TITLE_WIDTH = 20
+COLUMN_GAP = 2
+NUMBER_WIDTH = 14
+ELLIPSIS = "\u2026"
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog=PROGRAM, description="Search Israeli public tenders.")
+    parser.add_argument("--version", action="version", version=f"michraz {__version__}")
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--no-cache", action="store_true", help="do not read or write the on-disk cache")
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    search = commands.add_parser(Command.SEARCH.value, parents=[common], help="search tenders")
+    search.add_argument("--keyword", "-k", help="text to look for in the title or number")
+    search.add_argument("--open", action="store_true", help="only tenders that can still receive submissions")
+    search.add_argument("--source", choices=[name.value for name in SourceName], help="search a single source")
+    search.add_argument("--csv", metavar="FILE", help="also write the results to a CSV file (UTF-8 with BOM)")
+    search.add_argument("--json", action="store_true", help="print JSON instead of a table")
+
+    commands.add_parser(
+        Command.SOURCES.value, parents=[common], help="list sources, their attribution and when each was last fetched"
+    )
+    return parser
+
+
+def _when(value: datetime | None) -> str:
+    return value.astimezone(_dates.JERUSALEM).strftime(DATE_FORMAT) if value else NO_DATE
+
+
+def _clip(text: str, width: int) -> str:
+    return text if len(text) <= width else text[: width - 1] + ELLIPSIS
+
+
+def _print_table(tenders: Sequence[Tender]) -> None:
+    # Hebrew is printed in logical order and the terminal lays it out. The title goes last so the
+    # fixed-width columns stay aligned whatever the text direction.
+    header = TABLE_HEADER
+    rows = [
+        (
+            t.source,
+            _clip(t.number or NO_DATE, NUMBER_WIDTH),
+            _when(t.deadline),
+            STATE_OPEN if t.is_open() else STATE_CLOSED,
+        )
+        for t in tenders
+    ]
+    widths = [max(len(cells[i]) for cells in [header, *rows]) for i in range(len(header))]
+    title_width = max(shutil.get_terminal_size().columns - sum(widths) - COLUMN_GAP * len(widths), MIN_TITLE_WIDTH)
+
+    def line(cells: Sequence[str], title: str) -> str:
+        fixed = (COLUMN_GAP * " ").join(cell.ljust(width) for cell, width in zip(cells, widths, strict=True))
+        return f"{fixed}{COLUMN_GAP * ' '}{title}"
+
+    print(line(header, TITLE_HEADER))
+    for cells, tender in zip(rows, tenders, strict=True):
+        print(line(cells, _clip(tender.title, title_width)))
+    print(f"\n{len(rows)} tender{'' if len(rows) == 1 else 's'}")
+    for credit in sorted({t.attribution for t in tenders}):
+        print(f"Data: {credit}")
+
+
+def _search(args: argparse.Namespace, m: Michraz) -> int:
+    tenders = m.search(keyword=args.keyword, open_only=args.open, source=args.source)
+    if args.csv:
+        count = to_csv(tenders, args.csv)
+        print(f"wrote {count} tenders to {args.csv}", file=sys.stderr)
+    if args.json:
+        print(json.dumps(to_dicts(tenders), ensure_ascii=False, indent=2))
+    else:
+        _print_table(tenders)
+    for message in m.last_errors:
+        print(f"warning: {message}", file=sys.stderr)
+    return ExitCode.OK
+
+
+def _sources(m: Michraz) -> int:
+    for source in m.sources:
+        fetched = source.last_fetched() if isinstance(source, BaseSource) else None
+        print(f"{source.name}\n  {source.description}\n  data: {source.attribution}\n  last fetch: {_when(fetched)}")
+    return ExitCode.OK
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Runs the command-line interface.
+
+    Args:
+        argv: Arguments without the program name. Defaults to ``sys.argv[1:]``.
+
+    Returns:
+        The process exit code: 0 on success, 1 if a source failed.
+    """
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(errors="replace")  # a console that cannot show Hebrew must not crash the run
+    args = _build_parser().parse_args(argv)
+    try:
+        with Michraz(cache_dir=None if args.no_cache else DEFAULT_CACHE_DIR) as m:
+            return _search(args, m) if args.command == Command.SEARCH else _sources(m)
+    except MichrazError as exc:
+        print(f"michraz: error: {exc}", file=sys.stderr)
+        return ExitCode.ERROR

michraz/client.py

@@ -0,0 +1,116 @@
+"""The :class:`Michraz` facade: one object to search every source."""
+
+from __future__ import annotations
+
+import logging
+import os
+from collections.abc import Sequence
+from datetime import date, datetime, timedelta
+
+from michraz._closeable import Closeable
+from michraz._http import (
+    DEFAULT_CACHE_DIR,
+    DEFAULT_CACHE_TTL,
+    DEFAULT_MIN_INTERVAL,
+    HttpClient,
+)
+from michraz.filters import TenderFilter, sort_by_deadline
+from michraz.models import Tender
+from michraz.sources import BaseSource, BeerShevaSource, RmiSource, Source
+
+logger = logging.getLogger(__name__)
+
+
+class Michraz(Closeable):
+    """Searches several tender sources through one polite HTTP client.
+
+    Use it as a context manager so the connection pool is closed:
+
+        with Michraz() as m:
+            tenders = m.search(keyword="גינון", open_only=True)
+
+    Args:
+        sources: Sources to search. Defaults to RMI and Beer Sheva.
+        cache_dir: Directory for cached responses. Defaults to ``~/.cache/michraz``. None disables the cache.
+        cache_ttl: How long a cached response stays valid.
+        min_interval: Minimum seconds between requests to the same host. Must be at least 0.5.
+
+    Attributes:
+        sources: The sources in use.
+        last_errors: Records skipped during the last :meth:`search`, one message each.
+
+    Raises:
+        ValueError: If ``min_interval`` is below 0.5 seconds or two sources share a name.
+    """
+
+    def __init__(
+        self,
+        sources: Sequence[Source] | None = None,
+        cache_dir: str | os.PathLike[str] | None = DEFAULT_CACHE_DIR,
+        cache_ttl: timedelta = DEFAULT_CACHE_TTL,
+        min_interval: float = DEFAULT_MIN_INTERVAL,
+    ) -> None:
+        self._http = HttpClient(cache_dir=cache_dir, cache_ttl=cache_ttl, min_interval=min_interval)
+        self.sources: tuple[Source, ...] = tuple(sources) if sources is not None else (RmiSource(), BeerShevaSource())
+        names = [s.name for s in self.sources]
+        if len(set(names)) != len(names):
+            raise ValueError(f"source names must be unique, got {names}")
+        for source in self.sources:
+            if isinstance(source, BaseSource):
+                source.bind(self._http)
+        self.last_errors: list[str] = []
+
+    def search(
+        self,
+        keyword: str | None = None,
+        open_only: bool = False,
+        source: str | None = None,
+        closing_before: datetime | date | None = None,
+        closing_after: datetime | date | None = None,
+    ) -> list[Tender]:
+        """Fetches tenders from the sources and filters them.
+
+        Args:
+            keyword: Keep tenders whose title or number contains this text (case-insensitive, NFKC).
+            open_only: Keep only tenders that can still receive submissions.
+            source: Search only the source with this name.
+            closing_before: Keep tenders whose deadline is before this moment. A date means the start of
+                that day in Asia/Jerusalem.
+            closing_after: Keep tenders whose deadline is at or after this moment.
+
+        Returns:
+            Matching tenders sorted by deadline, earliest first. Tenders without a deadline come last.
+
+        Raises:
+            ValueError: If ``source`` names no known source or a datetime bound is naive.
+            SourceUnavailableError: If a source cannot be reached.
+            SourceFormatError: If a source answers in an unexpected shape.
+        """
+        criteria = TenderFilter(
+            keyword=keyword, open_only=open_only, closing_before=closing_before, closing_after=closing_after
+        )
+        self.last_errors = []
+        tenders: list[Tender] = []
+        for src in self._select(source):
+            tenders.extend(src.fetch())
+            self.last_errors.extend(src.errors)
+        return sort_by_deadline(criteria.apply(tenders))
+
+    def _select(self, name: str | None) -> tuple[Source, ...]:
+        if name is None:
+            return self.sources
+        chosen = tuple(s for s in self.sources if s.name == name)
+        if not chosen:
+            known = ", ".join(s.name for s in self.sources)
+            raise ValueError(f"unknown source {name!r}; known sources: {known}")
+        return chosen
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(sources={[s.name for s in self.sources]})"
+
+    def close(self) -> None:
+        """Closes the shared connection pool."""
+        self._http.close()
+        for source in self.sources:
+            if isinstance(source, BaseSource):
+                source.close()