Python::Object - Encapuslate python objects

pyperl documentation Contained in the pyperl distribution.

Index

Code Index:

NAME

Top

Python::Object - Encapuslate python objects

SYNOPSIS

Top

    my $dict = Python::dict(foo => 42);

    # attribute access
    print $dict->foo, "\n";    # get
    $dict->bar(84);

    # boolean context
    if ($dict) {
	# ...
    }

    # automatic stringify
    print $dict

DESCRIPTION

Top

Instances of the Python::Object class encapulate objects within the python interpreter. All builtin python datatypes as well as user defined classes, instances, extention types, and functions are python objects.

Various functions in the Python:: namespace provide means for creation and maniplation of Python::Object instances. See Python for details.

The Python::Object class provide AUTOLOAD and overload features that make it convenient to use python objects as if they where native perl objects. A python sequence object (like a list or a tuple) can basically be treated as if it was a perl array. A python mapping object can be treaded as a hash, and callable objects can be called directly as if they where perl code references. Python objects also turn into strings if used in string context or into a reasonable test in boolean context.

Attribute access and method calls

Python object attributes can be manipulated with the getattr(), setattr(), hasattr() and delattr() functions found in the Python package, but usually it is more convenient to rely on the automatic mapping from method calls to attribute access operations:

$o->foo

This will read the attribute called "foo", i.e. is a shorthand for getattr($o, "foo") in most cases. If the attribute is callable, then it will be automatically called as well.

$o->foo(42)

This will try to set the value of attribute "foo" to be 42, i.e. it is a shorthand for setattr($o, "foo" => 42), with the difference that it will return the old value of the attribute as well.

If the "foo" attribute happen to be callable then this will be resolved as a plain method call with a single argument instead.

$o->foo("bar", "baz")

If multiple arguments are passed to a method then it will always be resolved as a method call, i.e. this is always just a short hand for:

  funcall(getattr($o, "foo"), "bar", "baz")

As an additional convenience, if an attribute is accessed in list context and the object to be returned is some python sequence, then the sequence is unwrapped and the elements are returned as a perl list. That helps in making code like this work as expected:

   foreach ($o->method_returning_a_list) {
       # do something with each element
   }

In the same way, a mapping object in list context is unwrapped into separate key/value pairs. I.e. this should work as expected:

   %hash = $o->method_return_a_dictinary;

Keyword arguments are also supported for methods called this way. There are currently two ways to set them up. Either use globs to indicate keys:

   $o->foo($pos1, $pos2, *key1 => $val1, *key2 => $val2);

or make a special hash object constructed with Python::KW() the last argument:

  $o->foo($pos1, $pos2, Python::KW(key1 => $val1, key2 => $val2));

The KW() function can be imported to reduce clutter in the argument list:

  use Python qw(KW);
  $o->foo($pos1, $pos2,
	  KW(key1 => $val1, key2 => $val2)
	 );

Note: One of these ways of specifying keyword arguments might be dropped in the final version of this interface.

Overloading

The Python::Object class use perl's overloading mechanism to make instances behave like perl data. Python sequence objects can be treated like perl arrays and python mapping object can be treated like hashes. If $list is a reference to a Python::Object wrapping a list then statements like these are allowed:

   @array = @$list;     # copy list elements into a perl array
   $list->[0];          # same as getitem($list, 0)
   $list->[0] = 42;     # same as setitem($list, 0, 42)
   pop(@$list);         # same as $list->pop;

Correspondingly, a python dictionary $dict can be used like this:

   @array = %$dict;     # copy key/value pairs out of the dictionary
   $dict->{foo};        # same as getitem($dict, "foo")
   $dict->{foo} = 42;   # same as setitem($dict, "foo", 42)
   delete $dict->{foo}; # same as delitem($dict, "foo")
   exists $dict->{foo};

We also provide code dereferencing which make it possible to invoke objects directly:

   $callable->("foo");  # same as funcall($callable, "foo")

For objects used in string context, the str() function will be automatically invoked.

  "$obj";               # same as str($obj)

For objects used in boolean context, the PyObject_IsTrue() function will be automatically invoked.

  if ($obj) { ...}     # same as if (PyObject_IsTrue($obj)) { ...}

BUGS

Top

Some all upper case method names (see perltie) are used by the overload/tie interface and will hide the corresponding python attribute in the object. If you need to access an attribute with a name clash, you need to use functions like getattr() and setattr().

COPYRIGHT

Top

(C) 2000-2001 ActiveState

This code is distributed under the same terms as Perl; you can redistribute it and/or modify it under the terms of either the GNU General Public License or the Artistic License.

THIS SOFTWARE IS PROVIDED BY ACTIVESTATE `AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL ACTIVESTATE OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

SEE ALSO

Top

Python, Python::Err, perlmodule

pyperl documentation Contained in the pyperl distribution. 
# Copyright 2000-2001 ActiveState

package Python::Object;

use strict;
use vars qw(@ISA $VERSION $AUTOLOAD);

require DynaLoader;
@ISA = qw(DynaLoader);

require Carp;

use overload '""'   => \&Python::PyObject_Str,
             'bool' => \&Python::PyObject_IsTrue,
             '@{}'  => sub { my @a; tie @a, "Python::Object", @_; \@a },
             '%{}'  => sub { my %h; tie %h, "Python::Object::Hash", @_; \%h },
             '&{}'  => sub { my $self = shift;
                             return sub {
				 Python::PyObject_CallObject($self, @_);
			     }
                           };

$VERSION = '1.00';

Python::Object->bootstrap($VERSION);

# We could have moved these methods to the Python::Object::Array
# namespace, but that would mean one more level of indirection and is
# probably not worth it.
sub TIEARRAY { $_[1] }

*FETCH = \&Python::PyObject_GetItem;
*STORE = \&Python::PyObject_SetItem;
*FETCHSIZE = \&Python::PyObject_Length;

sub PUSH {
    my $o = shift;
    while (@_) {
	$o->append(shift);
    }
}

sub UNSHIFT {
    my $o = shift;
    while (@_) {
	$o->insert(0, pop);
    }
}

sub POP {
    shift->pop();
}

sub SHIFT {
    shift->pop(0);
}


sub SPLICE {
    my $o = shift;
    my $olen = FETCHSIZE($o);
    my $offset = @_ ? shift : 0;
    if ($offset < 0) {
	$offset += $olen;
	die "offset outside" if $offset < 0;
    }
    elsif ($offset > $olen) {
	$offset = $olen;
    }
    my $len = @_ ? shift : $olen - $offset;
    if ($len < 0) {
	$len = $olen - $offset + $len;
	$len = 0 if $len < 0;
    }
    elsif ($offset + $len > $olen) {
	$len = $olen - $offset;
    }

    # take out
    my @old;
    push(@old, $o->pop($offset)) while $len--;

    # put back
    while (@_) {
	$o->insert($offset, pop);
    }

    return @old;
}

sub EXISTS {
    eval { &FETCH; };
    return !$@;
}

sub DELETE {
    my $old = &FETCH;
    &Python::PyObject_DelItem;
    $old;
}

sub DESTROY { }


# The following AUTOLOAD provide a more convenient way to access
# attributes that mimic the normal way to give attribute access in
# perl.
#
#   $obj->foo
#
# will return an attribute or call a method.  An exception will be
# raised if the object does not have such an attribute.
#
#   $obj->foo(42)
#
# will set an attribute or call a method
#
#  $obj->foo(3,4)
#
# will always be treated as a method call.

sub AUTOLOAD {
    my $self = shift;
    my $method = substr($AUTOLOAD, rindex($AUTOLOAD, '::')+2);
    Carp::croak("No static method $method for $self") unless ref($self);
    if (@_ == 1 && !Python::hasattr($self, $method)) {
	Python::setattr($self, $method, $_[0]);
	return;
    }
    my $attr = Python::getattr($self, $method);
    if (@_ > 1 || Python::PyCallable_Check($attr)) {
	my $kw;
	# I could not really decide on what way to support
	# keyword arguments to python methods, so I ended up
	# with two ways for now.
	if (@_ && UNIVERSAL::isa($_[-1], "Python::Keywords")) {
	    $kw = pop(@_);
	}
	else {
	    while (@_ >= 2 && ref(\$_[-2]) eq "GLOB") {
		my($key, $val) = splice(@_, -2);
		$kw->{substr($key, rindex($key, "::")+2)} = $val;
	    }
	}
	$attr = Python::apply($attr, \@_, $kw);
    }
    elsif (@_ == 1) {
	Python::setattr($self, $method, @_);
    }

    if (wantarray) {
	return @$attr if Python::PySequence_Check($attr);
	return %$attr if Python::PyMapping_Check($attr);
    }

    return $attr;
}

package Python;

# set up some aliases
*hasattr = \&PyObject_HasAttr;
*getattr = \&PyObject_GetAttr;
*setattr = \&PyObject_SetAttr;
*delattr = \&PyObject_DelAttr;

# should we??
*getitem = \&PyObject_GetItem;
*setitem = \&PyObject_SetItem;
*delitem = \&PyObject_DelItem;

*str   = \&PyObject_Str;
*repr  = \&PyObject_Repr;
*cmp   = \&PyObject_Compare;
*type  = \&PyObject_Type;
*hash  = \&PyObject_Hash;
*len   = \&PyObject_Length;

*funcall = \&PyObject_CallObject;  # a bit Lisp influence here :-)
*apply   = \&PyEval_CallObjectWithKeywords;
*Import  = \&PyImport_ImportModule;

sub KW {
    bless Python::dict(@_), "Python::Keywords";
}

require Exporter;
*import = \&Exporter::import;

our @EXPORT_OK = qw(hasattr getattr setattr delattr
                    getitem setitem delitem
                    str repr cmp type hash len
                    exec eval
                    funcall apply
                    Import
                    KW
                   );

package Python::Keywords;

use vars qw(@ISA);
@ISA=qw(Python::Object);

package Python::Object::Hash;

# Helper class because we need to keep keys during iteration

require Carp;

sub TIEHASH {
    my($class, $obj) = @_;
    Carp::croak("Can't treat non-mapping object as hash")
	  unless Python::PyMapping_Check($obj);

    # We use an array as our object representation. The first element is the
    # Python dictionary and the rest are the remaining keys in reverse order.
    bless [$obj], $class;
}

sub FETCH {
    $_[0] = $_[0][0];
    &Python::PyObject_GetItem;
}

sub EXISTS {
    $_[0][0]->has_key($_[1]);
}

sub STORE {
    $_[0] = $_[0][0];
    &Python::PyObject_SetItem;
}

sub DELETE {
    $_[0] = $_[0][0];
    my $old = &Python::PyObject_GetItem;
    &Python::PyObject_DelItem;
    $old;
}

sub CLEAR {
    my $self = shift;
    $self->[0]->clear;
    splice(@$self, 1);  # remove key state
}

sub FIRSTKEY {
    my $self = shift;
    my $dict = $self->[0];
    @$self = ($dict, reverse $dict->keys);
    NEXTKEY($self);
}

sub NEXTKEY {
    my $self = shift;
    return if @$self == 1;
    pop(@$self);
}


package Python::Err;

use overload '""'   => \&as_string,
             'bool' => \&as_bool;

1;

__END__