NAME

Inline::Python - Write Perl subroutines and classes in Python.

SYNOPSIS

print "9 + 16 = ", add(9, 16), "\n";
print "9 - 16 = ", subtract(9, 16), "\n";

use Inline Python => <<'END_OF_PYTHON_CODE';
def add(x,y): 
   return x + y

def subtract(x,y):
   return x - y

END_OF_PYTHON_CODE

DESCRIPTION

The Inline::Python module allows you to put Python source code directly "inline" in a Perl script or module. A Python interpreter is loaded and the Python code is interpreted, then Perl asks the Python interpreter what global functions and classes have been defined. Those functions and classes are made available to your Perl program as if they had been written in Perl.

The process of interrogating the Python interpreter for globals only occurs the first time you run your Python code. The namespace is cached, and subsequent calls use the cached version.

Using the Inline::Python Module

Inline::Python is driven by fundamentally the same idea as other Inline language modules, like Inline::C or Inline::CPP. Because Python is interpreted, the method of getting your code is different, but overall, using Inline::Python is very similar to any other Inline language module.

This section will explain the different ways to use Inline::Python. For more details on Inline, see 'perldoc Inline'.

The Basics: Functions

The most basic form for using Inline::Python is:

use Inline Python => 'Python source code';

Of course, you can use Perl's "here document" style of quoting to make the code slightly easier to read:

use Inline Python => <<'END';

  Python source code goes here.

END

The source code can also be specified as a filename, a subroutine reference (sub routine should return source code), or an array reference (array contains lines of source code). This information is detailed in 'perldoc Inline'.

More Advanced: Classes and Objects

Because Python is object oriented, any interface between Perl and Python needs to support Python classes adequately.

Example:

use Inline Python => <<'END';

class Foo:
   def __init__(self):
      print "new Foo object being created"
      self.data = {}
   def get_data(self): return self.data
   def set_data(self,dat): 
      self.data = dat

END

use Data::Dumper;
my $obj = new Foo;
print Dumper $obj;
print Dumper $obj->get_data();
$obj->set_data({string => 'hello',
                number => 0.7574,
                array => [1, 2, 3],
               });
print Dumper $obj->get_data();

The output from this program is:

new Foo object being created
$VAR1 = bless( do{\(my $o = 135870536)}, 'main::Foo' );
$VAR1 = {};
$VAR1 = {
          'string' => 'hello',
          'array' => [
                       '1',
                       '2',
                       '3'
                     ],
          'number' => '0.7574'
        };

Inline::Python created a new namespace called main::Foo and created the following functions:

sub main::Foo::new { ... }
sub main::Foo::DESTROY { ... }
sub main::Foo::set_data { ... }
sub main::Foo::get_data { ... }
sub main::Foo::__init__ { ... }

If you don't like the fact that the "private" method __init__() was bound to Perl, you can feed Inline::Python options to disable binding to private functions. You can even specify what a private function looks like.

Example:

use Inline Python => <<'END', PRIVATE_PREFIXES => ['__'];

class Foo:
   def __init__(self):
      print "new Foo object being created"
      self.data = {}
   def get_data(self): return self.data
   def set_data(self,dat): 
      self.data = dat

END

Inline::Python created a new namespace called main::Foo and only created the following functions:

sub main::Foo::new { ... }
sub main::Foo::DESTROY { ... }
sub main::Foo::set_data { ... }
sub main::Foo::get_data { ... }

By default, "private" symbols are ones which begin with one underscore, or ones that begin with two underscores. You can redefine the "prefix" used to filter out private functions by using the PRIV_STRING option, which adds new prefixes to the list of bad prefixes. You can pass a string or an array as the argument to PRIV_STRING.

Example:

use Inline Python => <<END, PRIVATE_PREFIXES => [undef, "_priv_"];

def _priv_function(): return None
def public_function(): return None

END

This code will not bind to _priv_function. Notice that undef clears the list PRIVATE_PREFIXES.

If you're like every other Perl hacker, though, you'll just leave all the functions available and let people use their own judgement.

What happens when I call a Python function?

When you call a "Python" function, you're actually calling a Perl function which knows how to get into Python space and back again. For instance, earlier we saw this example:

use Inline Python => <<'END';

class Foo:
   def __init__(self):
      print "new Foo object being created"
      self.data = {}
   def get_data(self): return self.data
   def set_data(self,dat): 
      self.data = dat

END

The code which is passed to eval() is this: (beautified slightly)

package main::Foo;

sub new {
   shift;
   Inline::Python::_eval_python_function(__PACKAGE__,"Foo", @_)
}

sub DESTROY {
  Inline::Python::_destroy_python_object(@_)
}

sub set_data {
  Inline::Python::_eval_python_method(__PACKAGE__,"set_data",@_)
}

sub get_data {
  Inline::Python::_eval_python_method(__PACKAGE__,"get_data",@_);
}

sub __init__ {
  Inline::Python::_eval_python_method(__PACKAGE__,"__init__",@_);
}

Can I do it myself?

If you just want access to Python's interpreter, Inline::Python provides a function you can use to interact with Python. There are three usages: the first one emulates Perl's own eval() -- you just pass it Python code as a string and Python runs it. The major difference between eval() and eval_python() is that Python's eval_python returns 1 or 0, depending on whether the code passed or failed. This may be changed in a subsequent release.

eval_python("python source code")

If you want to send data between Python and Perl, you'll need more than just a success flag. Two other usages of eval_python() are provided which return the results of running Python code:

eval_python("perl package", "python function", args...)

eval_python("perl package", "python method", object, args...)

The first argument, "perl package", is what package into which to bless an instance of a Python class. This is required to support Object Oriented programming properly.

To import eval_python() into your namespace, use the following syntax:

use Inline::Python qw(eval_python);

This will import eval_python() into your namespace, and do nothing else. (NB: most Inline language extensions do not support this syntax. For instance, 'use Inline::C' will generate an error.)

SUPPORTED PLATFORMS

This is an ALPHA release of Inline::Python. Further testing and expanded support for other operating systems and platforms will be a focus for future releases. It has been tested on RedHat Linux 6.2 with a variety of different Perl and Python configurations. It likely will work with many flavours of Unix, and possibly in Windows.

BUGS AND DEFICIENCIES

When reporting a bug, please do the following:

- Put "use Inline REPORTBUG;" at the top of your code, or 
  use the command line option "perl -MInline=REPORTBUG ...".
- Run your code.
- Follow the printed instructions.

Here are some things to watch out for:

The eval_python() function only returns the result of the compilation, not the result of running the code. You can only get the results of running Python code by putting code in a function and running that.

Example:

use Inline::Python qw(eval_python);

eval_python("def foo(): return {'apples': 1, 'oranges': 2}"); # returns 1
eval_python("foo()"); # returns 1 (NOT a hash)

What you need to do:

use Inline::Python qw(eval_python);

eval_python("def foo(): return {'apples': 1, 'oranges': 2}"); # returns 1
eval_python(__PACKAGE__, "foo"); # returns a hash

This bug will probably be fixed in a future release.

Note that the namespace imported into Perl is NOT recursively traversed. Only Python globals are imported into Perl -- subclasses, subfunctions, and other modules are not imported.

Example:
```
use Inline Python => <<'END';

import mymodule

class A: pass

END
```
The namespace imported into perl is ONLY that related to A. Nothing related to mymodule is imported, unless some Python code explictly copies variables from the mymodule namespace into the global namespace before Perl binds to it.

AUTHOR

Neil Watkiss <NEILW@cpan.org>

Brian Ingerson <INGY@cpan.org> is the author of Inline, Inline::C and Inline::CPR. He was responsible for much encouragement and many suggestions throughout the development of Inline::Python.

COPYRIGHT

(see http://www.perl.com/perl/misc/Artistic.html)

To install Inline::Python, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Inline::Python

CPAN shell

perl -MCPAN -e shell
install Inline::Python

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

Using the Inline::Python Module

The Basics: Functions

More Advanced: Classes and Objects

What happens when I call a Python function?

Can I do it myself?

SUPPORTED PLATFORMS

SEE ALSO

BUGS AND DEFICIENCIES

AUTHOR

COPYRIGHT

Module Install Instructions