`orthonym.jars`#

Note

Internal API. Names and behaviour may change between releases.

The two Java jars Orthonym uses, and where to find them.

Orthonym does not ship any jar. It uses two, pinned to one version and one: checksum each, and downloads them from their official releases:

OPSIN 2.9.0 (name -> structure), for the round-trip check of names.
centres 1.2.1, for CIP stereo descriptors.

Resolution order for each jar:

ORTHONYM_OPSIN_JAR / ORTHONYM_CENTRES_JAR – a path to the jar.
The jar directory (ORTHONYM_JAR_DIR, else <cache>/jars where <cache> is ORTHONYM_CACHE_DIR, $XDG_CACHE_HOME/orthonym or ~/.cache/orthonym), if the file there has the pinned checksum.
A download into the jar directory, unless ORTHONYM_NO_DOWNLOAD=1.

ORTHONYM_OPSIN=main (or main@<commit>) is an opt-in to OPSIN’s main branch: instead of the release jar, step 2 and 3 give a jar built from that commit with the local JDK and cached in the jar directory (opsin_build). Everything that asks for the OPSIN jar gets that one jar, so one OPSIN serves a whole process. ORTHONYM_OPSIN_JAR still wins over it, and with the variable unset or 2.9.0 nothing of the opt-in runs.

A jar that cannot be found is an error (JarUnavailable): naming without it would silently change names (no OPSIN check, a different CIP labeller). ORTHONYM_ALLOW_REDUCED=1 opts in to that reduced mode, in which the finders return None as before.

This module uses only the standard library, so the install-time build hook can load it by file path before Orthonym itself is installed.

class orthonym.jars.JarSpec(kind: str, version: str, filename: str, url: str, sha256: str, env_var: str)#

Bases: object

kind: str#

version: str#

filename: str#

url: str#

sha256: str#

env_var: str#

exception orthonym.jars.JarUnavailable#

Bases: RuntimeError

A pinned jar is missing and reduced mode was not requested.

Deliberately NOT an OrthonymLimitError: Orthonym.name turns those into ‘unknown organic compound’, and a missing jar must stop the run.

exception orthonym.jars.OpsinChoiceError#

Bases: JarUnavailable

ORTHONYM_OPSIN holds a value that is none of 2.9.0, main or main@<commit>. Always an error: reduced mode (ORTHONYM_ALLOW_REDUCED=1) is for a jar that cannot be found, not for a mistyped choice.

orthonym.jars.allow_reduced()#

True when the user opted in to naming without the jars.

orthonym.jars.jar_dir()#

Directory where downloaded jars are kept (not created here).

orthonym.jars.opsin_choice()#

The git ref of OPSIN’s main branch that ORTHONYM_OPSIN asks for; None for the release jar (the variable unset, empty or 2.9.0).

Raises:class:OpsinChoiceError (a:class:JarUnavailable) for any other value.

orthonym.jars.find_jar(kind, version=None, download=True)#

Absolute path to the pinned kind jar (‘opsin’ or ‘centres’).

A version other than the pinned one returns None (only pinned, checksummed jars are ever used). The outcome – a path or a failure – is resolved once for the settings in force and then reused. For OPSIN the settings ORTHONYM_OPSIN and ORTHONYM_OPSIN_JAR are part of what the outcome is kept for (the command line sets ORTHONYM_OPSIN after the package was imported), so a process that changes them gets a new outcome; the in-process JVM takes its jar once, so choose before the first name. On failure: raises:class:JarUnavailable, or returns None when ORTHONYM_ALLOW_REDUCED=1; a malformed ORTHONYM_OPSIN (OpsinChoiceError) is always raised.

With ORTHONYM_OPSIN set, find_jar("opsin") is the jar built from OPSIN’s main branch, for a caller that names the pinned version too.

orthonym.jars.active_opsin(download=True)#

Which OPSIN this process uses: label ("2.9.0", "main" or "custom", a jar given by ORTHONYM_OPSIN_JAR), the commit it was built from (None unless "main") and its path (None in reduced mode).

Resolves the jar like:func:find_jar, so it can raise:class:JarUnavailable.

orthonym.jars.require_all()#

Raise:class:JarUnavailable unless every pinned jar is available (or reduced mode was requested). Called once when a namer is created.

orthonym.jars.fetch_all(verbose=True)#

Download (if needed) and verify every pinned jar; return kind -> path.

Ignores ORTHONYM_NO_DOWNLOAD and reduced mode: this is the explicit fetch. Raises:class:JarUnavailable on the first failure.

orthonym.jars.fetch_opsin_choice(verbose=True)#

Build (if needed) and check the jar that ORTHONYM_OPSIN asks for, ahead of use.

Like:func:fetch_all it ignores ORTHONYM_NO_DOWNLOAD and reduced mode: this is the explicit request. Returns the jar’s path, or None when the release jar is in use (the variable unset or 2.9.0, or a jar given by ORTHONYM_OPSIN_JAR, which wins). Raises JarUnavailable on failure.

orthonym.jars#

`orthonym.jars`#