| <!DOCTYPE html> |
| |
| |
| <!-- |
| | Generated by Apache Maven Doxia Site Renderer 2.0.0 from src/site/xdoc/howto/python-howto.xml at 10 Sep 2025 |
| | Rendered using Apache Maven Fluido Skin 2.1.0 |
| --> |
| <html xmlns="http://www.w3.org/1999/xhtml" lang="en"> |
| <head> |
| <meta charset="UTF-8" /> |
| <meta name="viewport" content="width=device-width, initial-scale=1" /> |
| <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0" /> |
| <title>Python Howto – Apache Turbine</title> |
| <link rel="stylesheet" href="../css/apache-maven-fluido-2.1.0.min.css" /> |
| <link rel="stylesheet" href="../css/site.css" /> |
| <link rel="stylesheet" href="../css/print.css" media="print" /> |
| <script src="../js/apache-maven-fluido-2.1.0.min.js"></script> |
| <link rel="icon" type="image/png" sizes="48x48" href="https://apache.org/favicons/favicon.ico"> |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
| <style>.github-fork-ribbon:before { background-color: orange; }</style> |
| </head> |
| <body> |
| <a class="github-fork-ribbon right-top" href="https://github.com/apache/turbine-build" data-ribbon="Fork me on GitHub">Fork me on GitHub</a> |
| <div class="container-fluid container-fluid-top"> |
| <header> |
| <div id="banner"> |
| <div class="pull-left"><div id="bannerLeft"><h1><a href="https://turbine.apache.org/"><img src="https://www.apache.org/img/feather_glyph_notm.png" style="width: 50px;" /> The Apache Turbine project</a></h1></div></div> |
| <div class="pull-right"><div id="bannerRight"><h1><a href="https://turbine.apache.org/"><img src="https://turbine.apache.org/images/logo.gif" alt="Apache Turbine" /></a></h1></div></div> |
| <div class="clear"><hr/></div> |
| </div> |
| |
| <div id="breadcrumbs"> |
| <ul class="breadcrumb"> |
| <li id="publishDate">Last Published: 01 Apr 2025<span class="divider">|</span> |
| </li> |
| <li id="projectVersion">Version: 7.1-SNAPSHOT</li> |
| <li class="pull-right"><span class="divider">|</span> |
| <a href="https://turbine.apache.org/fulcrum/">Fulcrum</a></li> |
| <li class="pull-right"><span class="divider">|</span> |
| <a href="https://turbine.apache.org/">Turbine</a></li> |
| <li class="pull-right"><a href="https://www.apache.org">Apache</a></li> |
| </ul> |
| </div> |
| </header> |
| <div class="row-fluid"> |
| <header id="leftColumn" class="span2"> |
| <nav class="well sidebar-nav"> |
| <ul class="nav nav-list"> |
| <li class="nav-header">General Information</li> |
| <li><a href="../index.html">Overview</a></li> |
| <li><a href="../features.html">Features</a></li> |
| <li><a href="../fsd.html">Specification</a></li> |
| <li><a href="../getting-started.html">Getting Started</a></li> |
| <li><a href="../how-to-build.html">Howto Build Turbine</a></li> |
| <li><a href="../changes-report.html">Changes</a></li> |
| <li class="nav-header">Documentation</li> |
| <li><a href="../services/index.html"><span class="icon-chevron-right"></span>Services</a></li> |
| <li><a href="../howto/index.html"><span class="icon-chevron-down"></span>Howtos</a> |
| <ul class="nav nav-list"> |
| <li><a href="../howto/action-event-howto.html">Action Events Howto</a></li> |
| <li><a href="../howto/annotations.html">Annotations Howto</a></li> |
| <li><a href="../howto/configuration-howto.html">Configuration Howto</a></li> |
| <li><a href="../howto/extend-user-howto.html">Extend User Howto</a></li> |
| <li><a href="../howto/hibernate-howto.html">Hibernate OM Howto</a></li> |
| <li><a href="../howto/intake-howto.html">Intake Howto</a></li> |
| <li><a href="../howto/jsp-howto.html">JSP Howto</a></li> |
| <li><a href="../howto/migrate-from-2_1-howto.html">Migrating from 2.1 to 2.2</a></li> |
| <li><a href="../howto/migrate-from-2_2-howto.html">Migrating from 2.2 to 2.3</a></li> |
| <li><a href="../howto/migrate-from-2_3-howto.html">Migrating from 2.3 to 4.0</a></li> |
| <li><a href="../howto/migrate-from-4_0-howto.html">Migrating from 4.0 to 5.0</a></li> |
| <li><a href="../howto/pullmodel-howto.html">Pull Model Howto</a></li> |
| <li class="active"><a>Python Howto</a></li> |
| <li><a href="../howto/security-howto.html">Security Howto</a></li> |
| <li><a href="../howto/services-howto.html">Services Howto</a></li> |
| <li><a href="../howto/url-mapper-howto.html">URL Mapper Howto</a></li> |
| <li><a href="../howto/url-rewriting-howto.html">URL Rewriting Howto</a></li> |
| <li><a href="../howto/context-howto.html">Velocity Context Howto</a></li> |
| <li><a href="../howto/velocity-site-howto.html">Velocity Site Howto</a></li> |
| <li><a href="../howto/velocityonlylayout-howto.html">VelocityOnlyLayout Howto</a></li> |
| </ul></li> |
| <li><a href="https://cwiki.apache.org/confluence/display/TURBINE">Wiki</a></li> |
| <li><a href="../apidocs/index.html">JavaDocs</a></li> |
| <li class="nav-header">Development</li> |
| <li><a href="../proposals.html">Proposals</a></li> |
| <li><a href="../how-to-help.html">How To Help</a></li> |
| <li><a href="../todo.html">Todo</a></li> |
| <li class="nav-header">Project Documentation</li> |
| <li><a href="../project-info.html"><span class="icon-chevron-right"></span>Project Information</a></li> |
| <li><a href="../project-reports.html"><span class="icon-chevron-right"></span>Project Reports</a></li> |
| <li class="nav-header">Apache</li> |
| <li><a href="https://www.apache.org/">Apache Website</a></li> |
| <li><a href="https://www.apache.org/licenses/">License</a></li> |
| <li><a href="https://www.apache.org/foundation/how-it-works.html">How the ASF works</a></li> |
| <li><a href="https://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li> |
| <li><a href="https://www.apache.org/foundation/thanks.html">Thanks</a></li> |
| <li><a href="https://www.apache.org/security/">Security</a></li> |
| </ul> |
| </nav> |
| <div class="well sidebar-nav"> |
| <form id="search-form" action="https://www.google.com/search" method="get" > |
| <input value="http://turbine.apache.org/turbine/turbine-7-0" name="sitesearch" type="hidden" /> |
| <input class="search-query" name="q" id="query" type="text" placeholder="Search with Google..." /> |
| </form> |
| <div id="poweredBy"> |
| <div class="clear"></div> |
| <div class="clear"></div> |
| <a href="https://maven.apache.org/" class="builtBy" target="_blank"><img class="builtBy" alt="Built by Maven" src="../images/logos/maven-feather.png" /></a> |
| </div> |
| </div> |
| </header> |
| <main id="bodyColumn" class="span10"> |
| |
| |
| |
| <section><a id="Turbine_Python_Support"></a> |
| <h1>Turbine Python Support</h1> |
| |
| <p> |
| Turbine has support for creating assemblers (see the <a href="fsd.html"> |
| specifications</a>) with Python, by making use of |
| <a href="http://www.jpython.org" class="externalLink">JPython technology</a>. |
| </p> |
| |
| <p> |
| The first question that comes to mind is why one would want do to something |
| like this. Here are some of the reasons you might want to do this: |
| </p> |
| |
| <ul> |
| |
| <li> |
| Python is an interpreted language which means that you do not have |
| to recompile and copy a new jar each time you make changes. |
| </li> |
| |
| |
| <li> |
| Although Python is interpreted it is compiled to java bytecode. |
| Performance is on par with native java code. |
| </li> |
| |
| |
| <li> |
| Python is very easy to learn. This, together with the fact that |
| you don't need to use a compiler, makes it possible for people with |
| little java experience to create screens. |
| </li> |
| |
| |
| <li> |
| You can rapidly build a prototype using python, and later on find |
| that it is not necessary to systematically move to java :-) |
| </li> |
| </ul> |
| </section> |
| |
| <section><a id="Setting_Up_Python_for_Turbine"></a> |
| <h1>Setting Up Python for Turbine</h1> |
| |
| <p> |
| The first thing is to download JPython from www.jpython.org and copy |
| the jpython.jar file into your turibe/lib directory. Now you need to |
| prepare and compile the jpython files like this: |
| </p> |
| <pre class="prettyprint"><code> |
| build prepare-python |
| build jar |
| </code></pre> |
| This will create a new turbine library that contains the Python code. |
| You need to copy this new .jar file to your application's lib |
| directory. |
| |
| |
| <p> |
| Now we need to edit the TurbineResources.properties. Add the following |
| keys to your application's properties: |
| </p> |
| |
| <pre class="prettyprint"><code> |
| services.AssemblerBrokerService.assembler.screen= |
| org.apache.turbine.util.assemblerbroker.python.PythonScreenFactory |
| services.AssemblerBrokerService.assembler.action= |
| org.apache.turbine.util.assemblerbroker.python.PythonActionFactory |
| |
| services.AssemblerBrokerService.python.path=/path/to/python |
| </code></pre> |
| |
| <p> |
| The first two registers the Python Assembler Factories with the |
| AssemblerBrokerService. The last line tells the Python interpreter |
| where to find all the .py files for your application. |
| </p> |
| |
| <p> |
| In the root of your services.AssemblerBrokerService.python.path |
| you need to add a file named config.py that looks like this: |
| </p> |
| |
| |
| <pre class="prettyprint"><code> |
| import java |
| |
| from java.io import * |
| from java.util import * |
| |
| sys.add_package("org.apache.turbine.modules.screens") |
| sys.add_package("org.apache.turbine.modules") |
| sys.add_package("org.apache.turbine.util.db") |
| sys.add_package("org.apache.turbine.util") |
| sys.add_package("org.apache.turbine.services.security.TurbineSecurity") |
| sys.add_package("org.webmacro.servlet") |
| |
| |
| from org.apache.turbine.modules.screens import WebMacroSiteScreen |
| from org.apache.turbine.modules import Action |
| from org.apache.turbine.util.db import Criteria |
| from org.apache.turbine.util import RunData |
| from org.webmacro.servlet import WebContext |
| from org.apache.turbine.services.security import TurbineSecurity |
| </code></pre> |
| |
| |
| <p> |
| JPython sometimes gets a bit confused with the Servlet Engine |
| classloader, which forces us to call sys.add_package for each java |
| package that we wish to use in our Python code. You also need to |
| import all the classes that you wish to use explicitly. You needn't |
| add the classes here, but it avoid some duplicate declarations at the |
| top of each screen/action. |
| </p> |
| </section> |
| |
| <section><a id="Using_Python_with_Turbine"></a> |
| <h1>Using Python with Turbine</h1> |
| |
| <p> |
| To create python screens we use exactly the same methodology than for |
| normal java screens. First you need a /screens subdirectory in your |
| services.AssemblerBrokerService.python.path. This is where your |
| screen code will live. Layouts goes in /layouts, actions in /actions |
| and so forth (just remember to register the appropriate assembler |
| factories). |
| </p> |
| |
| <p> |
| I'm going to create a sample WebMacro screen. First we need a .py file |
| where this screen can live. The .py file should have the same name as |
| your .wm file and it must be all lower case. Inside this file we |
| create a new class with the same name as the file, but in this the |
| first letter is uppercase (the rest is always lower case). To override |
| a method is fairly simple (just create a new method with the same |
| name). |
| </p> |
| |
| <p> |
| There is one problem however - Python does not support method |
| overloading based on type signatures, so usually the simplest for is |
| used, which is doBuildTemplate( RunData data ) for WebMacroSiteScreen |
| in stead of doBuildTemplate( RunData data, WebContext context ). You |
| have two options to overcome this problem. (1) Create a new superclass |
| that exposes a method under a different name or (2) just call |
| getContext in your python code. I usually just go for the second |
| option because it is fairly straight forward anyway. |
| </p> |
| |
| <p> |
| Now for the code. Let's create a screen called Test. First create a |
| test.wm file (I assumer everybody knows how to do this). Now create a |
| test.py and place it in the python-path/screens directory. It should |
| look something like this: |
| </p> |
| |
| |
| <pre class="prettyprint"><code> |
| class Subjectslist(WebMacroSiteScreen): |
| def doBuildTemplate (self,data): |
| context = self.getContext(data) |
| context.put ("me","Leon") |
| context.put ("text","Python is cool"); |
| </code></pre> |
| |
| |
| <p> |
| For more information about the self parameter see the Python docs. You |
| can call any java code that you would normally be able to use (just |
| remember to add it to conf.py) including database, services, etc. You |
| can also freely use any of the Python built-in types and any Python |
| module that was built on 100% pure Python. |
| </p> |
| </section> |
| |
| |
| </main> |
| </div> |
| </div> |
| <hr/> |
| <footer> |
| <div class="container-fluid"> |
| <div class="row-fluid"> |
| <p>© 2000–2025 |
| <a href="https://www.apache.org/">The Apache Software Foundation</a> |
| </p> |
| </div> |
| </div> |
| </footer> |
| </body> |
| </html> |