| Name | logtalk-jupyter-kernel JSON |
| Version |
0.15.0
JSON |
| download |
| home_page | None |
| Summary | Hercutalk - A Jupyter Kernel for Logtalk |
| upload_time | 2024-11-15 19:03:19 |
| maintainer | None |
| docs_url | None |
| author | Anne Brecklinghaus, Michael Leuschel, dgelessus |
| requires_python | >=3.7 |
| license | Copyright (c) 2022-2023 Paulo Moura Copyright (c) 2022 Anne Brecklinghaus, Michael Leuschel, dgelessus 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. |
| keywords |
logtalk
prolog
logic-programming
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Hercutalk - A Jupyter Kernel for Logtalk
A [Jupyter](https://jupyter.org/) kernel for [Logtalk](https://logtalk.org/) based on [prolog-jupyter-kernel](https://github.com/hhu-stups/prolog-jupyter-kernel) and [IPython kernel](https://github.com/ipython/ipykernel).
This project is a fork of the [prolog-jupyter-kernel](https://github.com/hhu-stups/prolog-jupyter-kernel) project (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 the [LICENSE](LICENSE) file).
🙏 Sponsored by [Permion](https://permion.ai/) and [GitHub Sponsors](https://github.com/sponsors/pmoura).
## Supported Logtalk version
Logtalk 3.81.0 (or later version) plus at least one of the supported Prolog backends. The `LOGTALKHOME` and `LOGTALKUSER` environment variables **must** be defined.
## Supported Prolog backends and versions
- [ECLiPSe 7.0 #57 or later](http://eclipseclp.org/)
- [GNU Prolog 1.6.0 or later](http://www.gprolog.org/) (use git version until 1.6.0 is released)
- [SICStus Prolog 4.5.1 or later](https://sicstus.sics.se/)
- [SWI-Prolog 8.4.3 or later](https://www.swi-prolog.org/) (default)
- [Trealla Prolog 2.18.7 or later](https://github.com/trealla-prolog/trealla)
- [XVM 10.0.0 or later](https://permion.ai/)
- [YAP 7.2.1 or later](https://github.com/vscosta)
Note 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 for **extending the kernel for further Prolog backends** or running code with a different version of a backend. For further information about this, see [Configuration](#configuration).
Also see the [JupyterLab Logtalk CodeMirror Extension](https://github.com/LogtalkDotOrg/jupyterlab-logtalk-codemirror-extension) for *syntax highlighting* of Logtalk code in JupyterLab (forked from the [JupyterLab Prolog CodeMirror Extension](https://github.com/hhu-stups/jupyterlab-prolog-codemirror-extension)).
## Examples
The directory [notebooks](./notebooks) contains 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 with [nbviewer](https://nbviewer.org/) without having to install the kernel.
## Install
The kernel is provided as a Python package on the Python Package Index and can be installed with `pip`:
python3 -m pip install --upgrade logtalk-jupyter-kernel
python3 -m logtalk_kernel.install
There are the following options which can be seen when running `python3 -m logtalk_kernel.install --help`
- `--user`: install to the per-user kernel registry instead of `sys.prefix` (use if you get permission errors during installation)
- `--prefix PREFIX`: install to the given prefix: `PREFIX/share/jupyter/kernels/`
## Uninstall
python3 -m pip uninstall logtalk_kernel
jupyter kernelspec remove logtalk_kernel
## Running
Logtalk notebooks can be run using JupyterLab, Jupyter notebook, or VSCode.
### Running using JupyterLab
Simply start JupyterLab (e.g. by typing `jupyter-lab` in a shell) and then click on the Logtalk Notebook (or Logtalk Console) icon in the Launcher or open an existing notebook.
### Running using Jupyter notebook
Simply start Jupyter notebook (e.g. by typing `jupyter notebook` in a shell) and then open an existing notebook.
### Running using VSCode
Simply open an existing notebook. Ensure that the [Logtalk plug-in for VSCode](https://github.com/LogtalkDotOrg/logtalk-for-vscode) for syntax highlighting in code cells.
### Configuration
The kernel can be configured by defining a Python config file named `logtalk_kernel_config.py`. The kernel will look for this file in the Jupyter config path (can be retrieved with `jupyter --paths`) and the current working directory. An **example** of such a configuration file with an explanation of the options and their default values commented out can be found [here](./logtalk_kernel/logtalk_kernel_config.py).
**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 to `True`, the logging level is set to DEBUG by the kernel so that **Python debugging messages** are 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 to `DEBUG` in the file `kernel.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 to `True`, a **Logtalk server log file** is created.
- The name of the file consists of the implementation ID preceded by `.logtalk_server_log_`.
- `backend`: The name of the **Prolog backend integration script** with which the server is started.
- `backend_data`: The **Prolog backend-specific data** which is needed to run the server for code execution.
- This is required to be a dictionary containing at least an entry for the configured `backend`.
- Each entry needs to define values for
- `failure_response`: The output which is displayed if a query **fails**
- `success_response`: The output which is displayed if a query **succeeds without any variable bindings**
- `error_prefix`: The prefix that is output for **error messages**
- `informational_prefix`: The prefix that is output for **informational messages**
- `program_arguments`: **Command line arguments** with which the Logtalk server can be started
- All supported Prolog backends can be used by configuring the string `"default"`.
- Additionally, a `kernel_implementation_path` can be provided, which needs to be an **absolute path to a Python file**:
- The corresponding module is required to define a subclass of `LogtalkKernelBaseImplementation` named `LogtalkKernelImplementation`. This can be used to override some of the kernel's basic behavior (see [Overriding the Kernel Implementation](#overriding-the-kernel-implementation)).
If the given **`program_arguments` are invalid**, the kernel waits for a response from the server which it will never receive. In that state it is **not able to log any exception** and 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.
### Defining environment variables for notebooks
Notebooks may require defining environment variables. For example, a notebook running one of the Java integration examples found in the Logtalk distribution may require the `CLASSPATH` environment variable to be set. This can be easily accomplished by adding a `logtalk_kernel_config.py` file to the notebook directory and using the `os.environ` Python dictionary. For the Logtalk `document_converter` example, which uses Apache Tika, assuming we copied the JAR file to the notebook directory, we could write:
os.environ['CLASSPATH'] = './tika-app-2.8.0.jar'
### Using virtual environment for Logtalk packs
Notebooks may require loading Logtalk packs. Ideally, when sharing notebooks with other users, those packs should be installed in a virtual environment to avoid any conflicts with user installed packs or pack versions. The `lgtenv` script provided by the Logtalk distribution can be used to create the packs virtual environment in the same directory as the notebook. For example:
$ cd my_notebook_directory
$ lgtenv -p logtalk_packs
The packs can be pre-installed before sharing e.g. an archive with the notebook directory contents. Alternatively, installing the packs can be left to the user by providing a `requirements.lgt` file. For example:
registry(talkshow, 'https://github.com/LogtalkDotOrg/talkshow').
pack(talkshow, lflat, 2:1:0).
In this case, the user will need to run (possibly from a notebook code cell) the query:
?- logtalk_load(packs(loader)), packs::restore('requirements.lgt').
We also must ensure that the virtual environment will be used when the notebook runs. The best solution is to create a `settings.lgt` file in the same directory as the notebook defining the `logtalk_packs` library alias. For example, assuming a `logtalk_packs` sub-directory for the virtual environment:
:- multifile(logtalk_library_path/2).
:- dynamic(logtalk_library_path/2).
:- initialization((
logtalk_load_context(directory, Directory),
atom_concat(Directory, logtalk_packs, VirtualEnvironment),
asserta(logtalk_library_path(logtalk_packs, VirtualEnvironment))
)).
### Changing the Prolog backend in the fly
In most cases, the following shortcuts can be used:
- ECLiPSe: `eclipse`
- GNU Prolog: `gnu`
- SICStus Prolog: `sicstus`
- SWI-Prolog (default backend): `swi`
- Trealla Prolog: `trealla`
- XVM : `xvm`
- YAP: `yap`
If the shortcuts don't work due to some unusal Logtalk or Prolog backend setup, the `jupyter::set_prolog_backend(+Backend)` predicate is provided. In order for this to work, the configured `backend_data` dictionary needs to contain data for more than one Prolog backend. For example (in a notebook code cell):
jupyter::set_prolog_backend('xvmlgt.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 `.sh` extension when running the integration script, then use `tplgt.sh` instead of just `tplgt`).
## Development
### Requirements
- At least **Python** 3.5
- Tested with Python 3.11.7
- **Jupyter** installation with JupyterLab and/or Juypter Notebook
- Tested with
- `jupyter_core`: 5.7.2
- `jupyterlab`: 4.2.3
- `notebook`: 7.2.1
- Logtalk and one or more supported Prolog backends (see above)
- Installing **Graphviz** with `python3 -m pip` may not suffice (notably, on Windows)
- Also run the Graphviz [installer](https://graphviz.org/download/) and add its executables to the `PATH` (a reboot may be required afterwards)
The installation was tested with macOS 14.5, Ubuntu 20.0.4, and Windows 10.
### Install
python3 -m pip install --upgrade jupyterlab
git clone https://github.com/LogtalkDotOrg/logtalk-jupyter-kernel
cd logtalk-jupyter-kernel
make install
By default, `make install` uses `sys.prefix`. If it fails with a permission error, you can retry using either `sudo make install` or repeat its last step using `python3 -m logtalk_kernel.install --user` or `python3 -m logtalk_kernel.install --prefix PREFIX`.
On Ubuntu, if `make install` fails with an error, try to update `pip` to its latest version by running `python3 -m pip install --upgrade pip`.
### Uninstall
cd logtalk-jupyter-kernel
make clean
### Local Changes
In general, in order for local code adjustments to take effect, the kernel needs to be reinstalled. When installing the local project in *editable* mode with `python3 -m pip install -e .` (e.g. by running `make`), 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 publishing
python3 -m build .
twine upload dist/logtalk-jupyter-kernel-VERSION.tar.gz dist/logtalk_jupyter_kernel-VERSION-py3-none-any.whl
### Debugging
If you get a `Failed to start the Kernel.` error after selecting the Logtalk kernel, make sure that the `LOGTALKHOME` and `LOGTALKUSER` environment variables are defined.
Usually, 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, the **Logtalk 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, if `server_logging` is configured, **messages can be written to a log file** by calling `log/1` or `log/2` from the `jupyter_logging` object. 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 by `jupyter_query_handling::delete_output_file`. If an error occurs during the actual execution, the file cannot be deleted and thus, the **output 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 code** can be enabled by configuring `jupyter_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 restarted
These 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 a `set_stream/2` predicate:
?- 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 requirements
Adding 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 (including `user_output` and `user_error`) to a different stream and restoring the previous stream when the redirection is terminated.
### Overriding the Kernel Implementation
The actual kernel code determining the handling of requests is not implemented by the kernel class itself. Instead, there is the file [logtalk_kernel_base_implementation.py](./logtalk_kernel/logtalk_kernel_base_implementation.py) which defines the class `LogtalkKernelBaseImplementation`. 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, a `LogtalkKernelBaseImplementation` method is called. By **creating a subclass** of this and defining the path to it as `kernel_implementation_path`, the **actual implementation code can be replaced**. If no such path is defined, the path itself or the defined class is invalid, a **default implementation** is used instead.
Raw data
{
"_id": null,
"home_page": null,
"name": "logtalk-jupyter-kernel",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "Paulo Moura <pmoura@logtalk.org>",
"keywords": "logtalk, prolog, logic-programming",
"author": "Anne Brecklinghaus, Michael Leuschel, dgelessus",
"author_email": "Paulo Moura <pmoura@logtalk.org>",
"download_url": "https://files.pythonhosted.org/packages/78/24/2c2173568afe053111c8c6e6538b682db7e6bec29e87afc5b6ab6d18b947/logtalk_jupyter_kernel-0.15.0.tar.gz",
"platform": null,
"description": "\n# Hercutalk - A Jupyter Kernel for Logtalk\n\nA [Jupyter](https://jupyter.org/) kernel for [Logtalk](https://logtalk.org/) based on [prolog-jupyter-kernel](https://github.com/hhu-stups/prolog-jupyter-kernel) and [IPython kernel](https://github.com/ipython/ipykernel).\n\nThis project is a fork of the [prolog-jupyter-kernel](https://github.com/hhu-stups/prolog-jupyter-kernel) project (developed by Anne Brecklinghaus in her Master's thesis at the University of D\u00fcsseldorf under the supervision of Michael Leuschel and Philipp K\u00f6rner) 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 the [LICENSE](LICENSE) file).\n\n\ud83d\ude4f Sponsored by [Permion](https://permion.ai/) and [GitHub Sponsors](https://github.com/sponsors/pmoura).\n\n\n## Supported Logtalk version\n\nLogtalk 3.81.0 (or later version) plus at least one of the supported Prolog backends. The `LOGTALKHOME` and `LOGTALKUSER` environment variables **must** be defined.\n\n\n## Supported Prolog backends and versions\n\n- [ECLiPSe 7.0 #57 or later](http://eclipseclp.org/)\n- [GNU Prolog 1.6.0 or later](http://www.gprolog.org/) (use git version until 1.6.0 is released)\n- [SICStus Prolog 4.5.1 or later](https://sicstus.sics.se/)\n- [SWI-Prolog 8.4.3 or later](https://www.swi-prolog.org/) (default)\n- [Trealla Prolog 2.18.7 or later](https://github.com/trealla-prolog/trealla)\n- [XVM 10.0.0 or later](https://permion.ai/)\n- [YAP 7.2.1 or later](https://github.com/vscosta)\n\nNote 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).\n\nThe kernel is implemented in a way that basically all functionality except the loading of configuration files can easily be overridden. This is especially useful for **extending the kernel for further Prolog backends** or running code with a different version of a backend. For further information about this, see [Configuration](#configuration).\n\nAlso see the [JupyterLab Logtalk CodeMirror Extension](https://github.com/LogtalkDotOrg/jupyterlab-logtalk-codemirror-extension) for *syntax highlighting* of Logtalk code in JupyterLab (forked from the [JupyterLab Prolog CodeMirror Extension](https://github.com/hhu-stups/jupyterlab-prolog-codemirror-extension)).\n\n\n## Examples\n\nThe directory [notebooks](./notebooks) contains 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 with [nbviewer](https://nbviewer.org/) without having to install the kernel.\n\n\n## Install\n\nThe kernel is provided as a Python package on the Python Package Index and can be installed with `pip`:\n\n\tpython3 -m pip install --upgrade logtalk-jupyter-kernel\n\tpython3 -m logtalk_kernel.install\n\nThere are the following options which can be seen when running `python3 -m logtalk_kernel.install --help`\n\n- `--user`: install to the per-user kernel registry instead of `sys.prefix` (use if you get permission errors during installation)\n- `--prefix PREFIX`: install to the given prefix: `PREFIX/share/jupyter/kernels/`\n\n\n## Uninstall\n\n\tpython3 -m pip uninstall logtalk_kernel\n\tjupyter kernelspec remove logtalk_kernel\n\n\n## Running\n\nLogtalk notebooks can be run using JupyterLab, Jupyter notebook, or VSCode.\n\n### Running using JupyterLab\n\nSimply start JupyterLab (e.g. by typing `jupyter-lab` in a shell) and then click on the Logtalk Notebook (or Logtalk Console) icon in the Launcher or open an existing notebook.\n\n### Running using Jupyter notebook\n\nSimply start Jupyter notebook (e.g. by typing `jupyter notebook` in a shell) and then open an existing notebook.\n\n### Running using VSCode\n\nSimply open an existing notebook. Ensure that the [Logtalk plug-in for VSCode](https://github.com/LogtalkDotOrg/logtalk-for-vscode) for syntax highlighting in code cells.\n\n### Configuration\n\nThe kernel can be configured by defining a Python config file named `logtalk_kernel_config.py`. The kernel will look for this file in the Jupyter config path (can be retrieved with `jupyter --paths`) and the current working directory. An **example** of such a configuration file with an explanation of the options and their default values commented out can be found [here](./logtalk_kernel/logtalk_kernel_config.py).\n\n**Note:** If a config file exists in the current working directory, it overrides values from other configuration files.\n\nIn 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:\n- `jupyter_logging`: If set to `True`, the logging level is set to DEBUG by the kernel so that **Python debugging messages** are logged.\n - 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.\n - 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 to `DEBUG` in the file `kernel.py` (which contains a corresponding comment).\n - However, note that this causes messages to be printed in the Jupyter console applications, which interferes with the other output.\n\n- `server_logging`: If set to `True`, a **Logtalk server log file** is created.\n - The name of the file consists of the implementation ID preceded by `.logtalk_server_log_`.\n- `backend`: The name of the **Prolog backend integration script** with which the server is started.\n- `backend_data`: The **Prolog backend-specific data** which is needed to run the server for code execution.\n - This is required to be a dictionary containing at least an entry for the configured `backend`.\n - Each entry needs to define values for\n - `failure_response`: The output which is displayed if a query **fails**\n - `success_response`: The output which is displayed if a query **succeeds without any variable bindings**\n - `error_prefix`: The prefix that is output for **error messages**\n - `informational_prefix`: The prefix that is output for **informational messages**\n - `program_arguments`: **Command line arguments** with which the Logtalk server can be started\n - All supported Prolog backends can be used by configuring the string `\"default\"`.\n - Additionally, a `kernel_implementation_path` can be provided, which needs to be an **absolute path to a Python file**:\n - The corresponding module is required to define a subclass of `LogtalkKernelBaseImplementation` named `LogtalkKernelImplementation`. This can be used to override some of the kernel's basic behavior (see [Overriding the Kernel Implementation](#overriding-the-kernel-implementation)).\n\nIf the given **`program_arguments` are invalid**, the kernel waits for a response from the server which it will never receive. In that state it is **not able to log any exception** and 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.\n\n\n### Defining environment variables for notebooks\n\nNotebooks may require defining environment variables. For example, a notebook running one of the Java integration examples found in the Logtalk distribution may require the `CLASSPATH` environment variable to be set. This can be easily accomplished by adding a `logtalk_kernel_config.py` file to the notebook directory and using the `os.environ` Python dictionary. For the Logtalk `document_converter` example, which uses Apache Tika, assuming we copied the JAR file to the notebook directory, we could write:\n\n\tos.environ['CLASSPATH'] = './tika-app-2.8.0.jar'\n\n\n### Using virtual environment for Logtalk packs\n\nNotebooks may require loading Logtalk packs. Ideally, when sharing notebooks with other users, those packs should be installed in a virtual environment to avoid any conflicts with user installed packs or pack versions. The `lgtenv` script provided by the Logtalk distribution can be used to create the packs virtual environment in the same directory as the notebook. For example:\n\n\t$ cd my_notebook_directory\n\t$ lgtenv -p logtalk_packs\n\nThe packs can be pre-installed before sharing e.g. an archive with the notebook directory contents. Alternatively, installing the packs can be left to the user by providing a `requirements.lgt` file. For example:\n\n\tregistry(talkshow, 'https://github.com/LogtalkDotOrg/talkshow').\n\tpack(talkshow, lflat, 2:1:0).\n\nIn this case, the user will need to run (possibly from a notebook code cell) the query:\n\n\t?- logtalk_load(packs(loader)), packs::restore('requirements.lgt').\n\nWe also must ensure that the virtual environment will be used when the notebook runs. The best solution is to create a `settings.lgt` file in the same directory as the notebook defining the `logtalk_packs` library alias. For example, assuming a `logtalk_packs` sub-directory for the virtual environment:\n\n\t:- multifile(logtalk_library_path/2).\n\t:- dynamic(logtalk_library_path/2).\n\n\t:- initialization((\n\t\tlogtalk_load_context(directory, Directory),\n\t\tatom_concat(Directory, logtalk_packs, VirtualEnvironment),\n\t\tasserta(logtalk_library_path(logtalk_packs, VirtualEnvironment))\n\t)).\n\n\n### Changing the Prolog backend in the fly\n\nIn most cases, the following shortcuts can be used:\n\n- ECLiPSe: `eclipse`\n- GNU Prolog: `gnu`\n- SICStus Prolog: `sicstus`\n- SWI-Prolog (default backend): `swi` \n- Trealla Prolog: `trealla`\n- XVM : `xvm`\n- YAP: `yap`\n\nIf the shortcuts don't work due to some unusal Logtalk or Prolog backend setup, the `jupyter::set_prolog_backend(+Backend)` predicate is provided. In order for this to work, the configured `backend_data` dictionary needs to contain data for more than one Prolog backend. For example (in a notebook code cell):\n\n\tjupyter::set_prolog_backend('xvmlgt.sh').\n\nThe 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 `.sh` extension when running the integration script, then use `tplgt.sh` instead of just `tplgt`).\n\n\n## Development\n\n### Requirements\n\n- At least **Python** 3.5\n - Tested with Python 3.11.7\n- **Jupyter** installation with JupyterLab and/or Juypter Notebook\n - Tested with\n - `jupyter_core`: 5.7.2\n - `jupyterlab`: 4.2.3\n - `notebook`: 7.2.1\n- Logtalk and one or more supported Prolog backends (see above)\n- Installing **Graphviz** with `python3 -m pip` may not suffice (notably, on Windows)\n - Also run the Graphviz [installer](https://graphviz.org/download/) and add its executables to the `PATH` (a reboot may be required afterwards)\n\nThe installation was tested with macOS 14.5, Ubuntu 20.0.4, and Windows 10.\n\n### Install\n\n\tpython3 -m pip install --upgrade jupyterlab\n\tgit clone https://github.com/LogtalkDotOrg/logtalk-jupyter-kernel\n\tcd logtalk-jupyter-kernel\n\tmake install\n\nBy default, `make install` uses `sys.prefix`. If it fails with a permission error, you can retry using either `sudo make install` or repeat its last step using `python3 -m logtalk_kernel.install --user` or `python3 -m logtalk_kernel.install --prefix PREFIX`.\n\nOn Ubuntu, if `make install` fails with an error, try to update `pip` to its latest version by running `python3 -m pip install --upgrade pip`.\n\n### Uninstall\n\n\tcd logtalk-jupyter-kernel\n\tmake clean\n\n### Local Changes\n\nIn general, in order for local code adjustments to take effect, the kernel needs to be reinstalled. When installing the local project in *editable* mode with `python3 -m pip install -e .` (e.g. by running `make`), restarting the kernel suffices.\n\nAdjustments 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.\n\n### Building and publishing\n\n\tpython3 -m build .\n\ttwine upload dist/logtalk-jupyter-kernel-VERSION.tar.gz dist/logtalk_jupyter_kernel-VERSION-py3-none-any.whl\n\n### Debugging\n\nIf you get a `Failed to start the Kernel.` error after selecting the Logtalk kernel, make sure that the `LOGTALKHOME` and `LOGTALKUSER` environment variables are defined.\n\nUsually, 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, the **Logtalk 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.\n\nDebugging 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, if `server_logging` is configured, **messages can be written to a log file** by calling `log/1` or `log/2` from the `jupyter_logging` object. By default, only the responses sent to the client are logged.\n\nWhen a query is executed, all its output is written to a file named `.server_output`, which is deleted afterwards by `jupyter_query_handling::delete_output_file`. If an error occurs during the actual execution, the file cannot be deleted and thus, the **output of the goal can be accessed**. Otherwise, the deletion might be prevented.\n\nFurthermore, the server might send a response which the client cannot handle. In that case, **logging for the Python code** can be enabled by configuring `jupyter_logging`. For instance, the client logs the responses received from the server.\n\nWhen 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:\n\n\tSomething went wrong\n\tThe Logtalk server needs to be restarted\n\nThese 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 a `set_stream/2` predicate:\n\n\t?- open(out, write, S),\n\t set_stream(S, alias(current_output)),\n\t set_stream(S, alias(user_output)),\n\t set_stream(S, alias(user_error)),\n\t goal,\n\t close(S).\n\nIf 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.\n\n### Prolog backend requirements\n\nAdding support for other Prolog backends requires:\n\n- Command-line option(s) to silence (quiet) any banner and informative messages.\n- 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).\n- Ability to redirect current output (including `user_output` and `user_error`) to a different stream and restoring the previous stream when the redirection is terminated.\n\n### Overriding the Kernel Implementation\n\nThe actual kernel code determining the handling of requests is not implemented by the kernel class itself. Instead, there is the file [logtalk_kernel_base_implementation.py](./logtalk_kernel/logtalk_kernel_base_implementation.py) which defines the class `LogtalkKernelBaseImplementation`. 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, a `LogtalkKernelBaseImplementation` method is called. By **creating a subclass** of this and defining the path to it as `kernel_implementation_path`, the **actual implementation code can be replaced**. If no such path is defined, the path itself or the defined class is invalid, a **default implementation** is used instead.\n",
"bugtrack_url": null,
"license": "Copyright (c) 2022-2023 Paulo Moura Copyright (c) 2022 Anne Brecklinghaus, Michael Leuschel, dgelessus 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. ",
"summary": "Hercutalk - A Jupyter Kernel for Logtalk",
"version": "0.15.0",
"project_urls": {
"Issues": "https://github.com/LogtalkDotOrg/logtalk-jupyter-kernel/issues",
"Source": "https://github.com/LogtalkDotOrg/logtalk-jupyter-kernel"
},
"split_keywords": [
"logtalk",
" prolog",
" logic-programming"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "057d0c27b0d5930b825198c001fd8c687d3647ffa6eee00a88dea8200e9c82c6",
"md5": "7d816b31d50158be2b0b2f32951a0c29",
"sha256": "6bb5594990bcaa955318c27a108737cdf3a303f505954b259296962f7cce15c4"
},
"downloads": -1,
"filename": "logtalk_jupyter_kernel-0.15.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7d816b31d50158be2b0b2f32951a0c29",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 79585,
"upload_time": "2024-11-15T19:03:17",
"upload_time_iso_8601": "2024-11-15T19:03:17.909616Z",
"url": "https://files.pythonhosted.org/packages/05/7d/0c27b0d5930b825198c001fd8c687d3647ffa6eee00a88dea8200e9c82c6/logtalk_jupyter_kernel-0.15.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "78242c2173568afe053111c8c6e6538b682db7e6bec29e87afc5b6ab6d18b947",
"md5": "a24b9af503efbcbcf19e1a206ed910b9",
"sha256": "57c13aa1f8594241dc9cc5f85162baf6292410c93e6d2783f63db190fee6b86f"
},
"downloads": -1,
"filename": "logtalk_jupyter_kernel-0.15.0.tar.gz",
"has_sig": false,
"md5_digest": "a24b9af503efbcbcf19e1a206ed910b9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 79368,
"upload_time": "2024-11-15T19:03:19",
"upload_time_iso_8601": "2024-11-15T19:03:19.293809Z",
"url": "https://files.pythonhosted.org/packages/78/24/2c2173568afe053111c8c6e6538b682db7e6bec29e87afc5b6ab6d18b947/logtalk_jupyter_kernel-0.15.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-15 19:03:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "LogtalkDotOrg",
"github_project": "logtalk-jupyter-kernel",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "logtalk-jupyter-kernel"
}
