<!--
   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>