From 4afc0e03308d532d963e3fad3bbf4be9500276e7 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Wed, 14 Jul 2021 21:10:34 +0000 Subject: pyluatex (14jul21) git-svn-id: svn://tug.org/texlive/trunk@59928 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/lualatex/pyluatex/README.md | 56 +++ .../doc/lualatex/pyluatex/pyluatex-interpreter.py | 71 ++++ .../doc/lualatex/pyluatex/pyluatex-json.lua | 388 +++++++++++++++++++++ .../texmf-dist/doc/lualatex/pyluatex/pyluatex.lua | 137 ++++++++ .../texmf-dist/doc/lualatex/pyluatex/pyluatex.pdf | Bin 0 -> 64343 bytes .../texmf-dist/doc/lualatex/pyluatex/pyluatex.tex | 168 +++++++++ .../texmf-dist/tex/lualatex/pyluatex/pyluatex.sty | 45 +++ Master/tlpkg/bin/tlpkg-ctan-check | 2 +- Master/tlpkg/tlpsrc/collection-luatex.tlpsrc | 1 + Master/tlpkg/tlpsrc/pyluatex.tlpsrc | 0 10 files changed, 867 insertions(+), 1 deletion(-) create mode 100644 Master/texmf-dist/doc/lualatex/pyluatex/README.md create mode 100644 Master/texmf-dist/doc/lualatex/pyluatex/pyluatex-interpreter.py create mode 100644 Master/texmf-dist/doc/lualatex/pyluatex/pyluatex-json.lua create mode 100644 Master/texmf-dist/doc/lualatex/pyluatex/pyluatex.lua create mode 100644 Master/texmf-dist/doc/lualatex/pyluatex/pyluatex.pdf create mode 100644 Master/texmf-dist/doc/lualatex/pyluatex/pyluatex.tex create mode 100644 Master/texmf-dist/tex/lualatex/pyluatex/pyluatex.sty create mode 100644 Master/tlpkg/tlpsrc/pyluatex.tlpsrc 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 Binary files /dev/null and b/Master/texmf-dist/doc/lualatex/pyluatex/pyluatex.pdf differ 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\\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} diff --git a/Master/texmf-dist/tex/lualatex/pyluatex/pyluatex.sty b/Master/texmf-dist/tex/lualatex/pyluatex/pyluatex.sty new file mode 100644 index 00000000000..752f19d0e76 --- /dev/null +++ b/Master/texmf-dist/tex/lualatex/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/14 v0.1.2 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/Master/tlpkg/bin/tlpkg-ctan-check b/Master/tlpkg/bin/tlpkg-ctan-check index ebed5323758..331a8138060 100755 --- a/Master/tlpkg/bin/tlpkg-ctan-check +++ b/Master/tlpkg/bin/tlpkg-ctan-check @@ -651,7 +651,7 @@ my @TLP_working = qw( punk punk-latex punknova purifyeps puyotikz pwebmac pxbase pxchfon pxcjkcat pxfonts pxgreeks pxjahyper pxjodel pxpgfmark pxpic pxrubrica pxtatescale pxtxalfa pxufont - pygmentex python pythonhighlight pythontex + pygmentex pyluatex python pythonhighlight pythontex qcircuit qcm qobitree qrbill qrcode qsharp qstest qsymbols qtree qualitype quantikz quantumarticle quattrocento quicktype quiz2socrative quotchap quoting quotmark diff --git a/Master/tlpkg/tlpsrc/collection-luatex.tlpsrc b/Master/tlpkg/tlpsrc/collection-luatex.tlpsrc index df19437c63a..e70b37136d7 100644 --- a/Master/tlpkg/tlpsrc/collection-luatex.tlpsrc +++ b/Master/tlpkg/tlpsrc/collection-luatex.tlpsrc @@ -64,6 +64,7 @@ depend pdfarticle depend pdfextra depend placeat depend plantuml +depend pyluatex depend selnolig depend spelling depend stricttex diff --git a/Master/tlpkg/tlpsrc/pyluatex.tlpsrc b/Master/tlpkg/tlpsrc/pyluatex.tlpsrc new file mode 100644 index 00000000000..e69de29bb2d -- cgit v1.2.3