Google Git
Sign in
apache/tuscany-sca-cpp/refs/heads/cpp-contrib/./contrib/doc/PythonExtension.html
blob: f51af0d6c91cfe50a1742f4412a1fa76c500e1c3 [file] [log] [blame]
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML>
<HEAD>
<META CONTENT="text/html; charset=iso-8859-1" HTTP-EQUIV="Content-Type">
<META CONTENT="text/css" HTTP-EQUIV="Content-Style-Type">
<STYLE MEDIA="all" TYPE="text/css">
@import url("css/maven-base.css");
@import url("css/maven-theme.css");
</STYLE>
<LINK HREF="css/maven-theme.css" MEDIA="print" REL="stylesheet"
TYPE="text/css">
<TITLE>Tuscany SCA Native - Python Extension</TITLE>
</HEAD>
<BODY>
<DIV ID="bodyColumn">
<DIV ID="contentBox">
<DIV CLASS="section">
<H1>Tuscany SCA Native - Python Extension</H1>
<P>The Tuscany Python extension allows Python scripts to be used as components in
SCA composites and as clients that can invoke SCA services.
</P>
<P>The following samples demonstrate use of the Python extension:</P>
<UL>
<LI><A HREF="../samples/PythonCalculator/README.html">PythonCalculator</A></LI>
<LI><A HREF="../samples/PythonWeatherForecast/README.html">PythonWeatherForecast</A></LI>
<LI><A HREF="../samples/RestCustomer/README.html">RestCustomer</A></LI>
<LI><A HREF="../samples/RestYahoo/README.html">RestYahoo</A></LI>
<LI><A HREF="../samples/AlertAggregator/README.html">AlertAggregator</A></LI>
</UL>
</DIV>
<DIV CLASS="section">
<H2>Contents</H2>
<OL>
<LI><A HREF="#requirements">System Requirements</A></LI>
<LI><A HREF="#install">Installing the Tuscany SCA Python Extension..</A>
<UL>
<LI><A HREF="#linuxbin">..from the binary release on Linux and Mac OS X</A></LI>
<LI><A HREF="#linuxsrc">..from the source release on Linux and Mac OS X</A></LI>
<LI><A HREF="#winbin">..from the binary release on Windows</A></LI>
<LI><A HREF="#winsrc">..from the source release on Windows</A></LI>
</UL></LI>
<LI><A HREF="#pm">The Tuscany Python Programming Model</A></LI>
<UL>
<LI><A HREF="#clients">Clients</A></LI>
<LI><A HREF="#components">SCA Components</A></LI>
<LI><A HREF="#references">Component references</A></LI>
<LI><A HREF="#properties">Component properties</A></LI>
</UL>
<LI><A HREF="#help">Getting help</A></LI>
</OL>
</DIV>
<DIV CLASS="section">
<A NAME="requirements"><H2>System Requirements</H2></A>
<P>In order to install and use the Tuscany SCA Python Extension there are some
extra requirements in addition to the <A HREF="../GettingStarted.html#requirements">Tuscany
SCA requirements</A>:</P>
<TABLE CLASS="bodyTable">
<TBODY>
<TR CLASS="a">
<TD><B>Software</B></TD>
<TD><B>Download Link</B></TD>
</TR>
<TR CLASS="b">
<TD>Python version 2.5</TD>
<TD>
<A HREF="http://www.python.org/download/"
TARGET="_blank">http://www.python.org/download/</A><BR/>
Please download and follow the installation instructions.
</TD>
</TR>
</TBODY>
</TABLE>
</DIV>
<DIV CLASS="section">
<A NAME="install"><H2>Installing the Tuscany SCA Python Extension</H2></A>
<A NAME="linuxbin"><H3>Getting the Tuscany SCA Python Extension working with the binary release on Linux and Mac OS X</H3></A>
<OL>
<LI>Ensure the Python libraries are available on the PATH environment variable</LI>
<LI>Add the &lt;tuscany_sca_install_dir&gt;/extensions/python/lib directory to the PYTHONPATH environment variable</LI>
</OL>
<A NAME="linuxsrc"><H3>Getting the Tuscany SCA Python Extension working with the source release on Linux and Mac OS X</H3></A>
<OL>
<LI>You will need the Tuscany SCA and SDO libraries - follow the instructions
<A HREF="../GettingStarted.html">here</A> to build the SCA libraries and default extensions</LI>
<LI>The following environment variables are required:
<UL>
<LI>TUSCANY_SCACPP=&lt;path to built Tuscany SCA&gt;
<LI>TUSCANY_SDOCPP=&lt;path to installed Tuscany SDO&gt;
<LI>PYTHON_LIB=&lt;path to Python libraries&gt;</LI>
<LI>PYTHON_INCLUDE=&lt;path to Python includes&gt;</LI>
<LI>PYTHON_VERSION=&lt;name of the Python version&gt;<BR/>
Note: If you are using a default installation of Python 2.5 these are usually:<BR/>
PYTHON_LIB=/usr/lib<BR/>
PYTHON_INCLUDE=/usr/include/python2.5<BR/>
PYTHON_VERSION=python2.5<BR/></LI>
</UL></LI>
<LI>Build the Python source only with the following command sequence:
<UL>
<LI>cd &lt;tuscany_sca_install_dir&gt;</LI>
<LI>./configure --prefix=$TUSCANY_SCACPP --enable-python --enable-cpp=no --enable-wsbinding=no</LI>
<LI>make</LI>
<LI>make install</LI>
</UL>
NOTE: If you don't provide a --prefix configure option, it will by default install into
/usr/local/tuscany/sca</LI>
</OL>
<A NAME="winbin"><H3>Getting the Tuscany SCA Python Extension working with the binary release on Windows</H3></A>
<OL>
<LI>Ensure the Python libraries are available on the PATH environment variable</LI>
<LI>Add the &lt;tuscany_sca_install_dir&gt;\extensions\python\bin directory to the PYTHONPATH environment variable</LI>
</OL>
<A NAME="winsrc"><H3>Getting the Tuscany SCA Python Extension working with the source release on Windows</H3></A>
<OL>
<LI>Unzip the supplied source zip file</LI>
<LI>The following environment variables are required:
<UL>
<LI>TUSCANY_SCACPP=&lt;path to built Tuscany SCA&gt;
<LI>TUSCANY_SDOCPP=&lt;path to installed Tuscany SDO&gt;
<LI>PYTHON_HOME=&lt;path to installed Python&gt;
</UL></LI>
<LI>You must have set up the environment for Microsoft Visual C++ tools. The build command
will call vcvars32 to set the environment. Ensure the directory containing this is on your path.
This will be where you installed the compiler.</LI>
<LI>Build the source:
<UL>
<LI>cd &lt;to where you unzipped the source&gt;</LI>
<LI>build</LI>
</UL>
This will build all the projects and put the required output into the 'deploy' directory<BR/><BR/>
Alternatively, open the workspace at &lt;tuscany_sca_install_dir&gt;/projects/tuscany_sca/tuscany_sca.dsw
in Visual Studio 6 or at at &lt;tuscany_sca_install_dir&gt;/projectsvc7/tuscany_sca/tuscany_sca.sln
in Visual Studio 7.1 - you can build projects individually
<LI>Set the TUSCANY_SCACPP environment variable to point to the 'deploy' directory that was just created</LI>
</OL>
</DIV>
<DIV CLASS="section">
<A NAME="pm"><H2>The Tuscany Python Programming Model</H2></A>
<P>This section will explain
the Tuscany Python programming model to help you to write your own Python
components and clients.
</P>
<P>The Tuscany Python component and client support comes from a Python extension
package that is built in the &lt;tuscany_sca_install_dir&gt;/extensions/python/bin
directory on Windows and &lt;tuscany_sca_install_dir&gt;/extensions/python/lib on
Linux and Mac OS X. This package must be made available to your Python environment by
adding this directory to your PYTHONPATH environment variable. This makes the sca
module available for use by clients and allows references and properties to be
used in your Python components
</P>
<A NAME="clients"><H3>Clients</H3></A>
<P>Using the sca module, a Python client can search for an SCA service with:
</P>
<PRE>import sca
calculator = sca.locateservice("CalculatorComponent/CalculatorService")
</PRE>
<P>This finds the component and service as defined in the composite and componentType
side files and returns a proxy object that can call the SCA service. You can then
simply call a business method on "calculator", like this:
</P>
<PRE>result = calculator.add(12.3, 45.6)</PRE>
</P>
<A NAME="components"><H3>Components</H3></A>
<P>Python component implementations are standard Python scripts, where class-level
functions or module-level functions can be invoked by the Tuscany runtime. To
use a Python component implementation, use the implementation.python element in
your .composite file. For example, the following snippet will use the Python script
at path/to/module/PythonModuleName.py, where the path is relative to the location of
the composite file:
</P>
<PRE>&lt;implementation.python module="PythonModuleName" path="path/to/module"/&gt;
</PRE>
<P>To instantiate a class instance and use a class-level function, the Python class must
have a default constructor (an __init__ method that takes no arguments besides
'self') and the class attribute must be defined in the implementation.python element
in your composite, like so:
</P>
<PRE>&lt;implementation.python module="PythonModuleName" path="path/to/module" class="PythonClassName"/&gt;
</PRE>
<P>Tuscany currently supports passing simple types (strings, ints, floats, etc) as well
as Service Data Objects into and out of Ruby components. Service Data Objects are represented
in Python as xml.etree.ElementTree Element objects (see the <A HREF="../samples/PythonWeatherForecast/README.html">
PythonWeatherForecast sample</A> for a demonstration).
</P>
<P>You can write a componentType file for your Python component, but you don't have to - the Python
extension automatically exposes a service and adds references and properties to your Python component
implementation classes based on the information in the composite file.
</P>
<A NAME="references"><H3>References</H3></A>
<P>References are automatically added to your Python component implementation when
the runtime loads the implementation script, so they can be used like so:
</P>
<PRE># The module-level div function
def div(val1, val2):
# Use the divideService reference
result = divideService.divide(val1, val2)
return result
</PRE>
<P>and in your composite file:
</P>
<PRE>&lt;component name="CalculatorComponent"&gt;
&lt;implementation.python module="CalculatorImpl"/&gt;
&lt;reference name="divideService"&gt;DivideComponent/DivideService&lt;/reference&gt;
&lt;/component&gt;
</PRE>
<A NAME="properties"><H3>Properties</H3></A>
<P>A composite with a property defined for a component like so:
</P>
<PRE>&lt;component name="DivideComponent"&gt;
&lt;implementation.python module="DivideImpl"/&gt;
&lt;property name="doRounding"&gt;true&lt;/property&gt;
&lt;/component&gt;
</PRE>
<P>means the property is automatically instantiated and assigned the
property value in the Python component implementation, so it can be
used like so:
</P>
<PRE>def divide(val1, val2):
result = float(val1) / float(val2)
print "Python - DivideImpl.divide " + str(val1) + " / " + str(val2) + " = " + str(result)
# Use the doRounding property
if doRounding:
result = round(result)
print "Python - DivideImpl.divide is rounding the result to " + str(result)
return result
</PRE>
</P>
</DIV>
<DIV CLASS="section">
<A NAME="help"><H2>Getting Help</H2></A>
<P>First place to look is at the Tuscany FAQ at
<A HREF="http://incubator.apache.org/tuscany/faq.html"
TARGET="_blank">http://incubator.apache.org/tuscany/faq.html</A> </P>
<P>Any problem with this release can be reported to the Tuscany
<A HREF="http://incubator.apache.org/tuscany/mail-lists.html"
TARGET="_blank">mailing lists</A> or create a JIRA issue at&nbsp;<A HREF="http://issues.apache.org/jira/browse/Tuscany"
TARGET="_blank">http://issues.apache.org/jira/browse/Tuscany</A>.</P>
</DIV>
</DIV>
</DIV>
</BODY>
</HTML>