Package org.microproxy.starlark.stdlib

Class Stdlib

java.lang.Object
org.microproxy.starlark.stdlib.Stdlib
public final class Stdlib extends Object
The Python-compatible standard library ported from starlarky, for load() in scripts: load("@stdlib//urllib/parse", "parse"), load("@vendor//option/result", "Ok").

A label names a .star file under org/microproxy/starlark/<namespace>/ on the class path (@stdlib//io may also be io/__init__.star), or for @stdlib one of the native (Java) modules the files are built on, such as @stdlib//jzlib. Inside the library, a label without a namespace (load("types", ...)) means @stdlib.

Each module is compiled and run once per process, in its own thread under MODULE_LIMITS, with starlarky's predeclared environment (ENVIRONMENT: Python's bytes, iter, type, object, ... and Larky's _struct helpers). Its globals are then frozen, and the frozen module is shared by every script that loads it (and by every connection running those scripts): functions from it run in the calling script's thread, within its step and time limits, and so does the code of values the module made (Larky structs' dunder methods and properties run in StarlarkThread.current(), not in the thread that loaded the module). Loading the same label again returns the same module; a cycle of loads, a missing module, or a module that fails while loading is an error naming the chain of loads (a failed module is not cached, so the next load reports it again).

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final record 
    Stdlib.Limits
    Bounds on running a module's top-level statements.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final com.google.common.collect.ImmutableMap<String,Object>
    ENVIRONMENT
    The predeclared environment of library modules (and of starlarky's tests): Larky's globals (_struct, _mutablestruct, _partial, ...), Python builtins that replace Starlark's (bytes, int, iter, next, getattr, ...), and the class model (object, type, super, classmethod, staticmethod).
    static final Stdlib.Limits
    MODULE_LIMITS
    Bounds on running one module's top level (each module separately).

  • Method Summary

    Modifier and Type
    Method
    Description
    static Map<String,org.microproxy.thirdparty.starlark.eval.Module>
    loadAll(List<String> labels)
    Loads the modules a script's load statements name, by label (in order); see Stdlib.Loader.loadAll(java.util.List<java.lang.String>).
    static org.microproxy.thirdparty.starlark.eval.StarlarkSemantics
    withPythonStrings(org.microproxy.thirdparty.starlark.eval.StarlarkSemantics semantics)
    Python's string behaviour, which the library's code relies on: str % args with printf flags and widths, Unicode-aware case mapping and classification, Python's bounds for find/count/..., and CPython's codec names and error handlers for bytes.decode.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • MODULE_LIMITS

      public static final Stdlib.Limits MODULE_LIMITS
      Bounds on running one module's top level (each module separately).

    • ENVIRONMENT

      public static final com.google.common.collect.ImmutableMap<String,Object> ENVIRONMENT
      The predeclared environment of library modules (and of starlarky's tests): Larky's globals (_struct, _mutablestruct, _partial, ...), Python builtins that replace Starlark's (bytes, int, iter, next, getattr, ...), and the class model (object, type, super, classmethod, staticmethod). Scripts do not see these; they load what they need.

  • Method Details

    • withPythonStrings

      public static org.microproxy.thirdparty.starlark.eval.StarlarkSemantics withPythonStrings(org.microproxy.thirdparty.starlark.eval.StarlarkSemantics semantics)
      Python's string behaviour, which the library's code relies on: str % args with printf flags and widths, Unicode-aware case mapping and classification, Python's bounds for find/count/..., and CPython's codec names and error handlers for bytes.decode. Applied to the modules and to every script that loads one.
      Parameters:
      semantics - the base interpreter settings
      Returns:
      settings with the library's Python compatibility options applied

    • loadAll

      public static Map<String,org.microproxy.thirdparty.starlark.eval.Module> loadAll(List<String> labels) throws org.microproxy.thirdparty.starlark.eval.EvalException
      Loads the modules a script's load statements name, by label (in order); see Stdlib.Loader.loadAll(java.util.List<java.lang.String>).
      Parameters:
      labels - the standard-library or vendor module labels to load
      Returns:
      modules indexed by their labels as supplied
      Throws:
      org.microproxy.thirdparty.starlark.eval.EvalException - if a label is invalid or a module cannot be loaded or initialized