[Python-Dev] Python's C interface for types

[Thomas Wouters]

On 1/26/07, Nick Maclaren <nmm1 at cus.cam.ac.uk> wrote:

> Does Python use classic division (nb_divide) and inversion (nb_invert)
> or are they entirely historical?  Note that I can very easily provide
> the latter.


nb_divide is used for the division operation (/) when not using 'from
__future__ import division', and PyNumber_Divide(). It doesn't fall back to
foor_divide or true_divide.
nb_invert is used for bitwise inversion (~) and PyNumber_Invert(). It's not
historical, it's actual.

Is there any documentation on the coercion function (nb_coerce)?  It
> seems to have unusual properties.


I don't recall ever seeing useful documentation on coerce() and nb_coerce. I
suggest not to use it; it's gone in Python 3.0 anyway.

How critical is the 'numeric' property of the nb_hash function?  I
> can certainly honour it, but is it worth it?


Which numeric property? the fact that it returns a C long? Or that, for
natural numbers, it *seems* to return self? The former is quite important,
the latter not very. The important bit is that an object's hash() be equal
to the hash() of objects that it is considered equal to. That is to say, if
you have 'd = {5: "five"}' and you want 'f = yourtype(5); d[f]' to result in
"five", hash(f) must be equal to hash(5). The builtin floats do that.
There's no strict requirement that equal objects must have equal hashes, but
people using sets and dicts really appreciate it. ('f == 5 and f not in
set([5])' to be True would be confusing.)

I assume that Python will call nb_richcompare if defined and
> nb_compare if not.  Is that right?


Yes.

Are the inplace methods used and, if so, what is their specification?


(Hah, my specialty.) Inplace methods are used for the augmented-assignment
statements: '+=' and the like. They are free to modify 'self' or return a
new object. Python falls back to the normal, non-inplace operations if the
inplace methods are not defined. I assume your floating-point type is
immutable, so you won't have to implement them. (If the type is to be
mutable, don't forget to make them unhashable, by not defining nb_hash.)

I assume that I can ignore all of the allocation, deallocation and
> attribute handling functions, as the default for a VAR object is
> fine.  That seems to work.
>
> Except for one thing!  My base type is static, but I create some
> space for every derivation (and it can ONLY be used in derived form).
> The space creation is donein C but the derivation in Python.  I
> assume that I need a class (not instance) destructor, but what
> should it do to free the space?  Call C to Py_DECREF it?


Where do you allocate this space, and how do you allocate it? If it's space
you malloc() and store somewhere in the type struct, yecchh. You should not
just allocate stuff at the end of the type struct, as the type struct's
layout is not under your control (we actually extend the type struct as
needed, which is why newer features end up in less logical places at the end
of the struct ;) I would suggest using attributes of the type instead, with
the normal Python refcounting. That means the 'extra space' has to be an
actual Python object, though.


I assume that a class structure will never go away until after all
> instances have gone away (unless I use Py_DECREF), so a C pointer
> from an instance to something owned by the class is OK.


Correct.

Is there any documentation on how to support marshalling/pickling
> and the converse from C types?


I don't you can make your own type marshallable. For pickle it's more or
less the same as for Python types. The pickle docs (and maybe
http://www.python.org/dev/peps/pep-0307/) probably cover what you want to
know. You can also look at one of the complexer builtin types that support
pickling, like the datetime types.

I would quite like to provide some attributes.  They are 'simple'
> but need code executing to return them.  I assume that means that
> they aren't simple enough, and have to be provided as methods
> (like conjugate).  That's what I have done, anyway.


You can use PyGetSetDef to get 'easy' attributes with getters and setters.
http://docs.python.org/api/type-structs.html#l2h-1020

Is there any obvious place for a reduction method to be hooked in?
> That is a method that takes a sequence, all members of which must
> be convertible to a single class, and returns a member of that
> class.  Note that it specifically does NOT make sense on a single
> value of that class.


There's nothing I can think of that is a natural match for that in standard
Python methods. I would suggest just making it a classmethod.
(dict.fromkeysis a good example of a classmethod in C.)

As a final note: Python's source itself is a good source of answers and
examples. Almost all of the features of the Python API are used in a builtin
type or stdlib module, and for C source, Python's source is remarkably
readable ;-)

-- 
Thomas Wouters <thomas at python.org>

Hi! I'm a .signature virus! copy me into your .signature file to help me
spread!
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.python.org/pipermail/python-dev/attachments/20070126/fe246156/attachment-0001.htm