.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Python 3pm"
.TH Python 3pm "2020-11-19" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Inline::Python \- Write Perl subs and classes in Python.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&   print "9 + 16 = ", add(9, 16), "\en";
\&   print "9 \- 16 = ", subtract(9, 16), "\en";
\&
\&   use Inline Python => <<\*(AqEND_OF_PYTHON_CODE\*(Aq;
\&   def add(x,y): 
\&      return x + y
\&
\&   def subtract(x,y):
\&      return x \- y
\&
\&   END_OF_PYTHON_CODE
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \f(CW\*(C`Inline::Python\*(C'\fR module allows you to put Python source code
directly \*(L"inline\*(R" in a Perl script or module. It sets up an in-process
Python interpreter, runs your code, and then examines Python's symbol table
for things to bind to 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.
.PP
This document describes \f(CW\*(C`Inline::Python\*(C'\fR, the Perl package which gives you
access to a Python interpreter. For lack of a better place to keep it, it 
also gives you instructions on how to use \f(CW\*(C`perlmodule\*(C'\fR, the Python package 
which gives you access to the Perl interpreter.
.SH "WHAT'S NEW?"
.IX Header "WHAT'S NEW?"
Version 0.21 provides the ability to bind to 'new\-style' classes (as
defined by the python \s-1PEP\s0's 252 and 253.)  See \*(L"New-Style Classes\*(R" for
details.
.PP
See the Changes file for new features in recent versions.
.SH "Using the Inline::Python Module"
.IX Header "Using the Inline::Python Module"
Using Inline::Python will seem very similar to using another Inline
language, thanks to Inline's consistent look and feel.
.PP
This section will explain the different ways to use Inline::Python.
For more details on \f(CW\*(C`Inline\*(C'\fR, see 'perldoc Inline'.
.SS "Giving Your Source to Inline"
.IX Subsection "Giving Your Source to Inline"
The most basic form for using \f(CW\*(C`Inline::Python\*(C'\fR is this:
.PP
.Vb 1
\&   use Inline Python => \*(AqPython source code\*(Aq;
.Ve
.PP
Of course, you can use Perl's \*(L"here document\*(R" style of quoting to make 
the code slightly easier to read:
.PP
.Vb 1
\&   use Inline Python => <<\*(AqEND\*(Aq;
\&
\&     Python source code goes here.
\&
\&   END
.Ve
.PP
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:
.PP
.Vb 1
\&   use Inline Python;
\&
\&   ...
\&
\&   _\|_END_\|_
\&   _\|_Python_\|_
\&
\&   Python source code goes here.
.Ve
.PP
This information is detailed in 'perldoc Inline'.
.SS "Importing Functions"
.IX Subsection "Importing Functions"
Maybe you have a whole library written in Python that only needs one entry
point. You'll want to import that function. It's as easy as this:
.PP
.Vb 1
\&   use Inline Python;
\&
\&   doit();
\&
\&   _\|_END_\|_
\&   _\|_Python_\|_
\&
\&   from mylibrary import doit
.Ve
.PP
Inline::Python actually binds to every function in Python's \*(L"global\*(R" 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.
.SS "Importing Classes"
.IX Subsection "Importing Classes"
If you've written a library in Python, you'll make it object-oriented.
That's just something Python folks do. So you'll probably want to import a
class, not a function. That's just as easy:
.PP
.Vb 1
\&   use Inline Python;
\&
\&   my $obj = new Myclass;
\&
\&   _\|_END_\|_
\&   _\|_Python_\|_
\&
\&   from mylibrary import myclass as Myclass
.Ve
.SS "New-Style Classes"
.IX Subsection "New-Style Classes"
As of python 2.2, the python internals have begun to change in a way
which makes types 'look' more like classes.  This means that your python
code can now subclass builtin python types such as lists, tuples,
integers, and etc.  It also means that identifying python objects and
creating Perl bindings for them has become a little trickier.
.PP
See Guido's write-up (http://www.python.org/2.2.2/descrintro.html) and
the relevant Python Enhancement Proposals (\s-1PEP\s0) 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.
.PP
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.
.PP
In other cases, you may be writing Inline::Python code as follows:
.PP
.Vb 9
\&   use Inline Python => <<\*(AqEND\*(Aq;
\&   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
.Ve
.PP
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.
.PP
.Vb 3
\&  # Class is defined as \*(Aqdef Class(float):\*(Aq
\&  my $obj = Class\->new(4);
\&  print $$obj, "\en"; # will NOT print \*(Aq4.0\*(Aq
.Ve
.SS "New-Style"
.IX Subsection "New-Style"
.SS "Boundary Conditions"
.IX Subsection "Boundary Conditions"
What if you have a class that wasn't imported? Can you deal with instances 
of that class properly?
.PP
Of course you can! Check this out:
.PP
.Vb 1
\&   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(), "\en";
.Ve
.PP
In this example, \f(CW\*(C`Bar\*(C'\fR isn't imported because it isn't a global \*(-- it's hidden
inside the function \fBFoo()\fR. But \fBFoo()\fR is imported into Perl, and it returns an 
instance of the \f(CW\*(C`Bar\*(C'\fR class. What happens then?
.PP
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.
.SH "Exceptions"
.IX Header "Exceptions"
Exceptions thrown in Python code get translated to Perl exceptions which you can
catch using eval.
.SH "Boolean"
.IX Header "Boolean"
Python supports a Boolean type and two constants False and True. If one of
these is passed from Python to Perl, the value is represented by an
Inline::Python::Boolean object that uses overload to behave like 1 or undef
in boolean context in Perl. When this object is passed back to Python, it
is translated back to the False or True constant it originated from.
.PP
To pass a Boolean value that originated from Perl to Python use the two
constants \f(CW$Inline::Python::Boolean::true\fR and
\&\f(CW$Inline::Python::Boolean::false\fR if it is important that the value is
of type Boolean in Python.
.SH "Using Perl inside Python (inside Perl)"
.IX Header "Using Perl inside Python (inside Perl)"
This section doesn't talk at all about \f(CW\*(C`Inline::Python\*(C'\fR. It's about how
to use \f(CW\*(C`perl\*(C'\fR. \f(CW\*(C`perl\*(C'\fR is a Python module bundled with Inline::Python
that gives you access to Perl from inside your Python code. In the
future, it will be possible to compile Inline::Python to work the other
way around \*(-- to use Python as the main programming language, and jump
into Perl when you want to.
.PP
The \f(CW\*(C`perl\*(C'\fR package exposes Perl packages and subs. It uses the same code as
Inline::Python to automatically translate parameters and return values as
needed. Packages and subs are represented as \f(CW\*(C`PerlPkg\*(C'\fR and \f(CW\*(C`PerlSub\*(C'\fR,
respectively.
.SH "Using the PerlPkg Type"
.IX Header "Using the PerlPkg Type"
The \f(CW\*(C`perl\*(C'\fR package is actually not a package at all. As soon as you import
it, it replaces itself with an instance of the PerlPkg class, wrapping
the Perl package \*(L"main\*(R". Perl's 'main' package is analogous to '_\|_main_\|_' in
Python.
.PP
Here's what you can do with the 'main' PerlPkg:
.SS "\fBeval()\fP"
.IX Subsection "eval()"
.Vb 1
\&   eval(source code)
.Ve
.PP
Unlike Python, Perl has no \fBexec()\fR \*(-- the \fBeval()\fR function always returns the
result of the code it evaluated. \fBeval()\fR takes exactly one argument, the
perl source code, and returns the result of the evaluation.
.SS "\fBrequire()\fP and \fBuse()\fP"
.IX Subsection "require() and use()"
.Vb 2
\&   require(module name)
\&   use(module name)
.Ve
.PP
Use \fBrequire()\fR instead of \f(CW\*(C`import\*(C'\fR. In Python, you'd say this:
.PP
.Vb 1
\&   import md5
.Ve
.PP
But using the perl module, you'd say this:
.PP
.Vb 1
\&   perl.require("Digest::MD5")
.Ve
.PP
Of course, in Perl there's more than one way to do it (\s-1TM\s0). \fBrequire()\fR doesn't
run the package's \fBimport()\fR function. If you want symbols exported, for 
instance, use \fBuse()\fR instead of \fBrequire()\fR.
.PP
Here is the functionality common to all PerlPkg instances:
.SS "_\|_getattr_\|_"
.IX Subsection "__getattr__"
Python's _\|_getattr_\|_() function allows the package to dynamically return
something to satisfy the request. For instance, you can get at the subs
in a perl package by using \fBdir()\fR (which is the same as \f(CW\*(C`getattr(perl,
\&\*(Aq_\|_methods_\|_\*(Aq)\*(C'\fR.
.PP
Here's an example:
.PP
.Vb 5
\&   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)
.Ve
.PP
Notice what happens. First we call \fBeval()\fR to define a sub 'f'. Then we 
say \f(CW\*(C`perl.f\*(C'\fR, 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.
.PP
\fIAccessing a perl object's data\fR
.IX Subsection "Accessing a perl object's data"
.PP
_\|_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.
.PP
An example for the common hash based objects:
.PP
.Vb 4
\&   sub _\|_getattr_\|_ {
\&       my ($self, $attr) = @_;
\&       return $self\->{$attr}; 
\&   }
.Ve
.PP
This allows Python code to access the perl object's data like:
.PP
.Vb 1
\&   print my_perl_object.field_name
.Ve
.SS "named arguments"
.IX Subsection "named arguments"
When a Perl sub is called with named arguments from Python code, Inline::Python
follows the PyObject_Call protocol: positional arguments are given as array ref
followed by named arguments as a hash ref. A Perl method supporting named
arguments would therefore look like:
.PP
.Vb 8
\&    sub supports_named_arguments {
\&        my ($self, $positional, $named) = @_;
\&        foreach (qw( named1 named2 )) {
\&            last unless @$positional;
\&            $named\->{$_} = shift @$positional;
\&        }
\&        ...
\&    }
.Ve
.PP
If this method is called using only positional arguments, they would just be
pushed into \f(CW@_\fR like in any other method, complicating it to:
.PP
.Vb 10
\&    sub supports_named_arguments {
\&        my ($self, $positional, $named) = @_;
\&        if (@_ == 3 and $size and ref $size and ref $size eq \*(AqARRAY\*(Aq and ref $useimage eq \*(AqHASH\*(Aq) { # called using named parameters
\&            foreach (qw( named1 named2 ... )) {
\&                last unless @$positional;
\&                $named\->{$_} = shift @$positional;
\&            }
\&        }
\&        else {
\&            $named = { named1 => $positional, named2 => $named, named3 => $_[3], ... };
\&        }
\&        ...
\&    }
.Ve
.PP
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.
.SH "Using the PerlSub Type"
.IX Header "Using the PerlSub Type"
All Perl subs are wrapped in the PerlSub type, so that they can emulate Python
subroutines. You can call them. It's all good. Here's what you can do with
PerlSub objects:
.SS "Call"
.IX Subsection "Call"
PerlSub catches the call action and forwards the call to the real sub in Perl.
.SS "Set the evaluation flags"
.IX Subsection "Set the evaluation flags"
Perl has this notion of calling context. A subroutine can ask Perl what it is
being used for. The idea is that if no one cares about your return value, you
might be able to save time by not building it. By default, PerlSub objects
evaluate in 'list' context with no extra flags turned on.
.PP
.Vb 4
\&   perl.eval("sub f { 10 }")
\&   f = perl.f
\&   f.flags = f.flags | f.G_SCALAR
\&   x = f()
.Ve
.PP
Here are the most common flags you'll need. For more details about these and
other possible flags, see perlcall.
.IP "1." 4
G_VOID
.Sp
Calls the Perl subroutine in a void context. Guarantees that no results will
be returned. If any are returned, Perl deletes them.
.IP "2." 4
G_SCALAR
.Sp
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.
.IP "3." 4
G_ARRAY
.Sp
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.
.IP "4." 4
G_DISCARD
.Sp
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.
.IP "5." 4
G_NOARGS
.Sp
If you are not passing any arguments, you can optimize the call so that Perl
doesn't bother setting up the stack for parameters.
.IP "6." 4
G_EVAL
.Sp
It is possible for the Perl sub to fail, either by calling \fBdie()\fR 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.
.SH "Under the Hood"
.IX Header "Under the Hood"
When Inline::Python imports a class or function, it creates subs in Perl
which delegate the action to some C functions I've written, which know how
to call Python functions and methods.
.PP
.Vb 1
\&   use Inline Python => <<\*(AqEND\*(Aq;
\&
\&   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
.Ve
.PP
Inline::Python actually generates this code and \fBeval()\fRs it:
.PP
.Vb 2
\&   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;
\&   }
\&
\&   sub _\|_init_\|_ {
\&     splice @_, 1, 0, "_\|_init_\|_";
\&     return &Inline::Python::py_call_method;
\&   }
.Ve
.PP
More about those \f(CW\*(C`py_*\*(C'\fR functions, and how to generate this snippet of code
yourself, in the next section.
.SH "The Do-it-yourselfer's Guide to Inline::Python"
.IX Header "The Do-it-yourselfer's Guide to Inline::Python"
Sometimes you don't actually want to do things the Inline Way. Maybe you
just want to use a Python class as-is, without ever treating it like a normal
Perl class:
.PP
.Vb 1
\&   use Inline::Python qw(py_eval);
\&
\&   py_eval(<<\*(AqEND\*(Aq);
\&
\&   class MyClass:
\&       def _\|_init_\|_(self): self.data = {}
\&       def put(self, key, value): self.data[key] = value
\&       def get(self, key):
\&           try: return self.data[key]
\&           except KeyError: return None
\&
\&   END
\&
\&   my $o = Inline::Python::Object\->new(\*(Aq_\|_main_\|_\*(Aq, \*(AqMyClass\*(Aq);
\&   $o\->put("candy", "yummy");
\&   die "Ooops" unless $o\->get("candy") eq \*(Aqyummy\*(Aq;
.Ve
.PP
Inline::Python provides a full suite of exportable functions you can use to
manipulate Python objects and functions \*(L"directly\*(R".
.SS "\fBpy_eval()\fP"
.IX Subsection "py_eval()"
.Vb 1
\&   py_eval("python source code", [context])
.Ve
.PP
The new \fBpy_eval()\fR behaves a little like Perl's \fBeval()\fR. 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.
.IP "0" 4
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.
.IP "1" 4
.IX Item "1"
The default. Accepts arbitrarily long input, which may be any valid Python 
code. Always returns \f(CW\*(C`undef\*(C'\fR.
.IP "2" 4
.IX Item "2"
Accepts exactly one statement, and prints the result to \s-1STDOUT.\s0 This is
how Python works in interactive mode. Always returns \f(CW\*(C`undef\*(C'\fR.
.SS "\fBpy_call_function()\fP"
.IX Subsection "py_call_function()"
.Vb 1
\&   py_call_function("package", "function", args...)
.Ve
.PP
This function runs a Python function and returns the result. The \*(L"package\*(R" and
\&\*(L"function\*(R" uniquely identify a function, and the remaining args are passed 
to the function.
.PP
Those who know Python well enough will know you can actually \*(L"run\*(R" 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.
.SS "\fBpy_new_object()\fP"
.IX Subsection "py_new_object()"
.Vb 2
\&   py_new_object("perl package", "python package", 
\&                 "python class", args...)
.Ve
.PP
This function creates an instance of a Python class. The \*(L"python class\*(R" is the
name of the class inside the \*(L"python package\*(R". The new object is blessed into
the given \*(L"perl package\*(R". The remaining args are passed directly to the
constructor.
.SS "\fBpy_call_method()\fP"
.IX Subsection "py_call_method()"
.Vb 1
\&   py_call_method(object, "method name", args...)
.Ve
.PP
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 \fBpy_call_method()\fR 
can always perform method calls correctly since it unwraps the underlying
Python object.
.SS "\fBeval_python()\fP"
.IX Subsection "eval_python()"
Unlike in previous releases of Inline::Python, \fBeval_python()\fR can now return 
the result of the code. As before, \fBeval_python()\fR is overloaded:
.IP "1." 4
eval_python(code, [context])
.Sp
Evaluate the code using \fBpy_eval()\fR.
.IP "2." 4
eval_python(python package, function, args...)
.Sp
Run the given function and return the results using \fBpy_call_function()\fR.
.IP "3." 4
eval_python(object, method, args...)
.Sp
Invoke the given method on the object using \fBpy_call_method()\fR and return the
results.
.SS "\fBpy_bind_func()\fP"
.IX Subsection "py_bind_func()"
.Vb 1
\&   py_bind_func("symbol name", "python package", "function")
.Ve
.PP
This function imports a Python function (named \*(L"function\*(R") as the symbol
named by \*(L"perl symbol\*(R". After this function has been called, the
Python function can be called as if it were a Perl function in the given
package.
.PP
.Vb 1
\&   use Inline::Python qw(py_eval py_bind_func);
\&
\&   py_eval(<<\*(AqEND\*(Aq);
\&
\&   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(), "\en";
.Ve
.PP
This call to \fBpy_bind_func()\fR will generate this code and \fBeval()\fR it:
.PP
.Vb 4
\&   sub main::Bar {
\&       unshift @_, "_\|_main_\|_", "Foo";
\&       return &Inline::Python::py_call_function;
\&   }
.Ve
.SS "\fBpy_bind_class()\fP"
.IX Subsection "py_bind_class()"
.Vb 1
\&   py_bind_class("perl package", "python package", "class", methods...)
.Ve
.PP
This function imports a Python class (named \*(L"class\*(R") into the Perl package
named by \*(L"perl package\*(R". After this function has been called, the
Perl package will look just like a regular Perl class.
.PP
The example I showed earlier in the \*(L"Under the Hood\*(R" section shows the 
output of py_bind_class. Here's another look at it:
.PP
.Vb 1
\&   use Inline::Python qw(py_eval py_bind_class);
\&
\&   py_eval(<<\*(AqEND\*(Aq);
\&
\&   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;
.Ve
.PP
This call to \fBpy_bind_class()\fR will generate this code and \fBeval()\fR it:
.PP
.Vb 2
\&   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;
\&   }
.Ve
.PP
Note that if you want methods to be created as I've shown, you must pass
them to \fBpy_bind_class()\fR yourself. It doesn't create anything except \fBnew()\fR
and the \f(CW@ISA\fR 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 \s-1AUTOLOAD\s0 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 \fBpy_study_package()\fR, described below.
.SS "\fBpy_study_package()\fP"
.IX Subsection "py_study_package()"
.Vb 1
\&   py_study_package(["package"])
.Ve
.PP
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:
.PP
.Vb 2
\&   py_eval(\*(Aqimport pickle\*(Aq);
\&   my %namespace = py_study_package("pickle");
.Ve
.PP
On my machine, \f(CW%namespace\fR looks something like this:
.PP
.Vb 12
\&   $VAR1 = {
\&             \*(Aqclasses\*(Aq => { ... },
\&             \*(Aqfunctions\*(Aq => [
\&                              \*(Aq_keep_alive\*(Aq,
\&                              \*(Aqloads\*(Aq,
\&                              \*(Aqdump\*(Aq,
\&                              \*(Aqload\*(Aq,
\&                              \*(Aqdumps\*(Aq,
\&                              \*(Aqtest\*(Aq,
\&                              \*(Aqwhichmodule\*(Aq
\&                            ]
\&           };
.Ve
.PP
Each result can be fed to \fBpy_bind_function()\fR and \fBpy_bind_class()\fR, which is 
exactly what Inline::Python itself does.
.SS "\fBpy_is_tuple()\fP"
.IX Subsection "py_is_tuple()"
.Vb 2
\&   my $array_ref = py_eval(\*(Aq(1, 2)\*(Aq)
\&   $is_tuple = py_is_tuple($array_ref)
.Ve
.PP
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 \s-1API\s0 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.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
For information about using \f(CW\*(C`Inline\*(C'\fR, see Inline.
.PP
For information about other Inline languages, see Inline-Support.
.PP
Inline::Python's mailing list is inline@perl.org
.PP
To subscribe, send email to inline\-subscribe@perl.org
.SH "BUGS AND DEFICIENCIES"
.IX Header "BUGS AND DEFICIENCIES"
This is a production quality release of Inline::Python. It is fairly feature
complete and runs stable with no known crasher bugs or memory leaks. Further
testing and expanded support for other operating systems and platforms will be
a focus for future releases.
.PP
When reporting a bug, please do the following:
.PP
.Vb 4
\& \- 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.
.Ve
.PP
Here are some things to watch out for:
.IP "1." 4
Note that the namespace imported into Perl is \s-1NOT\s0 recursively
traversed. Only Python \fBglobals\fR are imported into Perl \*(--
subclasses, subfunctions, and other modules are not imported.
.Sp
Example:
.Sp
.Vb 1
\&   use Inline Python => <<\*(AqEND\*(Aq;
\&
\&   import mymodule
\&
\&   class A: 
\&       class B: pass
\&
\&   END
.Ve
.Sp
The namespace imported into perl is \s-1ONLY\s0 that related to \f(CW\*(C`A\*(C'\fR. Nothing
related to \f(CW\*(C`mymodule\*(C'\fR or \f(CW\*(C`B\*(C'\fR is imported, unless some Python code 
explicitly copies variables from the mymodule namespace into the global 
namespace before Perl binds to it.
.SH "SUPPORTED PLATFORMS"
.IX Header "SUPPORTED PLATFORMS"
Inline::Python has been tested on RedHat Linux 6.2 with a variety of different
Perl and Python configurations. It also seems to be running pretty well on
openSUSE at least from 10.3 to 13.1 and on Solaris.  Previous versions of
Inline::Python worked on Windows and Cygwin \*(-- this version has never been
tested there. I strongly suspect it will require patching. Please send me
patches.
.PP
This version of Inline::Python has been tested with Python versions from 2.5 to
2.7 and from 3.1 to 3.4.
.SH "PORTING YOUR INLINE PYTHON CODE FROM 2 TO 3"
.IX Header "PORTING YOUR INLINE PYTHON CODE FROM 2 TO 3"
First of all, follow the Python guide from 2 to 3:
https://docs.python.org/3/howto/pyporting.html
.PP
For Perl integration:
.PP
.Vb 4
\& \- Non\-utf8\-flagged Perl strings will be Python bytes, utf8\-flagged Perl strings will be Python string
\& \- _\|_cmp_\|_ is no more supported in Python 3 and has been replaced by "rich comparison" (i.e. _\|_eq_\|_, _\|_le_\|_, etc.).
\&Since booleans in Perl are integers, renaming _\|_cmp_\|_ to _\|_eq_\|_ is often enough while wrapping a Perl object in Python.
\& \- perl.require, perl.use and perl.eval accept either bytes or strings.
.Ve
.SH "SOURCE REPOSITORY"
.IX Header "SOURCE REPOSITORY"
The Github repository for this project is at <https://github.com/niner/inline\-python\-pm>. Pull requests are welcome.
.SH "AUTHOR"
.IX Header "AUTHOR"
Neil Watkiss <NEILW@cpan.org>
.PP
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.
.PP
Eric Wilhelm provided support for 'new\-style' classes in version 0.21. Many
thanks, Eric!
.PP
Stefan Seifert <NINE@cpan.org> fixed some bugs and is current co-maintainer.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2001, Neil Watkiss.
.PP
All Rights Reserved. This module is free software. It may be used,
redistributed and/or modified under the same terms as Perl itself.
.PP
(see http://www.perl.com/perl/misc/Artistic.html)