Python en z/OS: entorno virtual (venv y pyproject.toml)
Esta entrada sigue la serie de Python en z/OS: Actualizar Python en z/OS, pySDSF en z/OS 3.2: vigilar el spool y avisar por Microsoft Teams y Crear usuario para scripts Python en batch (RACF).
Hasta ahora, el job SPOOLCHK lanza python3, el que encuentra en el PATH a través del enlace /u/python/current. Ese enlace es cómodo para cambiar de versión, pero tiene un problema: pySDSF está instalado en la 3.13 (su wheel es cp313), y si mañana apunto current a la 3.14, el job deja de funcionar sin haber tocado nada en él.
La solución es un entorno virtual: una carpeta que usa una versión concreta de Python y tiene sus propios paquetes. Y con un pyproject.toml, el script se instala como un comando, spool-alert, que es lo que lanza el job.
Qué es un entorno virtual y qué es pyproject.toml
- Un entorno virtual (
venv) es un directorio con un Python ligero que usa el intérprete con el que se creó y tiene su propia carpeta de paquetes. Lo que instalo en él no toca la Python del sistema ni la de otros usuarios. En su ficheropyvenv.cfgqueda apuntada la ruta del Python que lo creó. pyproject.tomles el fichero estándar que describe un proyecto de Python: su nombre, su versión, la versión de Python que necesita, sus dependencias y los comandos que crea al instalarlo.
Las versiones de Python que tengo
En mi sistema conviven:
- La 3.14 de la stock image, en
/usr/lpp/IBM/cyp/v3r14/pyz, que no toco. - La 3.13.15.1 y la 3.14.7.1 que instalé yo, cada una en su zFS dentro de
/u/python. - El enlace
/u/python/current, que apunta a la que uso en el día a día.

Creo un enlace fijo para la 3.13, /u/python/py313, para tener una ruta corta a esta versión que no cambia cuando apunto current a otra. La uso para crear el entorno, en el LIBPATH de los jobs y para encontrar el wheel de setuptools. Y si instalo una nueva release de la 3.13, basta con apuntar py313 a ella y volver a crear el entorno, sin tocar los jobs. Lo creo con un job lanzado por IBMUSER:
//PYLINK JOB (ACCT),'PYTHON LINK',CLASS=A,MSGCLASS=X,NOTIFY=&SYSUID
//* Create a fixed link to Python 3.13, apart from the current link
//RUN EXEC PGM=BPXBATCH
//STDOUT DD SYSOUT=*
//STDERR DD SYSOUT=*
//STDPARM DD *
SH cd /u/python &&
rm -f py313 &&
ln -s python-v3.13.15.1/usr/lpp/IBM/cyp/v3r13/pyz py313 &&
ls -l /u/python
/*El enlace es relativo, como current: apunta a la carpeta de la 3.13 dentro de /u/python. El rm -f borra el enlace si ya existía, para poder volver a lanzar el job.



Crear el entorno como PYBATCH
El entorno es de PYBATCH, así que lo crea un job con USER=PYBATCH, y queda en su HOME, en /u/pybatch/venv. En el mismo job instalo pySDSF dentro del entorno desde su wheel, que viene con SDSF en /usr/lpp/sdsf/python/dist:
//PYVENV JOB (ACCT),'PYBATCH VENV',CLASS=A,MSGCLASS=X,NOTIFY=&SYSUID,
// USER=PYBATCH,REGION=256M
//* Create a Python 3.13 virtual environment for PYBATCH and
//* install pySDSF in it
//RUN EXEC PGM=BPXBATCH
//STDOUT DD SYSOUT=*
//STDERR DD SYSOUT=*
//STDPARM DD *
SH PY=/u/python/py313;
export LIBPATH=$PY/lib:$LIBPATH;
V=/u/pybatch/venv;
W=/usr/lpp/sdsf/python/dist;
$PY/bin/python3 -m venv $V &&
$V/bin/pip install --no-index $W/pysdsf-3.2-cp313-none-any.whl &&
$V/bin/pip list &&
cat $V/pyvenv.cfg
/*Paso a paso:
PYes la 3.13, por su enlace fijo. IBM pide tener ellibde Python en elLIBPATH, y el.profilede PYBATCH pone el decurrent; por eso pongo delante el de la 3.13, para que se encuentre primero aunquecurrentapunte a otra versión.python3 -m venvcrea el entorno con la 3.13.pip install --no-indexinstala el wheel de pySDSF sin buscar nada en internet.pip listypyvenv.cfgmuestran qué hay en el entorno y con qué Python se creó.
Escribo cada orden completa en su línea del STDPARM, terminada en ; o &&, para que ninguna quede partida entre dos líneas.

Podemos observar los procesos que se lanzan para crear el entorno.


Comprobamos que termina bien.

Vemos que ha instalado el paquete pySDSF 3.2.

En pyvenv.cfg, command muestra que el entorno se creó con /u/python/py313, pero home y executable apuntan a la ruta real de la 3.13.15.1: venv resuelve el enlace al crear el entorno, y el entorno queda atado a esa release. Si un día instalo otra release de la 3.13 y apunto py313 a ella, el entorno seguiría usando la anterior, así que hay que volver a crearlo: borrar /u/pybatch/venv y lanzar PYVENV y PYINST.
Probar el entorno con who()
Lanzo who.py con el Python del entorno:
//PYWHO JOB (ACCT),'PYBATCH WHO',CLASS=A,MSGCLASS=X,NOTIFY=&SYSUID,
// USER=PYBATCH,REGION=256M
//* Run who.py with the Python of the PYBATCH virtual environment
//RUN EXEC PGM=BPXBATCH
//STDOUT DD SYSOUT=*
//STDERR DD SYSOUT=*
//STDPARM DD *
SH export LIBPATH=/u/python/py313/lib:$LIBPATH;
/u/pybatch/venv/bin/python /u/pybatch/scripts/who.py
/*
Confirmamos que se ejecuta correctamente. Además, estamos usando el usuario PYBATCH, que creamos en Crear usuario para scripts Python en batch (RACF), por lo tanto, no deberíamos encontrar problemas.

El proyecto con pyproject.toml
Creo la carpeta del proyecto, /u/pybatch/spoolalert, con el script y su pyproject.toml:
[build-system]
requires = ["setuptools>=70"]
build-backend = "setuptools.build_meta"
[project]
name = "spool-alert"
version = "1.0.0"
requires-python = ">=3.13,<3.14"
dependencies = ["pysdsf"]
[project.scripts]
spool-alert = "spool_alert:main"
[tool.setuptools]
py-modules = ["spool_alert"]requires-pythondeja escrito que el proyecto es para la 3.13: si alguien lo instala con otra versión, pip lo rechaza.dependenciesdice que necesita pySDSF, que ya está en el entorno.[project.scripts]crea el comandospool-alert, que llama a la funciónmain()despool_alert.py.
Para instalar el proyecto, pip necesita setuptools, y un entorno nuevo no lo trae. No hace falta bajarlo: el SDK de Python de IBM trae su wheel entre los datos de las pruebas de Python, en lib/python3.13/test/wheeldata (setuptools-80.8.0-py3-none-any.whl). Es Python puro (py3-none-any), así que vale para z/OS. Si no estuviera, se puede bajar de PyPI y subirlo en binario.
El pyproject.toml lo escribo con un job: IEBGENER copia las líneas que van en el JCL a un fichero de z/OS UNIX. (Hay más formas de crear el fichero, simplemente, es una forma distinta de hacerlo para tener más recursos que podamos utilizar en diferentes situaciones).
//PYTOML JOB (ACCT),'PYBATCH TOML',CLASS=A,MSGCLASS=X,NOTIFY=&SYSUID
//* Write pyproject.toml from the in-stream lines (EBCDIC)
//TOML EXEC PGM=IEBGENER
//SYSPRINT DD SYSOUT=*
//SYSIN DD DUMMY
//SYSUT2 DD PATH='/tmp/pyproject.e',
// PATHOPTS=(OWRONLY,OCREAT,OTRUNC),
// PATHMODE=(SIRUSR,SIWUSR,SIRGRP,SIROTH),
// FILEDATA=TEXT,RECFM=FB,LRECL=80,BLKSIZE=3200
//SYSUT1 DD *
[build-system]
requires = ["setuptools>=70"]
build-backend = "setuptools.build_meta"
[project]
name = "spool-alert"
version = "1.0.0"
requires-python = ">=3.13,<3.14"
dependencies = ["pysdsf"]
[project.scripts]
spool-alert = "spool_alert:main"
[tool.setuptools]
py-modules = ["spool_alert"]
/*SYSUT1lleva el contenido delpyproject.tomltal cual, entreDD *y/*.SYSUT2, conPATH, escribe en un fichero de z/OS UNIX en lugar de en un data set.PATHOPTSlo crea, o lo vacía si ya existe, yPATHMODEle da permisosrw-r--r--.FILEDATA=TEXThace que cada línea acabe con su salto de línea. Las líneas quedan en EBCDIC, como están en el JCL, en un fichero temporal,/tmp/pyproject.e.
La página de códigos del emulador. Las líneas del JCL quedan con la página de códigos del emulador 3270 con el que las escribo o las pego en el editor, y el siguiente job las convierte desde IBM-1047. Con otra página, por ejemplo la española (IBM-284), los corchetes del pyproject.toml quedan con otros códigos, iconv los convierte como si fueran de la 1047 y pip falla al leer el fichero con un UnicodeDecodeError. Por eso pongo la sesión del emulador en 1047 antes de escribir o pegar el job. Y con NUM OFF en el editor, para que no haya números de secuencia en las columnas 73 a 80, que acabarían dentro del fichero.



Python espera el fichero en ASCII. Otro job, también lanzado con IBMUSER:
- Crea la carpeta del proyecto y la de wheels.
- Convierte el fichero a ASCII y borra el temporal.
- Copia el script y el wheel de setuptools.
- Pone la etiqueta de texto a los ficheros del proyecto, igual que a los scripts (el wheel es binario y no la lleva).
- Pone el owner PYBATCH.
//PYPROJ JOB (ACCT),'PYBATCH PROJ',CLASS=A,MSGCLASS=X,NOTIFY=&SYSUID
//* Create the spool-alert project and the wheels folder for PYBATCH
//RUN EXEC PGM=BPXBATCH
//STDOUT DD SYSOUT=*
//STDERR DD SYSOUT=*
//STDPARM DD *
SH P=/u/pybatch/spoolalert;
WH=/u/pybatch/wheels;
T=/u/python/py313/lib/python3.13/test/wheeldata;
mkdir -p $P $WH &&
iconv -f IBM-1047 -t ISO8859-1 /tmp/pyproject.e > $P/pyproject.toml &&
rm /tmp/pyproject.e &&
cp /u/pybatch/scripts/spool_alert.py $P/ &&
cp $T/setuptools-*.whl $WH/ &&
chtag -tc ISO8859-1 $P/* &&
chown -R PYBATCH:PYGRP $P $WH &&
ls -lT $P $WH
/*

Y lo instalo en el entorno con otro job como PYBATCH:
//PYINST JOB (ACCT),'PYBATCH INSTALL',CLASS=A,MSGCLASS=X,
// NOTIFY=&SYSUID,USER=PYBATCH,REGION=256M
//* Install the spool-alert project in the PYBATCH virtual environment
//RUN EXEC PGM=BPXBATCH
//STDOUT DD SYSOUT=*
//STDERR DD SYSOUT=*
//STDPARM DD *
SH export LIBPATH=/u/python/py313/lib:$LIBPATH;
V=/u/pybatch/venv;
WH=/u/pybatch/wheels;
P=/u/pybatch/spoolalert;
$V/bin/pip install --no-index --find-links $WH setuptools &&
$V/bin/pip install --no-index --no-build-isolation $P &&
ls -l $V/bin
/*- El primer
pip installinstala setuptools desde la carpeta de wheels. - El segundo instala el proyecto. Con
--no-build-isolation, pip usa el setuptools del entorno en lugar de intentar bajarlo. ls -lmuestra el comandospool-alertenbin.

Esperamos a que termine.




El job de vigilancia con el comando
El job SPOOLCHK queda así:
//SPOOLCHK JOB (ACCT),'SPOOL CHECK',CLASS=A,MSGCLASS=X,NOTIFY=&SYSUID,
// USER=PYBATCH,REGION=256M
//* Check JES2 spool usage with pySDSF and alert Microsoft Teams
//RUN EXEC PGM=BPXBATCH
//STDOUT DD SYSOUT=*
//STDERR DD SYSOUT=*
//STDPARM DD *
SH export LIBPATH=/u/python/py313/lib:$LIBPATH;
/u/pybatch/venv/bin/spool-alert
/*El .profile de PYBATCH sigue cargando la URL del webhook, así que el job no cambia nada más.



El spool está por debajo del 70 %, así que no hay aviso. Para probar la tarjeta, bajo el umbral con la variable SPOOL_THRESHOLD:
//SPOOLCHK JOB (ACCT),'SPOOL CHECK',CLASS=A,MSGCLASS=X,NOTIFY=&SYSUID,
// USER=PYBATCH,REGION=256M
//* Check JES2 spool usage with a 20% threshold to test the alert
//RUN EXEC PGM=BPXBATCH
//STDOUT DD SYSOUT=*
//STDERR DD SYSOUT=*
//STDPARM DD *
SH export LIBPATH=/u/python/py313/lib:$LIBPATH;
SPOOL_THRESHOLD=20 /u/pybatch/venv/bin/spool-alert
/*

Comprobamos que hemos recibido la alerta en Microsoft Teams.

Más de un comando en el mismo proyecto
Un proyecto puede crear varios comandos. Cada línea de [project.scripts] es un comando, con la forma nombre = "módulo:función", y cada módulo nuevo se añade a py-modules. Por ejemplo, para tener también who.py como comando, primero lo rehago con una función main():
"""Show the SDSF session of the user (who) with pySDSF."""
import sys
from pysdsf import Connection
from pysdsf.isfexception import ISFException
def main():
connection = Connection()
try:
for row in connection.who():
print(row)
except ISFException as e:
print(e, file=sys.stderr)
return 8
finally:
connection.close()
return 0
if __name__ == "__main__":
sys.exit(main())- Hace lo mismo que antes, pero si SDSF devuelve un error lo escribe en STDERR y devuelve 8, así que el paso del job ya no acaba con RC 0.
- Con el
if __name__del final se sigue pudiendo lanzar como script, como en el job PYWHO.
Lo subo en binario a /u/pybatch/scripts, en lugar del anterior, y, como IBMUSER desde OMVS, le pongo la etiqueta y se lo doy a PYBATCH:

chtag -tc ISO8859-1 /u/pybatch/scripts/who.py
chown PYBATCH:PYGRP /u/pybatch/scripts/who.py
ls -lT /u/pybatch/scripts/who.py
En el pyproject.toml subo la versión, añado el comando y añado el módulo, y lo vuelvo a escribir con PYTOML1, con la sesión del emulador en 1047:
//PYTOML1 JOB (ACCT),'PYBATCH TOML',CLASS=A,MSGCLASS=X,NOTIFY=&SYSUID
//* Write pyproject.toml from the in-stream lines (EBCDIC)
//TOML EXEC PGM=IEBGENER
//SYSPRINT DD SYSOUT=*
//SYSIN DD DUMMY
//SYSUT2 DD PATH='/tmp/pyproject.e',
// PATHOPTS=(OWRONLY,OCREAT,OTRUNC),
// PATHMODE=(SIRUSR,SIWUSR,SIRGRP,SIROTH),
// FILEDATA=TEXT,RECFM=FB,LRECL=80,BLKSIZE=3200
//SYSUT1 DD *
[build-system]
requires = ["setuptools>=70"]
build-backend = "setuptools.build_meta"
[project]
name = "spool-alert"
version = "1.1.0"
requires-python = ">=3.13,<3.14"
dependencies = ["pysdsf"]
[project.scripts]
spool-alert = "spool_alert:main"
spool-who = "who:main"
[tool.setuptools]
py-modules = ["spool_alert", "who"]
/*

Y PYPROJ1, que ahora copia también who.py al proyecto:
//PYPROJ1 JOB (ACCT),'PYBATCH PROJ',CLASS=A,MSGCLASS=X,NOTIFY=&SYSUID
//* Copy who.py and the new pyproject.toml to the spool-alert project
//RUN EXEC PGM=BPXBATCH
//STDOUT DD SYSOUT=*
//STDERR DD SYSOUT=*
//STDPARM DD *
SH P=/u/pybatch/spoolalert;
WH=/u/pybatch/wheels;
T=/u/python/py313/lib/python3.13/test/wheeldata;
mkdir -p $P $WH &&
iconv -f IBM-1047 -t ISO8859-1 /tmp/pyproject.e > $P/pyproject.toml &&
rm /tmp/pyproject.e &&
cp /u/pybatch/scripts/spool_alert.py /u/pybatch/scripts/who.py $P/ &&
cp $T/setuptools-*.whl $WH/ &&
chtag -tc ISO8859-1 $P/* &&
chown -R PYBATCH:PYGRP $P $WH &&
ls -lT $P $WH
/*

Después vuelvo a lanzar PYINST, sin cambios, como PYINST1: instala la versión 1.1.0 y en bin aparece spool-who junto a spool-alert.
//PYINST1 JOB (ACCT),'PYBATCH INSTALL',CLASS=A,MSGCLASS=X,
// NOTIFY=&SYSUID,USER=PYBATCH,REGION=256M
//* Install the spool-alert project in the PYBATCH virtual environment
//RUN EXEC PGM=BPXBATCH
//STDOUT DD SYSOUT=*
//STDERR DD SYSOUT=*
//STDPARM DD *
SH export LIBPATH=/u/python/py313/lib:$LIBPATH;
V=/u/pybatch/venv;
WH=/u/pybatch/wheels;
P=/u/pybatch/spoolalert;
$V/bin/pip install --no-index --find-links $WH setuptools &&
$V/bin/pip install --no-index --no-build-isolation $P &&
ls -l $V/bin
/*


Y lo lanzo con un job como PYBATCH:
//PYWHO1 JOB (ACCT),'PYBATCH WHO',CLASS=A,MSGCLASS=X,NOTIFY=&SYSUID,
// USER=PYBATCH,REGION=256M
//* Run the spool-who command of the spool-alert project
//RUN EXEC PGM=BPXBATCH
//STDOUT DD SYSOUT=*
//STDERR DD SYSOUT=*
//STDPARM DD *
SH export LIBPATH=/u/python/py313/lib:$LIBPATH;
/u/pybatch/venv/bin/spool-who
/*

Algunas cosas más sobre los comandos:
- El comando llama a la función sin argumentos. Si necesita parámetros, los lee con
sys.argvoargparse. - Lo que devuelve la función es el código de salida del comando: si no es 0, el paso de BPXBATCH no acaba con RC 0.
- Un mismo fichero puede dar varios comandos, cada uno con una función distinta: por ejemplo,
spool-alert = "spool_alert:main"yspool-status = "spool_alert:status", sispool_alert.pytuviera una funciónstatus(). - pip copia los módulos dentro del entorno, en su
site-packages. Si cambio un script, tengo que volver a lanzar PYTOML1, PYPROJ1 y PYINST1, en ese orden, para que el comando use la versión nueva: PYPROJ1 necesita el fichero que deja PYTOML1 en/tmp. - Subir la versión del proyecto en el
pyproject.toml(la líneaversion, de 1.0.0 a 1.1.0) no es obligatorio: pip reinstala el proyecto desde su carpeta aunque tenga la misma versión. La subo para que quede constancia del cambio.
Módulos sueltos o un paquete
En Python, cada fichero .py es un módulo, y su nombre es el del fichero sin el .py: who.py es el módulo who. Cuando un programa hace import who, Python busca un módulo con ese nombre en las carpetas que conoce. En un entorno virtual, la principal es site-packages, que es donde pip deja todo lo que instala.
Lo que hemos hecho en este proyecto son módulos sueltos: spool_alert.py y who.py están directamente en la carpeta del proyecto, y al instalarlo pip los copia tal cual a site-packages, uno al lado del otro y junto a lo que instalan otros paquetes, como pySDSF.
Un paquete es una carpeta que agrupa varios módulos bajo un mismo nombre. Para que Python la trate como paquete, lleva dentro un fichero __init__.py, que puede estar vacío. Con un paquete, el proyecto quedaría así:
/u/pybatch/spoolalert/
pyproject.toml
spoolalert/
__init__.py
alert.py
who.pyAhora el módulo ya no se llama who a secas, sino spoolalert.who: el nombre del paquete, un punto y el del módulo. En el pyproject.toml se cambia py-modules por packages = ["spoolalert"], y los comandos apuntan a "spoolalert.alert:main" y "spoolalert.who:main".
Qué cambia:
- Los nombres no chocan.
whoes un nombre muy corriente: si otro paquete que instale en el entorno trajera también unwho.py, uno sobrescribiría al otro ensite-packages. Dentro del paquete esspoolalert.who, y no hay confusión. - Es fácil compartir código. Si los dos comandos necesitan lo mismo, por ejemplo abrir la conexión a SDSF o mandar el aviso a Teams, se pone en un módulo del paquete, como
spoolalert/common.py, y los dos lo usan, en lugar de repetirlo en cada script. - Todo queda junto. Con muchos scripts, en
site-packageshay una sola carpeta del proyecto en lugar de muchos ficheros sueltos.
Con dos scripts, como ahora, los módulos sueltos son suficientes. Si el proyecto crece, conviene pasar a un paquete.
Qué ganamos
- El job ya no usa
current: el entorno usa siempre la 3.13.15.1, la release con la que se creó, y elLIBPATHpone delante sulib. - Los paquetes de PYBATCH están en su entorno y no tocan la Python del sistema ni la de otros usuarios.
- El proyecto deja escrito qué versión de Python y qué dependencias necesita.
- El JCL lanza un comando con nombre en lugar de la ruta del script.
- Un mismo proyecto puede dar varios comandos, como
spool-alertyspool-who.
Referencias
- venv — Creation of virtual environments (documentación de Python).
- Writing your pyproject.toml (Python Packaging User Guide).