Newer version, the diff contain the changes since the last version. I put the section describing the module functions as "Module Functions", hope someone give a better name then that.
On Monday 05 September 2011 05:17:55 matti.p.ai...@nokia.com wrote: > Sorry! > > On Aug 30, 2011, at 18:50, ext Hugo Parente Lima wrote: > > On Monday 15 August 2011 09:07:50 matti.p.ai...@nokia.com wrote: > >> Thanks! Looking pretty good already - I'm assigning it PSEP 106 > >> (should've done it earlier already). I took the liberty of adding the > >> post history and updating the discussion section for you. The latest > >> version is here: > >> > >> http://www.pyside.org/docs/pseps/psep-0106.html > > Sorry that I didn't catch this earlier: > > the document structure is a bit lacking now. The "Rationale" section should > be an introduction section, describing why the work described in the PSEP > is needed. Then, there should be a separate section documenting the actual > meat, as in your current Rationale. > > > It's impossible to check if the pointer is valid, it can e.g. point to a > > valid memory address but not to an object of the same type specified by > > the user, so the best we can promise for such low level function is an > > undefined behavior that must be read as "If it wont crash it's your luck > > day.", undefined behavior is a bit of C++ism and maybe this term isn't > > used very often on Python world, however I have no suggestion for this > > paragraph but accept suggestions. > > Then, how about: > > If the address is invalid or does not point to a C++ object of given type, > use of the wrapped object may result in a segmentation fault or other > undefined behaviour. > > > Yes it has: > > > > QProgressDialog::wasCanceled and the wasHeld() from QML MouseEvent > > element. > > > > But I guess they are outlaws in Qt, and reading > > http://doc.qt.nokia.com/qq/qq13-apis.html raised a question of: > > > > isCreatedByPython(obj) vs createdByPython(obj) > > Nice link. Reading that through, I think it would point us to > "createdByPython". > > >> isDeleted > > > > This is equivalent to the isValid() > > OK! > > >> setDeleted > > > > I didn't find a valid use case for it, as it's not worth implement things > > without use cases I didn't added it when reviewing the sip API, but I > > could add it if someone have a valid one. > > Debugging? I believe it could be conceivable that people face issues with > the bindings and might want to tweak around before filing a bug report but > are not willing to dive into regenerating the bindings again. > > >> __version__ > >> __version_info__ > > > > My only doubt is if the shiboken module will have it's own version > > numbering or if it will follow the version of the whole shiboken > > package. > > I thought it would follow the shiboken package version numbers. > > >> Also the transferto and transferback sound like they could be really > >> useful for debugging purposes (although I hate the names). > > > > I never needed to do such thing in Python, just on C++ binding code, this > > is why I didn't find a use case for this functions, for debugging > > purposes is useful to known who owns the object, but we already have a > > function to do this. > > Again, Python-side debugging could be the usecase, but ... > > >> So, I propose adding the above methods to the PSEP as well. > > > > I think is better to find use cases for the functions without one before > > just adding them to the module: > > > > setDeleted > > transferTo > > transferBack > > ... if you insist they're not useful for that, better leave them off. > > > I want also to add that we can't expose to much of libshiboken internals > > or it will be very hard to do internal changes in the future without > > break the ABI. > > Good point. > > Could you prepare a new version. Assuming no other comments are > forthcoming, that version could then be submitted for core dev team's > review and hopefully marked accepted soon. > > Cheers, > > ma. -- Hugo Parente Lima INdT - Instituto Nokia de Tecnologia
PSEP: 0106
Title: Shiboken helper module
Version: $Revision$
Last-Modified: $Date$
Author: Hugo Parente Lima <hugo.l...@openbossa.org>
Status: Draft
Type: Standards Track
Content-Type: text/x-rst
Created: 02-Aug-2011
Post-History: 05-Aug-2011, 12-Aug-2011
.. |maya| unicode:: Maya U+2122
Abstract
========
This PSEP describes a new module to access internal information related
to our binding technology. Access to this internal information is
required to e.g.: integrate PySide with Qt based programs that offer
Python scripting like |maya| or just for debug purposes.
Rationale
=========
When developing bindings is common the need to get information about the
internal state of a Python object, a separated module with simple
functions to query these informations can help the creation of stronger
unit tests. Besides the debugging context, access to the internal state
of Python objects is need to integrate Shiboken-based bindings with other
technologies like |maya| or any other software using Qt and Python.
Module Functions
================
The Python module named "shiboken", will offer the following functions:
Some function description refer to "Shiboken based objects", which mean
Python object instances of any Python type created using Shiboken.
``isValid(obj)``
Given a Python object, returns True if the object methods can be called
without an exception being thrown. A Python wrapper becomes invalid when
the underlying C++ object is destroyed or unreachable.
``invalidate(obj)``
Mark the object as invalid, so the underlying C++ object will not be
destroyed by Shiboken and any use of this object will raise an exception.
``wrapInstance(address, type)``
Creates a Python wrapper for a C++ object instantiated at a given memory
address - the returned object type will be the same given by the user.
The type must be a Shiboken type, the C++ object will not be
destroyed when the returned Python object reach zero references.
If the address is invalid or does not point to a C++ object of given type,
use of the wrapped object may result in a segmentation fault or other
undefined behaviour.
``getCppPointer(obj)``
Returns a tuple of longs that contain the memory addresses of the
C++ instances wrapped by the given object.
``delete(obj)``
Deletes the C++ object wrapped by the given Python object.
``isOwnedByPython(obj)``
Given a Python object, returns True if Python is responsible for deleting
the underlying C++ object, False otherwise.
If the object was not a Shiboken based object, a TypeError is
thrown.
``createdByPython(obj)``
Returns true if the given Python object was created by Python.
``dump(obj)``
Returns a string with implementation-defined information about the
object.
This method should be used **only** for debug purposes by developers
creating their own bindings as no guarantee is provided that
the string format will be the same across different versions.
If the object is not a Shiboken based object, a TypeError is thrown.
``__version__``
String with Shiboken version.
``__version_info__``
A tuple containing the five components of the version number: major,
minor, micro, releaselevel, and serial.
Discussion
==========
Carlo Giesa wanted to do some integration of PySide with |maya| [#maya]_
and noticed that PySide doesn't have anything equivalent to PyQt4
``sip.wrapinstance()``.
David MartÃnez Martà filed a feature request [#bug536]_ for a function to
return True or False if an object still valid or not.
Thomas Perl filed feature request [#bug902]_ summarizing some
functions that should appear in a helper module.
Sebastian Wiesner requested to have an inverse of ``wrapInstance(type,
address)`` to be able to pass PySide-created objects to native Qt
libraries.
Matti Airas suggested that a review of PyQt's ``sip`` module should be
made and all relevant methods from there added to this PSEP.
References
==========
.. [#bug536] `Bug 536 <http://bugs.pyside.org/show_bug.cgi?id=536>`_ -
Add property to QObject that exposes if a C++ reference is still valid.
.. [#bug902] `Bug 902 <http://bugs.pyside.org/show_bug.cgi?id=902>`_ -
Expose Shiboken functionality through a Python module.
.. [#maya] A 3D Animation, Visual Effects & Compositing Software -
http://usa.autodesk.com/maya/
Copyright
=========
This document has been placed in the public domain.
..
Local Variables:
mode: indented-text
indent-tabs-mode: nil
sentence-end-double-space: t
fill-column: 70
coding: utf-8
End:
diff --git a/psep-0106.txt b/psep-0106.txt
index 6e05f59..a9acf52 100644
--- a/psep-0106.txt
+++ b/psep-0106.txt
@@ -22,6 +22,17 @@ Python scripting like |maya| or just for debug purposes.
Rationale
=========
+When developing bindings is common the need to get information about the
+internal state of a Python object, a separated module with simple
+functions to query these informations can help the creation of stronger
+unit tests. Besides the debugging context, access to the internal state
+of Python objects is need to integrate Shiboken-based bindings with other
+technologies like |maya| or any other software using Qt and Python.
+
+
+Module Functions
+================
+
The Python module named "shiboken", will offer the following functions:
Some function description refer to "Shiboken based objects", which mean
@@ -33,6 +44,11 @@ Python object instances of any Python type created using Shiboken.
without an exception being thrown. A Python wrapper becomes invalid when
the underlying C++ object is destroyed or unreachable.
+``invalidate(obj)``
+
+ Mark the object as invalid, so the underlying C++ object will not be
+ destroyed by Shiboken and any use of this object will raise an exception.
+
``wrapInstance(address, type)``
Creates a Python wrapper for a C++ object instantiated at a given memory
@@ -41,8 +57,9 @@ Python object instances of any Python type created using Shiboken.
The type must be a Shiboken type, the C++ object will not be
destroyed when the returned Python object reach zero references.
- If the address is invalid or doesn't point to a C++ object of given type
- the behavior is undefined.
+ If the address is invalid or does not point to a C++ object of given type,
+ use of the wrapped object may result in a segmentation fault or other
+ undefined behaviour.
``getCppPointer(obj)``
@@ -61,7 +78,7 @@ Python object instances of any Python type created using Shiboken.
If the object was not a Shiboken based object, a TypeError is
thrown.
-``wasCreatedByPython(obj)``
+``createdByPython(obj)``
Returns true if the given Python object was created by Python.
@@ -75,6 +92,15 @@ Python object instances of any Python type created using Shiboken.
If the object is not a Shiboken based object, a TypeError is thrown.
+``__version__``
+
+ String with Shiboken version.
+
+``__version_info__``
+
+ A tuple containing the five components of the version number: major,
+ minor, micro, releaselevel, and serial.
+
Discussion
==========
signature.asc
Description: This is a digitally signed message part.
_______________________________________________ PySide mailing list PySide@lists.pyside.org http://lists.pyside.org/listinfo/pyside
