.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Python::Object 3"
.TH Python::Object 3 "2021-04-27" "perl v5.32.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Python::Object \- Encapuslate python objects
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& my $dict = Python::dict(foo => 42);
\&
\& # attribute access
\& print $dict\->foo, "\en"; # get
\& $dict\->bar(84);
\&
\& # boolean context
\& if ($dict) {
\& # ...
\& }
\&
\& # automatic stringify
\& print $dict
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Instances of the \f(CW\*(C`Python::Object\*(C'\fR 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.
.PP
Various functions in the \f(CW\*(C`Python::\*(C'\fR namespace provide means for
creation and maniplation of \f(CW\*(C`Python::Object\*(C'\fR instances. See
Python for details.
.PP
The \f(CW\*(C`Python::Object\*(C'\fR class provide \s-1AUTOLOAD\s0 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.
.SS "Attribute access and method calls"
.IX Subsection "Attribute access and method calls"
Python object attributes can be manipulated with the \fBgetattr()\fR,
\&\fBsetattr()\fR, \fBhasattr()\fR and \fBdelattr()\fR functions found in the \f(CW\*(C`Python\*(C'\fR
package, but usually it is more convenient to rely on the automatic
mapping from method calls to attribute access operations:
.ie n .IP "$o\->foo" 4
.el .IP "\f(CW$o\fR\->foo" 4
.IX Item "$o->foo"
This will read the attribute called \*(L"foo\*(R", i.e. is a shorthand for
getattr($o, \*(L"foo\*(R") in most cases. If the attribute is callable, then
it will be automatically called as well.
.ie n .IP "$o\->foo(42)" 4
.el .IP "\f(CW$o\fR\->foo(42)" 4
.IX Item "$o->foo(42)"
This will try to set the value of attribute \*(L"foo\*(R" to be 42, i.e. it is
a shorthand for setattr($o, \*(L"foo\*(R" => 42), with the difference that it
will return the old value of the attribute as well.
.Sp
If the \*(L"foo\*(R" attribute happen to be callable then this will be
resolved as a plain method call with a single argument instead.
.ie n .IP "$o\->foo(""bar"", ""baz"")" 4
.el .IP "\f(CW$o\fR\->foo(``bar'', ``baz'')" 4
.IX Item "$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:
.Sp
.Vb 1
\& funcall(getattr($o, "foo"), "bar", "baz")
.Ve
.PP
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:
.PP
.Vb 3
\& foreach ($o\->method_returning_a_list) {
\& # do something with each element
\& }
.Ve
.PP
In the same way, a mapping object in list context is unwrapped into
separate key/value pairs. I.e. this should work as expected:
.PP
.Vb 1
\& %hash = $o\->method_return_a_dictinary;
.Ve
.PP
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:
.PP
.Vb 1
\& $o\->foo($pos1, $pos2, *key1 => $val1, *key2 => $val2);
.Ve
.PP
or make a special hash object constructed with \fBPython::KW()\fR the last
argument:
.PP
.Vb 1
\& $o\->foo($pos1, $pos2, Python::KW(key1 => $val1, key2 => $val2));
.Ve
.PP
The \s-1\fBKW\s0()\fR function can be imported to reduce clutter in the argument
list:
.PP
.Vb 4
\& use Python qw(KW);
\& $o\->foo($pos1, $pos2,
\& KW(key1 => $val1, key2 => $val2)
\& );
.Ve
.PP
Note: One of these ways of specifying keyword arguments might be
dropped in the final version of this interface.
.SS "Overloading"
.IX Subsection "Overloading"
The \f(CW\*(C`Python::Object\*(C'\fR 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 \f(CW$list\fR is a reference to a \f(CW\*(C`Python::Object\*(C'\fR wrapping a
list then statements like these are allowed:
.PP
.Vb 4
\& @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;
.Ve
.PP
Correspondingly, a python dictionary \f(CW$dict\fR can be used like this:
.PP
.Vb 5
\& @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};
.Ve
.PP
We also provide code dereferencing which make it possible to invoke
objects directly:
.PP
.Vb 1
\& $callable\->("foo"); # same as funcall($callable, "foo")
.Ve
.PP
For objects used in string context, the \fBstr()\fR function will be
automatically invoked.
.PP
.Vb 1
\& "$obj"; # same as str($obj)
.Ve
.PP
For objects used in boolean context, the \fBPyObject_IsTrue()\fR function
will be automatically invoked.
.PP
.Vb 1
\& if ($obj) { ...} # same as if (PyObject_IsTrue($obj)) { ...}
.Ve
.SH "BUGS"
.IX Header "BUGS"
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 \fBgetattr()\fR and \fBsetattr()\fR.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
(C) 2000\-2001 ActiveState
.PP
This code is distributed under the same terms as Perl; you can
redistribute it and/or modify it under the terms of either the \s-1GNU\s0
General Public License or the Artistic License.
.PP
\&\s-1THIS SOFTWARE IS PROVIDED BY ACTIVESTATE\s0 `\s-1AS IS\s0'' \s-1AND ANY EXPRESSED OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED.\s0 \s-1IN NO EVENT SHALL ACTIVESTATE OR ITS CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES\s0 (\s-1INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES\s0; \s-1LOSS OF USE, DATA, OR PROFITS\s0; \s-1OR
BUSINESS INTERRUPTION\s0) \s-1HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT\s0 (\s-1INCLUDING NEGLIGENCE
OR OTHERWISE\s0) \s-1ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\s0
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Python, Python::Err, perlmodule