pyluatex (14jul21)

git-svn-id: svn://tug.org/texlive/trunk@59928 c570f23f-e606-0410-a88d-b1316a301751

6 files changed, 820 insertions, 0 deletions

diff --git a/Master/texmf-dist/doc/lualatex/pyluatex/README.md b/Master/texmf-dist/doc/lualatex/pyluatex/README.md
new file mode 100644
index 00000000000..f9e727fabfd
--- /dev/null
+++ b/Master/texmf-dist/doc/lualatex/pyluatex/README.md
@@ -0,0 +1,56 @@
+# PyLuaTeX
+**Execute Python code on the fly in your LaTeX documents**
+
+PyLuaTeX allows you to execute Python code and to include the resulting output in your LaTeX documents in a *single compilation run*.
+LaTeX documents must be compiled with LuaLaTeX for this to work.
+
+
+## Example
+1\. LaTeX document `example.tex`
+```latex
+\documentclass{article}
+
+\usepackage{pyluatex}
+
+\begin{python}
+import math
+import random
+
+random.seed(0)
+
+greeting = 'Hello PyLuaTeX!'
+\end{python}
+
+\newcommand{\randint}[2]{\py{random.randint(#1, #2)}}
+
+\begin{document}
+\py{greeting}
+
+$\sqrt{371} = \py{math.sqrt(371)}$
+
+\randint{2}{5}
+\end{document}
+```
+2\. Compile using LuaLaTeX (shell escape is required)
+```
+lualatex -shell-escape example.tex
+```
+
+**Note:** Running LaTeX with the shell escape option enabled allows arbitrary code to be
+executed. For this reason, it is recommended to compile trusted documents only.
+
+## Requirements
+* LuaLaTeX
+* Python 3
+* Linux, macOS or Windows
+
+Our automated tests currently use TeX Live 2021 and Python 3.7+ on
+Ubuntu 20.04, macOS Catalina 10.15 and Windows Server 2019.
+
+## License
+[LPPL 1.3c](http://www.latex-project.org/lppl.txt) for LaTeX code and
+[MIT license](https://opensource.org/licenses/MIT) for Python and Lua code.
+
+We use the great [json.lua](https://github.com/rxi/json.lua) library under the terms
+of the [MIT license](https://opensource.org/licenses/MIT).
+
diff --git a/Master/texmf-dist/doc/lualatex/pyluatex/pyluatex-interpreter.py b/Master/texmf-dist/doc/lualatex/pyluatex/pyluatex-interpreter.py
new file mode 100644
index 00000000000..4a17b5f5b0f
--- /dev/null
+++ b/Master/texmf-dist/doc/lualatex/pyluatex/pyluatex-interpreter.py
@@ -0,0 +1,71 @@
+"""
+MIT License
+
+Copyright (c) 2021 Tobias Enderle
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included
+in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.
+"""
+
+from code import InteractiveInterpreter, compile_command
+import traceback
+from io import StringIO
+from contextlib import redirect_stdout, redirect_stderr
+import socketserver
+import json
+import textwrap
+from collections import defaultdict
+
+class Interpreter(InteractiveInterpreter):
+    def execute(self, code):
+        with StringIO() as out, redirect_stdout(out), redirect_stderr(out):
+            self.success = True
+            try:
+                code_obj = compile_command(code, symbol='exec')
+                if code_obj is None:
+                    print('Incomplete Python code:\n' + code)
+                    self.success = False
+                else:
+                    self.runcode(code_obj)
+            except:
+                traceback.print_exc()
+                self.success = False
+            return self.success, out.getvalue()
+
+    def showtraceback(self):
+        super().showtraceback()
+        self.success = False
+
+class Handler(socketserver.StreamRequestHandler):
+    def handle(self):
+        interpreters = defaultdict(Interpreter)
+        while True:
+            data = self.rfile.readline().decode('utf-8')
+            if len(data) == 0:
+                return
+
+            data = json.loads(data)
+            interpreter = interpreters[data['session']]
+            success, output = interpreter.execute(textwrap.dedent(data['code']))
+            response = { 'success': success, 'output': output }
+            self.wfile.write((json.dumps(response) + '\n').encode('utf-8'))
+
+if __name__ == '__main__':
+    with socketserver.TCPServer(('localhost', 0), Handler) as server:
+        print(server.server_address[1], end='\n', flush=True)  # publish port
+        server.handle_request()
diff --git a/Master/texmf-dist/doc/lualatex/pyluatex/pyluatex-json.lua b/Master/texmf-dist/doc/lualatex/pyluatex/pyluatex-json.lua
new file mode 100644
index 00000000000..711ef786196
--- /dev/null
+++ b/Master/texmf-dist/doc/lualatex/pyluatex/pyluatex-json.lua
@@ -0,0 +1,388 @@
+--
+-- json.lua
+--
+-- Copyright (c) 2020 rxi
+--
+-- Permission is hereby granted, free of charge, to any person obtaining a copy of
+-- this software and associated documentation files (the "Software"), to deal in
+-- the Software without restriction, including without limitation the rights to
+-- use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+-- of the Software, and to permit persons to whom the Software is furnished to do
+-- so, subject to the following conditions:
+--
+-- The above copyright notice and this permission notice shall be included in all
+-- copies or substantial portions of the Software.
+--
+-- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+-- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+-- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+-- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+-- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+-- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+-- SOFTWARE.
+--
+
+local json = { _version = "0.1.2" }
+
+-------------------------------------------------------------------------------
+-- Encode
+-------------------------------------------------------------------------------
+
+local encode
+
+local escape_char_map = {
+  [ "\\" ] = "\\",
+  [ "\"" ] = "\"",
+  [ "\b" ] = "b",
+  [ "\f" ] = "f",
+  [ "\n" ] = "n",
+  [ "\r" ] = "r",
+  [ "\t" ] = "t",
+}
+
+local escape_char_map_inv = { [ "/" ] = "/" }
+for k, v in pairs(escape_char_map) do
+  escape_char_map_inv[v] = k
+end
+
+
+local function escape_char(c)
+  return "\\" .. (escape_char_map[c] or string.format("u%04x", c:byte()))
+end
+
+
+local function encode_nil(val)
+  return "null"
+end
+
+
+local function encode_table(val, stack)
+  local res = {}
+  stack = stack or {}
+
+  -- Circular reference?
+  if stack[val] then error("circular reference") end
+
+  stack[val] = true
+
+  if rawget(val, 1) ~= nil or next(val) == nil then
+    -- Treat as array -- check keys are valid and it is not sparse
+    local n = 0
+    for k in pairs(val) do
+      if type(k) ~= "number" then
+        error("invalid table: mixed or invalid key types")
+      end
+      n = n + 1
+    end
+    if n ~= #val then
+      error("invalid table: sparse array")
+    end
+    -- Encode
+    for i, v in ipairs(val) do
+      table.insert(res, encode(v, stack))
+    end
+    stack[val] = nil
+    return "[" .. table.concat(res, ",") .. "]"
+
+  else
+    -- Treat as an object
+    for k, v in pairs(val) do
+      if type(k) ~= "string" then
+        error("invalid table: mixed or invalid key types")
+      end
+      table.insert(res, encode(k, stack) .. ":" .. encode(v, stack))
+    end
+    stack[val] = nil
+    return "{" .. table.concat(res, ",") .. "}"
+  end
+end
+
+
+local function encode_string(val)
+  return '"' .. val:gsub('[%z\1-\31\\"]', escape_char) .. '"'
+end
+
+
+local function encode_number(val)
+  -- Check for NaN, -inf and inf
+  if val ~= val or val <= -math.huge or val >= math.huge then
+    error("unexpected number value '" .. tostring(val) .. "'")
+  end
+  return string.format("%.14g", val)
+end
+
+
+local type_func_map = {
+  [ "nil"     ] = encode_nil,
+  [ "table"   ] = encode_table,
+  [ "string"  ] = encode_string,
+  [ "number"  ] = encode_number,
+  [ "boolean" ] = tostring,
+}
+
+
+encode = function(val, stack)
+  local t = type(val)
+  local f = type_func_map[t]
+  if f then
+    return f(val, stack)
+  end
+  error("unexpected type '" .. t .. "'")
+end
+
+
+function json.encode(val)
+  return ( encode(val) )
+end
+
+
+-------------------------------------------------------------------------------
+-- Decode
+-------------------------------------------------------------------------------
+
+local parse
+
+local function create_set(...)
+  local res = {}
+  for i = 1, select("#", ...) do
+    res[ select(i, ...) ] = true
+  end
+  return res
+end
+
+local space_chars   = create_set(" ", "\t", "\r", "\n")
+local delim_chars   = create_set(" ", "\t", "\r", "\n", "]", "}", ",")
+local escape_chars  = create_set("\\", "/", '"', "b", "f", "n", "r", "t", "u")
+local literals      = create_set("true", "false", "null")
+
+local literal_map = {
+  [ "true"  ] = true,
+  [ "false" ] = false,
+  [ "null"  ] = nil,
+}
+
+
+local function next_char(str, idx, set, negate)
+  for i = idx, #str do
+    if set[str:sub(i, i)] ~= negate then
+      return i
+    end
+  end
+  return #str + 1
+end
+
+
+local function decode_error(str, idx, msg)
+  local line_count = 1
+  local col_count = 1
+  for i = 1, idx - 1 do
+    col_count = col_count + 1
+    if str:sub(i, i) == "\n" then
+      line_count = line_count + 1
+      col_count = 1
+    end
+  end
+  error( string.format("%s at line %d col %d", msg, line_count, col_count) )
+end
+
+
+local function codepoint_to_utf8(n)
+  -- http://scripts.sil.org/cms/scripts/page.php?site_id=nrsi&id=iws-appendixa
+  local f = math.floor
+  if n <= 0x7f then
+    return string.char(n)
+  elseif n <= 0x7ff then
+    return string.char(f(n / 64) + 192, n % 64 + 128)
+  elseif n <= 0xffff then
+    return string.char(f(n / 4096) + 224, f(n % 4096 / 64) + 128, n % 64 + 128)
+  elseif n <= 0x10ffff then
+    return string.char(f(n / 262144) + 240, f(n % 262144 / 4096) + 128,
+                       f(n % 4096 / 64) + 128, n % 64 + 128)
+  end
+  error( string.format("invalid unicode codepoint '%x'", n) )
+end
+
+
+local function parse_unicode_escape(s)
+  local n1 = tonumber( s:sub(1, 4),  16 )
+  local n2 = tonumber( s:sub(7, 10), 16 )
+   -- Surrogate pair?
+  if n2 then
+    return codepoint_to_utf8((n1 - 0xd800) * 0x400 + (n2 - 0xdc00) + 0x10000)
+  else
+    return codepoint_to_utf8(n1)
+  end
+end
+
+
+local function parse_string(str, i)
+  local res = ""
+  local j = i + 1
+  local k = j
+
+  while j <= #str do
+    local x = str:byte(j)
+
+    if x < 32 then
+      decode_error(str, j, "control character in string")
+
+    elseif x == 92 then -- `\`: Escape
+      res = res .. str:sub(k, j - 1)
+      j = j + 1
+      local c = str:sub(j, j)
+      if c == "u" then
+        local hex = str:match("^[dD][89aAbB]%x%x\\u%x%x%x%x", j + 1)
+                 or str:match("^%x%x%x%x", j + 1)
+                 or decode_error(str, j - 1, "invalid unicode escape in string")
+        res = res .. parse_unicode_escape(hex)
+        j = j + #hex
+      else
+        if not escape_chars[c] then
+          decode_error(str, j - 1, "invalid escape char '" .. c .. "' in string")
+        end
+        res = res .. escape_char_map_inv[c]
+      end
+      k = j + 1
+
+    elseif x == 34 then -- `"`: End of string
+      res = res .. str:sub(k, j - 1)
+      return res, j + 1
+    end
+
+    j = j + 1
+  end
+
+  decode_error(str, i, "expected closing quote for string")
+end
+
+
+local function parse_number(str, i)
+  local x = next_char(str, i, delim_chars)
+  local s = str:sub(i, x - 1)
+  local n = tonumber(s)
+  if not n then
+    decode_error(str, i, "invalid number '" .. s .. "'")
+  end
+  return n, x
+end
+
+
+local function parse_literal(str, i)
+  local x = next_char(str, i, delim_chars)
+  local word = str:sub(i, x - 1)
+  if not literals[word] then
+    decode_error(str, i, "invalid literal '" .. word .. "'")
+  end
+  return literal_map[word], x
+end
+
+
+local function parse_array(str, i)
+  local res = {}
+  local n = 1
+  i = i + 1
+  while 1 do
+    local x
+    i = next_char(str, i, space_chars, true)
+    -- Empty / end of array?
+    if str:sub(i, i) == "]" then
+      i = i + 1
+      break
+    end
+    -- Read token
+    x, i = parse(str, i)
+    res[n] = x
+    n = n + 1
+    -- Next token
+    i = next_char(str, i, space_chars, true)
+    local chr = str:sub(i, i)
+    i = i + 1
+    if chr == "]" then break end
+    if chr ~= "," then decode_error(str, i, "expected ']' or ','") end
+  end
+  return res, i
+end
+
+
+local function parse_object(str, i)
+  local res = {}
+  i = i + 1
+  while 1 do
+    local key, val
+    i = next_char(str, i, space_chars, true)
+    -- Empty / end of object?
+    if str:sub(i, i) == "}" then
+      i = i + 1
+      break
+    end
+    -- Read key
+    if str:sub(i, i) ~= '"' then
+      decode_error(str, i, "expected string for key")
+    end
+    key, i = parse(str, i)
+    -- Read ':' delimiter
+    i = next_char(str, i, space_chars, true)
+    if str:sub(i, i) ~= ":" then
+      decode_error(str, i, "expected ':' after key")
+    end
+    i = next_char(str, i + 1, space_chars, true)
+    -- Read value
+    val, i = parse(str, i)
+    -- Set
+    res[key] = val
+    -- Next token
+    i = next_char(str, i, space_chars, true)
+    local chr = str:sub(i, i)
+    i = i + 1
+    if chr == "}" then break end
+    if chr ~= "," then decode_error(str, i, "expected '}' or ','") end
+  end
+  return res, i
+end
+
+
+local char_func_map = {
+  [ '"' ] = parse_string,
+  [ "0" ] = parse_number,
+  [ "1" ] = parse_number,
+  [ "2" ] = parse_number,
+  [ "3" ] = parse_number,
+  [ "4" ] = parse_number,
+  [ "5" ] = parse_number,
+  [ "6" ] = parse_number,
+  [ "7" ] = parse_number,
+  [ "8" ] = parse_number,
+  [ "9" ] = parse_number,
+  [ "-" ] = parse_number,
+  [ "t" ] = parse_literal,
+  [ "f" ] = parse_literal,
+  [ "n" ] = parse_literal,
+  [ "[" ] = parse_array,
+  [ "{" ] = parse_object,
+}
+
+
+parse = function(str, idx)
+  local chr = str:sub(idx, idx)
+  local f = char_func_map[chr]
+  if f then
+    return f(str, idx)
+  end
+  decode_error(str, idx, "unexpected character '" .. chr .. "'")
+end
+
+
+function json.decode(str)
+  if type(str) ~= "string" then
+    error("expected argument of type string, got " .. type(str))
+  end
+  local res, idx = parse(str, next_char(str, 1, space_chars, true))
+  idx = next_char(str, idx, space_chars, true)
+  if idx <= #str then
+    decode_error(str, idx, "trailing garbage")
+  end
+  return res
+end
+
+
+return json
diff --git a/Master/texmf-dist/doc/lualatex/pyluatex/pyluatex.lua b/Master/texmf-dist/doc/lualatex/pyluatex/pyluatex.lua
new file mode 100644
index 00000000000..07d8ea49d3f
--- /dev/null
+++ b/Master/texmf-dist/doc/lualatex/pyluatex/pyluatex.lua
@@ -0,0 +1,137 @@
+--[[
+MIT License
+
+Copyright (c) 2021 Tobias Enderle
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included
+in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.
+--]]
+
+local json = require("pyluatex-json")
+local socket = require("socket")
+
+pyluatex = pyluatex or {
+    verbose = false,
+    session = "default"
+}
+
+-- status.filename: path to pyluatex.sty
+local folder = file.pathpart(file.collapsepath(status.filename, true))
+local script = file.join(folder, "pyluatex-interpreter.py")
+local tcp = nil
+
+local python_lines = {}
+
+local env_end = "\\end{python}"
+
+local function err_cmd(message)
+    return "\\PackageError{PyLuaTeX}{" .. message .. "}{}"
+end
+
+function pyluatex.start(executable)
+    local is_windows = package.config:sub(1,1) ~= "/"
+    local cmd
+    if is_windows then
+        cmd = "start /B " .. executable .. " \"" .. script .. "\""
+    else
+        cmd = executable .. " \"" .. script .. "\" &"
+    end
+    local f = io.popen(cmd, "r")
+    local port = f:read("*l"):gsub("\r", ""):gsub("\n", "")
+    f:close()
+
+    if port then
+        tcp = socket.tcp()
+        tcp:connect("127.0.0.1", port)
+    else
+        tex.sprint(err_cmd("Python backend (executable: " .. executable ..
+                           ") could not be started"))
+    end
+end
+
+local function request(data)
+    tcp:send(json.encode(data) .. "\n")
+    local output = tcp:receive("*l")
+    local response = json.decode(output)
+    return response.success, response.output
+end
+
+local function print_input(code)
+    texio.write_nl("PyLuaTeX input for session \"" .. pyluatex.session .. "\": " .. code)
+end
+
+local function print_output(code)
+    texio.write_nl("PyLuaTeX output: " .. code)
+end
+
+function pyluatex.execute(code, write)
+    if pyluatex.verbose then print_input(code) end
+
+    local success, output = request({ session = pyluatex.session, code = code })
+    if success then
+        if pyluatex.verbose then print_output(output) end
+        if write then
+            tex.sprint(output)
+        else
+            return output
+        end
+    else
+        if not pyluatex.verbose then print_input(code) end
+        print_output(output)
+        if write then
+            tex.sprint(err_cmd("Python error (see above)"))
+        end
+    end
+    return nil
+end
+
+local function record_line(line)
+    local s, e = line:find(env_end)
+    if s ~= nil then
+        luatexbase.remove_from_callback("process_input_buffer", "pyluatex_record_line")
+        table.insert(python_lines, line:sub(1, s - 1))
+        local code = table.concat(python_lines, "\n")
+        local output = pyluatex.execute(code, false)
+        if output ~= nil then
+            return output .. line:sub(s)
+        else
+            return env_end .. err_cmd("Python error (see above)") .. line:sub(e + 1)
+        end
+    else
+        table.insert(python_lines, line)
+        return ""
+    end
+end
+
+function pyluatex.record_env()
+    python_lines = {}
+    luatexbase.add_to_callback("process_input_buffer", record_line, "pyluatex_record_line")
+end
+
+function pyluatex.run_file(path)
+    local f = io.open(path, "r")
+    if f then
+        local code = f:read("*a")
+        f:close()
+        pyluatex.execute(code, true)
+    else
+        tex.sprint(err_cmd("File not found: " .. path))
+    end
+end
+
+return pyluatex
diff --git a/Master/texmf-dist/doc/lualatex/pyluatex/pyluatex.pdf b/Master/texmf-dist/doc/lualatex/pyluatex/pyluatex.pdf
new file mode 100644
index 00000000000..2ff342d0f82
--- /dev/null
+++ b/Master/texmf-dist/doc/lualatex/pyluatex/pyluatex.pdf
diff --git a/Master/texmf-dist/doc/lualatex/pyluatex/pyluatex.tex b/Master/texmf-dist/doc/lualatex/pyluatex/pyluatex.tex
new file mode 100644
index 00000000000..a6a66fbde27
--- /dev/null
+++ b/Master/texmf-dist/doc/lualatex/pyluatex/pyluatex.tex
@@ -0,0 +1,168 @@
+\documentclass{article}
+\usepackage{helvet}
+\usepackage{courier}
+\renewcommand{\familydefault}{\sfdefault}
+\usepackage[margin=2.5cm]{geometry}
+\usepackage{parskip}
+\linespread{1.2}
+\usepackage{tabularx}
+\usepackage{xcolor}
+\usepackage[listings,breakable,xparse]{tcolorbox}
+\tcbset{breakable,listing only,size=fbox,colframe=black!10,boxrule=3pt,colback=black!10}
+\NewTotalTCBox{\inlcode}{ v }{
+    on line,boxsep=0pt,left=0.5ex,right=0.5ex,top=0pt,bottom=0pt,
+    boxrule=0pt}{\lstinline[style=tcblatex]|#1|\rule[-.3\baselineskip]{0pt}{0.9\baselineskip}}
+\usepackage{url}
+\title{The \emph{pyluatex} package}
+\author{Tobias Enderle\\\url{https://github.com/tndrle/PyLuaTeX}}
+\date{v0.1.2 (2021/07/14)}
+\begin{document}
+\maketitle
+\raggedright
+
+\textbf{Execute Python code on the fly in your \LaTeX{} documents}
+
+PyLuaTeX allows you to execute Python code and to include the resulting output in your \LaTeX{} documents in a \textit{single compilation run}.
+\LaTeX{} documents must be compiled with Lua\LaTeX{} for this to work.
+
+
+\section{Example}
+\begin{enumerate}
+\item  \LaTeX{} document \inlcode|example.tex|
+\begin{tcblisting}{breakable,listing only,
+    size=fbox,colframe=black!8,boxrule=3pt,colback=black!8}
+\documentclass{article}
+
+\usepackage{pyluatex}
+
+\begin{python}
+import math
+import random
+
+random.seed(0)
+
+greeting = 'Hello PyLuaTeX!'
+\end{python}
+
+\newcommand{\randint}[2]{\py{random.randint(#1, #2)}}
+
+\begin{document}
+\py{greeting}
+
+$\sqrt{371} = \py{math.sqrt(371)}$
+
+\randint{2}{5}
+\end{document}
+\end{tcblisting}
+\item  Compile using Lua\LaTeX{} (shell escape is required)
+\begin{tcblisting}{breakable,listing only,
+    size=fbox,colframe=black!8,boxrule=3pt,colback=black!8}
+lualatex -shell-escape example.tex
+\end{tcblisting}
+\end{enumerate}
+\textbf{Note:} Running \LaTeX{} with the shell escape option enabled allows arbitrary code to be
+executed. For this reason, it is recommended to compile trusted documents only.
+
+\subsection{Further Examples}
+The folder \inlcode|example| contains additional example documents:
+\begin{itemize}
+\item \inlcode|readme-example.tex|\\[0.5ex]
+  The example above
+\item \inlcode|sessions.tex|\\[0.5ex]
+  Demonstrates the use of different Python sessions in a document
+\item \inlcode|data-visualization.tex|\\[0.5ex]
+  Demonstrates the visualization of data using \textit{pgfplots} and \textit{pandas}
+\end{itemize}
+For more intricate use cases have a look at our tests in the folder \inlcode|test|.
+
+\section{Installation}
+PyLuaTeX is not yet available through package managers or CTAN\footnote{\url{https://ctan.org}}.
+
+To install PyLuaTeX, do the following steps:
+\begin{enumerate}
+\item  Locate your local \textit{TEXMF} folder\\[0.5ex]
+The location of this folder may vary. Typical defaults for TeX Live are \inlcode|~/texmf| for Linux,
+\inlcode|~/Library/texmf| for macOS, and \inlcode|C:\Users\<user name>\texmf| for Windows.
+If you are lucky, the command \inlcode|kpsewhich -var-value=TEXMFHOME| tells you the location.
+For MiKTeX, the folder can be found and configured in the \textit{MiKTeX Console}.
+\item  Download the latest release\footnote{\url{https://github.com/tndrle/PyLuaTeX/releases/latest}} of PyLuaTeX
+\item  Put the downloaded files in the folder \inlcode|TEXMF/tex/latex/pyluatex| (where \inlcode|TEXMF| is the folder located in 1.)\\[0.5ex]
+The final folder structure must be
+\begin{tcblisting}{breakable,listing only,
+    size=fbox,colframe=black!8,boxrule=3pt,colback=black!8}
+TEXMF/tex/latex/pyluatex/
+|-- pyluatex-interpreter.py
+|-- pyluatex-json.lua
+|-- pyluatex.lua
+|-- pyluatex.sty
+|-- ...
+\end{tcblisting}
+\end{enumerate}
+\section{Reference}
+PyLuaTeX offers a simple set of options, macros and environments.
+
+\subsection{Package Options}
+\begin{itemize}
+\item \inlcode|verbose|\\[0.5ex]
+  If this option is enabled, Python input and output is written to the log file.\\[0.5ex]
+  \textit{Example:} \inlcode|\usepackage[verbose]{pyluatex}|
+\item \inlcode|executable|\\[0.5ex]
+  Specifies the path to the Python executable. (default: \inlcode|python3|)\\[0.5ex]
+  \textit{Example:} \inlcode|\usepackage[executable=/usr/local/bin/python3]{pyluatex}|
+\end{itemize}
+\subsection{Macros}
+\begin{itemize}
+\item \inlcode|\py{code}|\\[0.5ex]
+  Executes \inlcode|code| and writes the output to the document.\\[0.5ex]
+  \textit{Example:} \inlcode|\py{3 + 7}|
+\item \inlcode|\pyc{code}|\\[0.5ex]
+  Executes \inlcode|code|\\[0.5ex]
+  \textit{Example:} \inlcode|\pyc{x = 5}|
+\item \inlcode|\pyfile{path}|\\[0.5ex]
+  Executes the Python file specified by \inlcode|path|.\\[0.5ex]
+  \textit{Example:} \inlcode|\pyfile{main.py}|
+\item \inlcode|\pysession{session}|\\[0.5ex]
+  Selects \inlcode|session| as Python session for subsequent Python code.\\[0.5ex]
+  The session that is active at the beginning is \inlcode|default|.\\[0.5ex]
+  \textit{Example:} \inlcode|\pysession{main}|
+\end{itemize}
+\subsection{Environments}
+\begin{itemize}
+\item \inlcode|python|\\[0.5ex]
+  Executes the provided block of Python code.\\[0.5ex]
+  The environment handles characters like \inlcode|_|, \inlcode|#|, \inlcode|%|, \inlcode|\|, etc.\\[0.5ex]
+  Code on the same line as \inlcode|\begin{python}| is ignored, i.e., code must start on the next line.\\[0.5ex]
+  If leading spaces are present they are gobbled automatically up to the first level of indentation.\\[0.5ex]
+  \textit{Example:}
+  \begin{tcblisting}{breakable,listing only,
+    size=fbox,colframe=black!8,boxrule=3pt,colback=black!8}
+\begin{python}
+    x = 'Hello PyLuaTeX'
+    print(x)
+\end{python}
+\end{tcblisting}
+\end{itemize}
+\section{Requirements}
+\begin{itemize}
+\item Lua\LaTeX{}
+\item Python 3
+\item Linux, macOS or Windows
+\end{itemize}
+Our automated tests currently use TeX Live 2021 and Python 3.7+ on
+Ubuntu 20.04, macOS Catalina 10.15 and Windows Server 2019.
+
+\section{How It Works}
+PyLuaTeX runs a Python \inlcode|InteractiveInterpreter|\footnote{\url{https://docs.python.org/3/library/code.html#code.InteractiveInterpreter}} (actually several if you use different sessions) in the background for on the fly code execution.
+Python code from your \LaTeX{} file is sent to the background interpreter through a TCP socket.
+This approach allows your Python code to be executed and the output to be integrated in your \LaTeX{} file in a single compilation run.
+No additional processing steps are needed.
+No intermediate files have to be written.
+No placeholders have to be inserted.
+
+\section{License}
+LPPL 1.3c\footnote{\url{http://www.latex-project.org/lppl.txt}} for \LaTeX{} code and
+MIT license\footnote{\url{https://opensource.org/licenses/MIT}} for Python and Lua code.
+
+We use the great json.lua\footnote{\url{https://github.com/rxi/json.lua}} library under the terms
+of the MIT license\footnote{\url{https://opensource.org/licenses/MIT}}.
+\end{document}