acquaint.lookup

Finding the right record: exact references, handle resolution, the conflation check, and channel choice.

All functions take a Store and return plain data. Matching is deterministic normalisation (case, punctuation and accents ignored). Nothing here acts on a partial match or picks between candidates: an id and another record’s exact alias compete on equal terms, partials are offered as suggestions, and find_entity() refuses when more than one record fits. One unreadable record is reported and skipped; it never takes a lookup down.

Module Attributes

TIERS	Who set a rule, most authoritative first.
USABLE_STATUSES	An identity is usable only with one of these statuses (none recorded means active).
INACTIVE_RULES	A rule is out of use with one of these statuses.
NO_CHANNEL_NAMED	What a channel entry is called when its rule named none, so no repr stands in for one.

Functions

check_text(store, text)	Scan prose for people errors before it is published.
find_entity(store, ref, *[, names])	The one store key a reference names, or an AcquaintError saying why not.
match(store, query)	Store keys matching a name, alias, handle, email or id: {"exact": [...], "partial": [...], "unreadable": [...]}.
normalise_handle(platform, value)	A handle's comparable form: an email lowercased, with Gmail dots and +tags folded; any other value lowercased, without a leading @.
normalize(text)	Lowercase ASCII letters and digits only, for comparing names and handles.
reach_channels(store, key, *[, defaults_text])	Ordered channels for reaching one entity in a context (purpose, urgency, project, message_type, topic).
resolve_handle(store, handle)	Who a channel handle belongs to, with the evidence: {"platform", "matches", "inactive", "by_name", "unreadable"}.

acquaint.lookup.INACTIVE_RULES = {'dead', 'draft', 'expired', 'retracted', 'superseded'}

A rule is out of use with one of these statuses.

acquaint.lookup.NO_CHANNEL_NAMED = '(no channel named)'

What a channel entry is called when its rule named none, so no repr stands in for one.

acquaint.lookup.TIERS = ('self', 'operator', 'affiliation', 'observed', 'default')

Who set a rule, most authoritative first. The operator’s instruction for the message at hand outranks all of these; it belongs to the caller, not the store.

acquaint.lookup.USABLE_STATUSES = {'active', 'relay'}

An identity is usable only with one of these statuses (none recorded means active). Anything else (stale, former, unverified, retracted, dead, …) is reported, never acted on.

acquaint.lookup.check_text(store, text)

Scan prose for people errors before it is published.

Reports the entities mentioned; conflations (one entity written as if it were two: two different names for it joined by “or”, “and”, “/”, “,” …, citation order such as “Lovelace, Ada” excepted); ambiguous forms shared by several entities; and unknown name-like phrases that match nobody.

Return type:

dict[str, Any]

acquaint.lookup.find_entity(store, ref, *, names=True)

The one store key a reference names, or an AcquaintError saying why not.

person:ada-lovelace and people/ada-lovelace are exact and decide on their own. A bare word is looked up as an id (in any kind, any case) and, with names, as an exact name, alias, handle or email; it resolves only when exactly one record fits all of these together. A partial match never counts; it is offered as a suggestion. Operations that rewrite or remove records pass names=False and need the id.

Return type:

str

acquaint.lookup.match(store, query)

Store keys matching a name, alias, handle, email or id: {"exact": [...], "partial": [...], "unreadable": [...]}.

partial holds entities where the query is part of a longer form (three characters or more): suggestions for a person, never something to act on.

Return type:

dict[str, list]

acquaint.lookup.normalise_handle(platform, value)

A handle’s comparable form: an email lowercased, with Gmail dots and +tags folded; any other value lowercased, without a leading @.

Return type:

str

acquaint.lookup.normalize(text)

Lowercase ASCII letters and digits only, for comparing names and handles.

Return type:

str

>>> normalize("Zoë O'Example")
'zoeoexample'

acquaint.lookup.reach_channels(store, key, *, defaults_text='', **context)

Ordered channels for reaching one entity in a context (purpose, urgency, project, message_type, topic).

Precedence: the person’s own stated rules > the operator’s rules about them > norms of a project or affiliation > observed habits > global defaults. Within a tier the most specific matching rule wins. Only usable addresses are offered; a rule value that is not a channel name is skipped with a note. It returns addresses; it sends nothing.

Each channel carries address_kind: stated when a rule gave the address, identity when it was built from one of the entity’s identities, None when there is no address. The distinction matters because an identity-built address is a handle (github:ada), and a channel addressed by conversation rather than by person (GitHub, a web inbox, a chat channel) does not take one. Such a channel’s rule states its address.

A channel’s position is decided by the best-placed rule that names it; its address by the best-placed rule that states one, which may be a different rule. A rule that names a channel without stating an address expresses no opinion about where that channel goes, so it does not bury an address a lower-placed rule states; the note says which rule file the address came from when the two differ.

Return type:

dict[str, Any]

acquaint.lookup.resolve_handle(store, handle)

Who a channel handle belongs to, with the evidence: {"platform", "matches", "inactive", "by_name", "unreadable"}.

github:octocat, email:ada@example.org and ada@example.org name a platform; @octocat does not, so it matches that handle on any platform. Only identities with a usable status (see USABLE_STATUSES) are matches; the rest are reported under inactive with their status. A handle found in no identity file is matched against names under by_name, which is never enough to act on.

Return type:

dict[str, Any]