"""The reach of a pull: which countries, and whether remote roles, each company board is asked for, derived from the search agents that are switched on. Computed once per pull (`plan`) and handed to each board's batch as the `reach` the runner narrows to its reader's filters (`plugins/readers/_runner.py`, `ask_for`). - **Base reach**: the union of the enabled agents' `any` gates on country, place (a town or region, mapped to its country through the gazetteer) and remote. An agent whose `any` group is empty, or holds any other member (a function, a remote value other than `remote`, a place the gazetteer does not know), can take a role from anywhere, so the base reach is then everywhere. - **Wide reach, for the companies tagged All roles** (`companies.all_roles`, global): the union over the enabled agents of their `require` reach, the intersection of each one's `require` gates on country and place, Europe today, expanded to its countries through the gazetteer, and the base reach, so a tag never reads less than the board would untagged. An agent with no `require` gate on place makes it everywhere. A role in Freiburg may be open to remote, or worth asking the company about for Denmark. Favourite (affinity 2) is scoring only, where it skips the `any` gates; it does not widen what is fetched. - **Board override**: a board whose subscription `params` name a country, a place or remote gets no reach here; `ask_for` reads the params instead. - **Small boards**: a board that listed under `SMALL` roles when last read whole gets no filter; filtering it saves little and risks closing roles. A reach of more countries than a `one`-filter host should be asked one by one (the wide reach's Europe on SmartRecruiters) is dropped by `ask_for`, which knows the reader (`MAX_SERIES`), so such a board is read whole. """ from __future__ import annotations from collections.abc import Iterable, Mapping from dataclasses import dataclass, field from typing import Any from app import places from app.models import Agent, Gate, Subscription, company_key from app.storage import Store from plugins import readers from plugins.readers import _runner #: A board that listed fewer roles than this when last read whole is read #: whole. SMALL = 300 #: `state` key of a board's size, `ats:size:`: the roles its last #: unfiltered read listed, written by `plugins/ats.py`. SIZE = "ats:size:" #: The params that make a board's own reach (see `_runner._PARAM_DIMENSION`). OVERRIDE_KEYS = frozenset(("countries", "country", "places", "place", "remote")) @dataclass(frozen=True) class Reach: """Countries (ISO codes) and remote, or everywhere.""" countries: frozenset[str] = frozenset() remote: bool = False everywhere: bool = False def __or__(self, other: Reach) -> Reach: if self.everywhere or other.everywhere: return EVERYWHERE return Reach(self.countries | other.countries, self.remote or other.remote) def params(self) -> dict[str, Any] | None: """What `ask_for` takes as `reach`; None for everywhere.""" if self.everywhere: return None out: dict[str, Any] = {"countries": sorted(self.countries)} if self.remote: out["remote"] = True return out def describe(self) -> str: """"DK, SE, remote", "31 countries", "everywhere".""" if self.everywhere: return "everywhere" codes = sorted(self.countries) words = [", ".join(codes)] if len(codes) <= 4 else [f"{len(codes)} countries"] if self.remote: words.append("remote") return ", ".join(w for w in words if w) or "nothing" EVERYWHERE = Reach(everywhere=True) NOWHERE = Reach() def _countries_of(ids: Iterable[int], gaz: places.Gazetteer) -> set[str]: """The ISO codes of the countries the places lie in, a continent's every country.""" out: set[str] = set() for place_id in ids: place = gaz.places.get(place_id) if place is None: continue if place.kind == "continent": out |= {gaz.places[p].key for p in gaz.under((place_id,)) if gaz.places[p].kind == "country"} elif code := gaz.country(place_id): out.add(code) return out def gate_reach(gate: Gate, gaz: places.Gazetteer) -> Reach: """Where a role that meets `gate` can be: its countries, remote, or everywhere for a gate that says nothing of place or names one the gazetteer does not know.""" values = [str(v).strip() for v in gate.values if str(v).strip()] if gate.field == "remote": return Reach(remote=True) if values and all(v.lower() == "remote" for v in values) \ else EVERYWHERE if gate.field not in ("country", "place") or not values: return EVERYWHERE found: set[str] = set() for value in values: named = gaz.lookup(f"country:{value}" if gate.field == "country" else value) if named is None: if gate.field == "country" and len(value) == 2 and value.isalpha(): found.add(value.upper()) continue return EVERYWHERE found |= _countries_of(named, gaz) return Reach(frozenset(found)) if found else EVERYWHERE def any_reach(agent: Agent, gaz: places.Gazetteer) -> Reach: """The union of the agent's `any` gates; everywhere with none.""" group = [g for g in agent.gates if g.mode == "any"] if not group: return EVERYWHERE out = NOWHERE for gate in group: out = out | gate_reach(gate, gaz) return out def require_reach(agent: Agent, gaz: places.Gazetteer) -> Reach: """The intersection of the agent's `require` gates on country and place, or remote alone for a `require` of remote only; everywhere with neither, or when the intersection is empty.""" kept: frozenset[str] | None = None remote = False for gate in agent.gates: if gate.mode != "require": continue reach = gate_reach(gate, gaz) if reach.everywhere: continue if reach.countries: kept = reach.countries if kept is None else kept & reach.countries elif reach.remote: remote = True if kept: return Reach(kept) return Reach(remote=True) if remote and kept is None else EVERYWHERE @dataclass class Plan: """The reach of one pull: `base` for every board, `wide` for the boards of the companies in `tagged` (tagged All roles), and each board's size by target.""" base: Reach wide: Reach = EVERYWHERE sizes: dict[str, int] = field(default_factory=dict) tagged: frozenset[str] = frozenset() def why(self, sub: Subscription) -> tuple[Reach, str]: """The reach `sub` is read with, and why: `override`, `small`, `unknown` (a board never read whole), `tag` (its company is tagged All roles) or `agents`.""" if OVERRIDE_KEYS & set(sub.params or {}): return EVERYWHERE, "override" size = self.sizes.get(sub.target) if size is None: return EVERYWHERE, "unknown" if size < SMALL: return EVERYWHERE, "small" if company_key(sub.company or sub.label) in self.tagged: return self.wide, "tag" return self.base, "agents" def for_subscription(self, sub: Subscription) -> dict[str, Any] | None: """The `reach` a board's batch hands `ask_for`; None for none.""" return self.why(sub)[0].params() def sizes(store: Store, subs: Iterable[Subscription]) -> dict[str, int]: """Each board's size: the roles its last unfiltered read listed (`ats:size:`), else, for a board read before that was kept and never filtered, its open roles. A board never read has none.""" state = store.state counts = store.open_countries_by_subscription() out: dict[str, int] = {} for sub in subs: kept = state.get(f"{SIZE}{sub.target}", "") if kept.isdigit(): out[sub.target] = int(kept) elif state.get(f"ats:ok:{sub.target}") and not state.get(f"ats:filtered:{sub.target}"): out[sub.target] = sum(counts.get(sub.id, {}).values()) return out def plan(store: Store, subs: Iterable[Subscription] | None = None) -> Plan: """The reach of a pull, from the enabled agents and the companies tagged All roles, and the sizes of `subs` (every `ats` subscription when None).""" gaz = store.gazetteer() agents = store.agents(enabled_only=True) base = wide = NOWHERE for agent in agents: base = base | any_reach(agent, gaz) wide = wide | require_reach(agent, gaz) if not agents: base = wide = EVERYWHERE subs = list(store.subscriptions(source="ats") if subs is None else subs) tagged = frozenset(c.key for c in store.companies() if c.all_roles) # A tag never reads less than the board would untagged: the base's # remote, which a `require` of Europe does not name, is kept. return Plan(base, wide | base, sizes(store, subs), tagged) def reaches(store: Store, subs: Iterable[Subscription]) -> Mapping[str, dict[str, Any]]: """`target -> reach` for the boards that get one, what a pull puts in its batches' payloads.""" subs = list(subs) found = plan(store, subs) return {s.target: r for s in subs if (r := found.for_subscription(s)) is not None} #: Why a board is read whole, as the Companies list says it. _WHOLE = {"small": f"under {SMALL} roles", "unknown": "not read whole yet", "override": "set here", "tag": "company tag, too many countries to ask", "agents": "an agent takes any place"} #: Why a board is read filtered, as the Companies list says it. _SAID = {"override": "set here", "tag": "company tag"} def line(found: Plan, sub: Subscription) -> str: """What a pull asks `sub`'s board for, once its reader has narrowed the reach, in a few words: "DK, SE, remote · agents", "33 countries, remote · company tag", "all roles · under 300 roles", "all roles · Greenhouse cannot filter".""" module = readers.HOSTS.get(sub.target.partition(":")[0]) if module is None: return "" given, why = found.why(sub) ask = _runner.ask_for(module, sub.params, given.params()) if _runner.filtered(ask): words = sorted(ask.countries) if len(ask.countries) <= 4 \ else [f"{len(ask.countries)} countries"] if ask.remote: words.append("remote") return f"{', '.join(words)} · {_SAID.get(why, why)}" if why in ("agents", "tag") and given.everywhere: return f"all roles · {'company tag' if why == 'tag' else _WHOLE[why]}" if why in ("agents", "tag") and not module.READS.filters.declared(): return f"all roles · {module.LABEL} cannot filter" if why == "agents": return f"all roles · {module.LABEL} cannot ask for these" return f"all roles · {_WHOLE[why]}"