locutor 0.1.0__py3-none-any.whl

locutor/__init__.py

@@ -0,0 +1,105 @@
+"""locutor: call R and Julia from Python, as a function or as a script.
+
+Two ways of calling, one for each lifetime::
+
+    import locutor
+
+    # a function, in memory: one persistent child per language, nothing on disk
+    rotated = locutor.call("methods/rotation.R:double_rotation", u, v, w)
+    total = locutor.call("stats.jl:total", series, skip_missing=True)
+
+    # a script, in a process of its own
+    locutor.run("fetch.R", "2026-11-13", out="data/raw.csv")
+
+A configured interpreter is an object, for packages, a file of helpers, another
+program than the one on PATH, or a session of its own::
+
+    with locutor.R(packages=["stats"], include="helpers.R") as r:
+        r.call("stats::median", series)
+        r.call("my_helper", series, window=5)
+
+What crosses a call is a number, a string, a boolean, ``None``, a numeric array
+and a list or a mapping of those (:mod:`locutor.wire`). Every double crosses as
+its 64 bits: nothing is printed and parsed, and a NaN arrives as it left.
+"""
+
+import atexit
+import os
+
+from .language import Language, find_program, language, names, of_file
+from .script import Result
+from .session import Session, close_all
+from .wire import Items, pack, unpack
+
+__version__ = "0.1.0"
+
+__all__ = ["Language", "R", "Julia", "Python", "Session", "Result", "Items",
+           "call", "run", "session", "available", "close", "names", "language",
+           "of_file", "find_program", "pack", "unpack", "close_all"]
+
+#: The interpreter each language is called through when none is given: one of
+#: each, built at its first use.
+_DEFAULT = {}
+
+
+def __getattr__(name):
+    # The language classes by their own names, imported when asked for.
+    for known in names():
+        found = language(known)
+        if found.__name__ == name:
+            return found
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def default(name):
+    """The shared, unconfigured interpreter of one language."""
+    found = language(name)
+    if found.NAME not in _DEFAULT:
+        _DEFAULT[found.NAME] = found()
+    return _DEFAULT[found.NAME]
+
+
+def session(name):
+    """The persistent child the module-level :func:`call` uses for a language."""
+    return default(name).session
+
+
+def call(target, *args, **kwargs):
+    """Call ``path/file.ext:function`` with ``args`` and ``kwargs``.
+
+    The language is the file's, by its extension; the function runs in that
+    language's shared session, started at the first call and kept. For a
+    package's function or a session with packages of its own, build the
+    language (``locutor.R(packages=[...])``) and call that.
+    """
+    path, sep, function = str(target).rpartition(":")
+    if not sep or not function or not os.path.splitext(path)[1]:
+        raise ValueError(
+            f"{target!r} is not 'path/file.ext:function'. A function that is "
+            f"not a file's is called on a language: locutor.R().call(...)")
+    return default(of_file(path).NAME).call_file(path, function, *args, **kwargs)
+
+
+def run(script, *arguments, **options):
+    """Run a script in a process of its own, by its extension's interpreter.
+
+    ``arguments`` go on its command line as they are and keyword ``options`` as
+    ``--key value``. ``check``, ``capture``, ``cwd``, ``env`` and ``timeout``
+    are the runner's own (:func:`locutor.script.run_script`). Returns a
+    :class:`Result`.
+    """
+    return default(of_file(script).NAME).run(script, *arguments, **options)
+
+
+def available():
+    """``{language: its interpreter's path, or None}`` on this machine."""
+    return {name: default(name).find() for name in names()}
+
+
+def close():
+    """End the shared sessions. Also done when the interpreter exits."""
+    for held in list(_DEFAULT.values()):
+        held.close()
+
+
+atexit.register(close)

locutor/cli.py

@@ -0,0 +1,126 @@
+"""``locutor``: the same two calls from a shell.
+
+::
+
+    locutor languages
+    locutor run script.R 2026-11-13 --out data/raw.csv
+    locutor call stats.jl:total "[1, 2.5, 4]" --skip_missing true
+
+``run`` hands everything after the script to the script, untouched, and exits
+with its status. ``call`` reads each value as JSON where it is JSON and as text
+where it is not, and prints the answer as JSON; a NaN is ``null`` there.
+"""
+
+import argparse
+import json
+import math
+import subprocess
+import sys
+
+import numpy as np
+
+from . import __version__, available, call, close, default, names, of_file
+from .wire import Items
+
+
+def _value(text):
+    try:
+        return json.loads(text)
+    except ValueError:
+        return text
+
+
+def _plain(value):
+    """An answer as JSON can say it."""
+    if isinstance(value, Items):
+        items = [_plain(item) for item in value]
+        return dict(zip(value.names, items)) if value.names else items
+    if isinstance(value, np.ndarray):
+        return _plain(value.tolist())
+    if isinstance(value, (list, tuple)):
+        return [_plain(item) for item in value]
+    if isinstance(value, dict):
+        return {str(key): _plain(item) for key, item in value.items()}
+    if isinstance(value, (float, np.floating)):
+        return None if math.isnan(value) else float(value)
+    if isinstance(value, np.generic):
+        return value.item()
+    return value
+
+
+def _split(words):
+    """``(positional values, keyword values)`` of a call's command line."""
+    args, kwargs, at = [], {}, 0
+    while at < len(words):
+        word = words[at]
+        if word.startswith("--") and len(word) > 2:
+            key, sep, text = word[2:].partition("=")
+            if not sep:
+                at += 1
+                if at >= len(words):
+                    raise SystemExit(f"--{key} is given no value")
+                text = words[at]
+            kwargs[key] = _value(text)
+        else:
+            args.append(_value(word))
+        at += 1
+    return args, kwargs
+
+
+def _version(name, program):
+    flag = {"r": "--version", "julia": "--version", "python": "--version"}
+    try:
+        done = subprocess.run([program, flag.get(name, "--version")],
+                              capture_output=True, text=True, timeout=60)
+    except (OSError, subprocess.TimeoutExpired):
+        return ""
+    lines = (done.stdout or done.stderr).strip().splitlines()
+    return lines[0] if lines else ""
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(
+        prog="locutor", description="Call R and Julia as a function or as a "
+                                    "script.")
+    parser.add_argument("--version", action="version",
+                        version=f"locutor {__version__}")
+    commands = parser.add_subparsers(dest="command", required=True)
+    commands.add_parser("languages", help="the languages there are, and "
+                                          "which have an interpreter here")
+    running = commands.add_parser("run", help="run a script in a process of "
+                                              "its own")
+    running.add_argument("script")
+    running.add_argument("arguments", nargs=argparse.REMAINDER,
+                         help="handed to the script as they are")
+    calling = commands.add_parser("call", help="call a function of a file, "
+                                               "in memory")
+    calling.add_argument("target", help="path/file.ext:function")
+    calling.add_argument("values", nargs=argparse.REMAINDER,
+                         help="values as JSON, and --key value for keywords")
+    options = parser.parse_args(argv)
+
+    if options.command == "languages":
+        for name, program in available().items():
+            found = (f"{program}  ({_version(name, program)})" if program
+                     else f"not found: {default(name).GET}")
+            print(f"{name:8}{found}")
+        return 0
+    if options.command == "run":
+        language = default(of_file(options.script).NAME)
+        result = language.run(options.script, *options.arguments, check=False,
+                              capture=False)
+        return result.returncode
+    args, kwargs = _split(options.values)
+    try:
+        answer = call(options.target, *args, **kwargs)
+    except (RuntimeError, ValueError, FileNotFoundError, TypeError) as exc:
+        print(f"locutor: {exc}", file=sys.stderr)
+        return 1
+    finally:
+        close()
+    print(json.dumps(_plain(answer)))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

locutor/language.py

@@ -0,0 +1,233 @@
+"""A language: where its interpreter is, how it is started, and what is asked of it.
+
+One module of :mod:`locutor.languages` to a language, holding one subclass of
+:class:`Language` and found by being there (:func:`names`). The subclass says
+what the language is called, what its interpreter and its files are called, how
+a session and a script are started, and how a missing package is installed.
+Everything else -- finding the interpreter, the session, what crosses -- is the
+same for all of them.
+
+An instance is one configured interpreter: which program, which packages its
+session attaches, which file it reads at its start. It runs scripts
+(:meth:`Language.run`) and calls functions (:meth:`Language.call`,
+:meth:`Language.call_file`), the second through one persistent child started at
+the first call.
+"""
+
+import importlib
+import os
+import pkgutil
+import re
+import shutil
+
+from . import languages as _languages
+from .script import run_script
+from .session import Session
+
+#: How deep a ``search`` root is walked for an interpreter.
+SEARCH_DEPTH = 4
+
+_HERE = os.path.dirname(os.path.abspath(__file__))
+
+
+def _natural(name):
+    return [int(part) if part.isdigit() else part.lower()
+            for part in re.split(r"(\d+)", name)]
+
+
+def find_program(names, search=(), depth=SEARCH_DEPTH):
+    """Absolute path to the first of ``names`` found, or ``None``.
+
+    PATH first, then each ``search`` root walked ``depth`` levels down, the
+    highest-numbered of side-by-side installs first (``R-4.4.0`` before
+    ``R-4.3.1``), whatever order the filesystem lists them in.
+    """
+    names = [name for name in names if name]
+    for name in names:
+        found = shutil.which(name)
+        if found:
+            return found
+    wanted = {n.lower() for n in names} | {n.lower() + ".exe" for n in names}
+    for root in search:
+        root = os.path.expanduser(os.path.expandvars(str(root)))
+        if not os.path.isdir(root):
+            continue
+        base = root.rstrip("/\\").count(os.sep)
+        for dirpath, dirnames, filenames in os.walk(root):
+            if dirpath.count(os.sep) - base >= depth:
+                dirnames[:] = []
+            else:
+                dirnames.sort(key=_natural, reverse=True)
+            for name in sorted(filenames):
+                path = os.path.join(dirpath, name)
+                if name.lower() in wanted and os.access(path, os.X_OK):
+                    return path
+    return None
+
+
+class Language:
+    """One configured interpreter of one language.
+
+    ``program`` is the interpreter's name or path, found on PATH and then under
+    each ``search`` root. ``packages`` are what a session attaches when it
+    starts and ``include`` is one file it reads then, whose functions are
+    called by their bare names. ``label`` names the session in the log and in
+    errors, for a caller that holds several.
+
+    Building one starts nothing.
+    """
+
+    #: The name the language is asked for by (``locutor.language("r")``).
+    NAME = ""
+    #: What the language is called where a message names it.
+    WORD = ""
+    #: The interpreter looked for when none is named.
+    PROGRAM = ""
+    #: What a file of the language ends in, the first being the usual one.
+    EXTENSIONS = ()
+    #: The child's end of a session, a file of ``locutor/servers``.
+    SERVER = ""
+    #: Where to get the language, for the refusal that says it is not here.
+    GET = ""
+
+    def __init__(self, program=None, search=(), packages=(), include=None,
+                 label=""):
+        self.program = str(program or self.PROGRAM)
+        self.search = self._listed(search)
+        self.packages = self._listed(packages)
+        self.include = os.path.abspath(include) if include else ""
+        self.label = str(label or "")
+        self._session = None
+
+    @staticmethod
+    def _listed(value):
+        return [value] if isinstance(value, str) else [str(v) for v in value or []]
+
+    def __repr__(self):
+        return f"<{type(self).__name__} {self.program}>"
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        self.close()
+
+    # ------------------------------------------------- what a language says #
+    def command(self, program, script, *arguments):
+        """The command line that starts a session's child on ``script``."""
+        raise NotImplementedError
+
+    def script_command(self, program, script, arguments):
+        """The command line that runs a script of the user's."""
+        return [program, script, *arguments]
+
+    def install(self, package, program=None):
+        """The command that installs one package into what the child runs."""
+        raise NotImplementedError
+
+    def unready(self, program, hello):
+        """The refusal for a child that started and cannot hold a session."""
+        return (f"the {self.WORD} at {program} cannot hold a session: "
+                f"{hello.get('error') or hello}")
+
+    # --------------------------------------------------------- the program #
+    @property
+    def server(self):
+        """The file the session's child runs."""
+        return os.path.join(_HERE, "servers", self.SERVER)
+
+    def find(self):
+        """The interpreter's absolute path, or ``None``: PATH, then ``search``."""
+        if os.path.isabs(self.program) and os.access(self.program, os.X_OK):
+            return self.program
+        return find_program([self.program], self.search)
+
+    def interpreter(self):
+        """The interpreter's path, or the refusal that says where it was
+        looked for."""
+        path = self.find()
+        if path:
+            return path
+        under = (f", nor under {', '.join(self.search)}" if self.search else "")
+        raise RuntimeError(
+            f"{self.WORD} was asked for and {self.program!r} was not found: "
+            f"not on PATH{under}. Install {self.WORD} ({self.GET}) or put the "
+            f"directory that holds {self.program} on PATH.")
+
+    def uninstalled(self, program, problems, why=""):
+        """The refusal for packages the child could not attach."""
+        lines = [f"The {self.WORD} at {program} cannot load what was asked of "
+                 f"it" + (f", {why}" if why else "") + ":"]
+        for problem in problems:
+            package, message = problem.get("package"), problem.get("message")
+            if message:
+                lines.append(f"  {package} is installed and did not load: "
+                             f"{message}")
+            else:
+                lines.append(f"  {package} is not installed. Install it:")
+                lines.append(f"    {self.install(package, program)}")
+        return "\n".join(lines)
+
+    # ------------------------------------------------------------ the calls #
+    @property
+    def session(self):
+        """This interpreter's persistent child; not started by being asked for."""
+        if self._session is None:
+            self._session = Session(self)
+        return self._session
+
+    def call(self, name, *args, **kwargs):
+        """Call a function by the name the language knows it by: a package's
+        (``pkg::function``, ``Pkg.function``), or one ``include`` defines."""
+        return self.session.call(name, *args, **kwargs)
+
+    def call_file(self, path, function, *args, **kwargs):
+        """Call ``function`` of the source file ``path``.
+
+        The child reads the file once, into a namespace of its own, so two
+        files may define one name.
+        """
+        path = os.path.abspath(path)
+        if not os.path.isfile(path):
+            raise FileNotFoundError(f"no {self.WORD} file {path}")
+        return self.session.call_in(path, function, *args, **kwargs)
+
+    def run(self, script, *arguments, **options):
+        """Run a script in a process of its own; see :func:`locutor.run`."""
+        return run_script(self, script, *arguments, **options)
+
+    def close(self):
+        """End the session's child, if one was started."""
+        if self._session is not None:
+            self._session.close()
+
+
+# --------------------------------------------------------------------------- #
+# the languages there are
+# --------------------------------------------------------------------------- #
+def names():
+    """The languages there are: the modules of :mod:`locutor.languages`."""
+    return tuple(sorted(info.name for info in
+                        pkgutil.iter_modules(_languages.__path__)
+                        if not info.name.startswith("_")))
+
+
+def language(name):
+    """The :class:`Language` subclass of one language, by name."""
+    name = str(name).lower()
+    if name not in names():
+        raise ValueError(f"{name!r} is no language locutor speaks (known: "
+                         f"{', '.join(names())})")
+    return importlib.import_module(f"{_languages.__name__}.{name}").LANGUAGE
+
+
+def of_file(path):
+    """The :class:`Language` subclass a file is written in, by its extension."""
+    extension = os.path.splitext(str(path))[1].lower()
+    for name in names():
+        found = language(name)
+        if extension in {e.lower() for e in found.EXTENSIONS}:
+            return found
+    known = ", ".join(e for name in names() for e in language(name).EXTENSIONS)
+    raise ValueError(f"{path!r} is in no language locutor speaks, by its "
+                     f"extension (known: {known})")

locutor/languages/__init__.py

@@ -0,0 +1 @@
+"""One module to a language. Adding a file here adds a language."""

locutor/languages/julia.py

@@ -0,0 +1,37 @@
+"""Julia.
+
+A session's child is ``julia``, started without the startup file and with the
+environment (``JULIA_PROJECT``, ``JULIA_LOAD_PATH``, ``JULIA_NUM_THREADS``),
+since where a user's packages are is said there. It needs nothing but Julia.
+
+A function is called as ``Pkg.function`` (``Pkg.Sub.function``) where it
+belongs to a package the session imported, or by its bare name where the
+``include`` file defines it. Keyword arguments are passed as keywords. Julia
+tells a number from a vector of one, so a number sent says it is one and a
+vector of one coming back keeps its shape. ``missing`` in a float array comes
+back as NaN.
+"""
+
+from ..language import Language
+
+FLAGS = ("--startup-file=no", "--history-file=no", "--color=no")
+
+
+class Julia(Language):
+    NAME = "julia"
+    WORD = "Julia"
+    PROGRAM = "julia"
+    EXTENSIONS = (".jl",)
+    SERVER = "session.jl"
+    GET = "https://julialang.org/downloads"
+
+    def command(self, program, script, *arguments):
+        return [program, *FLAGS, script, *arguments]
+
+    def install(self, package, program=None):
+        program = program or self.find() or self.program
+        program = f'"{program}"' if " " in program else program
+        return f"{program} -e 'import Pkg; Pkg.add(\"{package}\")'"
+
+
+LANGUAGE = Julia

locutor/languages/python.py

@@ -0,0 +1,70 @@
+"""Python, which needs no translating.
+
+Here so that a caller need not ask which language a file is in: a ``.py``
+script runs with this interpreter, and a function of a ``.py`` file is imported
+and called in this process, with no child and nothing crossing. A file is
+imported once and again when it has changed on disk.
+"""
+
+import importlib
+import importlib.util
+import os
+import sys
+
+from ..language import Language
+
+
+class Python(Language):
+    NAME = "python"
+    WORD = "Python"
+    PROGRAM = sys.executable or "python"
+    EXTENSIONS = (".py",)
+    GET = "https://www.python.org"
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._modules = {}
+
+    def install(self, package, program=None):
+        return f"{program or self.program} -m pip install {package}"
+
+    def call(self, name, *args, **kwargs):
+        """Call ``module:function`` (or ``module.function``) of an importable
+        module, or a function of the ``include`` file by its bare name."""
+        module, sep, function = name.rpartition(":")
+        if not sep:
+            module, sep, function = name.rpartition(".")
+        if not sep:
+            if not self.include:
+                raise RuntimeError(f"Python has no {name} to call: no file "
+                                   f"was included to define it")
+            return self.call_file(self.include, name, *args, **kwargs)
+        for package in self.packages:
+            importlib.import_module(package)
+        return getattr(importlib.import_module(module), function)(*args, **kwargs)
+
+    def call_file(self, path, function, *args, **kwargs):
+        path = os.path.abspath(path)
+        if not os.path.isfile(path):
+            raise FileNotFoundError(f"no Python file {path}")
+        stamp = os.stat(path).st_mtime_ns
+        held = self._modules.get(path)
+        if held is None or held[0] != stamp:
+            spec = importlib.util.spec_from_file_location(
+                "locutor_file_" + os.path.splitext(os.path.basename(path))[0],
+                path)
+            module = importlib.util.module_from_spec(spec)
+            spec.loader.exec_module(module)
+            held = self._modules[path] = (stamp, module)
+        try:
+            found = getattr(held[1], function)
+        except AttributeError:
+            raise RuntimeError(f"Python has no {function} to call: "
+                               f"'{function}' is not defined by {path}") from None
+        return found(*args, **kwargs)
+
+    def close(self):
+        self._modules.clear()
+
+
+LANGUAGE = Python

locutor/languages/r.py

@@ -0,0 +1,48 @@
+"""R.
+
+A session's child is ``Rscript``, started without the profiles (code that would
+run before ours, free to print or to change an option) and with the environment
+files, since where a user's packages are installed is said there. It reads its
+requests with ``jsonlite``, which the R it runs has to have.
+
+A function is called as ``pkg::function`` where it is an exported function of a
+package the session attached, or by its bare name where the ``include`` file
+defines it. R has no scalar, so a number arrives as a vector of one, and a
+vector of one comes back as a number.
+
+``NA`` and ``NaN`` are both NaN to Python; the 64 bits of each cross unchanged.
+"""
+
+from ..language import Language
+
+FLAGS = ("--no-save", "--no-restore", "--no-site-file", "--no-init-file")
+
+
+class R(Language):
+    NAME = "r"
+    WORD = "R"
+    PROGRAM = "Rscript"
+    EXTENSIONS = (".R", ".r")
+    SERVER = "session.R"
+    GET = "https://cran.r-project.org"
+
+    def command(self, program, script, *arguments):
+        # Sourced rather than run as the file, so the same line works for any
+        # path the script may have.
+        return [program, *FLAGS, "-e", "source(commandArgs(TRUE)[1])", script,
+                *arguments]
+
+    def install(self, package, program=None):
+        program = program or self.find() or self.program
+        program = f'"{program}"' if " " in program else program
+        return f"{program} -e \"install.packages('{package}')\""
+
+    def unready(self, program, hello):
+        if hello.get("needs"):
+            return self.uninstalled(
+                program, [{"package": hello["needs"], "message": ""}],
+                why="which is what the session reads its requests with")
+        return super().unready(program, hello)
+
+
+LANGUAGE = R