def c_declare(self, name, sub):
"""Required: Return c code to declare variables that will be
instantiated by `c_extract`.
Example:
.. code-block: python
return "PyObject ** addr_of_%(name)s;"
:param name: the name of the ``PyObject *`` pointer that will the value for this Type
:type name: string
:param sub: a dictionary of special codes. Most importantly sub['fail']. See CLinker
for more info on `sub` and ``fail``.
:type sub: dict string -> string
:note: It is important to include the `name` inside of variables which are declared
here, so that name collisions do not occur in the source file that is generated.
:note: The variable called ``name`` is not necessarily defined yet where this code is
inserted. This code might be inserted to create class variables for example, whereas
the variable ``name`` might only exist inside certain functions in that class.
:todo: Why should variable declaration fail? Is it even allowed to?
:Exceptions:
- `MethodNotDefined`: Subclass does not implement this method
"""
raise MethodNotDefined()
def c_literal(self, data):
"""Optional: WRITEME
:Parameters:
- `data`: WRITEME
WRITEME
:Exceptions:
- `MethodNotDefined`: Subclass does not implement this method
"""
raise MethodNotDefined("c_literal", type(self),
self.__class__.__name__)
def c_init(self, name, sub):
"""Required: Return c code to initialize the variables that were declared by
self.c_declare()
Example:
.. code-block: python
return "addr_of_%(name)s = NULL;"
:note: The variable called ``name`` is not necessarily defined yet where this code is
inserted. This code might be inserted in a class constructor for example, whereas
the variable ``name`` might only exist inside certain functions in that class.
:todo: Why should variable initialization fail? Is it even allowed to?
"""
raise MethodNotDefined("c_init", type(self), self.__class__.__name__)
def filter(self, data, strict=False, allow_downcast=None):
"""Required: Return data or an appropriately wrapped/converted data.
Subclass implementation should raise a TypeError exception if the data is not of an
acceptable type.
If strict is True, the data returned must be the same as the
data passed as an argument. If it is False, and allow_downcast
is True, filter may cast it to an appropriate type. If
allow_downcast is False, filter may only upcast it, not lose
precision. If allow_downcast is None (default), the behaviour can be
Type-dependent, but for now it means only Python floats can be
downcasted, and only to floatX scalars.
:Exceptions:
- `MethodNotDefined`: subclass doesn't implement this function.
"""
raise MethodNotDefined("filter", type(self), self.__class__.__name__)
def c_sync(self, name, sub):
"""Required: Return c code to pack C types back into a PyObject.
The code returned from this function must be templated using "%(name)s",
representing the name that the caller wants to call this Variable. The
returned code may set "py_%(name)s" to a PyObject* and that PyObject*
will be accessible from Python via variable.data. Do not forget to adjust
reference counts if "py_%(name)s" is changed from its original value.
:Parameters:
- `name`: WRITEME
WRITEME
- `sub`: WRITEME
WRITEME
:Exceptions:
- `MethodNotDefined`: Subclass does not implement this method
"""
raise MethodNotDefined("c_sync", type(self), self.__class__.__name__)
def c_cleanup(self, name, sub):
"""Optional: Return c code to clean up after `c_extract`.
This returns C code that should deallocate whatever `c_extract`
allocated or decrease the reference counts. Do not decrease
py_%(name)s's reference count.
WRITEME
:Parameters:
- `name`: WRITEME
WRITEME
- `sub`: WRITEME
WRITEME
:Exceptions:
- `MethodNotDefined`: Subclass does not implement this method
"""
raise MethodNotDefined()
def c_extract(self, name, sub):
"""Required: Return c code to extract a PyObject * instance.
The code returned from this function must be templated using
``%(name)s``, representing the name that the caller wants to
call this `Variable`. The Python object self.data is in a
variable called "py_%(name)s" and this code must set the
variables declared by c_declare to something representative
of py_%(name)s. If the data is improper, set an appropriate
exception and insert "%(fail)s".
:todo: Point out that template filling (via sub) is now performed
by this function. --jpt
Example:
.. code-block: python
return "if (py_%(name)s == Py_None)" + \\\
addr_of_%(name)s = &py_%(name)s;" + \\\
"else" + \\\
{ PyErr_SetString(PyExc_ValueError, \\\
'was expecting None'); %(fail)s;}"
:param name: the name of the ``PyObject *`` pointer that will
store the value for this Type
:type name: string
:param sub: a dictionary of special codes. Most importantly
sub['fail']. See CLinker for more info on `sub` and ``fail``.
:type sub: dict string -> string
:Exceptions:
- `MethodNotDefined`: Subclass does not implement this method
"""
raise MethodNotDefined("c_extract", type(self),
self.__class__.__name__)