orthonym.failure_mode#

Note

Internal API. Names and behaviour may change between releases.

What a public naming call returns for a structure it cannot name (GitHub issue 45).

Three modes, chosen with the on_failure argument of:func:orthonym.name_compound and orthonym.Orthonym.name():

"empty" (the default)

Return "" and log one warning on the logger orthonym with the SMILES, the limit code and the label (UNNAMEABLE: unknown organic compound). The label is not a name.

"label"

Return the label, as the engine did before the option existed.

"raise"

Raise:class:orthonym.errors.OrthonymLimitError (the same as raise_on_limit=True).

The choice applies to the caller’s own call only, the outermost naming call on the stack (is_callers_own_call()). The engine names parts of a molecule through the same public entries (name_compound and Orthonym.name inside handlers, producers and rescues) and reads what they return as a string, so a nested call always gets the label, whatever the argument says.

"empty" keeps the name the "label" call would return: the call is made as a "label" call and a result that:func:orthonym.errors.is_failure_name calls a failure is blanked. It is not made through raise_on_limit, because that option also skips the late recoveries and the trivial fallback of the wider tiers (measured on 159 development molecules at the best-effort tier: 7 names the plain call gives came back as errors). The limit code is read from what the call recorded (the default tier’s decline, the abstention record), else classified from the structure (orthonym.errors.classify_failure_limit()).

orthonym.failure_mode.logger = <Logger orthonym (WARNING)>#

The logger the unnamed-structure warning goes to. The record carries orthonym_smiles, orthonym_code and orthonym_label, so a handler can read them without parsing the text.

orthonym.failure_mode.is_callers_own_call()#

Whether a naming call now being made is the caller’s own, outside any naming.

orthonym.failure_mode.resolve(on_failure, raise_on_limit=False)#

The mode of a call: on_failure checked, "raise" when raise_on_limit is set, and "label" in place of "empty" for a call made inside a naming.

Raises ValueError for a value that is not one of:data:MODES.

orthonym.failure_mode.limit_of(namer, smiles, produced)#

The limit behind produced, a label (or "") that a naming call returned.

The default tier’s decline of a name that is not a verified PIN (recorded by namer), the ring-system refusal (recorded as the abstention detail), else the structure’s own classification, as for:func:orthonym.classify_limit.

orthonym.failure_mode.warn_unnamed(smiles, limit)#

Log the one warning for a structure that got no name. limit is a limit as a dict (OrthonymLimitError.as_dict()).

orthonym.failure_mode.blank(namer, given, produced)#

produced when it is a name; else "" with the warning ("empty" mode).

orthonym.failure_mode.settle_confidence(mode, record, smiles)#

record, the dict of name_compound(..., include_confidence=True), settled for mode. A structure that got no name has a limit in its record (or no name, or a label for it): "empty" sets its "name" to "" and logs the warning, "raise" raises the limit, "label" leaves the record as it is.

orthonym.failure_mode.failure_mode_scope(fn)#

The on_failure argument of Orthonym.name, outside every other scope of it.

fn is the whole name. A nested call, and a call with a mode other than "empty", run fn as they always did ("raise" is raise_on_limit=True); the caller’s own "empty" call runs it as a "label" call and blanks a failure.