Skip to content

Commit 65e0cf1

Browse files
aparrishaparrish
committed
python/jython/java tutorial
1 parent 2e10fce commit 65e0cf1

4 files changed

Lines changed: 305 additions & 0 deletions

File tree

‎Tutorials/python-jython-java/imgs/python-jython-java.jpg‎

14.5 KB
Loading

‎Tutorials/python-jython-java/index.html‎

Lines changed: 294 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,294 @@
1+
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2+
3+
<html>
4+
<head>
5+
<meta name="generator" content=
6+
"HTML Tidy for Mac OS X (vers 31 October 2006 - Apple Inc. build 15.12), see www.w3.org">
7+
8+
<title></title>
9+
</head>
10+
11+
<body>
12+
<h1>Python, Jython and Java</h1>
13+
14+
<table width="656">
15+
<tr>
16+
<td>
17+
<p class="license">This tutorial is for Processing's Python Mode.
18+
If you see any errors or have comments, please <a href=
19+
"https://github.com/processing/processing-docs/issues?state=open">
20+
let us know</a>. This work is licensed under a <a href="http://creativecommons.org/licenses/by-nc-sa/4.0/"> Creative Commons
21+
Attribution-NonCommercial-ShareAlike 4.0 International License.</a> </p>
22+
23+
<p>Processing.py is based on the Java implementation of <a
24+
href="http://www.processing.org/">Processing</a>. It uses making use of
25+
<a href="http://www.jython.org/">Jython</a>, an implementation of Python
26+
that runs on the Java Virtual Machine (JVM), to directly access the
27+
underlying Java library. The benefit of this strategy is that your
28+
Processing.py sketches can do pretty much anything regular Processing
29+
sketches can do, and newer versions of Processing.py immediately benefit
30+
from performance enhancements and new features that are added to the Java
31+
implementation. When you're making sketches with Processing.py, you have
32+
access to best of three different software platforms and ecosystems:
33+
Python, Java, and Processing.</p>
34+
35+
<p>However, if you're already familar with any of these platforms, you may
36+
find that some things work in unintuitive way, or fail to work at all. This
37+
tutorial is designed to help you become literate about how Processing.py,
38+
Processing, Python and Java all work together, so you can reason better
39+
about how to diagnose problems and use the full potential of the
40+
platform.</p>
41+
42+
<h2>Jython's limitations (and quirks)</h2>
43+
44+
<p>Jython is an implementation of Python that runs on the Java Virtual
45+
Machine (JVM). Jython was initially developed as a way to write Python
46+
programs that make use of existing Java libraries, frameworks and
47+
infrastructure. Jython is designed to be as compatible as possible
48+
with all Python programs, and is generally just as fast as <a
49+
href="https://en.wikipedia.org/wiki/CPython">CPython</a> (the
50+
"reference" implementation of Python, written in C) for most tasks.</p>
51+
52+
<p>However, Jython does have some significant limitations, especially if
53+
you're used to working with CPython. For more details, see the <a
54+
href="https://wiki.python.org/jython/JythonFaq">official Jython
55+
FAQ</a>. But here's a rundown of the most important differences for
56+
users of Processing.py.</p>
57+
58+
<h3>Python versions</h3>
59+
60+
<p>The latest version of Jython implements Python 2.7. Python 2.7 is still
61+
widely used, but Python 3 (which has a number of incompatibilities with
62+
earlier versions) is gaining popularity. If you're new to Python, keep in
63+
mind that some tutorials and example programs you find on the web will be
64+
written in Python 3, not Python 2.7, and may require a bit of reworking to
65+
make them functional in Processing.py.</p>
66+
67+
<h3>Python Libraries</h3>
68+
69+
<p>Jython supports almost all of the Python standard
70+
library (i.e., the libraries that come with Python when you first install
71+
it). One notable exception is <a
72+
href="https://docs.python.org/2/library/sqlite3.html">sqlite3</a>
73+
(although you can access SQLite databases using ODBC, and <a
74+
href="http://bugs.jython.org/issue1682864">there's an open
75+
ticket for sqlite3 support in the Jython bug tracker</a>. Jython does
76+
*not* support third-party Python libraries that use extensions written in
77+
C. This means that popular Python libraries like <a
78+
href="http://www.numpy.org/">numpy</a>, <a
79+
href="http://www.scipy.org/">scipy</a> and <a
80+
href="http://scikit-learn.org/stable/">scikit-learn</a> <i>will not
81+
work</i> in Jython (and, for this reason, will not work in
82+
Processing.py).</p>
83+
84+
<p>Unfortunately, there's no easy way to tell whether or not a
85+
library uses a C extension (or has a dependency on a library with a C
86+
extension) without attempting to install it, though there
87+
are some libraries that ship with a pure-Python fallback if it's impossible
88+
to compile the C extension.</p>
89+
90+
<h3>Python and Java don't always see eye to eye</h3>
91+
92+
<p>Java is a statically-typed language, whereas Python is dynamically
93+
typed. To make the two languages talk to each other, the implementors of
94+
Jython had to bridge the gap. This can occasionally result in unexpected
95+
problems when attempting to call Java code from Jython, or when attempting
96+
to write Jython code that can be called into from Java code.</p>
97+
98+
<p>One notable example is that classes in Jython are defined at
99+
<em>runtime</em> (unlike pure Java classes, which are usually defined at
100+
compile-time). This means that a number of features that are important for
101+
interoperability with Processing libraries, like method introspection, <a
102+
href="https://github.com/jdf/processing.py/issues/201">sometimes don't
103+
work as expected</a>. The <a
104+
href="http://www.jython.org/jythonbook/en/1.0/JythonAndJavaIntegration.html">Jython
105+
and Java Integration chapter</a> from <a
106+
href="http://www.jython.org/jythonbook/en/1.0/index.html">The Jython
107+
Book</a> has a number of good tips and tricks.</p>
108+
109+
<h2>Gotchas for Python programmers</h2>
110+
111+
<p>One of the goals of Processing.py is to follow the standard Processing
112+
API as closely as possible. This means that the functions you might call in
113+
"vanilla" Processing (i.e., the Java implementation) have exactly the same
114+
functionality in Processing.py.</p>
115+
116+
<h3>Conflicting names</h3>
117+
118+
<p>There are, however, a number of Processing
119+
functions whose names conflict with existing built-in Python functions. To
120+
cope with these cases, Processing.py implements special "wrapper" functions
121+
invoke the appropriate underlying code based on the number of parameters
122+
passed to the call. Here's a list of some of the affected functions:</p>
123+
124+
<ul>
125+
<li><tt>filter()</tt>. In Processing, this function <a
126+
href="https://processing.org/reference/filter_.html">applies a filter or
127+
shader to the pixels in the current frame</a>. In Python, this is
128+
<a href="https://docs.python.org/2/library/functions.html#filter">a
129+
built-in function that constructs a list by evaluating a function
130+
on each item of an existing list</a>. Processing.py checks the
131+
types of the variables passed to the function at runtime and invokes the
132+
Processing function if the parameters match the appropriate signature,
133+
and the Python built-in otherwise.</li>
134+
<li><tt>map()</tt>. In Processing, <a
135+
href="https://processing.org/reference/map_.html">map()</a> is one of several functions
136+
(along with <a
137+
href="https://processing.org/reference/lerp_.html">lerp()</a>, <a
138+
href="https://processing.org/reference/constrain_.html">constrain()</a>,
139+
etc.) that help interpolate numerical values between ranges.
140+
Processing.py's wrapper will invoke the Processing function if the number and type of
141+
the arguments in the function call matches the signature, and invoke the
142+
Python built-in <a
143+
href="https://docs.python.org/2/library/functions.html#map">map()</a> otherwise.
144+
<li><tt>set()</tt>. This Processing function <a
145+
href="https://processing.org/reference/set_.html">sets the color of
146+
a single pixel on the screen or draws an image</a>. In Python, <a
147+
href="https://docs.python.org/2/library/functions.html#func-set">set()</a>
148+
creates a new set object or converts an iterable to a set. Again,
149+
Processing.py's wrapper function invokes either the Processing or
150+
Python function based on the signature of the arguments passed in the
151+
original call.</li>
152+
</ul>
153+
154+
<p>Processing.py makes the core Processing functions available by setting
155+
attributes of Jython's `__builtins__` object. If you're interested in the
156+
technical details, <a
157+
href="https://github.com/jdf/processing.py/blob/master/runtime/src/jycessing/core.py">the
158+
built-ins are assigned in core.py</a>, and the "wrapper" functions are
159+
implemented in <a
160+
href="https://github.com/jdf/processing.py/blob/master/runtime/src/jycessing/PAppletJythonDriver.java">PAppletJythonDriver.java</a>.
161+
162+
<h3>Lists and arrays</h3>
163+
164+
<p>To make things easier on beginner programmers, vanilla Java Processing
165+
includes a number of functions for easily manipulating arrays
166+
such as <tt>split()</tt>, <tt>splitTokens</tt>, <tt>append</tt>,
167+
<tt>arrayCopy</tt>, <tt>reverse</tt>, etc.). For compatibility purposes,
168+
Processing.py supports these functions, even though in most cases you would
169+
want to use Python built-in data structures instead.</p>
170+
171+
<p>If you do end up using these functions, be aware that they return
172+
Python <tt>array</tt> objects, not lists. (Jython internally represents
173+
Java arrays as objects of type <tt>array</tt> from Python's <a
174+
href="https://docs.python.org/2/library/array.html">array</a> module.)
175+
For example, consider the following two lines of code:</p>
176+
177+
<pre>
178+
print type(split("a,b,c,d", ",")) # Processing built-in, prints <type 'array.array'>
179+
print type("a,b,c,d".split(",")) # Python string method, prints <type 'list'>
180+
</pre>
181+
182+
<p>In most situations, arrays and lists are interchangeable, so you might not
183+
even notice. But arrays and lists have subtly different functionality,
184+
which might cause bugs in your program if you're not careful. For
185+
example, the following code raises a TypeError:</p>
186+
187+
<pre>
188+
x = split("a,b,c,d", ",")
189+
x.append(20)
190+
</pre>
191+
192+
<p>... because <tt>split()</tt> returns a strictly-typed array of Java
193+
String objects, and you can't append an integer to such an array. Likewise,
194+
lists and arrays don't compare element-wise, as illustrated by the
195+
following example:</p>
196+
197+
<pre>
198+
x = split("a,b,c,d", ",")
199+
y = ["a", "b", "c", "d"]
200+
print x == y # prints False
201+
</pre>
202+
203+
<p>Always keep an eye on the types of your variables and make sure you know
204+
what you're working with. In addition to the Processing functions mentioned
205+
above, there may be third-party libraries that you use in your
206+
Processing.py sketch that return array types as well. Fortunately, there's
207+
an easy fix: use the Python built-in <tt>list()</tt> function to convert
208+
the arrays into a list. For example:</p>
209+
210+
<pre>
211+
x = list(split("a,b,c,d", ","))
212+
y = ["a", "b", "c", "d"]
213+
print x == y # prints True
214+
</pre>
215+
216+
<p>Note, however, that most vanilla Java Processing function that normally
217+
takes an array as a parameter will happily accept plain Python lists in
218+
their stead, though they'll still return an array. So, for example:</p>
219+
220+
<pre>
221+
print shorten([1, 2, 3, 4]) # prints array('i', [1, 2, 3])
222+
</pre>
223+
224+
<h2>Gotchas for Java/Processing programmers</h2>
225+
226+
<p>For various reasons, Processing.py's implementation of Processing
227+
functions differ in small ways from the implementation in vanilla Java
228+
Processing. For the most part, these differences will be invisible to you
229+
and the functions should "just work" as expected. Included below are a few
230+
quirks that might come up.</p>
231+
232+
<ul>
233+
<li>As noted in the previous section, Processing.py supports many
234+
string and array manipulation functions from vanilla Java Processing.
235+
But it's almost always a better idea to use Python built-in types and
236+
their methods instead. (The official <a
237+
href="https://docs.python.org/2.7/tutorial/index.html">Python
238+
Tutorial</a> is a good place to start if you want to learn more
239+
about Python lists, strings and other data structures.)</li>
240+
241+
<li>Processing.py does not support the <tt>loadTable()</tt> function.
242+
Use the Python standard library <a
243+
href="https://docs.python.org/2/library/csv.html">csv</a> module
244+
instead. Likewise, use the <a
245+
href="https://docs.python.org/2/library/json.html">json</a> module
246+
from the Python standard library for loading, manipulating and saving
247+
JSON data (instead of, e.g., vanilla Java Processing's
248+
<tt>loadJSONObject()</tt>), and <a
249+
href="https://docs.python.org/2/library/xml.etree.elementtree.html">elementtree</a>
250+
for XML data (instead of <tt>loadXML()</tt>).</li>
251+
252+
<li>Processing.py does not support "web color notation" for specifying
253+
colors. Instead, enclose the notation in a string literal and pass that
254+
to the relevant function. (e.g., <tt>fill(#0000FF)</tt> is a syntax
255+
error, but <tt>fill("#0000FF")</tt> works just fine).</li>
256+
</ul>
257+
258+
<h2>Using Processing Libraries</h2>
259+
260+
<p>Most Processing libraries work with Processing.py out of the box. In
261+
Python Mode in the Processing IDE, you can search for and add libraries to
262+
your sketch using the "Add Tool..." dialog, just like you do with vanilla
263+
Java Processing. Processing.py adds a global variable
264+
<tt>this</tt> to your sketch automatically which you can pass to
265+
third-party libraries that need a reference to the current sketch.</p>
266+
267+
<p>Some Processing libraries want you to define functions in your sketch with particular
268+
names and signatures in your sketch as callbacks or event handlers. Right
269+
now, these libraries won't work in Processing.py unless specific support has been
270+
added. As of this writing, full or partial support exists for
271+
<a href="https://processing.org/reference/libraries/serial/index.html">Serial</a>,
272+
<a
273+
href="https://processing.org/reference/libraries/video/index.html">Video</a>,
274+
<a href="https://processing.org/reference/libraries/net/index.html">Net</a>
275+
and <a href="http://www.sojamo.de/libraries/oscp5/">oscP5</a>. If there's a
276+
library that you'd like to use that isn't yet supported, <a
277+
href="https://github.com/jdf/processing.py/issues">open an issue
278+
here</a>.</p>
279+
280+
<h2>Further reading</h2>
281+
282+
<ul>
283+
<li>The <a
284+
href="https://github.com/jdf/processing.py#faq">Processing.py
285+
FAQ</a> in the Github repository has more tips and tricks on how to
286+
use Processing libraries with Processing.py.</li>
287+
<li>The <a href="https://wiki.python.org/jython/JythonFaq">Jython
288+
FAQ</a> has more in-depth answers for questions about compatibility
289+
between Python, Jython and Java.</li>
290+
</ul>
291+
292+
</td>
293+
</tr>
294+
</table>

‎Tutorials/python-jython-java/tutorial.xml‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
2+
<root>
3+
<image>python-jython-java.jpg</image>
4+
<title>Python, Jython and Java</title>
5+
<author>Allison Parrish</author>
6+
<blurb>
7+
<p>Learn how Processing.py brings together Python, Jython and Java</p>
8+
<p>Level: Advanced</p>
9+
</blurb>
10+
</root>

‎Tutorials/tutorials.xml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,4 +14,5 @@
1414
<tutorial>p3d</tutorial>
1515
<tutorial>anatomy</tutorial>
1616
<tutorial>command-line</tutorial>
17+
<tutorial>python-jython-java</tutorial>
1718
</root>

0 commit comments

Comments
 (0)