Perl 6 By Example: Idiomatic Use of Inline::Python

This blog post is part of my ongoing project
to write a book about Perl 6.

If you’re interested, either in this book project or any other Perl 6 book news, please sign up for the mailing list at the bottom of
the article, or here. It will be
low volume (less than an email per month, on average).


In the two
previous
installments,
we’ve seen Python libraries being used in Perl 6 code through the
Inline::Python module. Here
we will explore some options to make the Perl 6 code more idiomatic and
closer to the documentation of the Python modules.

Types of Python APIs

Python is an object-oriented language, so many APIs involve method
calls, which Inline::Python helpfully automatically translates for us.

But the objects must come from somewhere and typically this is by
calling a function that returns an object, or by instantiating a class.
In Python, those two are really the same under the hood, since
instantiating a class is the same as calling the class as if it were a
function.

An example of this (in Python) would be

from matplotlib.pyplot import subplots
result = subplots()

But the matplotlib documentation tends to use another, equivalent
syntax:

import matplotlib.pyplot as plt
result = plt.subplots()

This uses the subplots symbol (class or function) as a method on the
module matplotlib.pyplot, which the import statement aliases to plt.
This is a more object-oriented syntax for the same API.

Mapping the Function API

The previous code examples used this Perl 6 code to call the subplots
symbol:

my $py = Inline::Python.new;
$py.run('import matplotlib.pyplot');
sub plot(Str $name, |c) {
    $py.call('matplotlib.pyplot', $name, |c);
}

my ($figure, $subplots) = plot('subplots');

If we want to call subplots() instead of plot('subplots'), and
bar(args) instead of `plot(‘bar’, args), we can use a function to
generate wrapper functions:

my $py = Inline::Python.new;

sub gen(Str $namespace, *@names) {
    $py.run("import $namespace");

    return @names.map: -> $name {
        sub (|args) {
            $py.call($namespace, $name, |args);
        }
    }
}

my (&subplots, &bar, &legend, &title, &show)
    = gen('matplotlib.pyplot', <subplots bar legend title show>);

my ($figure, $subplots) = subplots();

# more code here

legend($@plots, $@top-authors);
title('Contributions per day');
show();

This makes the functions’ usage quite nice, but comes at the cost
of duplicating their names. One can view this as a
feature, because it allows the creation of different aliases, or as a
source for bugs when the order is messed up, or a name misspelled.

How could we avoid the duplication should we choose to create wrapper
functions?

This is where Perl 6’s flexibility and introspection abilities pay off.
There are two key components that allow a nicer solution: the fact that
declarations are expressions and that you can introspect variables for
their names.

The first part means you can write mysub my ($a, $b), which
declares the variables $a and $b, and calls a function with those
variables as arguments. The second part means that $a.VAR.name returns
a string '$a', the name of the variable.

Let’s combine this to create a wrapper that initializes subroutines for
us:

sub pysub(Str $namespace, |args) {
    $py.run("import $namespace");

    for args[0] <-> $sub {
        my $name = $sub.VAR.name.substr(1);
        $sub = sub (|args) {
            $py.call($namespace, $name, |args);
        }
    }
}

pysub 'matplotlib.pyplot',
    my (&subplots, &bar, &legend, &title, &show);

This avoids duplicating the name, but forces us to use some lower-level
Perl 6 features in sub pysub. Using ordinary variables means that accessing their
.VAR.name results in the name of the variable, not the name of the
variable that’s used on the caller side. So we can’t use slurpy
arguments as in

sub pysub(Str $namespace, *@subs)

Instead we must use
|args to obtain the rest of the arguments in a
Capture. This doesn’t
flatten the list of variables passed to the function, so when we iterate
over them, we must do so by accessing args[0]. By default, loop
variables are read-only, which we can avoid by using <-> instead of
-> to introduce the signature. Fortunately, that also preserves the
name of the caller side variable.

An Object-Oriented Interface

Instead of exposing the functions, we can also create types that emulate
the method calls on Python modules. For that we can implement a class with a
method FALLBACK, which Perl 6 calls for us when calling a method that is not
implemented in the class:

class PyPlot is Mu {
    has $.py;
    submethod TWEAK {
        $!py.run('import matplotlib.pyplot');
    }
    method FALLBACK($name, |args) {
        $!py.call('matplotlib.pyplot', $name, |args);
    }
}

my $pyplot = PyPlot.new(:$py);
my ($figure, $subplots) = $pyplot.subplots;
# plotting code goes here
$pyplot.legend($@plots, $@top-authors);

$pyplot.title('Contributions per day');
$pyplot.show;

Class PyPlot inherits directly from Mu, the root of the Perl 6 type
hierarchy, instead of Any, the default parent class (which in turn inherits
from Mu). Any introduces a large number of methods that Perl 6 objects
get by default and since FALLBACK is only invoked when a method is not
present, this is something to avoid.

The method TWEAK is another method that
Perl 6 calls automatically for us, after the object has been fully
instantiated. All-caps method names are reserved for such special purposes.
It is marked as a submethod, which means it is not inherited into subclasses.
Since TWEAK is called at the level of each class, if it were a regular
method, a subclass would call it twice implicitly. Note that TWEAK is only
supported in Rakudo version 2016.11 and later.

There’s nothing specific to the Python package matplotlib.pyplot in class
PyPlot, except the namespace name. We could easily generalize it to any
namespace:

class PythonModule is Mu {
    has $.py;
    has $.namespace;
    submethod TWEAK {
        $!py.run("import $!namespace");
    }
    method FALLBACK($name, |args) {
        $!py.call($!namespace, $name, |args);
    }
}

my $pyplot = PythonModule.new(:$py, :namespace<matplotlib.pyplot>);

This is one Perl 6 type that can represent any Python module. If instead we
want a separate Perl 6 type for each Python module, we could use roles, which
are optionally parameterized:

role PythonModule[Str $namespace] is Mu {
    has $.py;
    submethod TWEAK {
        $!py.run("import $namespace");
    }
    method FALLBACK($name, |args) {
        $!py.call($namespace, $name, |args);
    }
}

my $pyplot = PythonModule['matplotlib.pyplot'].new(:$py);

Using this approach, we can create type constraints for Python modules in
Perl 6 space:

sub plot-histogram(PythonModule['matplotlib.pyplot'], @data) {
    # implementation here
}

Passing in any other wrapped Python module than matplotlib.pyplot results
in a type error.

Summary

Perl 6 offers enough flexibility to create function and method call APIs
around Python modules. With a bit of meta programming, we can emulate the
typical Python APIs close enough that translating from the Python
documentation to Perl 6 code becomes easy.

Subscribe to the Perl 6 book mailing list

* indicates required

  • Article By :

Random Article You May Like

Leave a Reply

Your email address will not be published. Required fields are marked *

*
*