1Python(3) User Contributed Perl Documentation Python(3)
2
6 Inline::Python - Write Perl subs and classes in Python.
7
9 print "9 + 16 = ", add(9, 16), "\n";
10 print "9 - 16 = ", subtract(9, 16), "\n";
11 use Inline Python => <<'END_OF_PYTHON_CODE';
13 def add(x,y):
14 return x + y
15 def subtract(x,y):
17 return x - y
18 END_OF_PYTHON_CODE
20
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 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
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 See the Changes file for new features in recent versions.
41
43 Using Inline::Python will seem very similar to using another Inline
44 language, thanks to Inline's consistent look and feel.
45 This section will explain the different ways to use Inline::Python.
47 For more details on "Inline", see 'perldoc Inline'.
48 Giving Your Source to Inline
50 The most basic form for using "Inline::Python" is this:
51 use Inline Python => 'Python source code';
53 Of course, you can use Perl's "here document" style of quoting to make
55 the code slightly easier to read:
56 use Inline Python => <<'END';
58 Python source code goes here.
60 END
62 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 use Inline Python;
69 ...
71 __END__
73 __Python__
74 Python source code goes here.
76 This information is detailed in 'perldoc Inline'.
78 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 use Inline Python;
84 doit();
86 __END__
88 __Python__
89 from mylibrary import doit
91 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 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 use Inline Python;
102 my $obj = new Myclass;
104 __END__
106 __Python__
107 from mylibrary import myclass as Myclass
109 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 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 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 In other cases, you may be writing Inline::Python code as follows:
130 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 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 # Class is defined as 'def Class(float):'
147 my $obj = Class->new(4);
148 print $$obj, "\n"; # will NOT print '4.0'
149 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 Of course you can! Check this out:
156 use Inline Python => <<END;
158 def Foo():
160 class Bar:
161 def __init__(self):
162 print "new Bar()"
163 def tank(self):
164 return 10
165 return Bar()
166 END
168 my $o = Foo();
170 print $o->tank(), "\n";
171 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 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
182 Exceptions thrown in Python code get translated to Perl exceptions
183 which you can catch using eval.
184
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 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
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 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
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 Here's what you can do with the 'main' PerlPkg:
218 eval()
220 eval(source code)
221 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 require() and use()
227 require(module name)
228 use(module name)
229 Use require() instead of "import". In Python, you'd say this:
231 import md5
233 But using the perl module, you'd say this:
235 perl.require("Digest::MD5")
237 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 Here is the functionality common to all PerlPkg instances:
243 __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 Here's an example:
251 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 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 Accessing a perl object's data
264 __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 An example for the common hash based objects:
271 sub __getattr__ {
273 my ($self, $attr) = @_;
274 return $self->{$attr};
275 }
276 This allows Python code to access the perl object's data like:
278 print my_perl_object.field_name
280 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 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 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 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 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
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 Call
323 PerlSub catches the call action and forwards the call to the real sub
324 in Perl.
325 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 perl.eval("sub f { 10 }")
334 f = perl.f
335 f.flags = f.flags | f.G_SCALAR
336 x = f()
337 Here are the most common flags you'll need. For more details about
339 these and other possible flags, see perlcall.
340 1. G_VOID
342 Calls the Perl subroutine in a void context. Guarantees that no
344 results will be returned. If any are returned, Perl deletes them.
345 2. G_SCALAR
347 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 3. G_ARRAY
353 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 4. G_DISCARD
359 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 5. G_NOARGS
365 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 6. G_EVAL
370 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
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 use Inline Python => <<'END';
382 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 END
392 Inline::Python actually generates this code and eval()s it:
394 package main::Foo;
396 @main::Foo::ISA = qw(Inline::Python::Object);
397 sub new {
399 splice @_, 1, 0, "__main__", "Foo";
400 return &Inline::Python::py_new_object;
401 }
402 sub set_data {
404 splice @_, 1, 0, "set_data";
405 return &Inline::Python::py_call_method;
406 }
407 sub get_data {
409 splice @_, 1, 0, "get_data";
410 return &Inline::Python::py_call_method;
411 }
412 sub __init__ {
414 splice @_, 1, 0, "__init__";
415 return &Inline::Python::py_call_method;
416 }
417 More about those "py_*" functions, and how to generate this snippet of
419 code yourself, in the next section.
420
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 use Inline::Python qw(py_eval);
427 py_eval(<<'END');
429 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 END
438 my $o = Inline::Python::Object->new('__main__', 'MyClass');
440 $o->put("candy", "yummy");
441 die "Ooops" unless $o->get("candy") eq 'yummy';
442 Inline::Python provides a full suite of exportable functions you can
444 use to manipulate Python objects and functions "directly".
445 py_eval()
447 py_eval("python source code", [context])
448 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 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 1 The default. Accepts arbitrarily long input, which may be any valid
459 Python code. Always returns "undef".
460 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 py_call_function()
466 py_call_function("package", "function", args...)
467 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 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 py_new_object()
478 py_new_object("perl package", "python package",
479 "python class", args...)
480 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 py_call_method()
487 py_call_method(object, "method name", args...)
488 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 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 1. eval_python(code, [context])
501 Evaluate the code using py_eval().
503 2. eval_python(python package, function, args...)
505 Run the given function and return the results using
507 py_call_function().
508 3. eval_python(object, method, args...)
510 Invoke the given method on the object using py_call_method() and
512 return the results.
513 py_bind_func()
515 py_bind_func("symbol name", "python package", "function")
516 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 use Inline::Python qw(py_eval py_bind_func);
523 py_eval(<<'END');
525 def Foo():
527 return 42
528 END
530 # 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 This call to py_bind_func() will generate this code and eval() it:
536 sub main::Bar {
538 unshift @_, "__main__", "Foo";
539 return &Inline::Python::py_call_function;
540 }
541 py_bind_class()
543 py_bind_class("perl package", "python package", "class", methods...)
544 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 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 use Inline::Python qw(py_eval py_bind_class);
553 py_eval(<<'END');
555 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 END
565 py_bind_class("main::Foo", "__main__", "Foo", "set_data", "get_data");
567 my $o = new Foo;
568 This call to py_bind_class() will generate this code and eval() it:
570 package main::Foo;
572 @main::Foo::ISA = qw(Inline::Python::Object);
573 sub new {
575 splice @_, 1, 0, "__main__", "Foo";
576 return &Inline::Python::py_new_object;
577 }
578 sub set_data {
580 splice @_, 1, 0, "set_data";
581 return &Inline::Python::py_call_method;
582 }
583 sub get_data {
585 splice @_, 1, 0, "get_data";
586 return &Inline::Python::py_call_method;
587 }
588 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 py_study_package()
599 py_study_package(["package"])
600 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 py_eval('import pickle');
606 my %namespace = py_study_package("pickle");
607 On my machine, %namespace looks something like this:
609 $VAR1 = {
611 'classes' => { ... },
612 'functions' => [
613 '_keep_alive',
614 'loads',
615 'dump',
616 'load',
617 'dumps',
618 'test',
619 'whichmodule'
620 ]
621 };
622 Each result can be fed to py_bind_function() and py_bind_class(), which
624 is exactly what Inline::Python itself does.
625 py_is_tuple()
627 my $array_ref = py_eval('(1, 2)')
628 $is_tuple = py_is_tuple($array_ref)
629 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
638 For information about using "Inline", see Inline.
639 For information about other Inline languages, see Inline-Support.
641 Inline::Python's mailing list is inline@perl.org
643 To subscribe, send email to inline-subscribe@perl.org
645
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 When reporting a bug, please do the following:
653 - 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 Here are some things to watch out for:
660 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 Example:
666 use Inline Python => <<'END';
668 import mymodule
670 class A:
672 class B: pass
673 END
675 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
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 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
693 First of all, follow the Python guide from 2 to 3:
694 https://docs.python.org/3/howto/pyporting.html
695 For Perl integration:
697 - 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
704 The Github repository for this project is at
705 <https://github.com/niner/inline-python-pm>. Pull requests are welcome.
706
708 Neil Watkiss <NEILW@cpan.org>
709 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 Eric Wilhelm provided support for 'new-style' classes in version 0.21.
715 Many thanks, Eric!
716 Stefan Seifert <NINE@cpan.org> fixed some bugs and is current co-
718 maintainer.
719
721 Copyright (c) 2001, Neil Watkiss.
722 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 (see http://www.perl.com/perl/misc/Artistic.html)
727perl v5.34.0 2021-08-19 Python(3)