diff options
Diffstat (limited to 'sources/shiboken2/doc/considerations.rst')
| -rw-r--r-- | sources/shiboken2/doc/considerations.rst | 183 |
1 files changed, 0 insertions, 183 deletions
diff --git a/sources/shiboken2/doc/considerations.rst b/sources/shiboken2/doc/considerations.rst deleted file mode 100644 index 3488c3407..000000000 --- a/sources/shiboken2/doc/considerations.rst +++ /dev/null @@ -1,183 +0,0 @@ -.. _words-of-advice: - -*************** -Words of Advice -*************** - -When writing or using Python bindings there is some things you must keep in mind. - - -.. _duck-punching-and-virtual-methods: - -Duck punching and virtual methods -================================= - -The combination of duck punching, the practice of altering class characteristics -of already instantiated objects, and virtual methods of wrapped C++ classes, can -be tricky. That was an optimistic statement. - -Let's see duck punching in action for educational purposes. - - .. code-block:: python - - import types - import Binding - - obj = Binding.CppClass() - - # CppClass has a virtual method called 'virtualMethod', - # but we don't like it anymore. - def myVirtualMethod(self_obj, arg): - pass - - obj.virtualMethod = types.MethodType(myVirtualMethod, obj, Binding.CppClass) - - -If some C++ code happens to call `CppClass::virtualMethod(...)` on the C++ object -held by "obj" Python object, the new duck punched "virtualMethod" method will be -properly called. That happens because the underlying C++ object is in fact an instance -of a generated C++ class that inherits from `CppClass`, let's call it `CppClassWrapper`, -responsible for receiving the C++ virtual method calls and finding out the proper Python -override to which handle such a call. - -Now that you know this, consider the case when C++ has a factory method that gives you -new C++ objects originated somewhere in C++-land, in opposition to the ones generated in -Python-land by the usage of class constructors, like in the example above. - -Brief interruption to show what I was saying: - - .. code-block:: python - - import types - import Binding - - obj = Binding.createCppClass() - def myVirtualMethod(self_obj, arg): - pass - - # Punching a dead duck... - obj.virtualMethod = types.MethodType(myVirtualMethod, obj, Binding.CppClass) - - -The `Binding.createCppClass()` factory method is just an example, C++ created objects -can pop out for a number of other reasons. Objects created this way have a Python wrapper -holding them as usual, but the object held is not a `CppClassWrapper`, but a regular -`CppClass`. All virtual method calls originated in C++ will stay in C++ and never reach -a Python virtual method overridden via duck punching. - -Although duck punching is an interesting Python feature, it don't mix well with wrapped -C++ virtual methods, specially when you can't tell the origin of every single wrapped -C++ object. In summary: don't do it! - - -.. _pyside-old-style-class: - -Python old style classes and PySide -=================================== - -Because of some architectural decisions and deprecated Python types. -Since PySide 1.1 old style classes are not supported with multiple inheritance. - -Below you can check the examples: - -Example with old style class: - - .. code-block:: python - - from PySide2 import QtCore - - class MyOldStyleObject: - pass - - class MyObject(QtCore, MyOldStyleObject): - pass - - -this example will raise a 'TypeError' due to the limitation on PySide, to fix -this you will need use the new style class: - - - .. code-block:: python - - from PySide2 import QtCore - - class MyOldStyleObject(object): - pass - - class MyObject(QtCore, MyOldStyleObject): - pass - - -All classes used for multiple inheritance with other PySide types need to have -'object' as base class. -************************** -Frequently Asked Questions -************************** - -This is a list of Frequently Asked Questions about |project|. -Feel free to suggest new entries using our `Mailing list`_ or our IRC channel! - -General -======= - -What is Shiboken? ------------------ - -Shiboken is a Generator Runner plugin that outputs C++ code for CPython -extensions. -The first version of PySide had source code based on Boost templates. -It was easier to produce code but a paradigm change was needed, as the next -question explains. - - -Why did you switch from Boost.Python to Shiboken? -------------------------------------------------- - -The main reason was the size reduction. Boost.Python makes excessive use of -templates resulting in a significant increase of the binaries size. -On the other hand, as Shiboken generates CPython code, the resulting binaries -are smaller. - -Creating bindings -================= - -Can I wrap non-Qt libraries? ----------------------------- - -Yes. Check Shiboken source code for an example (libsample). - - -Is there any runtime dependency on the generated binding? ---------------------------------------------------------- - -Yes. Only libshiboken, and the obvious Python interpreter -and the C++ library that is being wrapped. - -What do I have to do to create my bindings? -------------------------------------------- - -Most of the work is already done by the API Extractor. -The developer creates a :std:doc:`typesystem <typesystem>` -file with any customization wanted in -the generated code, like removing classes or changing method signatures. -The generator will output the *.h* and *.cpp* files with the CPython code that -will wrap the target library for python. - - -Is there any recommended build system? --------------------------------------- - -Both API Extractor and generator uses and recommends the CMake build system. - -Can I write closed-source bindings with the generator? ------------------------------------------------------- - -Yes, as long as you use a LGPL version of Qt, due to runtime requirements. - -What is 'inject code'? ----------------------- - -That's how we call customized code that will be *injected* into the -generated at specific locations. They are specified inside the typesystem. - -.. _`Mailing list`: http://lists.qt-project.org/mailman/listinfo/pyside |