Package: logtalk-jupyter-kernel
Hercutalk - A Jupyter Kernel for LogtalkAJupyterkernel forLogtalkbased onprolog-jupyter-kernelandIPython kernel.This project is a fork of theprolog-jupyter-kernelproject (developed by Anne Brecklinghaus in her Master's thesis at the University of Düsseldorf under the supervision of Michael Leuschel and Philipp Körner) and still under development. It includes back-ports of recent patches and improvements by Michael Leuschel, dgelessus, and Silas Kraume. Major changes are committed and more are expected. Furthermore, no liability is accepted for correctness and completeness (see theLICENSEfile).Supported Logtalk versionLogtalk 3.71.0 (or later version) plus at least one of the supported Prolog backends.Supported Prolog backends and versionsECLiPSe 7.0 #57 or laterGNU Prolog 1.6.0 or later(use git version until 1.6.0 is released)LVM 6.3.0 or laterSICStus Prolog 4.5.1 or laterSWI-Prolog 8.4.3 or later(default)Trealla Prolog 2.18.7 or laterYAP 7.2.1 or laterNote that a public online use of this kernel (instead of private or local) may be restricted to a subset of these backends (notably, due to some systems requiring commercial licenses).The kernel is implemented in a way that basically all functionality except the loading of configuration files can easily be overridden. This is especially useful forextending the kernel for further Prolog backendsor running code with a different version of a backend. For further information about this, seeConfiguration.Also see theJupyterLab Logtalk CodeMirror Extensionforsyntax highlightingof Logtalk code in JupyterLab (forked from theJupyterLab Prolog CodeMirror Extension).ExamplesThe directorynotebookscontains some example Juypter notebooks, including a Logtalk short tutorial and a notebook giving an overview of the kernel's features and its implementation. Note that all of them can be viewed withnbviewerwithout having to install the kernel.InstallThe kernel is provided as a Python package on the Python Package Index and can be installed withpip:python3 -m pip install --upgrade logtalk-jupyter-kernel
python3 -m logtalk_kernel.installThere are the following options which can be seen when runningpython3 -m logtalk_kernel.install --help--user: install to the per-user kernel registry instead ofsys.prefix(use if you get permission errors during installation)--prefix PREFIX: install to the given prefix:PREFIX/share/jupyter/kernels/Uninstallpython3 -m pip uninstall logtalk_kernel
jupyter kernelspec remove logtalk_kernelRunningLogtalk notebooks can be run using JupyterLab, Jupyter notebook, or VSCode.Running using JupyterLabSimply start JupyterLab (e.g. by typingjupyter-labin a shell) and then click on the Logtalk Notebook (or Logtalk Console) icon in the Launcher or open an existing notebook.Running using Jupyter notebookSimply start Jupyter notebook (e.g. by typingjupyter notebookin a shell) and then open an existing notebook.Running using VSCodeSimply open an existing notebook. Ensure that theLogtalk plug-in for VSCodefor syntax highlighting in code cells.ConfigurationThe kernel can be configured by defining a Python config file namedlogtalk_kernel_config.py. The kernel will look for this file in the Jupyter config path (can be retrieved withjupyter --paths) and the current working directory. Anexampleof such a configuration file with an explanation of the options and their default values commented out can be foundhere.Note:If a config file exists in the current working directory, it overrides values from other configuration files.In general, the kernel can be configured to use a different Prolog backend (which is responsible for code execution) or kernel implementation. Furthermore, it can be configured to use another Prolog backend altogether which might not be supported by default. The following options can be configured:jupyter_logging: If set toTrue, the logging level is set to DEBUG by the kernel so thatPython debugging messagesare logged.Note that this way, logging debugging messages can only be enabled after reading a configuration file. Therefore, for instance, the user cannot be informed that no configuration file was loaded if none was defined at one of the expected locations.In order to switch on debugging messages by default, the development installation described in the GitHub repository can be followed and the logging level set toDEBUGin the filekernel.py(which contains a corresponding comment).However, note that this causes messages to be printed in the Jupyter console applications, which interferes with the other output.server_logging: If set toTrue, aLogtalk server log fileis created.The name of the file consists of the implementation ID preceded by.logtalk_server_log_.backend: The name of theProlog backend integration scriptwith which the server is started.backend_data: TheProlog backend-specific datawhich is needed to run the server for code execution.This is required to be a dictionary containing at least an entry for the configuredbackend.Each entry needs to define values forfailure_response: The output which is displayed if a queryfailssuccess_response: The output which is displayed if a querysucceeds without any variable bindingserror_prefix: The prefix that is output forerror messagesinformational_prefix: The prefix that is output forinformational messagesprogram_arguments:Command line argumentswith which the Logtalk server can be startedAll supported Prolog backends can be used by configuring the string"default".Additionally, akernel_implementation_pathcan be provided, which needs to be anabsolute path to a Python file:The corresponding module is required to define a subclass ofLogtalkKernelBaseImplementationnamedLogtalkKernelImplementation. This can be used to override some of the kernel's basic behavior (seeOverriding the Kernel Implementation).Changing the Prolog backend in the flyIn most cases, the following shortcuts can be used:ECLiPSe:eclipseGNU Prolog:gnuLVM :lvmSICStus Prolog:sicstusSWI-Prolog (default backend):swiTrealla Prolog:treallaYAP:yapIf the shortcuts don't work due to some unusal Logtalk or Prolog backend setup, thejupyter::set_prolog_backend(+Backend)predicate is provided. In order for this to work, the configuredbackend_datadictionary needs to contain data for more than one Prolog backend. For example (in a notebook code cell):jupyter::set_prolog_backend('lvmlgt.sh').The predicate argument is the name of the integration script used to run Logtalk. On Windows, always use the PowerShell scripts (e.g.sicstuslgt.ps1). On POSIX systems, use the ones that work for your Logtalk installation (e.g. if you're using Logtalk with Trealla Prolog with a setup that requires the.shextension when running the integration script, then usetplgt.shinstead of justtplgt).Troubleshooting:In case of SICStus Prolog, if the givenprogram_argumentsare invalid(e.g. if the Prolog code file does not exist), the kernel waits for a response from the server which it will never receive. In that state it isnot able to log any exceptionand instead, nothing happens.
To facilitate finding the cause of the error, before trying to start the Logtalk server, the arguments and the directory from which they are tried to be executed are logged.DevelopmentRequirementsAt leastPython3.5Tested with Python 3.11.7Jupyterinstallation with JupyterLab and/or Juypter NotebookTested withjupyter_core: 5.7.1jupyterlab: 4.0.12notebook: 7.0.7Logtalk and one or more supported Prolog backends (see above)For Windows, installingGraphvizwithpython3 -m pipdoes not sufficeInstead, it can be installed fromhereand added to thePATH(a reboot is required afterwards)The installation was tested with macOS 14.3, Ubuntu 20.0.4, and Windows 10.Installpython3 -m pip install --upgrade jupyterlab
git clone https://github.com/LogtalkDotOrg/logtalk-jupyter-kernel
cd logtalk-jupyter-kernel
make installBy default,make installusessys.prefix. If it fails with a permission error, you can retry using eithersudo make installor repeat its last step usingpython3 -m logtalk_kernel.install --userorpython3 -m logtalk_kernel.install --prefix PREFIX.On Ubuntu, ifmake installfails with an error, try to updatepipto its latest version by runningpython3 -m pip install --upgrade pip.Uninstallcd logtalk-jupyter-kernel
make cleanLocal ChangesIn general, in order for local code adjustments to take effect, the kernel needs to be reinstalled. When installing the local project ineditablemode withpython3 -m pip install -e .(e.g. by runningmake), restarting the kernel suffices.Adjustments of the Logtalk server code are loaded when the server is restarted. Thus, when changing Logtalk code only, instead of restarting the whole kernel, it can be interrupted, which causes the Logtalk server to be restarted.Building and publishingpython3 -m build .
twine upload dist/logtalk-jupyter-kernel-VERSION.tar.gz dist/logtalk_jupyter_kernel-VERSION-py3-none-any.whlDebuggingUsually, if the execution of a goal causes an exception, the corresponding Logtalk error message is captured and displayed in the Jupyter frontend. However, in case something goes wrong unexpectedly or the query does not terminate, theLogtalk server might not be able to send a response to the client. In that case, the user can only see that the execution does not terminate without any information about the error or output that might have been produced. However, it is possible to write logging messages and access any potential output, which might facilitate finding the cause of the error.Debugging the server code is not possible in the usual way by tracing invocations. Furthermore, all messages exchanged with the client are written to the standard streams. Therefore, printing helpful debugging messages does not work either. Instead, ifserver_loggingis configured,messages can be written to a log fileby callinglog/1orlog/2from thejupyter_loggingobject. By default, only the responses sent to the client are logged.When a query is executed, all its output is written to a file named.server_output, which is deleted afterwards byjupyter_query_handling::delete_output_file. If an error occurs during the actual execution, the file cannot be deleted and thus, theoutput of the goal can be accessed. Otherwise, the deletion might be prevented.Furthermore, the server might send a response which the client cannot handle. In that case,logging for the Python codecan be enabled by configuringjupyter_logging. For instance, the client logs the responses received from the server.When the Logtalk code makes calls to foreign language libraries (notably C or C++ code), it's possible that output is generated that is not diverted to a file when the kernel redirects the Prolog output streams. This unexpected output is most likely not a valid JSON payload and thus breaks communication between the notebook and the kernel. In this case, the notebook displays the following error:Something went wrong
The Logtalk server needs to be restartedThese issues can be debugged by running the problematic query in a terminal after diverting the Prolog output streams to a file. For example, assuming in the Prolog backend you're using the stream redirecting uses aset_stream/2predicate:?- open(out, write, S),
   set_stream(S, alias(current_output)),
   set_stream(S, alias(user_output)),
   set_stream(S, alias(user_error)),
   goal,
   close(S).If you get any output while the goal is running (e.g. foreign library debugging messages), you will need to find a way to turn off that output.Prolog backend requirementsAdding support for other Prolog backends requires:Command-line option(s) to silence (quiet) any banner and informative messages.Programatic solution to check if a quiet command-line option was used to start the Logtalk/Prolog process (e.g. by checking a boolean Prolog flag).Ability to redirect current output (includinguser_outputanduser_error) to a different stream and restoring the previous stream when the redirection is terminated.Overriding the Kernel ImplementationThe actual kernel code determining the handling of requests is not implemented by the kernel class itself. Instead, there is the filelogtalk_kernel_base_implementation.pywhich defines the classLogtalkKernelBaseImplementation. When the kernel is started, a (sub)object of this class is created. It handles the starting of and communication with the Logtalk server. For all requests (execution, shutdown, completion, inspection) the kernel receives, aLogtalkKernelBaseImplementationmethod is called. Bycreating a subclassof this and defining the path to it askernel_implementation_path, theactual implementation code can be replaced. If no such path is defined, the path itself or the defined class is invalid, adefault implementationis used instead.