summaryrefslogtreecommitdiff
path: root/macros/luatex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2021-07-13 03:00:55 +0000
committerNorbert Preining <norbert@preining.info>2021-07-13 03:00:55 +0000
commit4ac920a9909dd7d233ed3662bb576e1ae4ade873 (patch)
tree946aeeae5a3e59d9ec5aec51ee0520dbc712af55 /macros/luatex
parent1caaed73030c69f9f96c5138594089e2689e768b (diff)
CTAN sync 202107130300
Diffstat (limited to 'macros/luatex')
-rw-r--r--macros/luatex/latex/pyluatex/README.md56
-rw-r--r--macros/luatex/latex/pyluatex/interpreter.py71
-rw-r--r--macros/luatex/latex/pyluatex/json.lua388
-rw-r--r--macros/luatex/latex/pyluatex/pyluatex.lua137
-rw-r--r--macros/luatex/latex/pyluatex/pyluatex.pdfbin0 -> 64341 bytes
-rw-r--r--macros/luatex/latex/pyluatex/pyluatex.sty45
-rw-r--r--macros/luatex/latex/pyluatex/pyluatex.tex168
7 files changed, 865 insertions, 0 deletions
diff --git a/macros/luatex/latex/pyluatex/README.md b/macros/luatex/latex/pyluatex/README.md
new file mode 100644
index 0000000000..f9e727fabf
--- /dev/null
+++ b/macros/luatex/latex/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/macros/luatex/latex/pyluatex/interpreter.py b/macros/luatex/latex/pyluatex/interpreter.py
new file mode 100644
index 0000000000..4a17b5f5b0
--- /dev/null
+++ b/macros/luatex/latex/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/macros/luatex/latex/pyluatex/json.lua b/macros/luatex/latex/pyluatex/json.lua
new file mode 100644
index 0000000000..711ef78619
--- /dev/null
+++ b/macros/luatex/latex/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/macros/luatex/latex/pyluatex/pyluatex.lua b/macros/luatex/latex/pyluatex/pyluatex.lua
new file mode 100644
index 0000000000..01a06f548e
--- /dev/null
+++ b/macros/luatex/latex/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("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, "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/macros/luatex/latex/pyluatex/pyluatex.pdf b/macros/luatex/latex/pyluatex/pyluatex.pdf
new file mode 100644
index 0000000000..bfb1a27576
--- /dev/null
+++ b/macros/luatex/latex/pyluatex/pyluatex.pdf
Binary files differ
diff --git a/macros/luatex/latex/pyluatex/pyluatex.sty b/macros/luatex/latex/pyluatex/pyluatex.sty
new file mode 100644
index 0000000000..b5c8298bca
--- /dev/null
+++ b/macros/luatex/latex/pyluatex/pyluatex.sty
@@ -0,0 +1,45 @@
+%% Copyright 2021 Tobias Enderle
+%%
+%% This work may be distributed and/or modified under the
+%% conditions of the LaTeX Project Public License, either version 1.3
+%% of this license or (at your option) any later version.
+%% The latest version of this license is in
+%% http://www.latex-project.org/lppl.txt
+%% and version 1.3 or later is part of all distributions of LaTeX
+%% version 2005/12/01 or later.
+
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesPackage{pyluatex}[2021/07/12 v0.1.1 Execute Python code on the fly]
+
+\RequirePackage{expl3}
+\ExplSyntaxOn
+\sys_if_engine_luatex:TF{}{%
+\PackageError{PyLuaTeX}{LuaTeX~is~required}{}%
+}
+\sys_if_shell_unrestricted:TF{}{%
+\PackageError{PyLuaTeX}{Shell~escape~required~(add~-shell-escape~option)}{}%
+}
+\ExplSyntaxOff
+
+\directlua{require("pyluatex")}
+
+\RequirePackage{kvoptions}
+\DeclareStringOption[python3]{executable}
+\DeclareVoidOption{verbose}{\directlua{pyluatex.verbose = true}}
+\ProcessKeyvalOptions*
+
+\directlua{pyluatex.start([==[\pyluatex@executable]==])}
+
+\newenvironment{python}{\directlua{pyluatex.record_env()}}{}
+
+\newcommand*{\py}[1]{%
+\directlua{pyluatex.execute([==[print(str(#1), end='')]==], true)}%
+}
+
+\newcommand*{\pyc}[1]{\directlua{pyluatex.execute([==[#1]==], true)}}
+
+\newcommand*{\pysession}[1]{\directlua{pyluatex.session = [==[#1]==]}}
+
+\newcommand*{\pyfile}[1]{\directlua{pyluatex.run_file([==[#1]==])}}
+
+\endinput
diff --git a/macros/luatex/latex/pyluatex/pyluatex.tex b/macros/luatex/latex/pyluatex/pyluatex.tex
new file mode 100644
index 0000000000..4552698539
--- /dev/null
+++ b/macros/luatex/latex/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.1 (2021/07/12)}
+\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/
+|-- interpreter.py
+|-- 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}