NAME

Python::Object - Encapuslate python objects

SYNOPSIS

    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

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 the Python manpage 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

Some all upper case method names (see the perltie manpage) 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

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.