Giving Your Source to Inline

   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). The recommended way of using Inline is this:

   use Inline Python;

   ...

   __END__
   __Python__

   Python source code goes here.

This information is detailed in 'perldoc Inline'.

Importing Functions

   use Inline Python;

   doit();

   __END__
   __Python__

   from mylibrary import doit

Inline::Python actually binds to every function in Python's "global" namespace (those of you in the know, know that namespace is called '__main__'). So if you had another function there, you'd get that too.

Importing Classes

   use Inline Python;

   my $obj = new Myclass;

   __END__
   __Python__

   from mylibrary import myclass as Myclass

New-Style Classes

See Guido's write-up (http://www.python.org/2.2.2/descrintro.html) and the relevant Python Enhancement Proposals (PEP) numbers 252 and 253 for details about the python code. Also, see the mailing-list discussion (http://mail.python.org/pipermail/python-dev/2004-July/046060.html) for possible implications regarding C-language python extensions.

This change should not affect code which uses Inline::Python, except that it allows you to bind to python classes which have been written using these new features. In most cases, you will be importing an entire class from an external library as defined in the example above.

In other cases, you may be writing Inline::Python code as follows:

   use Inline Python => <<'END';
   class Foo(object):
      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

Additional caveats may exist. Note that if the python class is subclassing one of the builtin types which would normally be accessible as a 'Perlish' translation, that the instance will be an opaque object accessible only through its class methods.

  # Class is defined as 'def Class(float):'
  my $obj = Class->new(4);
  print $$obj, "\n"; # will NOT print '4.0'

New-Style

Boundary Conditions

Of course you can! Check this out:

   use Inline Python => <<END;

   def Foo():
       class Bar:
           def __init__(self):
               print "new Bar()"
           def tank(self):
               return 10
       return Bar()

   END

   my $o = Foo();
   print $o->tank(), "\n";

In this example, "Bar" isn't imported because it isn't a global -- it's hidden inside the function Foo(). But Foo() is imported into Perl, and it returns an instance of the "Bar" class. What happens then?

Whenever Inline::Python needs to return an instance of a class to Perl, it generates an instance of Inline::Python::Object, the base class for all Inline::Python objects. This base class knows how to do all the things you need: calling methods, in this case.

eval()

   eval(source code)

Unlike Python, Perl has no exec() -- the eval() function always returns the result of the code it evaluated. eval() takes exactly one argument, the perl source code, and returns the result of the evaluation.

require() and use()

   require(module name)
   use(module name)

Use require() instead of "import". In Python, you'd say this:

   import md5

But using the perl module, you'd say this:

   perl.require("Digest::MD5")

Of course, in Perl there's more than one way to do it (TM). require() doesn't run the package's import() function. If you want symbols exported, for instance, use use() instead of require().

Here is the functionality common to all PerlPkg instances:

__getattr__

Here's an example:

   perl.eval("sub f { 10 }")    # define main::f
   f = perl.f
   f(); f("hello")              # no argument checking
   if perl.f() != 10: 
       import sys; sys.exit(1)

Notice what happens. First we call eval() to define a sub 'f'. Then we say "perl.f", which goes into the __getattr__() method. We check the Perl namespace and see a function called f, which we return, wrapped in an instance of the PerlSub type.

Accessing a perl object's data

__getattr__ may also be used to access a Perl object's attributes, just like Python allows. The Perl object just has to implement a sub __getattr__ returning the requested attribute, which may even be calculated on the fly.

An example for the common hash based objects:

   sub __getattr__ {
       my ($self, $attr) = @_;
       return $self->{$attr}; 
   }

This allows Python code to access the perl object's data like:

   print my_perl_object.field_name

named arguments

    sub supports_named_arguments {
        my ($self, $positional, $named) = @_;
        foreach (qw( named1 named2 )) {
            last unless @$positional;
            $named->{$_} = shift @$positional;
        }
        ...
    }

If this method is called using only positional arguments, they would just be pushed into @_ like in any other method, complicating it to:

    sub supports_named_arguments {
        my ($self, $positional, $named) = @_;
        if (@_ == 3 and $size and ref $size and ref $size eq 'ARRAY' and ref $useimage eq 'HASH') { # called using named parameters
            foreach (qw( named1 named2 ... )) {
                last unless @$positional;
                $named->{$_} = shift @$positional;
            }
        }
        else {
            $named = { named1 => $positional, named2 => $named, named3 => $_[3], ... };
        }
        ...
    }

As this adds a lot of boiler plate code to subroutines, it is better to just use Perl named arguments conventions (single hashref parameter) if possible.

Call

Set the evaluation flags

   perl.eval("sub f { 10 }")
   f = perl.f
   f.flags = f.flags | f.G_SCALAR
   x = f()

Here are the most common flags you'll need. For more details about these and other possible flags, see perlcall.

1.

G_VOID

Calls the Perl subroutine in a void context. Guarantees that no results will be returned. If any are returned, Perl deletes them.

2.

G_SCALAR

Calls the Perl subroutine in a scalar context. Ensures that only one element is returned from the sub. If the sub returns a list, only the last element is actually saved.

3.

G_ARRAY

Calls the Perl subroutine in a list context. Ensures that any items returned from the subroutine are returned. This is the default for PerlSub objects.

4.

G_DISCARD

If you are not interested in the return values, you can optimize slightly by telling Perl, and it will discard all returned values for you.

5.

G_NOARGS

If you are not passing any arguments, you can optimize the call so that Perl doesn't bother setting up the stack for parameters.

6.

G_EVAL

It is possible for the Perl sub to fail, either by calling die() explicitly or by calling a non-existent sub. By default, the process will terminate immediately. To avoid this happening, you can trap the exception using the G_EVAL flag.

py_eval()

   py_eval("python source code", [context])

The new py_eval() behaves a little like Perl's eval(). It evaluates the code or croaks on failure. The optional context argument can be used to place restrictions on the type of code allowed, as well as influence what happens to the result.

0

Accepts only expressions. Complete statements yield a syntax error. An expression is anything that can appear to the right of an '=' sign. Returns the value of the expression.

1

The default. Accepts arbitrarily long input, which may be any valid Python code. Always returns "undef".

2

Accepts exactly one statement, and prints the result to STDOUT. This is how Python works in interactive mode. Always returns "undef".

py_call_function()

   py_call_function("package", "function", args...)

This function runs a Python function and returns the result. The "package" and "function" uniquely identify a function, and the remaining args are passed to the function.

Those who know Python well enough will know you can actually "run" a class and get an instance of that class back. But in case that's just too weird for you, I've given you a slightly higher-level wrapper around that common idiom.

py_new_object()

   py_new_object("perl package", "python package", 
                 "python class", args...)

This function creates an instance of a Python class. The "python class" is the name of the class inside the "python package". The new object is blessed into the given "perl package". The remaining args are passed directly to the constructor.

py_call_method()

   py_call_method(object, "method name", args...)

Given an instance of a Python class, this function can call a method on it. This is useful if you have an object which is blessed into a non-existent Perl package. Attempts to use Perl's object syntax would fail, because Perl wouldn't find any methods in that package. But py_call_method() can always perform method calls correctly since it unwraps the underlying Python object.

eval_python()

1.

eval_python(code, [context])

Evaluate the code using py_eval().

2.

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

Run the given function and return the results using py_call_function().

3.

eval_python(object, method, args...)

Invoke the given method on the object using py_call_method() and return the results.

py_bind_func()

   py_bind_func("symbol name", "python package", "function")

This function imports a Python function (named "function") as the symbol named by "perl symbol". After this function has been called, the Python function can be called as if it were a Perl function in the given package.

   use Inline::Python qw(py_eval py_bind_func);

   py_eval(<<'END');

   def Foo():
      return 42

   END

   # For the purposes of this example, so I know the package, I set it:
   py_bind_func("main::Bar", "__main__", "Foo");
   print "The meaning of life is: ", Bar(), "\n";

This call to py_bind_func() will generate this code and eval() it:

   sub main::Bar {
       unshift @_, "__main__", "Foo";
       return &Inline::Python::py_call_function;
   }

py_bind_class()

   py_bind_class("perl package", "python package", "class", methods...)

This function imports a Python class (named "class") into the Perl package named by "perl package". After this function has been called, the Perl package will look just like a regular Perl class.

The example I showed earlier in the "Under the Hood" section shows the output of py_bind_class. Here's another look at it:

   use Inline::Python qw(py_eval py_bind_class);

   py_eval(<<'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

   py_bind_class("main::Foo", "__main__", "Foo", "set_data", "get_data");
   my $o = new Foo;

This call to py_bind_class() will generate this code and eval() it:

   package main::Foo;
   @main::Foo::ISA = qw(Inline::Python::Object);

   sub new {
     splice @_, 1, 0, "__main__", "Foo";
     return &Inline::Python::py_new_object;
   }

   sub set_data {
     splice @_, 1, 0, "set_data";
     return &Inline::Python::py_call_method;
   }

   sub get_data {
     splice @_, 1, 0, "get_data";
     return &Inline::Python::py_call_method;
   }

Note that if you want methods to be created as I've shown, you must pass them to py_bind_class() yourself. It doesn't create anything except new() and the @ISA array. It doesn't need to, since the base class knows how to deal with any method call -- but it's also slower, since it has to walk up the inheritance tree to the AUTOLOAD method. I recommend binding to the functions you know about, especially if you're the one writing the code. If it's auto-generated, use py_study_package(), described below.

py_study_package()

   py_study_package(["package"])

This function interrogates the Python interpreter about the given package (or '__main__' if you don't specify one). It returns a list of key/value pairs, so it should be used like this:

   py_eval('import pickle');
   my %namespace = py_study_package("pickle");

On my machine, %namespace looks something like this:

   $VAR1 = {
             'classes' => { ... },
             'functions' => [
                              '_keep_alive',
                              'loads',
                              'dump',
                              'load',
                              'dumps',
                              'test',
                              'whichmodule'
                            ]
           };

Each result can be fed to py_bind_function() and py_bind_class(), which is exactly what Inline::Python itself does.

py_is_tuple()

   my $array_ref = py_eval('(1, 2)')
   $is_tuple = py_is_tuple($array_ref)

This function can tell you if the array reference you got from calling some Python code was a tuple in Python or not (e.g. a normal array). This can be useful if an API requires a distinction between those cases. py_is_tuple works by looking for a magic marker put onto array refs by Py2Pl. Bear in mind that this marker may get lost when copying the array data.