1Python(3)             User Contributed Perl Documentation            Python(3)
2
3
4

NAME

6       Inline::Python - Write Perl subs and classes in Python.
7

SYNOPSIS

9          print "9 + 16 = ", add(9, 16), "\n";
10          print "9 - 16 = ", subtract(9, 16), "\n";
11
12          use Inline Python => <<'END_OF_PYTHON_CODE';
13          def add(x,y):
14             return x + y
15
16          def subtract(x,y):
17             return x - y
18
19          END_OF_PYTHON_CODE
20

DESCRIPTION

22       The "Inline::Python" module allows you to put Python source code
23       directly "inline" in a Perl script or module. It sets up an in-process
24       Python interpreter, runs your code, and then examines Python's symbol
25       table for things to bind to Perl. The process of interrogating the
26       Python interpreter for globals only occurs the first time you run your
27       Python code.  The namespace is cached, and subsequent calls use the
28       cached version.
29
30       This document describes "Inline::Python", the Perl package which gives
31       you access to a Python interpreter. For lack of a better place to keep
32       it, it also gives you instructions on how to use "perlmodule", the
33       Python package which gives you access to the Perl interpreter.
34

WHAT'S NEW?

36       Version 0.21 provides the ability to bind to 'new-style' classes (as
37       defined by the python PEP's 252 and 253.)  See "New-Style Classes" for
38       details.
39
40       See the Changes file for new features in recent versions.
41

Using the Inline::Python Module

43       Using Inline::Python will seem very similar to using another Inline
44       language, thanks to Inline's consistent look and feel.
45
46       This section will explain the different ways to use Inline::Python.
47       For more details on "Inline", see 'perldoc Inline'.
48
49   Giving Your Source to Inline
50       The most basic form for using "Inline::Python" is this:
51
52          use Inline Python => 'Python source code';
53
54       Of course, you can use Perl's "here document" style of quoting to make
55       the code slightly easier to read:
56
57          use Inline Python => <<'END';
58
59            Python source code goes here.
60
61          END
62
63       The source code can also be specified as a filename, a subroutine
64       reference (sub routine should return source code), or an array
65       reference (array contains lines of source code). The recommended way of
66       using Inline is this:
67
68          use Inline Python;
69
70          ...
71
72          __END__
73          __Python__
74
75          Python source code goes here.
76
77       This information is detailed in 'perldoc Inline'.
78
79   Importing Functions
80       Maybe you have a whole library written in Python that only needs one
81       entry point. You'll want to import that function. It's as easy as this:
82
83          use Inline Python;
84
85          doit();
86
87          __END__
88          __Python__
89
90          from mylibrary import doit
91
92       Inline::Python actually binds to every function in Python's "global"
93       namespace (those of you in the know, know that namespace is called
94       '__main__'). So if you had another function there, you'd get that too.
95
96   Importing Classes
97       If you've written a library in Python, you'll make it object-oriented.
98       That's just something Python folks do. So you'll probably want to
99       import a class, not a function. That's just as easy:
100
101          use Inline Python;
102
103          my $obj = new Myclass;
104
105          __END__
106          __Python__
107
108          from mylibrary import myclass as Myclass
109
110   New-Style Classes
111       As of python 2.2, the python internals have begun to change in a way
112       which makes types 'look' more like classes.  This means that your
113       python code can now subclass builtin python types such as lists,
114       tuples, integers, and etc.  It also means that identifying python
115       objects and creating Perl bindings for them has become a little
116       trickier.
117
118       See Guido's write-up (http://www.python.org/2.2.2/descrintro.html) and
119       the relevant Python Enhancement Proposals (PEP) numbers 252 and 253 for
120       details about the python code.  Also, see the mailing-list discussion
121       (http://mail.python.org/pipermail/python-dev/2004-July/046060.html) for
122       possible implications regarding C-language python extensions.
123
124       This change should not affect code which uses Inline::Python, except
125       that it allows you to bind to python classes which have been written
126       using these new features.  In most cases, you will be importing an
127       entire class from an external library as defined in the example above.
128
129       In other cases, you may be writing Inline::Python code as follows:
130
131          use Inline Python => <<'END';
132          class Foo(object):
133             def __init__(self):
134                print "new Foo object being created"
135                self.data = {}
136             def get_data(self): return self.data
137             def set_data(self,dat):
138                self.data = dat
139          END
140
141       Additional caveats may exist.  Note that if the python class is
142       subclassing one of the builtin types which would normally be accessible
143       as a 'Perlish' translation, that the instance will be an opaque object
144       accessible only through its class methods.
145
146         # Class is defined as 'def Class(float):'
147         my $obj = Class->new(4);
148         print $$obj, "\n"; # will NOT print '4.0'
149
150   New-Style
151   Boundary Conditions
152       What if you have a class that wasn't imported? Can you deal with
153       instances of that class properly?
154
155       Of course you can! Check this out:
156
157          use Inline Python => <<END;
158
159          def Foo():
160              class Bar:
161                  def __init__(self):
162                      print "new Bar()"
163                  def tank(self):
164                      return 10
165              return Bar()
166
167          END
168
169          my $o = Foo();
170          print $o->tank(), "\n";
171
172       In this example, "Bar" isn't imported because it isn't a global -- it's
173       hidden inside the function Foo(). But Foo() is imported into Perl, and
174       it returns an instance of the "Bar" class. What happens then?
175
176       Whenever Inline::Python needs to return an instance of a class to Perl,
177       it generates an instance of Inline::Python::Object, the base class for
178       all Inline::Python objects. This base class knows how to do all the
179       things you need: calling methods, in this case.
180

Exceptions

182       Exceptions thrown in Python code get translated to Perl exceptions
183       which you can catch using eval.
184

Boolean

186       Python supports a Boolean type and two constants False and True. If one
187       of these is passed from Python to Perl, the value is represented by an
188       Inline::Python::Boolean object that uses overload to behave like 1 or
189       undef in boolean context in Perl. When this object is passed back to
190       Python, it is translated back to the False or True constant it
191       originated from.
192
193       To pass a Boolean value that originated from Perl to Python use the two
194       constants $Inline::Python::Boolean::true and
195       $Inline::Python::Boolean::false if it is important that the value is of
196       type Boolean in Python.
197

Using Perl inside Python (inside Perl)

199       This section doesn't talk at all about "Inline::Python". It's about how
200       to use "perl". "perl" is a Python module bundled with Inline::Python
201       that gives you access to Perl from inside your Python code. In the
202       future, it will be possible to compile Inline::Python to work the other
203       way around -- to use Python as the main programming language, and jump
204       into Perl when you want to.
205
206       The "perl" package exposes Perl packages and subs. It uses the same
207       code as Inline::Python to automatically translate parameters and return
208       values as needed. Packages and subs are represented as "PerlPkg" and
209       "PerlSub", respectively.
210

Using the PerlPkg Type

212       The "perl" package is actually not a package at all. As soon as you
213       import it, it replaces itself with an instance of the PerlPkg class,
214       wrapping the Perl package "main". Perl's 'main' package is analogous to
215       '__main__' in Python.
216
217       Here's what you can do with the 'main' PerlPkg:
218
219   eval()
220          eval(source code)
221
222       Unlike Python, Perl has no exec() -- the eval() function always returns
223       the result of the code it evaluated. eval() takes exactly one argument,
224       the perl source code, and returns the result of the evaluation.
225
226   require() and use()
227          require(module name)
228          use(module name)
229
230       Use require() instead of "import". In Python, you'd say this:
231
232          import md5
233
234       But using the perl module, you'd say this:
235
236          perl.require("Digest::MD5")
237
238       Of course, in Perl there's more than one way to do it (TM). require()
239       doesn't run the package's import() function. If you want symbols
240       exported, for instance, use use() instead of require().
241
242       Here is the functionality common to all PerlPkg instances:
243
244   __getattr__
245       Python's __getattr__() function allows the package to dynamically
246       return something to satisfy the request. For instance, you can get at
247       the subs in a perl package by using dir() (which is the same as
248       "getattr(perl, '__methods__')".
249
250       Here's an example:
251
252          perl.eval("sub f { 10 }")    # define main::f
253          f = perl.f
254          f(); f("hello")              # no argument checking
255          if perl.f() != 10:
256              import sys; sys.exit(1)
257
258       Notice what happens. First we call eval() to define a sub 'f'. Then we
259       say "perl.f", which goes into the __getattr__() method. We check the
260       Perl namespace and see a function called f, which we return, wrapped in
261       an instance of the PerlSub type.
262
263       Accessing a perl object's data
264
265       __getattr__ may also be used to access a Perl object's attributes, just
266       like Python allows. The Perl object just has to implement a sub
267       __getattr__ returning the requested attribute, which may even be
268       calculated on the fly.
269
270       An example for the common hash based objects:
271
272          sub __getattr__ {
273              my ($self, $attr) = @_;
274              return $self->{$attr};
275          }
276
277       This allows Python code to access the perl object's data like:
278
279          print my_perl_object.field_name
280
281   named arguments
282       When a Perl sub is called with named arguments from Python code,
283       Inline::Python follows the PyObject_Call protocol: positional arguments
284       are given as array ref followed by named arguments as a hash ref. A
285       Perl method supporting named arguments would therefore look like:
286
287           sub supports_named_arguments {
288               my ($self, $positional, $named) = @_;
289               foreach (qw( named1 named2 )) {
290                   last unless @$positional;
291                   $named->{$_} = shift @$positional;
292               }
293               ...
294           }
295
296       If this method is called using only positional arguments, they would
297       just be pushed into @_ like in any other method, complicating it to:
298
299           sub supports_named_arguments {
300               my ($self, $positional, $named) = @_;
301               if (@_ == 3 and $size and ref $size and ref $size eq 'ARRAY' and ref $useimage eq 'HASH') { # called using named parameters
302                   foreach (qw( named1 named2 ... )) {
303                       last unless @$positional;
304                       $named->{$_} = shift @$positional;
305                   }
306               }
307               else {
308                   $named = { named1 => $positional, named2 => $named, named3 => $_[3], ... };
309               }
310               ...
311           }
312
313       As this adds a lot of boiler plate code to subroutines, it is better to
314       just use Perl named arguments conventions (single hashref parameter) if
315       possible.
316

Using the PerlSub Type

318       All Perl subs are wrapped in the PerlSub type, so that they can emulate
319       Python subroutines. You can call them. It's all good. Here's what you
320       can do with PerlSub objects:
321
322   Call
323       PerlSub catches the call action and forwards the call to the real sub
324       in Perl.
325
326   Set the evaluation flags
327       Perl has this notion of calling context. A subroutine can ask Perl what
328       it is being used for. The idea is that if no one cares about your
329       return value, you might be able to save time by not building it. By
330       default, PerlSub objects evaluate in 'list' context with no extra flags
331       turned on.
332
333          perl.eval("sub f { 10 }")
334          f = perl.f
335          f.flags = f.flags | f.G_SCALAR
336          x = f()
337
338       Here are the most common flags you'll need. For more details about
339       these and other possible flags, see perlcall.
340
341       1.  G_VOID
342
343           Calls the Perl subroutine in a void context. Guarantees that no
344           results will be returned. If any are returned, Perl deletes them.
345
346       2.  G_SCALAR
347
348           Calls the Perl subroutine in a scalar context. Ensures that only
349           one element is returned from the sub. If the sub returns a list,
350           only the last element is actually saved.
351
352       3.  G_ARRAY
353
354           Calls the Perl subroutine in a list context. Ensures that any items
355           returned from the subroutine are returned. This is the default for
356           PerlSub objects.
357
358       4.  G_DISCARD
359
360           If you are not interested in the return values, you can optimize
361           slightly by telling Perl, and it will discard all returned values
362           for you.
363
364       5.  G_NOARGS
365
366           If you are not passing any arguments, you can optimize the call so
367           that Perl doesn't bother setting up the stack for parameters.
368
369       6.  G_EVAL
370
371           It is possible for the Perl sub to fail, either by calling die()
372           explicitly or by calling a non-existent sub. By default, the
373           process will terminate immediately. To avoid this happening, you
374           can trap the exception using the G_EVAL flag.
375

Under the Hood

377       When Inline::Python imports a class or function, it creates subs in
378       Perl which delegate the action to some C functions I've written, which
379       know how to call Python functions and methods.
380
381          use Inline Python => <<'END';
382
383          class Foo:
384             def __init__(self):
385                print "new Foo object being created"
386                self.data = {}
387             def get_data(self): return self.data
388             def set_data(self,dat):
389                self.data = dat
390
391          END
392
393       Inline::Python actually generates this code and eval()s it:
394
395          package main::Foo;
396          @main::Foo::ISA = qw(Inline::Python::Object);
397
398          sub new {
399            splice @_, 1, 0, "__main__", "Foo";
400            return &Inline::Python::py_new_object;
401          }
402
403          sub set_data {
404            splice @_, 1, 0, "set_data";
405            return &Inline::Python::py_call_method;
406          }
407
408          sub get_data {
409            splice @_, 1, 0, "get_data";
410            return &Inline::Python::py_call_method;
411          }
412
413          sub __init__ {
414            splice @_, 1, 0, "__init__";
415            return &Inline::Python::py_call_method;
416          }
417
418       More about those "py_*" functions, and how to generate this snippet of
419       code yourself, in the next section.
420

The Do-it-yourselfer's Guide to Inline::Python

422       Sometimes you don't actually want to do things the Inline Way. Maybe
423       you just want to use a Python class as-is, without ever treating it
424       like a normal Perl class:
425
426          use Inline::Python qw(py_eval);
427
428          py_eval(<<'END');
429
430          class MyClass:
431              def __init__(self): self.data = {}
432              def put(self, key, value): self.data[key] = value
433              def get(self, key):
434                  try: return self.data[key]
435                  except KeyError: return None
436
437          END
438
439          my $o = Inline::Python::Object->new('__main__', 'MyClass');
440          $o->put("candy", "yummy");
441          die "Ooops" unless $o->get("candy") eq 'yummy';
442
443       Inline::Python provides a full suite of exportable functions you can
444       use to manipulate Python objects and functions "directly".
445
446   py_eval()
447          py_eval("python source code", [context])
448
449       The new py_eval() behaves a little like Perl's eval(). It evaluates the
450       code or croaks on failure. The optional context argument can be used to
451       place restrictions on the type of code allowed, as well as influence
452       what happens to the result.
453
454       0   Accepts only expressions. Complete statements yield a syntax error.
455           An expression is anything that can appear to the right of an '='
456           sign. Returns the value of the expression.
457
458       1   The default. Accepts arbitrarily long input, which may be any valid
459           Python code. Always returns "undef".
460
461       2   Accepts exactly one statement, and prints the result to STDOUT.
462           This is how Python works in interactive mode. Always returns
463           "undef".
464
465   py_call_function()
466          py_call_function("package", "function", args...)
467
468       This function runs a Python function and returns the result. The
469       "package" and "function" uniquely identify a function, and the
470       remaining args are passed to the function.
471
472       Those who know Python well enough will know you can actually "run" a
473       class and get an instance of that class back. But in case that's just
474       too weird for you, I've given you a slightly higher-level wrapper
475       around that common idiom.
476
477   py_new_object()
478          py_new_object("perl package", "python package",
479                        "python class", args...)
480
481       This function creates an instance of a Python class. The "python class"
482       is the name of the class inside the "python package". The new object is
483       blessed into the given "perl package". The remaining args are passed
484       directly to the constructor.
485
486   py_call_method()
487          py_call_method(object, "method name", args...)
488
489       Given an instance of a Python class, this function can call a method on
490       it. This is useful if you have an object which is blessed into a non-
491       existent Perl package. Attempts to use Perl's object syntax would fail,
492       because Perl wouldn't find any methods in that package. But
493       py_call_method() can always perform method calls correctly since it
494       unwraps the underlying Python object.
495
496   eval_python()
497       Unlike in previous releases of Inline::Python, eval_python() can now
498       return the result of the code. As before, eval_python() is overloaded:
499
500       1.  eval_python(code, [context])
501
502           Evaluate the code using py_eval().
503
504       2.  eval_python(python package, function, args...)
505
506           Run the given function and return the results using
507           py_call_function().
508
509       3.  eval_python(object, method, args...)
510
511           Invoke the given method on the object using py_call_method() and
512           return the results.
513
514   py_bind_func()
515          py_bind_func("symbol name", "python package", "function")
516
517       This function imports a Python function (named "function") as the
518       symbol named by "perl symbol". After this function has been called, the
519       Python function can be called as if it were a Perl function in the
520       given package.
521
522          use Inline::Python qw(py_eval py_bind_func);
523
524          py_eval(<<'END');
525
526          def Foo():
527             return 42
528
529          END
530
531          # For the purposes of this example, so I know the package, I set it:
532          py_bind_func("main::Bar", "__main__", "Foo");
533          print "The meaning of life is: ", Bar(), "\n";
534
535       This call to py_bind_func() will generate this code and eval() it:
536
537          sub main::Bar {
538              unshift @_, "__main__", "Foo";
539              return &Inline::Python::py_call_function;
540          }
541
542   py_bind_class()
543          py_bind_class("perl package", "python package", "class", methods...)
544
545       This function imports a Python class (named "class") into the Perl
546       package named by "perl package". After this function has been called,
547       the Perl package will look just like a regular Perl class.
548
549       The example I showed earlier in the "Under the Hood" section shows the
550       output of py_bind_class. Here's another look at it:
551
552          use Inline::Python qw(py_eval py_bind_class);
553
554          py_eval(<<'END');
555
556          class Foo:
557             def __init__(self):
558                print "new Foo object being created"
559                self.data = {}
560             def get_data(self): return self.data
561             def set_data(self,dat):
562                self.data = dat
563
564          END
565
566          py_bind_class("main::Foo", "__main__", "Foo", "set_data", "get_data");
567          my $o = new Foo;
568
569       This call to py_bind_class() will generate this code and eval() it:
570
571          package main::Foo;
572          @main::Foo::ISA = qw(Inline::Python::Object);
573
574          sub new {
575            splice @_, 1, 0, "__main__", "Foo";
576            return &Inline::Python::py_new_object;
577          }
578
579          sub set_data {
580            splice @_, 1, 0, "set_data";
581            return &Inline::Python::py_call_method;
582          }
583
584          sub get_data {
585            splice @_, 1, 0, "get_data";
586            return &Inline::Python::py_call_method;
587          }
588
589       Note that if you want methods to be created as I've shown, you must
590       pass them to py_bind_class() yourself. It doesn't create anything
591       except new() and the @ISA array. It doesn't need to, since the base
592       class knows how to deal with any method call -- but it's also slower,
593       since it has to walk up the inheritance tree to the AUTOLOAD method. I
594       recommend binding to the functions you know about, especially if you're
595       the one writing the code.  If it's auto-generated, use
596       py_study_package(), described below.
597
598   py_study_package()
599          py_study_package(["package"])
600
601       This function interrogates the Python interpreter about the given
602       package (or '__main__' if you don't specify one). It returns a list of
603       key/value pairs, so it should be used like this:
604
605          py_eval('import pickle');
606          my %namespace = py_study_package("pickle");
607
608       On my machine, %namespace looks something like this:
609
610          $VAR1 = {
611                    'classes' => { ... },
612                    'functions' => [
613                                     '_keep_alive',
614                                     'loads',
615                                     'dump',
616                                     'load',
617                                     'dumps',
618                                     'test',
619                                     'whichmodule'
620                                   ]
621                  };
622
623       Each result can be fed to py_bind_function() and py_bind_class(), which
624       is exactly what Inline::Python itself does.
625
626   py_is_tuple()
627          my $array_ref = py_eval('(1, 2)')
628          $is_tuple = py_is_tuple($array_ref)
629
630       This function can tell you if the array reference you got from calling
631       some Python code was a tuple in Python or not (e.g. a normal array).
632       This can be useful if an API requires a distinction between those
633       cases. py_is_tuple works by looking for a magic marker put onto array
634       refs by Py2Pl. Bear in mind that this marker may get lost when copying
635       the array data.
636

SEE ALSO

638       For information about using "Inline", see Inline.
639
640       For information about other Inline languages, see Inline-Support.
641
642       Inline::Python's mailing list is inline@perl.org
643
644       To subscribe, send email to inline-subscribe@perl.org
645

BUGS AND DEFICIENCIES

647       This is a production quality release of Inline::Python. It is fairly
648       feature complete and runs stable with no known crasher bugs or memory
649       leaks. Further testing and expanded support for other operating systems
650       and platforms will be a focus for future releases.
651
652       When reporting a bug, please do the following:
653
654        - Put "use Inline REPORTBUG;" at the top of your code, or
655          use the command line option "perl -MInline=REPORTBUG ...".
656        - Run your code.
657        - Follow the printed instructions.
658
659       Here are some things to watch out for:
660
661       1.  Note that the namespace imported into Perl is NOT recursively
662           traversed. Only Python globals are imported into Perl --
663           subclasses, subfunctions, and other modules are not imported.
664
665           Example:
666
667              use Inline Python => <<'END';
668
669              import mymodule
670
671              class A:
672                  class B: pass
673
674              END
675
676           The namespace imported into perl is ONLY that related to "A".
677           Nothing related to "mymodule" or "B" is imported, unless some
678           Python code explicitly copies variables from the mymodule namespace
679           into the global namespace before Perl binds to it.
680

SUPPORTED PLATFORMS

682       Inline::Python has been tested on RedHat Linux 6.2 with a variety of
683       different Perl and Python configurations. It also seems to be running
684       pretty well on openSUSE at least from 10.3 to 13.1 and on Solaris.
685       Previous versions of Inline::Python worked on Windows and Cygwin --
686       this version has never been tested there. I strongly suspect it will
687       require patching. Please send me patches.
688
689       This version of Inline::Python has been tested with Python versions
690       from 2.5 to 2.7 and from 3.1 to 3.4.
691

PORTING YOUR INLINE PYTHON CODE FROM 2 TO 3

693       First of all, follow the Python guide from 2 to 3:
694       https://docs.python.org/3/howto/pyporting.html
695
696       For Perl integration:
697
698        - Non-utf8-flagged Perl strings will be Python bytes, utf8-flagged Perl strings will be Python string
699        - __cmp__ is no more supported in Python 3 and has been replaced by "rich comparison" (i.e. __eq__, __le__, etc.).
700       Since booleans in Perl are integers, renaming __cmp__ to __eq__ is often enough while wrapping a Perl object in Python.
701        - perl.require, perl.use and perl.eval accept either bytes or strings.
702

SOURCE REPOSITORY

704       The Github repository for this project is at
705       <https://github.com/niner/inline-python-pm>. Pull requests are welcome.
706

AUTHOR

708       Neil Watkiss <NEILW@cpan.org>
709
710       Brian Ingerson <INGY@cpan.org> is the author of Inline, Inline::C and
711       Inline::CPR. He was responsible for much encouragement and many
712       suggestions throughout the development of Inline::Python.
713
714       Eric Wilhelm provided support for 'new-style' classes in version 0.21.
715       Many thanks, Eric!
716
717       Stefan Seifert <NINE@cpan.org> fixed some bugs and is current co-
718       maintainer.
719
721       Copyright (c) 2001, Neil Watkiss.
722
723       All Rights Reserved. This module is free software. It may be used,
724       redistributed and/or modified under the same terms as Perl itself.
725
726       (see http://www.perl.com/perl/misc/Artistic.html)
727
728
729
730perl v5.30.0                      2019-07-26                         Python(3)
Impressum