Serge NOEL
194 lines
7.5 KiB
Plaintext
194 lines
7.5 KiB
Plaintext
<!DOCTYPE html>
|
|
<html lang="en">
|
|
|
|
<head>
|
|
<title>
|
|
JMRI: Python 3 Introduction
|
|
</title>
|
|
<meta name="author" content="Bob Jacobsen">
|
|
<meta name="keywords" content="JMRI Python3 Scripting"> <!-- make these specific, always include JMRI -->
|
|
<!--#include virtual="/help/en/parts/Style.shtml" -->
|
|
</head>
|
|
|
|
<body>
|
|
<!--#include virtual="/help/en/parts/Header.shtml" -->
|
|
|
|
<div id="mBody">
|
|
<!--#include virtual="Sidebar.shtml" -->
|
|
<div id="mainContent">
|
|
|
|
<div id="teaser"> <!-- Optional -->
|
|
<p>JMRI's support for Python 3 is under development. We expect
|
|
there to be changes before its production release in JMRI 5.</p>
|
|
|
|
<p class="important"><span class="since">Since <a href="https://jmri.org/releasenotes/jmri4.99.2.shtml">JMRI 4.99.2</a></span>
|
|
Python 3 support is only available in JMRI test release 4.99.2 or later.
|
|
Make sure to check the release notes of the JMRI version you're using!
|
|
</p>
|
|
<p class="important">
|
|
This support is experimental; we may still encounter killer problems that we're not
|
|
able to solve. Please feel free to experiment with it, but don't i.e.
|
|
write scripts that are critical to your railroad's operation using Python 3.
|
|
<p>
|
|
Please note that Python 3 support is currently only available for macOS and Linux
|
|
computers. Some of the components it requires are not yet available for Windows.
|
|
We'll update to use them and make Windows support available as soon as those
|
|
components are updated.
|
|
</p>
|
|
</div> <!-- closes #teaser-->
|
|
|
|
<!-- -------- -->
|
|
<!-- Page TOC --> <!-- Optional -->
|
|
<!-- -------- -->
|
|
|
|
<!--
|
|
<h1>Optional Table of Contents</h1>
|
|
<p>For a complicated page - like a user guide or technical reference</p>
|
|
<dl class="toc">
|
|
<dt><a href="#topic1">TOC entry 1</a></dt>
|
|
<dt><a href="#topic2">TOC entry 2</a></dt>
|
|
<dd>Some descriptive info about this TOC entry</dd>
|
|
<dt><a href="#topic3">TOC entry 3</a></dt>
|
|
<dd>
|
|
<ol>
|
|
<li>a list of sub items</li>
|
|
<li>a list of sub items</li>
|
|
<li>a list of sub items</li>
|
|
<li>a list of sub items</li>
|
|
</ol>
|
|
</dd>
|
|
<dt><a href="#topic4">TOC entry 4</a></dt>
|
|
<dd>Some info about this TOC entry</dd>
|
|
</dl>
|
|
<p>Alternatively, a simpler page may only need a simple TOC:</p>
|
|
<ul class="snav">
|
|
<li><a href="#topic1">TOC entry 1</a></li>
|
|
<li><a href="#topic2">TOC entry 2</a></li>
|
|
<li><a href="#topic3">TOC entry 3</a></li>
|
|
<li><a href="#topic4">TOC entry 4</a></li>
|
|
</ul>
|
|
<p>Choose one (or neither) ...</p>
|
|
-->
|
|
|
|
<!-- ------------- -->
|
|
<!-- Page Contents --> <!-- Required -->
|
|
<!-- ------------- -->
|
|
|
|
<h1>Python 3 Introduction</h1>
|
|
<div class="section">
|
|
<h2>Getting Started</h2>
|
|
|
|
JMRI's Python 3 support is provided, in part,
|
|
by running on a
|
|
<a href="https://www.graalvm.org">GraalVM</a>
|
|
virtual machine instead of the usual
|
|
Java Runtime Environment.
|
|
The first step is to install a GraalVM on your computer.
|
|
<p>
|
|
To do that, follow
|
|
<a href="https://www.graalvm.org/docs/getting-started/#install-graalvm">the GraalVM install instructions</a>
|
|
to install a Java 17 or later version. The Java 17 version is recommended.
|
|
Note that using Java 17 will cause
|
|
some problems for other JMRI functions, see the
|
|
<a href="../../doc/Technical/JVMCapabilities.shtml#jdk17">description of those</a>.
|
|
<p>Next, check that "python" has been installed in your GraalVM using the command
|
|
<code class="block">
|
|
gu list
|
|
</code>
|
|
If the <code>gu</code> command is not available, it's likely that your GraalVM installation
|
|
didn't go correctly. If that command doesn't show "python" installed, you have
|
|
to install it:
|
|
<code class="block">
|
|
gu install python
|
|
</code>
|
|
then check again with the <code>gu list</code> command.
|
|
<p>
|
|
Once you do all that and start JMRI, a "Python 3" choice should appear in the
|
|
language selector in the Script Input Window, and the file choosers for
|
|
running scripts should give you a similar choice.
|
|
<p>
|
|
Our convention is that Python 3 files use a .py3 extension.
|
|
|
|
</div>
|
|
|
|
<div class="section">
|
|
<h2>Issues and differences from Jython (Python 2.7)</h2>
|
|
|
|
In addition to the syntax differences between the Python 2.7 and Python 3 languages,
|
|
such as print statements need to have their value enclosed in parentheses
|
|
<code class="block">
|
|
print (123)
|
|
</code>
|
|
there are some scripting-related differences:
|
|
|
|
<ul>
|
|
<li>Scripts should start with
|
|
<code class="block">
|
|
import jmri as jmri
|
|
import java
|
|
exec( open("jython/jmri_bindings.py3").read() )
|
|
</code>
|
|
The third line is the Py3 syntax to read and execute another script file.
|
|
In this case, it reads and executes the file that defines a number of
|
|
symbols like `THROWN``, `turnouts`, etc.
|
|
<li>
|
|
The syntax for getting a class reference has changed. The only
|
|
place you're likely to see that is in InstanceManager calls. They become:
|
|
<code class="block">
|
|
manager = jmri.InstanceManager.getNullableDefault('jmri.MyManager')
|
|
</code>
|
|
(note quotes). More generally, if you need access to a Java type
|
|
object for other purposes, you can get it with
|
|
<code class="block">
|
|
java.type('jmri.MyManager')
|
|
</code>
|
|
but we've provided a new version of InstanceManager.getDefault and
|
|
InstanceManager.getNullableDefault that takes the class name as
|
|
a parameter to make those common operations simpler.
|
|
|
|
<li>
|
|
Constants are not inherited:
|
|
You have to reference <code>DigitalIO.ON</code>, not <code>Light.ON</code>.
|
|
|
|
<li>
|
|
Unlike Jython, JMRI's Python 3 can address (almost) any of the
|
|
Python libraries you have installed on your computer.
|
|
|
|
<li>
|
|
You can inherit a Python class from a Java class, i.e.
|
|
<code class="block">
|
|
class Automat(AbstractAutomaton) :
|
|
def init(self) :
|
|
print ("init in Python 3")
|
|
def handle(self) :
|
|
print ("handle in Python 3")
|
|
return False
|
|
</code>
|
|
<!-- The following was fixed in Java 17 Graal, which we recommend above:
|
|
|
|
but when you're doing that you can't add any additional
|
|
methods to the new class. This might require rethinking
|
|
how to connect Java class code to your own scripting code;
|
|
we hope to have some recommendations soon.
|
|
-->
|
|
|
|
<li>The "syntax error" message doesn't tell you where the
|
|
error was found. This is a real pain.
|
|
|
|
</ul>
|
|
|
|
For the most up-to-date information on these, see
|
|
the
|
|
<a href="https://github.com/JMRI/JMRI/blob/master/java/graalvm/DIFFERENCES.md">Differences.md file</a>
|
|
and the
|
|
<a href="http://jmri.org/jython/test/Python3Test.py3">jython/test/Python3Test.py3 demo file</a>.
|
|
</div>
|
|
|
|
<!--#include virtual="/help/en/parts/Footer.shtml" -->
|
|
|
|
</div><!-- closes #mainContent-->
|
|
</div> <!-- closes #mBody-->
|
|
<script src="/js/help.js"></script>
|
|
</body>
|
|
</html>
|