diff options
Diffstat (limited to 'sources/shiboken2/doc')
39 files changed, 5073 insertions, 0 deletions
diff --git a/sources/shiboken2/doc/CMakeLists.txt b/sources/shiboken2/doc/CMakeLists.txt new file mode 100644 index 000000000..7bd0161ad --- /dev/null +++ b/sources/shiboken2/doc/CMakeLists.txt @@ -0,0 +1,24 @@ + +find_program(SPHINX sphinx-build DOC "Path to sphinx-build binary.") + +if (SPHINX) + message("-- sphinx-build - found") + configure_file(conf.py.in conf.py @ONLY) + add_custom_target(doc ${SPHINX} -b html -c . ${CMAKE_CURRENT_SOURCE_DIR} html ) +else() + message("-- sphinx-build - not found! doc target disabled") + if (WIN32) + # if jom is used and we have no sphinx, then jom will crash. + # so for windows, we always create a doc target (until jom gets fixed...) + add_custom_target(doc echo. + COMMAND echo +++ This is a fake build, to make 'jom' happy. + COMMAND echo +++ The documentation was _not_ built! + COMMAND echo. + ) + endif() +endif() + +if (NOT WIN32) + file(GLOB manpages "${CMAKE_CURRENT_SOURCE_DIR}/*.1") + install(FILES ${manpages} DESTINATION share/man/man1) +endif() diff --git a/sources/shiboken2/doc/_templates/index.html b/sources/shiboken2/doc/_templates/index.html new file mode 100644 index 000000000..00ac64271 --- /dev/null +++ b/sources/shiboken2/doc/_templates/index.html @@ -0,0 +1,35 @@ +{% extends "layout.html" %} +{% set title = 'Overview' %} +{% block body %} +<div class="section"> + <h1>{{ project }} {{ version }}</h1> + + <p>{{ project }} is a plugin (front-end) for Generator Runner. It generates bindings for C++ libraries using CPython source code.</p> + + <h2>Documentation</h2> + <table class="contentstable" align="center" style="margin-left: 30px"><tr> + <td width="50%"> + <p class="biglink"><a class="biglink" href="{{ pathto("contents") }}">Contents</a><br/> + <span class="linkdescr">for a complete overview</span></p> + <p class="biglink"><a class="biglink" href="{{ pathto("faq") }}">FAQ</a><br/> + <span class="linkdescr">answers for frequent asked questions</span></p> + <p class="biglink"><a class="biglink" href="{{ pathto("commandlineoptions") }}">Command line options</a><br/> + <span class="linkdescr">explains the few flags used to change {{ project }} behaviour</span></p> + <p class="biglink"><a class="biglink" href="{{ pathto("typesystemvariables") }}">Type System Variables</a><br/> + <span class="linkdescr">describes the type system variables that could be used in user custom code</span></p> + <p class="biglink"><a class="biglink" href="{{ pathto("typeconverters") }}">Type Converters</a><br/> + <span class="linkdescr">describes how to define type converters</span></p> + </td> + <td width="50%"> + <p class="biglink"><a class="biglink" href="{{ pathto("codeinjectionsemantics") }}">Code Injection Semantics</a><br/> + <span class="linkdescr">explains how custom code injection is interpreted by {{ project }}</span></p> + <p class="biglink"><a class="biglink" href="{{ pathto("sequenceprotocol") }}">Sequence Protocol</a><br/> + <span class="linkdescr">support for python sequence protocol</span></p> + <p class="biglink"><a class="biglink" href="{{ pathto("ownership") }}">Object Ownership</a><br/> + <span class="linkdescr">object ownership features</span></p> + <p class="biglink"><a class="biglink" href="{{ pathto("wordsofadvice") }}">Words of Advice</a><br/> + <span class="linkdescr">Advice for binding developers and users.</span></p> + </td></tr> + </table> +</div> +{% endblock %} diff --git a/sources/shiboken2/doc/_templates/layout.html b/sources/shiboken2/doc/_templates/layout.html new file mode 100644 index 000000000..94ff3534e --- /dev/null +++ b/sources/shiboken2/doc/_templates/layout.html @@ -0,0 +1,29 @@ +{% extends "!layout.html" %} + +# Invert sidebars +{%- block sidebar1 %}{{ sidebar() }}{%- endblock %} +{%- block sidebar2 %}{%- endblock %} + +{%- block header %} +<div id="container"> +<div class="header"> + <div class="header_container"> + <div class="logo"><a href="http://www.pyside.org"><img alt="PySide" src="{{ pathto('_static/pysidelogo.png', 1) }}" width="199" height="102" /></a></div> + {{ relbar() }} + </div> +</div> +{%- endblock -%} + +{%- block footer %} + <div class="footer"> + <a href="http://www.qt.io/"><img src="{{ pathto('_static/logo_qt.png', 1) }}" alt="Qt" border="0" /></a> + <a href="http://www.python.org"><img src="{{ pathto('_static/logo_python.jpg', 1) }}" alt="Python" border="0" /></a> + </div> +</div> +{%- endblock %} + +# No top relbar. +{%- block relbar1 %}{%- endblock %} + +# No bottom relbar. +{%- block relbar2 %}{%- endblock %} diff --git a/sources/shiboken2/doc/_themes/pysidedocs/searchbox.html b/sources/shiboken2/doc/_themes/pysidedocs/searchbox.html new file mode 100644 index 000000000..55a972156 --- /dev/null +++ b/sources/shiboken2/doc/_themes/pysidedocs/searchbox.html @@ -0,0 +1,12 @@ +{%- if pagename != "search" %} +<div id="searchbox" style="display: none"> + <h3>{{ _('Quick search') }}</h3> + <form class="search" action="{{ pathto('search') }}" method="get"> + <input type="text" name="q" id="q" size="18" /> + <input type="submit" value="{{ _('Go') }}" id="search_button" /> + <input type="hidden" name="check_keywords" value="yes" /> + <input type="hidden" name="area" value="default" /> + </form> +</div> +<script type="text/javascript">$('#searchbox').show(0);</script> +{%- endif %} diff --git a/sources/shiboken2/doc/_themes/pysidedocs/static/bg_header.png b/sources/shiboken2/doc/_themes/pysidedocs/static/bg_header.png Binary files differnew file mode 100644 index 000000000..843e7e2c5 --- /dev/null +++ b/sources/shiboken2/doc/_themes/pysidedocs/static/bg_header.png diff --git a/sources/shiboken2/doc/_themes/pysidedocs/static/bg_topo.jpg b/sources/shiboken2/doc/_themes/pysidedocs/static/bg_topo.jpg Binary files differnew file mode 100644 index 000000000..4229ae8db --- /dev/null +++ b/sources/shiboken2/doc/_themes/pysidedocs/static/bg_topo.jpg diff --git a/sources/shiboken2/doc/_themes/pysidedocs/static/fakebar.png b/sources/shiboken2/doc/_themes/pysidedocs/static/fakebar.png Binary files differnew file mode 100644 index 000000000..b45830e00 --- /dev/null +++ b/sources/shiboken2/doc/_themes/pysidedocs/static/fakebar.png diff --git a/sources/shiboken2/doc/_themes/pysidedocs/static/logo_python.jpg b/sources/shiboken2/doc/_themes/pysidedocs/static/logo_python.jpg Binary files differnew file mode 100644 index 000000000..cd474efba --- /dev/null +++ b/sources/shiboken2/doc/_themes/pysidedocs/static/logo_python.jpg diff --git a/sources/shiboken2/doc/_themes/pysidedocs/static/logo_qt.png b/sources/shiboken2/doc/_themes/pysidedocs/static/logo_qt.png Binary files differnew file mode 100644 index 000000000..39a4a26f3 --- /dev/null +++ b/sources/shiboken2/doc/_themes/pysidedocs/static/logo_qt.png diff --git a/sources/shiboken2/doc/_themes/pysidedocs/static/pysidedocs.css b/sources/shiboken2/doc/_themes/pysidedocs/static/pysidedocs.css new file mode 100644 index 000000000..708ddf77c --- /dev/null +++ b/sources/shiboken2/doc/_themes/pysidedocs/static/pysidedocs.css @@ -0,0 +1,475 @@ +* { + font: 100% Verdana, Arial, Helvetica, sans-serif; + font-size:12px; +} + +html { + height: 100%; +} + +body { + margin: 0; + padding: 0; + background-color: #EBEBEB; + height: 100%; + color: #333; +} + +strong { + font-weight:bold; +} + +.document { + padding-bottom: 90px; +} + +#container { + position: relative; + min-height: 100%; + background-image: url(fakebar.png); + background-repeat: repeat-y; + background-color: white; +} + +.footer { + position: absolute; + bottom: 0px; + margin-top: 50px; + text-align:center; + background-color: white; + border-top: 2px solid #e0e0e0; + white-space: nowrap; + height: 90px; + width: 100%; +} + +.footer img { + margin-left: 8px; + margin-right: 8px; +} + +.sphinxsidebar { + float: left; + width: 250px; + padding: 0px 10px 0px 10px; + text-align: left; +} + +.sphinxsidebar ul { + padding: 0px; + margin: 0px; + list-style-position: inside; +} + +.sphinxsidebar > ul { + padding: 0px; + margin: 0px; +} + +.sphinxsidebar ul li { + margin-left: 10px; + padding: 0px; +} + +.sphinxsidebar h3, .sphinxsidebar h3 a { + font-weight: bold; + color: #333; +} + +.documentwrapper { + margin-left: 270px; + text-align: left; + background-color: #ffffff; + border-left: 1px solid #989898; + font-size:18px; + padding: 10px 50px 15px 50px; + height: 100%; +} + +h1 { + font-size:18px; + padding-left: 50px; + padding-bottom: 15px; + padding-top: 15px; + border-bottom: 1px solid #c2c2c2; + margin-right: -100px; + position: relative; + left: -50px; + top: -10px; +} + +h2 { + font-size:12px; + font-weight:bold; + border-left-width: 1px; + border-right-width: 1px; + border-top-width: 1px; + border-bottom-width: 2px; + border-style: solid; + border-left-color: #b1b1b1; + border-right-color: #b1b1b1; + border-top-color: #b1b1b1; + border-bottom-color: #009491; + background-color: #e0e0e0; + padding:5px; + margin-top: 20px; + -moz-border-radius:5px; + -webkit-border-radius:5px; + -khtml-border-radius:5px; +} + +h3, h4 { + font-weight: bolder; +} + +pre { + border-top: 1px solid #e0e0e0; + border-bottom: 1px solid #e0e0e0; + background-color: #fafafa; + padding: 5px; + font: 100% monospace; + overflow: auto; +} + +pre * { + font: 100% monospace; +} + +.pre { + font: 100% monospace; +} + +.headerlink { + font-size: 100%; + color: inherit; + float: right; + visibility: Hidden +} + +h1 .headerlink { + padding-right: 50px; +} + +h1:hover .headerlink, h2:hover .headerlink, h3:hover .headerlink { + visibility: Visible; +} + +a, a:visited { + color: #009491; + text-decoration: none; +} + +a:hover { + text-decoration: underline; +} + +/* -- admonitions ----------------------------------------------------------- */ + +div.admonition { + margin-top: 10px; + margin-bottom: 10px; + padding: 7px; +} + +div.admonition dt { + font-weight: bold; +} + +div.admonition dl { + margin-bottom: 0; +} + +p.admonition-title { + margin: 0px 10px 5px 0px; + font-weight: bold; +} + +div.body p.centered { + text-align: center; + margin-top: 25px; +} + +div.warning { + background-color: #ffe4e4; + border: 1px solid #f66; +} + +div.seealso { + background-color: #ffffcc; + border: 1px solid #ffff66; +} + +div.note { + border: 1px solid #e3e3e3; +} + +table.docutils { + margin-left: auto; + margin-right: auto; + margin-bottom: 10px; + border: none; +} + +table.docutils td { + border: none; +} + +table.docutils th { + border: none; + font-weight: bold; + vertical-align: top; +} + +h2 em { + float: right; + font-size: 10px; + position: relative; + top: -20px; +} + +/* Table of pymaemo components */ + +#development table.docutils td { + border-bottom: 1px solid #EBEBEB; +} + +#development th { + background-color: #EBEBEB; + color: #FC7E00; + padding: 5px; +} + +#development th:first-child { + -moz-border-radius: 20px 0px 0px 0px; + -webkit-border-radius: 20px 0px 0px 0px; + -khtml-border-radius: 20px 0px 0px 0px; + padding-left: 10px; +} +#development th:last-child { + -moz-border-radius: 0px 20px 0px 0px; + -webkit-border-radius: 0px 20px 0px 0px; + -khtml-border-radius: 0px 20px 0px 0px; + padding-right: 10px; + width: 100px; +} + +hr { + border: none; + border-bottom: 1px dashed #EBEBEB; + width: 70% +} + +.oldnews { + text-align: right; +} + +/******************* TOPO *****************************/ +.header { + background-image: url(bg_topo.jpg); + background-repeat: repeat-x; + height: 147px; +} + +.header_container { + background-image: url(bg_header.png); + background-repeat: no-repeat; + background-position: 100px 0px; +} + +.logo { + text-align: left; + margin-bottom: 10px; +} + +#searchbox { + border-top: 1px solid #989898; + padding-top: 10px; + margin-left: -10px; + margin-right: -10px; + padding-left: 10px; + padding-right: 10px; +} + +#search_button { + border: 1px solid #3A393A; + background-color: #3A393A; + color: white; + cursor: pointer; + -moz-border-radius: 5px; + -webkit-border-radius: 5px; + -khtml-border-radius: 5px; + +} + +form { + margin: 0px; + padding: 0px; +} + +/* search field */ +form #q { + width: 136px; +/* height: 22px; */ + border: none; + margin: 0px; + -moz-border-radius: 5px; + -webkit-border-radius: 5px; + -khtml-border-radius: 5px; + margin-top: 2px; + padding: 4px; + line-height: 22px +} + +#search-results h2 { + display: none; +} + +#search-results h2 { + display: none; +} + +#search-results ul.search { + margin: 0px; + padding: 0px; +} + +ul.search div.context { + padding-left: 40px; +} + +#installation td { + text-align: center; + font-weight: bold; +} + +em { + color: inherit; + font-style:italic; +} + +/******** REL bar *********/ + +.related { + display: inline; +} + +.related ul { + padding: 0px 0px 0px 10px; + margin: 0px; + text-align: left; + background-image: url(relbar_bg.png); +} + +.related li { + display: inline; + color: white; + font-weight: bold; +} + +.related li a { + color: inherit; + line-height: 35px; + font-weight: bold; + vertical-align: middle; +} + +.related li.right { + float: right; + margin-right: 5px; +} + +.related h3 { + display: none; +} + +.align-center { + text-align: center; +} + +.contentstable { + width: 100%; +} + +.contentstable td { + padding-left: 30px; + vertical-align: top; +} + +p.biglink a { + font-size: 20px; +} + +dt:target, .highlight { + background-color: #fbe54e; +} + +img { + border: 0px; +} + +.figure .caption { + font-style:italic; +} + +table.footnote { + margin: 0px; +} + +#synopsis table, table.field-list { + margin: 0px; +} + +tt.descname { + font-size: 120%; + font-weight: bold; +} + +#functions ul, #virtual-functions ul, #slots ul, #signals ul, #static-functions ul { + list-style: none; + margin: 0px; + padding: 10px; + border: 1px solid #ddd; + background-color: #f4f4f4; + -moz-border-radius:10px; + -webkit-border-radius:10px; + -khtml-border-radius:10px; +} + +#synopsis span.pre { + color: #009491; + font-weight: bolder; +} + +#detailed-description .class dt, #detailed-description .method dt, #detailed-description .attribute dt, #detailed-description .function dt { + margin: 0px; + padding: 10px; + border: 1px solid #ddd; + background-color: #f4f4f4; + -moz-border-radius:10px; + -webkit-border-radius:10px; + -khtml-border-radius:10px; +} + +.pysidetoc ul { + list-style: none; + padding: 0px; + margin: 0px; +} + +.pysidetoc em { + font-style: normal; +} + +.pysidetoc strong { + display: block; + padding: 5px; + border: 1px solid #ddd; + background-color: #f4f4f4; + -moz-border-radius:6px; + -webkit-border-radius:6px; + -khtml-border-radius:6px; +} + +.hide { + display: none; +} diff --git a/sources/shiboken2/doc/_themes/pysidedocs/static/pysidelogo.png b/sources/shiboken2/doc/_themes/pysidedocs/static/pysidelogo.png Binary files differnew file mode 100644 index 000000000..076c1057c --- /dev/null +++ b/sources/shiboken2/doc/_themes/pysidedocs/static/pysidelogo.png diff --git a/sources/shiboken2/doc/_themes/pysidedocs/static/relbar_bg.png b/sources/shiboken2/doc/_themes/pysidedocs/static/relbar_bg.png Binary files differnew file mode 100644 index 000000000..4036733a7 --- /dev/null +++ b/sources/shiboken2/doc/_themes/pysidedocs/static/relbar_bg.png diff --git a/sources/shiboken2/doc/_themes/pysidedocs/theme.conf b/sources/shiboken2/doc/_themes/pysidedocs/theme.conf new file mode 100644 index 000000000..e0a652a5d --- /dev/null +++ b/sources/shiboken2/doc/_themes/pysidedocs/theme.conf @@ -0,0 +1,7 @@ +[theme] +inherit = default +stylesheet = pysidedocs.css +pygments_style = none + +[options] +nosidebar = false diff --git a/sources/shiboken2/doc/codeinjectionsemantics.rst b/sources/shiboken2/doc/codeinjectionsemantics.rst new file mode 100644 index 000000000..d748a3aae --- /dev/null +++ b/sources/shiboken2/doc/codeinjectionsemantics.rst @@ -0,0 +1,397 @@ +************************ +Code Injection Semantics +************************ + +API Extractor provides the `inject-code +<http://www.pyside.org/docs/apiextractor/typesystem_manipulating_objects.html#inject-code>`_ tag +allowing the user to put custom written code to on specific locations of the generated code. +Yet this is only part of what is needed to generate proper binding code, where the custom code +should be written to depends upon the technology used on the generated binding code. + +This is the ``inject-code`` tag options that matters to |project|. + + .. code-block:: xml + + <inject-code class="native | target" position="beginning | end"> + // custom code + </inject-code> + +Conventions +=========== + +**C++ Wrapper** + This term refers to a generated C++ class that extends a class from the + wrapped library. It is used only when a wrapped C++ class is polymorphic, + i.e. it has or inherits any virtual methods. + +**Python Wrapper** + The code that exports the C++ wrapped class to Python. **Python wrapper** + refers to all the code needed to export a C++ class to Python, and + **Python method/function wrapper** means the specific function that calls + the C++ method/function on behalf of Python. + +**Native** + This is a possible value for the ``class`` attribute of the ``inject-code`` + tag, it means things more akin to the C++ side. + +**Target** + Another ``class`` attribute value, it indicates things more close to the + Python side. + +inject-code tag +=============== + +The following table describes the semantics of ``inject-code`` tag as used on +|project|. + + +---------------+------+---------+--------------------------------------------------------------+ + |Parent Tag |Class |Position |Meaning | + +===============+======+=========+==============================================================+ + |value-type, |native|beginning|Write to the beginning of a class wrapper ``.cpp`` file, right| + |object-type | | |after the ``#include`` clauses. A common use would be to write| + | | | |prototypes for custom functions whose definitions are put on a| + | | | |``native/end`` code injection. | + | | +---------+--------------------------------------------------------------+ + | | |end |Write to the end of a class wrapper ``.cpp`` file. Could be | + | | | |used to write custom/helper functions definitions for | + | | | |prototypes declared on ``native/beginning``. | + | +------+---------+--------------------------------------------------------------+ + | |target|beginning|Put custom code on the beginning of the wrapper initializer | + | | | |function (``init_CLASS(PyObject *module)``). This could be | + | | | |used to manipulate the ``PyCLASS_Type`` structure before | + | | | |registering it on Python. | + | | +---------+--------------------------------------------------------------+ + | | |end |Write the given custom code at the end of the class wrapper | + | | | |initializer function (``init_CLASS(PyObject *module)``). The | + | | | |code here will be executed after all the wrapped class | + | | | |components have been initialized. | + +---------------+------+---------+--------------------------------------------------------------+ + |modify-function|native|beginning|Code here is put on the virtual method override of a C++ | + | | | |wrapper class (the one responsible for passing C++ calls to a | + | | | |Python override, if there is any), right after the C++ | + | | | |arguments have been converted but before the Python call. | + | | +---------+--------------------------------------------------------------+ + | | |end |This code injection is put in a virtual method override on the| + | | | |C++ wrapper class, after the call to Python and before | + | | | |dereferencing the Python method and tuple of arguments. | + | +------+---------+--------------------------------------------------------------+ + | |target|beginning|This code is injected on the Python method wrapper | + | | | |(``PyCLASS_METHOD(...)``), right after the decisor have found | + | | | |which signature to call and also after the conversion of the | + | | | |arguments to be used, but before the actual call. | + | | +---------+--------------------------------------------------------------+ + | | |end |This code is injected on the Python method wrapper | + | | | |(``PyCLASS_METHOD(...)``), right after the C++ method call, | + | | | |but still inside the scope created by the overload for each | + | | | |signature. | + | +------+---------+--------------------------------------------------------------+ + | |shell |beginning|Used only for virtual functions. The code is injected when the| + | | | |function does not has a pyhton implementation, then the code | + | | | |is inserted before c++ call | + | | +---------+--------------------------------------------------------------+ + | | |end |Same as above, but the code is inserted after c++ call | + +---------------+------+---------+--------------------------------------------------------------+ + |typesystem |native|beginning|Write code to the beginning of the module ``.cpp`` file, right| + | | | |after the ``#include`` clauses. This position has a similar | + | | | |purpose as the ``native/beginning`` position on a wrapper | + | | | |class ``.cpp`` file, namely write function prototypes, but not| + | | | |restricted to this use. | + | | +---------+--------------------------------------------------------------+ + | | |end |Write code to the end of the module ``.cpp`` file. Usually | + | | | |implementations for function prototypes inserted at the | + | | | |beginning of the file with a ``native/beginning`` code | + | | | |injection. | + | +------+---------+--------------------------------------------------------------+ + | |target|beginning|Insert code at the start of the module initialization function| + | | | |(``initMODULENAME()``), before the calling ``Py_InitModule``. | + | | +---------+--------------------------------------------------------------+ + | | |end |Insert code at the end of the module initialization function | + | | | |(``initMODULENAME()``), but before the checking that emits a | + | | | |fatal error in case of problems importing the module. | + +---------------+------+---------+--------------------------------------------------------------+ + + +Anatomy of Code Injection +========================= + +To make things clear let's use a simplified example of generated wrapper code +and the places where each kind of code injection goes. + +Below is the example C++ class for whom wrapper code will be generated. + + .. code-block:: c++ + + class InjectCode { + public: + InjectCode(); + double overloadedMethod(int arg); + double overloadedMethod(double arg); + virtual int virtualMethod(int arg); + }; + +From the C++ class, |project| will generate a ``injectcode_wrapper.cpp`` file +with the binding code. The next section will use a simplified version of the +generated wrapper code with the injection spots marked with comments. + +Noteworthy Cases +---------------- + +The type system description system gives the binding developer a lot of +flexibility, which is power, which comes with responsibility. Some modifications +to the wrapped API will not be complete without some code injection. + + +Removing arguments and setting a default values for them +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A simple case is when a function have one argument removed, as when the C++ +method ``METHOD(ARG)`` is modified to be used from Python as ``METHOD()``; +of course the binding developer must provide some guidelines to the generator +on what to do to call it. The most common solution is to remove the argument and +set a default value for it at the same time, so the original C++ method could be +called without problems. + +Removing arguments and calling the method with your own hands +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If the argument is removed and no default value is provided, the generator will +not write any call to the method and expect the ``modify-function - target/beginning`` +code injection to call the original C++ method on its own terms. If even this +custom code is not provided the generator will put an ``#error`` clause to +prevent compilation of erroneus binding code. + +Calling the method with your own hands always! +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If your custom code to be injected contains a call to the wrapped C++ method, +it surely means that you don't want the generator to write another call to the +same method. As expected |project| will detect the user written call on the code +injection and will not write its own call, but for this to work properly the +binding developer must use the template variable ``%FUNCTION_NAME`` instead +of writing the actual name of the wrapped method/function. + +In other words, use + + .. code-block:: xml + + <inject-code class="target" position="beginning | end"> + %CPPSELF.originalMethodName(); + </inject-code> + + +instead of + + + .. code-block:: xml + + <inject-code class="target" position="beginning | end"> + %CPPSELF.%FUNCTION_NAME(); + </inject-code> + + +Code Injection for Functions/Methods +==================================== + + +.. _codeinjecting_method_native: + +On The Native Side +------------------ + +Notice that this is only used when there is a C++ wrapper, i.e. the wrapped +class is polymorphic. + + .. code-block:: c++ + + int InjectCodeWrapper::virtualMethod(int arg) + { + PyObject* method = BindingManager::instance().getOverride(this, "virtualMethod"); + if (!py_override) + return this->InjectCode::virtualMethod(arg); + + (... here C++ arguments are converted to Python ...) + + // INJECT-CODE: <modify-function><inject-code class="native" position="beginning"> + // Uses: pre method call custom code, modify the argument before the + // Python call. + + (... Python method call goes in here ...) + + // INJECT-CODE: <modify-function><inject-code class="native" position="end"> + // Uses: post method call custom code, modify the result before delivering + // it to C++ caller. + + (... Python method and argument tuple are dereferenced here ...) + + return Shiboken::Converter<int>::toCpp(method_result); + } + + +On The Target Side +------------------ + +All the overloads of a method from C++ are gathered together on a single Python +method that uses an overload decisor to call the correct C++ method based on the +arguments passed by the Python call. Each overloaded method signature has its +own ``beginning`` and ``end`` code injections. + + .. code-block:: c++ + + static PyObject* + PyInjectCode_overloadedMethod(PyObject* self, PyObject* arg) + { + PyObject* py_result = 0; + if (PyFloat_Check(arg)) { + double cpp_arg0 = Shiboken::Converter<double >::toCpp(arg); + + // INJECT-CODE: <modify-function><inject-code class="target" position="beginning"> + // Uses: pre method call custom code. + + py_result = Shiboken::Converter<double >::toPython( + PyInjectCode_cptr(self)->InjectCode::overloadedMethod(cpp_arg0) + ); + + // INJECT-CODE: <modify-function><inject-code class="target" position="end"> + // Uses: post method call custom code. + + } else if (PyNumber_Check(arg)) { + (... other overload calling code ...) + } else goto PyInjectCode_overloadedMethod_TypeError; + + if (PyErr_Occurred() || !py_result) + return 0; + + return py_result; + + PyInjectCode_overloadedMethod_TypeError: + PyErr_SetString(PyExc_TypeError, "'overloadedMethod()' called with wrong parameters."); + return 0; + } + + +.. _codeinjecting_classes: + +Code Injection for Wrapped Classes +================================== + +.. _codeinjecting_classes_native: + +On The Native Side +------------------ + +Those injections go in the body of the ``CLASSNAME_wrapper.cpp`` file for the +wrapped class. + + .. code-block:: c++ + + // Start of ``CLASSNAME_wrapper.cpp`` + #define protected public + // default includes + #include <shiboken.h> + (...) + #include "injectcode_wrapper.h" + using namespace Shiboken; + + // INJECT-CODE: <value/object-type><inject-code class="native" position="beginning"> + // Uses: prototype declarations + + (... C++ wrapper virtual methods, if any ...) + + (... Python wrapper code ...) + + PyAPI_FUNC(void) + init_injectcode(PyObject *module) + { + (...) + } + + (...) + + // INJECT-CODE: <value/object-type><inject-code class="native" position="end"> + // Uses: definition of functions prototyped at ``native/beginning``. + + // End of ``CLASSNAME_wrapper.cpp`` + + +.. _codeinjecting_classes_target: + +On The Target Side +------------------ + +Code injections to the class Python initialization function. + + .. code-block:: c++ + + // Start of ``CLASSNAME_wrapper.cpp`` + + (...) + + PyAPI_FUNC(void) + init_injectcode(PyObject *module) + { + // INJECT-CODE: <value/object-type><inject-code class="target" position="beginning"> + // Uses: Alter something in the PyInjectCode_Type (tp_flags value for example) + // before registering it. + + if (PyType_Ready(&PyInjectCode_Type) < 0) + return; + + Py_INCREF(&PyInjectCode_Type); + PyModule_AddObject(module, "InjectCode", + ((PyObject*)&PyInjectCode_Type)); + + // INJECT-CODE: <value/object-type><inject-code class="target" position="end"> + // Uses: do something right after the class is registered, like set some static + // variable injected on this same file elsewhere. + } + + (...) + + // End of ``CLASSNAME_wrapper.cpp`` + +Code Injection for Modules +========================== + +The C++ libraries are wapped as Python modules, a collection of classes, +functions, enums and namespaces. |project| creates wrapper files for all of +them and also one extra ``MODULENAME_module_wrapper.cpp`` to register the whole +module. Code injection xml tags who have the ``typesystem`` tag as parent will +be put on this file. + +On The Native Side +------------------ + +This works exactly as the class wrapper code injections :ref:`codeinjecting_classes_native`. + +On The Target Side +------------------ + +This is very similar to class wrapper code injections :ref:`codeinjecting_classes_target`. +Notice that the inject code at ``target/end`` is inserted before the check for errors +to prevent bad custom code to pass unnoticed. + + .. code-block:: c++ + + // Start of ``MODULENAME_module_wrapper.cpp`` + + (...) + initMODULENAME() + { + // INJECT-CODE: <typesystem><inject-code class="target" position="beginning"> + // Uses: do something before the module is created. + + PyObject* module = Py_InitModule("MODULENAME", MODULENAME_methods); + + (... initialization of wrapped classes, namespaces, functions and enums ...) + + // INJECT-CODE: <typesystem><inject-code class="target" position="end"> + // Uses: do something after the module is registered and initialized. + + if (PyErr_Occurred()) + Py_FatalError("can't initialize module sample"); + } + + (...) + + // Start of ``MODULENAME_module_wrapper.cpp`` + diff --git a/sources/shiboken2/doc/commandlineoptions.rst b/sources/shiboken2/doc/commandlineoptions.rst new file mode 100644 index 000000000..d373561cd --- /dev/null +++ b/sources/shiboken2/doc/commandlineoptions.rst @@ -0,0 +1,105 @@ +.. _command-line: + +Command line options +******************** + +Usage +----- + +:: + + shiboken [options] header-file typesystem-file + + +Options +------- + +``--disable-verbose-error-messages`` + Disable verbose error messages. Turn the CPython code hard to debug but saves a few kilobytes + in the generated binding. + +.. _parent-heuristic: + +``--enable-parent-ctor-heuristic`` + This flag enable an useful heuristic which can save a lot of work related to object ownership when + writing the typesystem. + For more info, check :ref:`ownership-parent-heuristics`. + +.. _pyside-extensions: + +``--enable-pyside-extensions`` + Enable pyside extensions like support for signal/slots. Use this if you are creating a binding based + on PySide. + +.. _return-heuristic: + +``--enable-return-value-heuristic`` + Enable heuristics to detect parent relationship on return values. + For more info, check :ref:`return-value-heuristics`. + +.. _api-version: + +``--api-version=<version>`` + Specify the supported api version used to generate the bindings. + +.. _debug-level: + +``--debug-level=[sparse|medium|full]`` + Set the debug level. + +.. _documentation-only: + +``--documentation-only`` + Do not generate any code, just the documentation. + +.. _drop-type-entries: + +``--drop-type-entries="<TypeEntry0>[;TypeEntry1;...]"`` + Semicolon separated list of type system entries (classes, namespaces, + global functions and enums) to be dropped from generation. + +.. _generation-set: + +``--generation-set`` + Generator set to be used (e.g. qtdoc). + +.. _help: + +``--help`` + Display this help and exit. + +.. _include-paths: + +``--include-paths=<path>[:<path>:...]`` + Include paths used by the C++ parser. + +.. _license-file=[license-file]: + +``--license-file=[license-file]`` + File used for copyright headers of generated files. + +.. _no-suppress-warnings: + +``--no-suppress-warnings`` + Show all warnings. + +.. _output-directory: + +``--output-directory=[dir]`` + The directory where the generated files will be written. + +.. _silent: + +``--silent`` + Avoid printing any message. + +.. _typesystem-paths: + +``--typesystem-paths=<path>[:<path>:...]`` + Paths used when searching for type system files. + +.. _version: + +``--version`` + Output version information and exit. + diff --git a/sources/shiboken2/doc/conf.py.in b/sources/shiboken2/doc/conf.py.in new file mode 100644 index 000000000..ed61d2695 --- /dev/null +++ b/sources/shiboken2/doc/conf.py.in @@ -0,0 +1,166 @@ +# -*- coding: utf-8 -*- +# +# PyQtB documentation build configuration file, created by +# sphinx-quickstart on Wed Apr 22 15:04:20 2009. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys, os + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.append(os.path.abspath('.')) + +# -- General configuration ----------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.ifconfig', 'sphinx.ext.coverage'] + +rst_epilog = """ +.. |project| replace:: Shiboken +""" + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['@CMAKE_CURRENT_SOURCE_DIR@/_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +source_encoding = 'utf-8' + +# The master toctree document. +#master_doc = 'contents' + +# General information about the project. +project = u'Shiboken' +copyright = u'Copyright (C) 2016 The Qt Company Ltd.' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '@shiboken_VERSION@' +# The full version, including alpha/beta/rc tags. +release = '@shiboken_VERSION@' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of documents that shouldn't be included in the build. +#unused_docs = [] + +# List of directories, relative to source directory, that shouldn't be searched +# for source files. +exclude_trees = ['_build'] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. Major themes that come with +# Sphinx are currently 'default' and 'sphinxdoc'. +html_theme = 'pysidedocs' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = { +#} + +# Add any paths that contain custom themes here, relative to this directory. +html_theme_path = ['@CMAKE_CURRENT_SOURCE_DIR@/_themes'] + +# The name for this set of Sphinx documents. If None, it defaults to +# "<project> v<release> documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +#html_static_path = ['@CMAKE_CURRENT_SOURCE_DIR@/_static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = { '' : ''} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +html_additional_pages = { 'index' : 'index.html'} + +# If false, no module index is generated. +html_use_modindex = False + +# If false, no index is generated. +html_use_index = False + +# If true, the index is split into individual pages for each letter. +html_split_index = False + +# If true, links to the reST sources are added to the pages. +html_show_sourcelink = False + +html_add_permalinks = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a <link> tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = '' + diff --git a/sources/shiboken2/doc/contents.rst b/sources/shiboken2/doc/contents.rst new file mode 100644 index 000000000..24adb1c68 --- /dev/null +++ b/sources/shiboken2/doc/contents.rst @@ -0,0 +1,17 @@ +Table of contents +***************** +.. toctree:: + :numbered: + :maxdepth: 3 + + faq.rst + overview.rst + commandlineoptions.rst + projectfile.rst + typesystemvariables.rst + typeconverters.rst + codeinjectionsemantics.rst + sequenceprotocol.rst + ownership.rst + wordsofadvice.rst + shibokenmodule.rst diff --git a/sources/shiboken2/doc/dependency-pyqtb.svg b/sources/shiboken2/doc/dependency-pyqtb.svg new file mode 100644 index 000000000..a458bf6fb --- /dev/null +++ b/sources/shiboken2/doc/dependency-pyqtb.svg @@ -0,0 +1,600 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="800" + height="340" + id="svg2" + sodipodi:version="0.32" + inkscape:version="0.46" + version="1.0" + sodipodi:docname="dependency-pyqtb.svg" + inkscape:output_extension="org.inkscape.output.svg.inkscape" + inkscape:export-filename="/var/www/lauro/dependency-pyqtb.png" + inkscape:export-xdpi="90" + inkscape:export-ydpi="90"> + <defs + id="defs4"> + <marker + inkscape:stockid="Arrow1Lstart" + orient="auto" + refY="0" + refX="0" + id="Arrow1Lstart" + style="overflow:visible"> + <path + id="path3270" + d="M 0,0 L 5,-5 L -12.5,0 L 5,5 L 0,0 z" + style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none" + transform="matrix(0.8,0,0,0.8,10,0)" /> + </marker> + <marker + inkscape:stockid="Arrow1Lend" + orient="auto" + refY="0" + refX="0" + id="Arrow1Lend" + style="overflow:visible"> + <path + id="path3679" + d="M 0,0 L 5,-5 L -12.5,0 L 5,5 L 0,0 z" + style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none" + transform="matrix(-0.8,0,0,-0.8,-10,0)" /> + </marker> + <inkscape:perspective + sodipodi:type="inkscape:persp3d" + inkscape:vp_x="0 : 526.18109 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_z="744.09448 : 526.18109 : 1" + inkscape:persp3d-origin="372.04724 : 350.78739 : 1" + id="perspective10" /> + <inkscape:perspective + id="perspective3480" + inkscape:persp3d-origin="372.04724 : 350.78739 : 1" + inkscape:vp_z="744.09448 : 526.18109 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 526.18109 : 1" + sodipodi:type="inkscape:persp3d" /> + <inkscape:perspective + id="perspective3498" + inkscape:persp3d-origin="372.04724 : 350.78739 : 1" + inkscape:vp_z="744.09448 : 526.18109 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 526.18109 : 1" + sodipodi:type="inkscape:persp3d" /> + <inkscape:perspective + id="perspective3541" + inkscape:persp3d-origin="372.04724 : 350.78739 : 1" + inkscape:vp_z="744.09448 : 526.18109 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 526.18109 : 1" + sodipodi:type="inkscape:persp3d" /> + </defs> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + gridtolerance="10000" + guidetolerance="10" + objecttolerance="10" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="1.0425" + inkscape:cx="400" + inkscape:cy="170" + inkscape:document-units="px" + inkscape:current-layer="g3995" + showgrid="false" + showguides="true" + inkscape:guide-bbox="true" + inkscape:window-width="1280" + inkscape:window-height="951" + inkscape:window-x="0" + inkscape:window-y="25" /> + <metadata + id="metadata7"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + </cc:Work> + </rdf:RDF> + </metadata> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1" + transform="translate(-94.976306,-355.09425)" /> + <g + id="g4087" + transform="translate(2.4157429e-6,1.9999951)"> + <g + id="g3995" + transform="translate(6,-3.2661035e-8)"> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.66823119px;stroke-linecap:butt;stroke-linejoin:miter;marker-start:url(#Arrow1Lstart);marker-end:none;stroke-opacity:1" + d="M 281.95594,47.06539 L 314.12853,47.06538" + id="path2877" + inkscape:connector-type="polyline" /> + <g + id="g3801" + transform="translate(-9.3125054,-154.20033)"> + <rect + y="286.49988" + x="322.2547" + height="73.367416" + width="194.85175" + id="rect3595" + style="fill:#9ac5ff;fill-opacity:1;fill-rule:evenodd;stroke:#003378;stroke-width:0.8142156;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + ry="10.318988" + rx="8.598484" /> + <g + transform="translate(1.7229236,-30.915768)" + id="g3599"> + <text + xml:space="preserve" + style="font-size:16.27989578px;font-style:normal;font-weight:normal;fill:#00183c;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="329.46826" + y="336.95081" + id="text2443"><tspan + sodipodi:role="line" + id="tspan2445" + x="329.46826" + y="336.95081">API Extractor</tspan></text> + <text + xml:space="preserve" + style="font-size:8.40044498px;font-style:normal;font-weight:normal;fill:#00183c;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="329.46826" + y="352.61548" + id="text2447"><tspan + sodipodi:role="line" + id="tspan2449" + x="329.46826" + y="352.61548">0.2</tspan></text> + <text + xml:space="preserve" + style="font-size:9.33067703px;font-style:normal;font-weight:normal;fill:#00183c;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="329.46826" + y="368.15546" + id="text2451"><tspan + sodipodi:role="line" + x="329.46826" + y="368.15546" + id="tspan2453">Headers and libraries - compile-time</tspan></text> + <text + xml:space="preserve" + style="font-size:8.26250458px;font-style:normal;font-weight:normal;fill:#00183c;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="329.46826" + y="383.47839" + id="text2455"><tspan + sodipodi:role="line" + id="tspan2457" + x="329.46826" + y="383.47839">LGPL version 2.1</tspan></text> + </g> + </g> + <g + id="g3729" + transform="translate(-9.3125054,-153.6367)"> + <rect + y="164.01837" + x="322.2547" + height="73.367416" + width="194.85175" + id="rect2459" + style="fill:#9ac5ff;fill-opacity:1;fill-rule:evenodd;stroke:#003378;stroke-width:0.8142156;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + ry="10.318988" + rx="8.598484" /> + <g + transform="translate(3.673984,2.3276517)" + id="g3585"> + <text + xml:space="preserve" + style="font-size:16.27989578px;font-style:normal;font-weight:normal;fill:#00183c;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="329.46826" + y="181.23659" + id="text2461"><tspan + sodipodi:role="line" + id="tspan2463" + x="329.46826" + y="181.23659">Shiboken (generator)</tspan></text> + <text + xml:space="preserve" + style="font-size:8.40044498px;font-style:normal;font-weight:normal;fill:#00183c;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="329.46826" + y="196.90126" + id="text2465"><tspan + sodipodi:role="line" + id="tspan2467" + x="329.46826" + y="196.90126">0.1</tspan></text> + <text + xml:space="preserve" + style="font-size:9.33067703px;font-style:normal;font-weight:normal;fill:#00183c;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="329.46826" + y="212.44124" + id="text2469"><tspan + sodipodi:role="line" + x="329.46826" + y="212.44124" + id="tspan2471">Binary executable - compile-time</tspan></text> + <text + xml:space="preserve" + style="font-size:8.26250458px;font-style:normal;font-weight:normal;fill:#00183c;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="329.46826" + y="227.76418" + id="text2473"><tspan + sodipodi:role="line" + id="tspan2475" + x="329.46826" + y="227.76418">GPL version 2</tspan></text> + </g> + </g> + <g + id="g3789" + transform="translate(-9.3125054,-154.20033)"> + <rect + y="406.48441" + x="322.2547" + height="73.367416" + width="194.85175" + id="rect3597" + style="fill:#f3a6a6;fill-opacity:1;fill-rule:evenodd;stroke:#6a0e0e;stroke-width:0.8142156;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + ry="10.318988" + rx="8.598484" /> + <g + transform="translate(-0.7447933,-64)" + id="g3633"> + <text + xml:space="preserve" + style="font-size:16.27989578px;font-style:normal;font-weight:normal;fill:#350707;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="329.46826" + y="489.09369" + id="text2565"><tspan + sodipodi:role="line" + id="tspan2567" + x="329.46826" + y="489.09369">boost::graph</tspan></text> + <text + xml:space="preserve" + style="font-size:8.40044498px;font-style:normal;font-weight:normal;fill:#350707;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="329.46826" + y="504.75836" + id="text2569"><tspan + sodipodi:role="line" + id="tspan2571" + x="329.46826" + y="504.75836">1.38.0</tspan></text> + <text + xml:space="preserve" + style="font-size:9.33067703px;font-style:normal;font-weight:normal;fill:#350707;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="329.46826" + y="520.29834" + id="text2573"><tspan + sodipodi:role="line" + x="329.46826" + y="520.29834" + id="tspan2575">headers and libraries - compile-time</tspan></text> + <text + xml:space="preserve" + style="font-size:8.26250458px;font-style:normal;font-weight:normal;fill:#350707;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="329.46826" + y="535.62128" + id="text2577"><tspan + sodipodi:role="line" + id="tspan2579" + x="329.46826" + y="535.62128">Boost Software License 1.0</tspan></text> + </g> + </g> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.77180147px;stroke-linecap:butt;stroke-linejoin:miter;marker-start:url(#Arrow1Lstart);marker-end:none;stroke-opacity:1" + d="M 410.36806,130.70564 L 410.36806,83.52386" + id="path2879" + inkscape:connector-type="polyline" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.77360356px;stroke-linecap:butt;stroke-linejoin:miter;marker-start:url(#Arrow1Lstart);marker-mid:none;marker-end:none;stroke-opacity:1" + d="M 410.36806,252.57322 L 410.36806,207.23899" + id="path2881" + inkscape:connector-type="polyline" /> + <g + id="g3565" + transform="translate(1.4608973,-106.88798)"> + <rect + ry="22.567146" + y="268.8403" + x="6.7667637" + height="163.45378" + width="273.78238" + id="rect7541" + style="fill:#e3e2db;stroke:#000000;stroke-width:1.30499184;stroke-opacity:1" + rx="22.567146" /> + <g + transform="translate(0.2849671,3.2991583)" + id="g3547"> + <g + id="g3516" + transform="translate(0,63.999998)"> + <text + id="text7543" + y="339.74512" + x="76.614265" + style="font-size:20.61732101px;font-style:normal;font-weight:normal;fill:#350707;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + y="339.74512" + x="76.614265" + id="tspan7545" + sodipodi:role="line">Boost</tspan></text> + <rect + ry="6.4285707" + y="321.55374" + x="21.614267" + height="22.5" + width="43.163269" + id="rect7555" + style="fill:#f3a6a6;fill-opacity:1;stroke:#6a0e0e;stroke-width:0.64285713;stroke-opacity:1" + rx="6.4285707" /> + </g> + <g + id="g3521" + transform="translate(0,-2.9523642)"> + <text + id="text7547" + y="372.67505" + x="76.614265" + style="font-size:20.61732101px;font-style:normal;font-weight:normal;fill:#1c2d0f;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + y="372.67505" + x="76.614265" + id="tspan7549" + sodipodi:role="line">Qt Software</tspan></text> + <rect + ry="6.4285707" + y="355.4823" + x="21.614267" + height="22.5" + width="43.163269" + id="rect7561" + style="fill:#97ce6c;fill-opacity:1;stroke:#385a1e;stroke-width:0.64285713;stroke-opacity:1" + rx="6.4285707" /> + </g> + <g + id="g3486" + transform="translate(0,2.8342009e-5)"> + <text + id="text7551" + y="304.38055" + x="76.614265" + style="font-size:20.61732101px;font-style:normal;font-weight:normal;fill:#00193c;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + y="304.38055" + x="76.614265" + id="tspan7553" + sodipodi:role="line">INdT/Nokia</tspan></text> + <rect + ry="6.4285707" + y="286.4823" + x="21.614267" + height="22.5" + width="43.163269" + id="rect7563" + style="fill:#9ac5ff;fill-opacity:1;stroke:#003378;stroke-width:0.64285713;stroke-opacity:1" + rx="6.4285707" /> + </g> + <g + id="g3526" + transform="translate(-1.3182277,-35.976168)" + style="fill:#ffe052;fill-opacity:1"> + <text + id="text3528" + y="372.67505" + x="76.614265" + style="font-size:20.61732101px;font-style:normal;font-weight:normal;fill:#3c3100;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + y="372.67505" + x="76.614265" + id="tspan3530" + sodipodi:role="line">Python Foundation</tspan></text> + <rect + ry="6.4285707" + y="355.4823" + x="21.614267" + height="22.5" + width="43.163269" + id="rect3532" + style="fill:#ffe052;fill-opacity:1;stroke:#786200;stroke-width:0.64285713;stroke-opacity:1" + rx="6.4285707" /> + </g> + </g> + </g> + <g + id="g3717" + transform="translate(232.28126,-66.767457)"> + <rect + y="77.149132" + x="322.2547" + height="73.367416" + width="194.85175" + id="rect3657" + style="fill:#9ac5ff;fill-opacity:1;fill-rule:evenodd;stroke:#003378;stroke-width:0.8142156;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + ry="10.318988" + rx="8.598484" /> + <g + transform="translate(4.8773009,-84.541588)" + id="g3659"> + <text + xml:space="preserve" + style="font-size:16.27989578px;font-style:normal;font-weight:normal;fill:#00183c;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="329.46826" + y="181.23659" + id="text3661"><tspan + sodipodi:role="line" + id="tspan3663" + x="329.46826" + y="181.23659">libshiboken</tspan></text> + <text + xml:space="preserve" + style="font-size:8.40044498px;font-style:normal;font-weight:normal;fill:#00183c;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="329.46826" + y="196.90126" + id="text3665"><tspan + sodipodi:role="line" + id="tspan3667" + x="329.46826" + y="196.90126">0.1</tspan></text> + <text + xml:space="preserve" + style="font-size:9.33067703px;font-style:normal;font-weight:normal;fill:#00183c;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="329.46826" + y="212.44124" + id="text3669"><tspan + sodipodi:role="line" + x="329.46826" + y="212.44124" + id="tspan3671">Headers and libraries - compile-time</tspan></text> + <text + xml:space="preserve" + style="font-size:8.26250458px;font-style:normal;font-weight:normal;fill:#00183c;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="329.46826" + y="227.76418" + id="text3673"><tspan + sodipodi:role="line" + id="tspan3675" + x="329.46826" + y="227.76418">LGPL version 2.1</tspan></text> + </g> + </g> + <g + id="g3752" + transform="translate(-10.802055,-155.79173)"> + <rect + rx="8.3239012" + y="166.21593" + x="18.860012" + height="73.282379" + width="274.18781" + id="rect2417" + style="fill:#97ce6c;fill-opacity:1;fill-rule:evenodd;stroke:#385a1e;stroke-width:0.96558368px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + ry="9.2689295" /> + <g + id="g3741"> + <text + xml:space="preserve" + style="font-size:16.27989578px;font-style:normal;font-weight:normal;fill:#1c2d0f;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="29.111408" + y="183.02223" + id="text2419"><tspan + sodipodi:role="line" + id="tspan2421" + x="29.111408" + y="183.02223">Qt 4.5</tspan></text> + <text + xml:space="preserve" + style="font-size:8.40044498px;font-style:normal;font-weight:normal;fill:#1c2d0f;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="29.111408" + y="198.68694" + id="text2423"><tspan + sodipodi:role="line" + id="tspan2425" + x="29.111408" + y="198.68694">4.5</tspan></text> + <text + xml:space="preserve" + style="font-size:9.33067703px;font-style:normal;font-weight:normal;fill:#1c2d0f;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="29.111408" + y="214.22688" + id="text2427"><tspan + sodipodi:role="line" + id="tspan2429" + x="29.111408" + y="214.22688">headers and libraries - compile-time and run-time</tspan></text> + <text + xml:space="preserve" + style="font-size:8.26250458px;font-style:normal;font-weight:normal;fill:#1c2d0f;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="29.111408" + y="224.19267" + id="text2431"><tspan + sodipodi:role="line" + id="tspan2433" + x="29.111408" + y="224.19267">GNU General Public License v3 /</tspan><tspan + id="tspan2472" + sodipodi:role="line" + x="29.111408" + y="234.5208">GNU Lesser General Public Licence v2.1</tspan></text> + </g> + </g> + <g + id="g3765" + transform="translate(201.65125,55.15042)"> + <rect + y="77.208275" + x="322.31384" + height="73.24913" + width="255.99348" + id="rect3767" + style="fill:#ffe052;fill-opacity:1;fill-rule:evenodd;stroke:#786200;stroke-width:0.93250537;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + ry="10.318988" + rx="8.598484" /> + <g + transform="translate(4.8773009,-84.541588)" + id="g3769"> + <text + xml:space="preserve" + style="font-size:16.27989578px;font-style:normal;font-weight:normal;fill:#3c3100;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="329.46826" + y="181.23659" + id="text3771"><tspan + sodipodi:role="line" + id="tspan3773" + x="329.46826" + y="181.23659">Python</tspan></text> + <text + xml:space="preserve" + style="font-size:8.40044498px;font-style:normal;font-weight:normal;fill:#3c3100;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="329.46826" + y="196.90126" + id="text3775"><tspan + sodipodi:role="line" + id="tspan3777" + x="329.46826" + y="196.90126">2.6</tspan></text> + <text + xml:space="preserve" + style="font-size:9.33067703px;font-style:normal;font-weight:normal;fill:#3c3100;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="329.46826" + y="212.44124" + id="text3779"><tspan + sodipodi:role="line" + x="329.46826" + y="212.44124" + id="tspan3781">Headers and libraries - compile-time and run-time</tspan></text> + <text + xml:space="preserve" + style="font-size:8.26250458px;font-style:normal;font-weight:normal;fill:#3c3100;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="329.46826" + y="227.76418" + id="text3783"><tspan + sodipodi:role="line" + id="tspan3785" + x="329.46826" + y="227.76418">Python license</tspan></text> + </g> + </g> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.77180147px;stroke-linecap:butt;stroke-linejoin:miter;marker-start:url(#Arrow1Lstart);marker-end:none;stroke-opacity:1" + d="M 651.96184,131.80908 L 651.96184,84.6273" + id="path3787" + inkscape:connector-type="polyline" /> + </g> + </g> +</svg> diff --git a/sources/shiboken2/doc/dependency-pyside.svg b/sources/shiboken2/doc/dependency-pyside.svg new file mode 100644 index 000000000..786bdb8a6 --- /dev/null +++ b/sources/shiboken2/doc/dependency-pyside.svg @@ -0,0 +1,527 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="900" + height="560" + id="svg2" + sodipodi:version="0.32" + inkscape:version="0.46" + version="1.0" + sodipodi:docname="dependency-pyside.svg" + inkscape:output_extension="org.inkscape.output.svg.inkscape" + inkscape:export-filename="/tmp/dependency-pyside.png" + inkscape:export-xdpi="90" + inkscape:export-ydpi="90"> + <defs + id="defs4"> + <marker + inkscape:stockid="Arrow1Lstart" + orient="auto" + refY="0" + refX="0" + id="Arrow1Lstart" + style="overflow:visible"> + <path + id="path3270" + d="M 0,0 L 5,-5 L -12.5,0 L 5,5 L 0,0 z" + style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none" + transform="matrix(0.8,0,0,0.8,10,0)" /> + </marker> + <marker + inkscape:stockid="Arrow1Lend" + orient="auto" + refY="0" + refX="0" + id="Arrow1Lend" + style="overflow:visible"> + <path + id="path3679" + d="M 0,0 L 5,-5 L -12.5,0 L 5,5 L 0,0 z" + style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none" + transform="matrix(-0.8,0,0,-0.8,-10,0)" /> + </marker> + <inkscape:perspective + sodipodi:type="inkscape:persp3d" + inkscape:vp_x="0 : 526.18109 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_z="744.09448 : 526.18109 : 1" + inkscape:persp3d-origin="372.04724 : 350.78739 : 1" + id="perspective10" /> + </defs> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + gridtolerance="10000" + guidetolerance="10" + objecttolerance="10" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="0.79440331" + inkscape:cx="-36.66006" + inkscape:cy="372.04724" + inkscape:document-units="px" + inkscape:current-layer="svg2" + showgrid="false" + showguides="true" + inkscape:guide-bbox="true" + inkscape:window-width="1278" + inkscape:window-height="949" + inkscape:window-x="0" + inkscape:window-y="0"> + <sodipodi:guide + orientation="1,0" + position="384.28571,590" + id="guide2601" /> + <sodipodi:guide + orientation="1,0" + position="678.57143,491.42857" + id="guide2603" /> + <sodipodi:guide + orientation="1,0" + position="78.571429,257.14286" + id="guide2605" /> + <sodipodi:guide + orientation="1,0" + position="93.571429,280.71429" + id="guide7565" /> + <sodipodi:guide + orientation="1,0" + position="148.57143,216.42857" + id="guide7567" /> + </sodipodi:namedview> + <metadata + id="metadata7"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + </cc:Work> + </rdf:RDF> + </metadata> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1" + transform="translate(-78.088635,-190.95252)" /> + <g + id="g5394" + transform="translate(6.1314759,14.304617)"> + <g + transform="translate(-65.84289,-190.95252)" + id="g5205"> + <g + id="g5171"> + <rect + rx="9.3643799" + y="338.7739" + x="678.57141" + height="73.281754" + width="274.54263" + id="rect2393" + style="fill:#aaeeff;fill-rule:evenodd;stroke:#006078;stroke-width:0.96620417px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + ry="13.104657" /> + <text + id="text2395" + y="355.93701" + x="683.46539" + style="font-size:16.27989578px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + y="355.93701" + x="683.46539" + id="tspan2397" + sodipodi:role="line">boost::python</tspan></text> + <text + id="text2399" + y="371.60172" + x="683.46539" + style="font-size:8.40044498px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + y="371.60172" + x="683.46539" + id="tspan2401" + sodipodi:role="line">1.38.0</tspan></text> + <text + id="text2403" + y="387.14166" + x="683.46539" + style="font-size:9.33067703px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + id="tspan2435" + y="387.14166" + x="683.46539" + sodipodi:role="line">headers and libraries - compile-time and run-time</tspan></text> + <text + id="text2413" + y="402.4646" + x="683.46539" + style="font-size:8.26250458px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + y="402.4646" + x="683.46539" + id="tspan2415" + sodipodi:role="line">Boost Software License 1.0</tspan></text> + </g> + <g + id="g5193"> + <rect + rx="8.3239012" + y="342.86383" + x="78.571426" + height="73.282379" + width="274.18781" + id="rect2417" + style="fill:#b3ff80;fill-rule:evenodd;stroke:#2a7800;stroke-width:0.96558368px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + ry="9.2689295" /> + <text + id="text2419" + y="359.67014" + x="88.822823" + style="font-size:16.27989578px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + y="359.67014" + x="88.822823" + id="tspan2421" + sodipodi:role="line">Qt 4.5</tspan></text> + <text + id="text2423" + y="375.33484" + x="88.822823" + style="font-size:8.40044498px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + y="375.33484" + x="88.822823" + id="tspan2425" + sodipodi:role="line">4.5</tspan></text> + <text + id="text2427" + y="390.87479" + x="88.822823" + style="font-size:9.33067703px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + y="390.87479" + x="88.822823" + id="tspan2429" + sodipodi:role="line">headers and libraries - compile-time and run-time</tspan></text> + <text + id="text2431" + y="400.84058" + x="88.822823" + style="font-size:8.26250458px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + y="400.84058" + x="88.822823" + id="tspan2433" + sodipodi:role="line">GNU General Public License v3 /</tspan><tspan + y="411.1687" + x="88.822823" + sodipodi:role="line" + id="tspan2472">GNU Lesser General Public Licence v2.1</tspan></text> + </g> + <g + id="g5120"> + <rect + y="496.43558" + x="384.28571" + height="73.281754" + width="274.54263" + id="rect2441" + style="fill:#e9ddaf;fill-rule:evenodd;stroke:#5f5019;stroke-width:0.96620417px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + ry="13.104635" + rx="10.404889" /> + <text + id="text2443" + y="513.59869" + x="389.17969" + style="font-size:16.27989578px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + y="513.59869" + x="389.17969" + id="tspan2445" + sodipodi:role="line">libapiextractor</tspan></text> + <text + id="text2447" + y="529.26337" + x="389.17969" + style="font-size:8.40044498px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + y="529.26337" + x="389.17969" + id="tspan2449" + sodipodi:role="line">0.1</tspan></text> + <text + id="text2451" + y="544.80334" + x="389.17969" + style="font-size:9.33067703px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + id="tspan2453" + y="544.80334" + x="389.17969" + sodipodi:role="line">headers and libraries - compile-time and run-time</tspan></text> + <text + id="text2455" + y="560.12628" + x="389.17969" + style="font-size:8.26250458px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + y="560.12628" + x="389.17969" + id="tspan2457" + sodipodi:role="line">LGPL version 2.1</tspan></text> + </g> + <g + id="g5131"> + <rect + y="340.72134" + x="384.28571" + height="73.281754" + width="274.54263" + id="rect2459" + style="fill:#e9ddaf;fill-rule:evenodd;stroke:#5f5019;stroke-width:0.96620417px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + ry="10.309408" + rx="9.3644047" /> + <text + id="text2461" + y="357.88449" + x="389.17969" + style="font-size:16.27989578px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + y="357.88449" + x="389.17969" + id="tspan2463" + sodipodi:role="line">BoostPythonGenerator</tspan></text> + <text + id="text2465" + y="373.54916" + x="389.17969" + style="font-size:8.40044498px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + y="373.54916" + x="389.17969" + id="tspan2467" + sodipodi:role="line">0.1</tspan></text> + <text + id="text2469" + y="389.08914" + x="389.17969" + style="font-size:9.33067703px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + id="tspan2471" + y="389.08914" + x="389.17969" + sodipodi:role="line">Binary executable - compile-time</tspan></text> + <text + id="text2473" + y="404.41208" + x="389.17969" + style="font-size:8.26250458px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + y="404.41208" + x="389.17969" + id="tspan2475" + sodipodi:role="line">LGPL version 2.1</tspan></text> + </g> + <g + id="g5142"> + <rect + y="191.43562" + x="384.28571" + height="73.281754" + width="274.54263" + id="rect2523" + style="fill:#e9ddaf;fill-opacity:1;fill-rule:evenodd;stroke:#5f5019;stroke-width:0.96620417px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + ry="14.285714" /> + <text + id="text2525" + y="208.59874" + x="389.17966" + style="font-size:16.27989578px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + y="208.59874" + x="389.17966" + id="tspan2527" + sodipodi:role="line">Qt Python bindings</tspan></text> + <text + id="text2529" + y="224.26344" + x="389.17966" + style="font-size:8.40044498px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + y="224.26344" + x="389.17966" + id="tspan2531" + sodipodi:role="line">0.1</tspan></text> + <text + id="text2533" + y="239.80339" + x="389.17966" + style="font-size:9.33067703px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + id="tspan2535" + y="239.80339" + x="389.17966" + sodipodi:role="line">Target</tspan></text> + <text + id="text2537" + y="255.12633" + x="389.17966" + style="font-size:8.26250458px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + y="255.12633" + x="389.17966" + id="tspan2539" + sodipodi:role="line">LGPL version 2.1</tspan></text> + </g> + <g + id="g5182"> + <rect + rx="10.404877" + y="648.57843" + x="384.28571" + height="73.281754" + width="274.54263" + id="rect2563" + style="fill:#aaeeff;fill-rule:evenodd;stroke:#006078;stroke-width:0.96620417px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + ry="11.287985" /> + <text + id="text2565" + y="665.74158" + x="389.17969" + style="font-size:16.27989578px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + y="665.74158" + x="389.17969" + id="tspan2567" + sodipodi:role="line">boost::graph</tspan></text> + <text + id="text2569" + y="681.40625" + x="389.17969" + style="font-size:8.40044498px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + y="681.40625" + x="389.17969" + id="tspan2571" + sodipodi:role="line">1.38.0</tspan></text> + <text + id="text2573" + y="696.94623" + x="389.17969" + style="font-size:9.33067703px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + id="tspan2575" + y="696.94623" + x="389.17969" + sodipodi:role="line">headers and libraries - compile-time and run-time</tspan></text> + <text + id="text2577" + y="712.26917" + x="389.17969" + style="font-size:8.26250458px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + y="712.26917" + x="389.17969" + id="tspan2579" + sodipodi:role="line">Boost Software License 1.0</tspan></text> + </g> + </g> + <path + inkscape:connector-type="polyline" + id="path2869" + d="M 212.85114,151.42852 L 368.56822,74.247959" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;marker-start:url(#Arrow1Lstart);marker-end:none;stroke-opacity:1" /> + <path + inkscape:connector-type="polyline" + id="path2871" + d="M 663.60462,147.33826 L 517.61788,74.247959" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;marker-start:url(#Arrow1Lstart);marker-end:none;stroke-opacity:1" /> + <path + inkscape:connector-type="polyline" + id="path2877" + d="M 443.4684,149.28571 L 443.46839,74.247959" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;marker-start:url(#Arrow1Lstart);marker-end:none;stroke-opacity:1" /> + <path + inkscape:connector-type="polyline" + id="path2879" + d="M 443.4684,304.99994 L 443.4684,223.53367" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;marker-start:url(#Arrow1Lstart);marker-end:none;stroke-opacity:1" /> + <path + inkscape:connector-type="polyline" + id="path2881" + d="M 443.4684,457.14279 L 443.4684,379.2479" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;marker-start:url(#Arrow1Lstart);marker-mid:none;marker-end:none;stroke-opacity:1" /> + <rect + ry="17.142857" + y="293.85626" + x="0.48279184" + height="124.28571" + width="211.42857" + id="rect7541" + style="fill:#e3e2db;stroke:#000000;stroke-opacity:1" /> + <text + id="text7543" + y="325.44049" + x="70.482788" + style="font-size:20.61732101px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + y="325.44049" + x="70.482788" + id="tspan7545" + sodipodi:role="line">Boost</tspan></text> + <text + id="text7547" + y="358.37042" + x="70.482788" + style="font-size:20.61732101px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + y="358.37042" + x="70.482788" + id="tspan7549" + sodipodi:role="line">Qt Software</tspan></text> + <text + id="text7551" + y="394.07593" + x="70.482788" + style="font-size:20.61732101px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + y="394.07593" + x="70.482788" + id="tspan7553" + sodipodi:role="line">INdT/Nokia</tspan></text> + <rect + ry="6.4285707" + y="307.24911" + x="15.482792" + height="22.5" + width="43.163269" + id="rect7555" + style="fill:#aaeeff;fill-opacity:1;stroke:#000000;stroke-width:0.64285713;stroke-opacity:1" /> + <rect + ry="6.4285707" + y="341.17767" + x="15.482792" + height="22.5" + width="43.163269" + id="rect7561" + style="fill:#b3ff80;fill-opacity:1;stroke:#000000;stroke-width:0.64285713;stroke-opacity:1" /> + <rect + ry="6.4285707" + y="376.17767" + x="15.482792" + height="22.5" + width="43.163269" + id="rect7563" + style="fill:#e9ddaf;fill-opacity:1;stroke:#000000;stroke-width:0.64285713;stroke-opacity:1" /> + </g> +</svg> diff --git a/sources/shiboken2/doc/faq.rst b/sources/shiboken2/doc/faq.rst new file mode 100644 index 000000000..77e0fbdfc --- /dev/null +++ b/sources/shiboken2/doc/faq.rst @@ -0,0 +1,67 @@ +************************** +Frequently Asked Questions +************************** + +This is a list of Frequently Asked Questions about |project|. Feel free to +suggest new entries! + +General +======= + +What is Shiboken? +----------------- + +Shiboken is a `GeneratorRunner <http://www.pyside.org/home-binding/binding-generator>`_ +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? +------------------------------------------- + +.. todo: put link to typesystem documentation + +Most of the work is already done by the API Extractor. The developer creates +a `typesystem <http://www.pyside.org/docs/apiextractor/typesystem.html>`_ 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 typesytem. + diff --git a/sources/shiboken2/doc/images/.directory b/sources/shiboken2/doc/images/.directory new file mode 100644 index 000000000..e65475f65 --- /dev/null +++ b/sources/shiboken2/doc/images/.directory @@ -0,0 +1,3 @@ +[Dolphin] +ShowPreview=true +Timestamp=2009,5,5,17,43,26 diff --git a/sources/shiboken2/doc/images/bindinggen-development.png b/sources/shiboken2/doc/images/bindinggen-development.png Binary files differnew file mode 100644 index 000000000..2dd64ba1d --- /dev/null +++ b/sources/shiboken2/doc/images/bindinggen-development.png diff --git a/sources/shiboken2/doc/images/bindinggen-development.svg b/sources/shiboken2/doc/images/bindinggen-development.svg new file mode 100644 index 000000000..3b6b3a26e --- /dev/null +++ b/sources/shiboken2/doc/images/bindinggen-development.svg @@ -0,0 +1,543 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="640" + height="200" + id="svg2" + sodipodi:version="0.32" + inkscape:version="0.46" + version="1.0" + sodipodi:docname="bindgen-development.svg" + inkscape:output_extension="org.inkscape.output.svg.inkscape" + inkscape:export-filename="bindinggen-development.png" + inkscape:export-xdpi="90" + inkscape:export-ydpi="90"> + <defs + id="defs4"> + <marker + inkscape:stockid="EmptyDiamondL" + orient="auto" + refY="0" + refX="0" + id="EmptyDiamondL" + style="overflow:visible"> + <path + id="path3930" + d="M 0,-7.0710768 L -7.0710894,0 L 0,7.0710589 L 7.0710462,0 L 0,-7.0710768 z" + style="fill:#ffffff;fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none" + transform="scale(0.8,0.8)" /> + </marker> + <marker + inkscape:stockid="EmptyTriangleInL" + orient="auto" + refY="0" + refX="0" + id="EmptyTriangleInL" + style="overflow:visible"> + <path + id="path3975" + d="M 5.77,0 L -2.88,5 L -2.88,-5 L 5.77,0 z" + style="fill:#ffffff;fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none" + transform="matrix(-0.8,0,0,-0.8,4.8,0)" /> + </marker> + <marker + inkscape:stockid="Arrow1Sstart" + orient="auto" + refY="0" + refX="0" + id="Arrow1Sstart" + style="overflow:visible"> + <path + id="path3835" + d="M 0,0 L 5,-5 L -12.5,0 L 5,5 L 0,0 z" + style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none" + transform="matrix(0.2,0,0,0.2,1.2,0)" /> + </marker> + <marker + inkscape:stockid="Arrow1Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow1Mend" + style="overflow:visible"> + <path + id="path3832" + d="M 0,0 L 5,-5 L -12.5,0 L 5,5 L 0,0 z" + style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none" + transform="matrix(-0.4,0,0,-0.4,-4,0)" /> + </marker> + <marker + inkscape:stockid="Tail" + orient="auto" + refY="0" + refX="0" + id="Tail" + style="overflow:visible"> + <g + id="g3859" + transform="scale(-1.2,-1.2)"> + <path + id="path3861" + d="M -3.8048674,-3.9585227 L 0.54352094,0" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80000001;stroke-linecap:round;marker-start:none;marker-end:none" /> + <path + id="path3863" + d="M -1.2866832,-3.9585227 L 3.0617053,0" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80000001;stroke-linecap:round;marker-start:none;marker-end:none" /> + <path + id="path3865" + d="M 1.3053582,-3.9585227 L 5.6537466,0" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80000001;stroke-linecap:round;marker-start:none;marker-end:none" /> + <path + id="path3867" + d="M -3.8048674,4.1775838 L 0.54352094,0.21974226" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80000001;stroke-linecap:round;marker-start:none;marker-end:none" /> + <path + id="path3869" + d="M -1.2866832,4.1775838 L 3.0617053,0.21974226" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80000001;stroke-linecap:round;marker-start:none;marker-end:none" /> + <path + id="path3871" + d="M 1.3053582,4.1775838 L 5.6537466,0.21974226" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80000001;stroke-linecap:round;marker-start:none;marker-end:none" /> + </g> + </marker> + <marker + inkscape:stockid="Arrow2Lend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Lend" + style="overflow:visible"> + <path + id="path3636" + style="font-size:12px;fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round" + d="M 8.7185878,4.0337352 L -2.2072895,0.016013256 L 8.7185884,-4.0017078 C 6.97309,-1.6296469 6.9831476,1.6157441 8.7185878,4.0337352 z" + transform="matrix(-1.1,0,0,-1.1,-1.1,0)" /> + </marker> + <inkscape:perspective + sodipodi:type="inkscape:persp3d" + inkscape:vp_x="0 : 526.18109 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_z="744.09448 : 526.18109 : 1" + inkscape:persp3d-origin="372.04724 : 350.78739 : 1" + id="perspective10" /> + </defs> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + gridtolerance="10000" + guidetolerance="10" + objecttolerance="10" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="1.0859375" + inkscape:cx="320" + inkscape:cy="136.17463" + inkscape:document-units="px" + inkscape:current-layer="g5658" + showgrid="false" + inkscape:window-width="1156" + inkscape:window-height="883" + inkscape:window-x="1396" + inkscape:window-y="35" + showguides="true" + inkscape:guide-bbox="true"> + <sodipodi:guide + orientation="1,0" + position="-557.55608,678.10875" + id="guide7299" /> + </sodipodi:namedview> + <metadata + id="metadata7"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + </cc:Work> + </rdf:RDF> + </metadata> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1" + transform="translate(-1758.7331,-2056.8567)"> + <flowRoot + xml:space="preserve" + id="flowRoot3229" + style="font-size:40px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + transform="translate(4.1137413,-2.3429609)"><flowRegion + id="flowRegion3231"><rect + id="rect3233" + width="125.74072" + height="40.5849" + x="388.45547" + y="279.5423" /></flowRegion><flowPara + id="flowPara3235" /></flowRoot> <g + id="g5658" + transform="translate(6.5767925,7.0112479)"> + <g + id="g5634"> + <g + id="g6271" + transform="translate(1086.3689,746.93837)"> + <g + transform="matrix(0,-1,1,0,-294.81158,2953.0504)" + id="g6252"> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;marker-start:none;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;display:inline" + d="M 1586.5317,1300.2858 L 1586.6222,1389.8124" + id="path11089" + inkscape:connector-type="polyline" + sodipodi:nodetypes="cc" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-type="polyline" + id="path2758" + d="M 1586.7489,1389.4756 L 1594.7468,1380.3688" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;marker-start:none;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;display:inline" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-type="polyline" + id="path2760" + d="M 1586.6031,1389.5063 L 1578.6052,1380.3994" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;marker-start:none;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;display:inline" /> + </g> + </g> + </g> + <g + transform="translate(134.35978,44.472131)" + id="g2777"> + <rect + style="fill:#addc52;fill-opacity:1;stroke:#6ca400;stroke-width:0.82399696;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + id="rect5172" + width="185.49777" + height="75.08918" + x="2047.775" + y="2029.4594" + ry="3.0323718" + rx="2.6724329" /> + <text + xml:space="preserve" + style="font-size:40px;font-style:normal;font-weight:normal;text-align:center;text-anchor:middle;fill:#035800;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="2140.5562" + y="2062.9375" + id="text5174"><tspan + sodipodi:role="line" + x="2140.5562" + y="2062.9375" + style="font-size:22px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;text-anchor:middle;fill:#050800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans Bold" + id="tspan5176">Qt bindings</tspan><tspan + id="tspan6109" + sodipodi:role="line" + x="2140.5562" + y="2084.457" + style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;text-anchor:middle;fill:#050800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans">(generated code)</tspan></text> + </g> + <g + transform="translate(141.86951,-31.391207)" + id="g3216"> + <rect + style="fill:#bff3bc;fill-opacity:1;stroke:#0af400;stroke-width:0.64492828;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + id="rect3625" + width="185.67708" + height="75.268074" + x="1829.1727" + y="2105.2332" + ry="2.3353095" + rx="2.1257713" /> + <text + xml:space="preserve" + style="font-size:38.71272278px;font-style:normal;font-weight:normal;text-align:center;text-anchor:middle;fill:#035800;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="1921.9705" + y="2136.9409" + id="text3627" + transform="scale(1.0000266,0.9999734)"><tspan + id="tspan3697" + sodipodi:role="line" + x="1921.9705" + y="2136.9409" + style="font-size:21.29199791px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;text-anchor:middle;fill:#035800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans Bold">generator</tspan><tspan + sodipodi:role="line" + x="1921.9705" + y="2163.5559" + style="font-size:21.29199791px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;text-anchor:middle;fill:#035800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans Bold" + id="tspan2464">front-end</tspan></text> + </g> + <g + id="g5641"> + <g + id="g5465" + transform="translate(874.42628,746.93837)"> + <g + transform="matrix(0,-1,1,0,-294.81158,2953.0504)" + id="g5467"> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;marker-start:none;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;display:inline" + d="M 1586.5317,1300.2858 L 1586.6222,1389.8124" + id="path5469" + inkscape:connector-type="polyline" + sodipodi:nodetypes="cc" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-type="polyline" + id="path5471" + d="M 1586.7489,1389.4756 L 1594.7468,1380.3688" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;marker-start:none;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;display:inline" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-type="polyline" + id="path5473" + d="M 1586.6031,1389.5063 L 1578.6052,1380.3994" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;marker-start:none;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;display:inline" /> + </g> + </g> + </g> + <g + transform="translate(-194.79968,-212.08495)" + id="g5440"> + <rect + rx="1.2158648" + ry="2.9911308" + y="2285.8806" + x="1953.809" + height="75.360634" + width="185.76964" + id="rect3166" + style="fill:#dfe994;fill-opacity:1;stroke:#d5f400;stroke-width:0.55236381;stroke-opacity:1" /> + <text + id="text3168" + y="2328.8809" + x="2046.646" + style="font-size:27.94354057px;font-style:normal;font-weight:normal;text-align:center;text-anchor:middle;fill:#4c5800;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + style="font-size:19.56047821px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;text-anchor:middle;fill:#4c5800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans" + y="2328.8809" + x="2046.646" + sodipodi:role="line" + id="tspan5424">API Extractor</tspan></text> + </g> + <g + transform="translate(-102.30216,-279.71223)" + id="g5541"> + <path + sodipodi:type="arc" + style="fill:#f28888;fill-opacity:1;stroke:#d5f400;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:3, 3;stroke-dashoffset:0;stroke-opacity:1" + id="path5535" + sodipodi:cx="255.10791" + sodipodi:cy="326.69064" + sodipodi:rx="38.848923" + sodipodi:ry="38.848923" + d="M 293.95683,326.69064 A 38.848923,38.848923 0 1 1 216.25899,326.69064 A 38.848923,38.848923 0 1 1 293.95683,326.69064 z" + transform="matrix(0.4405339,0,0,0.4405339,1842.2283,2282.9708)" /> + <text + xml:space="preserve" + style="font-size:27.62000275px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="1946.3259" + y="2435.7" + id="text5537"><tspan + sodipodi:role="line" + id="tspan5539" + x="1946.3259" + y="2435.7" + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-family:FreeMono;-inkscape-font-specification:FreeMono Bold">1</tspan></text> + </g> + <g + transform="translate(52.589867,-352.69787)" + id="g5546"> + <path + sodipodi:type="arc" + style="fill:#f28888;fill-opacity:1;stroke:#d5f400;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:3, 3;stroke-dashoffset:0;stroke-opacity:1" + id="path5548" + sodipodi:cx="255.10791" + sodipodi:cy="326.69064" + sodipodi:rx="38.848923" + sodipodi:ry="38.848923" + d="M 293.95683,326.69064 A 38.848923,38.848923 0 1 1 216.25899,326.69064 A 38.848923,38.848923 0 1 1 293.95683,326.69064 z" + transform="matrix(0.4405339,0,0,0.4405339,1842.2283,2282.9708)" /> + <text + xml:space="preserve" + style="font-size:27.62000275px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="1946.3259" + y="2435.7" + id="text5550"><tspan + sodipodi:role="line" + id="tspan5552" + x="1946.3259" + y="2435.7" + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-family:FreeMono;-inkscape-font-specification:FreeMono Bold">2</tspan></text> + </g> + <g + transform="matrix(0,-1,1,0,697.50638,3244.256)" + id="g5624"> + <g + id="g5626" + transform="matrix(0,-1,1,0,-294.81158,2953.0504)"> + <path + sodipodi:nodetypes="cc" + inkscape:connector-type="polyline" + id="path5628" + d="M 1586.5317,1348.2858 L 1586.6222,1389.8124" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;marker-start:none;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;display:inline" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;marker-start:none;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;display:inline" + d="M 1586.7489,1389.4756 L 1594.7468,1380.3688" + id="path5630" + inkscape:connector-type="polyline" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;marker-start:none;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;display:inline" + d="M 1586.6031,1389.5063 L 1578.6052,1380.3994" + id="path5632" + inkscape:connector-type="polyline" + sodipodi:nodetypes="cc" /> + </g> + </g> + <g + transform="translate(5.3442137,15.993306)" + id="g5459"> + <rect + rx="2.4652832" + ry="2.9818845" + y="2151.3206" + x="1965.7682" + height="75.127686" + width="185.53668" + id="rect3485" + style="fill:#b2e994;fill-opacity:1;stroke:#56f400;stroke-width:0.78531456;stroke-opacity:1" /> + <text + id="text3487" + y="2184.2461" + x="2059.1909" + style="font-size:27.94354057px;font-style:normal;font-weight:normal;text-align:center;text-anchor:middle;fill:#1f5800;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + id="tspan2509" + style="font-size:19.56047821px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;text-anchor:middle;fill:#1f5800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans" + y="2184.2461" + x="2059.1909" + sodipodi:role="line">typesystem</tspan><tspan + style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;text-anchor:middle;fill:#1f5800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans" + y="2205.1477" + x="2059.1909" + sodipodi:role="line" + id="tspan5432">(handwritten)</tspan></text> + </g> + <g + transform="matrix(0,-1,1,0,908.50929,3242.9612)" + id="g5648"> + <g + id="g5650" + transform="matrix(0,-1,1,0,-294.81158,2953.0504)"> + <path + sodipodi:nodetypes="cc" + inkscape:connector-type="polyline" + id="path5652" + d="M 1586.5317,1348.2858 L 1586.6222,1389.8124" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;marker-start:none;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;display:inline" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;marker-start:none;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;display:inline" + d="M 1586.7489,1389.4756 L 1594.7468,1380.3688" + id="path5654" + inkscape:connector-type="polyline" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;marker-start:none;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;display:inline" + d="M 1586.6031,1389.5063 L 1578.6052,1380.3994" + id="path5656" + inkscape:connector-type="polyline" + sodipodi:nodetypes="cc" /> + </g> + </g> + <g + transform="translate(299.78191,21.148391)" + id="g2771"> + <rect + style="fill:#cce994;fill-opacity:1;stroke:#a1f400;stroke-width:0.62429351;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + id="rect2733" + width="185.69771" + height="75.288704" + x="1882.2529" + y="2146.085" + ry="2.2607138" + rx="2.0576432" /> + <text + xml:space="preserve" + style="font-size:40px;font-style:normal;font-weight:normal;text-align:center;text-anchor:middle;fill:#3a5800;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="1975.134" + y="2180.2722" + id="text2735"><tspan + sodipodi:role="line" + x="1975.134" + y="2180.2722" + style="font-size:22px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;text-anchor:middle;fill:#3a5800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans Bold" + id="tspan2737">injected code</tspan><tspan + id="tspan2743" + sodipodi:role="line" + x="1975.134" + y="2201.7917" + style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;text-anchor:middle;fill:#3a5800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans">(handwritten)</tspan></text> + </g> + <g + transform="translate(200.4676,-222.96766)" + id="g5554"> + <path + sodipodi:type="arc" + style="fill:#f28888;fill-opacity:1;stroke:#d5f400;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:3, 3;stroke-dashoffset:0;stroke-opacity:1" + id="path5556" + sodipodi:cx="255.10791" + sodipodi:cy="326.69064" + sodipodi:rx="38.848923" + sodipodi:ry="38.848923" + d="M 293.95683,326.69064 A 38.848923,38.848923 0 1 1 216.25899,326.69064 A 38.848923,38.848923 0 1 1 293.95683,326.69064 z" + transform="matrix(0.4405339,0,0,0.4405339,1842.2283,2282.9708)" /> + <text + xml:space="preserve" + style="font-size:27.62000275px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="1946.3259" + y="2435.7" + id="text5558"><tspan + sodipodi:role="line" + id="tspan5560" + x="1946.3259" + y="2435.7" + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-family:FreeMono;-inkscape-font-specification:FreeMono Bold">3</tspan></text> + </g> + <g + transform="translate(413.633,-206.84535)" + id="g5562"> + <path + sodipodi:type="arc" + style="fill:#f28888;fill-opacity:1;stroke:#d5f400;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:3, 3;stroke-dashoffset:0;stroke-opacity:1" + id="path5564" + sodipodi:cx="255.10791" + sodipodi:cy="326.69064" + sodipodi:rx="38.848923" + sodipodi:ry="38.848923" + d="M 293.95683,326.69064 A 38.848923,38.848923 0 1 1 216.25899,326.69064 A 38.848923,38.848923 0 1 1 293.95683,326.69064 z" + transform="matrix(0.4405339,0,0,0.4405339,1842.2283,2282.9708)" /> + <text + xml:space="preserve" + style="font-size:27.62000275px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="1946.3259" + y="2435.7" + id="text5566"><tspan + sodipodi:role="line" + id="tspan5568" + x="1946.3259" + y="2435.7" + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-family:FreeMono;-inkscape-font-specification:FreeMono Bold">4</tspan></text> + </g> + </g> + </g> +</svg> diff --git a/sources/shiboken2/doc/images/boostgen.png b/sources/shiboken2/doc/images/boostgen.png Binary files differnew file mode 100644 index 000000000..ae9d9fc3d --- /dev/null +++ b/sources/shiboken2/doc/images/boostgen.png diff --git a/sources/shiboken2/doc/images/boostqtarch.png b/sources/shiboken2/doc/images/boostqtarch.png Binary files differnew file mode 100644 index 000000000..f1b145e9c --- /dev/null +++ b/sources/shiboken2/doc/images/boostqtarch.png diff --git a/sources/shiboken2/doc/images/boostqtarch.svg b/sources/shiboken2/doc/images/boostqtarch.svg new file mode 100644 index 000000000..9fbb38271 --- /dev/null +++ b/sources/shiboken2/doc/images/boostqtarch.svg @@ -0,0 +1,226 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="350" + height="220" + id="svg2" + sodipodi:version="0.32" + inkscape:version="0.46" + version="1.0" + sodipodi:docname="boostqtarch.svg" + inkscape:output_extension="org.inkscape.output.svg.inkscape" + inkscape:export-filename="boostqtarch.png" + inkscape:export-xdpi="90" + inkscape:export-ydpi="90"> + <defs + id="defs4"> + <marker + inkscape:stockid="Arrow2Lend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Lend" + style="overflow:visible"> + <path + id="path3636" + style="font-size:12px;fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round" + d="M 8.7185878,4.0337352 L -2.2072895,0.016013256 L 8.7185884,-4.0017078 C 6.97309,-1.6296469 6.9831476,1.6157441 8.7185878,4.0337352 z" + transform="matrix(-1.1,0,0,-1.1,-1.1,0)" /> + </marker> + <inkscape:perspective + sodipodi:type="inkscape:persp3d" + inkscape:vp_x="0 : 526.18109 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_z="744.09448 : 526.18109 : 1" + inkscape:persp3d-origin="372.04724 : 350.78739 : 1" + id="perspective10" /> + </defs> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + gridtolerance="10000" + guidetolerance="10" + objecttolerance="10" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="1.4812981" + inkscape:cx="145.70936" + inkscape:cy="94.089827" + inkscape:document-units="px" + inkscape:current-layer="layer1" + showgrid="false" + inkscape:window-width="1278" + inkscape:window-height="951" + inkscape:window-x="1592" + inkscape:window-y="29" + showguides="true" + inkscape:guide-bbox="true" /> + <metadata + id="metadata7"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + </cc:Work> + </rdf:RDF> + </metadata> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1" + transform="translate(-61.076804,-301.50489)"> + <flowRoot + xml:space="preserve" + id="flowRoot3229" + style="font-size:40px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + transform="translate(2.0918751e-6,-6.0000008)"><flowRegion + id="flowRegion3231"><rect + id="rect3233" + width="125.74072" + height="40.5849" + x="388.45547" + y="279.5423" /></flowRegion><flowPara + id="flowPara3235" /></flowRoot> <g + id="g3010" + transform="matrix(0.9508755,0,0,0.9508755,11.317746,20.273572)"> + <g + transform="translate(0,-9.7919846e-6)" + id="g2952"> + <rect + style="fill:#dfe994;fill-opacity:1;stroke:#d5f400;stroke-width:0.7162478;stroke-opacity:1" + id="rect3166" + width="349.23203" + height="67.403336" + x="61.417336" + y="377.74161" + ry="2.6752985" + rx="2.285728" /> + <text + xml:space="preserve" + style="font-size:29.38717079px;font-style:normal;font-weight:normal;text-align:center;text-anchor:middle;fill:#4c5800;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="236.08904" + y="397.98755" + id="text3168"><tspan + sodipodi:role="line" + x="236.08904" + y="397.98755" + style="font-size:20.57102013px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;text-anchor:middle;fill:#4c5800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans" + id="tspan3176">Boost::Python</tspan><tspan + sodipodi:role="line" + x="236.08904" + y="418.35535" + style="font-size:15.20761585px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;text-anchor:middle;fill:#4c5800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans" + id="tspan2880">helper library to interface with CPython API</tspan><tspan + id="tspan2922" + sodipodi:role="line" + x="236.08904" + y="437.36487" + style="font-size:15.20761585px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;text-anchor:middle;fill:#4c5800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans">and expose C++ entities to Python</tspan></text> + </g> + <g + transform="translate(0,-9.7025776e-6)" + id="g2959"> + <rect + style="fill:#addc52;fill-opacity:1;stroke:#6ca400;stroke-width:0.71624762;stroke-opacity:1" + id="rect3542" + width="349.23203" + height="67.403351" + x="61.417336" + y="301.84543" + ry="2.675298" + rx="2.285728" /> + <text + xml:space="preserve" + style="font-size:29.38717079px;font-style:normal;font-weight:normal;text-align:center;text-anchor:middle;fill:#050800;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="236.5123" + y="322.09137" + id="text3544"><tspan + id="tspan3596" + sodipodi:role="line" + x="236.5123" + y="322.09137" + style="font-size:20.57102013px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;text-anchor:middle;fill:#050800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans">Qt-Python Bindings</tspan><tspan + sodipodi:role="line" + x="236.5123" + y="342.45917" + style="font-size:15.20761585px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;text-anchor:middle;fill:#050800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans" + id="tspan12937">Qt classes and functions</tspan><tspan + sodipodi:role="line" + x="236.5123" + y="361.46869" + style="font-size:15.20761585px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;text-anchor:middle;fill:#050800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans" + id="tspan2411">exported to Python</tspan></text> + </g> + <g + id="g2998"> + <g + id="g2986"> + <rect + rx="2.285728" + ry="2.675298" + y="453.63776" + x="61.417336" + height="67.403336" + width="172.02341" + id="rect3485" + style="fill:#b2e994;fill-opacity:1;stroke:#56f400;stroke-width:0.71624762;stroke-opacity:1" /> + <text + id="text3487" + y="482.29712" + x="147.73038" + style="font-size:29.38717079px;font-style:normal;font-weight:normal;text-align:center;text-anchor:middle;fill:#1f5800;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + style="font-size:20.57102013px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;text-anchor:middle;fill:#1f5800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans" + y="482.29712" + x="147.73038" + sodipodi:role="line" + id="tspan3499">CPython</tspan><tspan + id="tspan2509" + style="font-size:20.57102013px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;text-anchor:middle;fill:#1f5800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans" + y="508.01089" + x="147.73038" + sodipodi:role="line">API</tspan></text> + </g> + <g + id="g2992"> + <rect + rx="2.285728" + ry="2.675298" + y="453.63776" + x="239.30101" + height="67.403351" + width="172.02295" + id="rect2459" + style="fill:#cce994;fill-opacity:1;stroke:#a1f400;stroke-width:0.71624762;stroke-opacity:1" /> + <text + id="text2461" + y="481.97067" + x="324.86047" + style="font-size:29.38717079px;font-style:normal;font-weight:normal;text-align:center;text-anchor:middle;fill:#3a5800;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + style="font-size:20.57102013px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;text-anchor:middle;fill:#3a5800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans" + y="481.97067" + x="324.86047" + sodipodi:role="line" + id="tspan2467">Qt4</tspan><tspan + id="tspan2490" + style="font-size:20.57102013px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;text-anchor:middle;fill:#3a5800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans" + y="507.68445" + x="324.86047" + sodipodi:role="line">Libraries</tspan></text> + </g> + </g> + </g> + </g> +</svg> diff --git a/sources/shiboken2/doc/images/converter.dot b/sources/shiboken2/doc/images/converter.dot new file mode 100644 index 000000000..412341df9 --- /dev/null +++ b/sources/shiboken2/doc/images/converter.dot @@ -0,0 +1,14 @@ +digraph Conversions { + rankdir=LR + CppType1 [ label="C++\nType" ] + Converter1 [ label="Converter\nPython -> C++", shape=hexagon ] + PythonType1 -> Converter1 + PythonType2 -> Converter1 + PythonType3 -> Converter1 + Converter1 -> CppType1 + + CppType2 [ label="C++\nType" ] + PythonType4 [ label="PythonType" ] + Converter2 [ label="Converter\nPython -> C++", shape=hexagon ] + CppType2 -> Converter2 -> PythonType4 +}
\ No newline at end of file diff --git a/sources/shiboken2/doc/images/converter.png b/sources/shiboken2/doc/images/converter.png Binary files differnew file mode 100644 index 000000000..51cd2af71 --- /dev/null +++ b/sources/shiboken2/doc/images/converter.png diff --git a/sources/shiboken2/doc/images/genrunnerarch.png b/sources/shiboken2/doc/images/genrunnerarch.png Binary files differnew file mode 100644 index 000000000..db1077cd0 --- /dev/null +++ b/sources/shiboken2/doc/images/genrunnerarch.png diff --git a/sources/shiboken2/doc/images/genrunnerarch.svg b/sources/shiboken2/doc/images/genrunnerarch.svg new file mode 100644 index 000000000..ea7eb73e7 --- /dev/null +++ b/sources/shiboken2/doc/images/genrunnerarch.svg @@ -0,0 +1,654 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> + +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="980" + height="380" + id="svg2" + sodipodi:version="0.32" + inkscape:version="0.47pre4 r22446" + version="1.0" + sodipodi:docname="genrunnerarch.svg" + inkscape:output_extension="org.inkscape.output.svg.inkscape" + inkscape:export-filename="genrunnerarch.png" + inkscape:export-xdpi="56.549999" + inkscape:export-ydpi="56.549999"> + <defs + id="defs4"> + <marker + inkscape:stockid="EmptyDiamondL" + orient="auto" + refY="0" + refX="0" + id="EmptyDiamondL" + style="overflow:visible"> + <path + id="path3930" + d="M 0,-7.0710768 -7.0710894,0 0,7.0710589 7.0710462,0 0,-7.0710768 z" + style="fill:#ffffff;fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none" + transform="scale(0.8,0.8)" /> + </marker> + <marker + inkscape:stockid="EmptyTriangleInL" + orient="auto" + refY="0" + refX="0" + id="EmptyTriangleInL" + style="overflow:visible"> + <path + id="path3975" + d="m 5.77,0 -8.65,5 0,-10 8.65,5 z" + style="fill:#ffffff;fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none" + transform="matrix(-0.8,0,0,-0.8,4.8,0)" /> + </marker> + <marker + inkscape:stockid="Arrow1Sstart" + orient="auto" + refY="0" + refX="0" + id="Arrow1Sstart" + style="overflow:visible"> + <path + id="path3835" + d="M 0,0 5,-5 -12.5,0 5,5 0,0 z" + style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none" + transform="matrix(0.2,0,0,0.2,1.2,0)" /> + </marker> + <marker + inkscape:stockid="Arrow1Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow1Mend" + style="overflow:visible"> + <path + id="path3832" + d="M 0,0 5,-5 -12.5,0 5,5 0,0 z" + style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none" + transform="matrix(-0.4,0,0,-0.4,-4,0)" /> + </marker> + <marker + inkscape:stockid="Tail" + orient="auto" + refY="0" + refX="0" + id="Tail" + style="overflow:visible"> + <g + id="g3859" + transform="scale(-1.2,-1.2)"> + <path + id="path3861" + d="M -3.8048674,-3.9585227 0.54352094,0" + style="fill:none;stroke:#000000;stroke-width:0.80000001;stroke-linecap:round;marker-start:none;marker-end:none" /> + <path + id="path3863" + d="M -1.2866832,-3.9585227 3.0617053,0" + style="fill:none;stroke:#000000;stroke-width:0.80000001;stroke-linecap:round;marker-start:none;marker-end:none" /> + <path + id="path3865" + d="M 1.3053582,-3.9585227 5.6537466,0" + style="fill:none;stroke:#000000;stroke-width:0.80000001;stroke-linecap:round;marker-start:none;marker-end:none" /> + <path + id="path3867" + d="M -3.8048674,4.1775838 0.54352094,0.21974226" + style="fill:none;stroke:#000000;stroke-width:0.80000001;stroke-linecap:round;marker-start:none;marker-end:none" /> + <path + id="path3869" + d="M -1.2866832,4.1775838 3.0617053,0.21974226" + style="fill:none;stroke:#000000;stroke-width:0.80000001;stroke-linecap:round;marker-start:none;marker-end:none" /> + <path + id="path3871" + d="M 1.3053582,4.1775838 5.6537466,0.21974226" + style="fill:none;stroke:#000000;stroke-width:0.80000001;stroke-linecap:round;marker-start:none;marker-end:none" /> + </g> + </marker> + <marker + inkscape:stockid="Arrow2Lend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Lend" + style="overflow:visible"> + <path + id="path3636" + style="font-size:12px;fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="matrix(-1.1,0,0,-1.1,-1.1,0)" /> + </marker> + <inkscape:perspective + sodipodi:type="inkscape:persp3d" + inkscape:vp_x="0 : 526.18109 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_z="744.09448 : 526.18109 : 1" + inkscape:persp3d-origin="372.04724 : 350.78739 : 1" + id="perspective10" /> + <inkscape:perspective + id="perspective3033" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + <inkscape:perspective + id="perspective3881" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + <inkscape:perspective + id="perspective3915" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + <inkscape:perspective + id="perspective3956" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + <inkscape:perspective + id="perspective5100" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + <inkscape:perspective + id="perspective5322" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + <inkscape:perspective + id="perspective5365" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + <inkscape:perspective + id="perspective5391" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + <marker + inkscape:stockid="EmptyTriangleInL" + orient="auto" + refY="0" + refX="0" + id="EmptyTriangleInL-4" + style="overflow:visible"> + <path + id="path3975-9" + d="m 5.77,0 -8.65,5 0,-10 8.65,5 z" + style="fill:#ffffff;fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none" + transform="matrix(-0.8,0,0,-0.8,4.8,0)" /> + </marker> + <inkscape:perspective + id="perspective5621" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + <inkscape:perspective + id="perspective5643" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + <marker + inkscape:stockid="EmptyDiamondL" + orient="auto" + refY="0" + refX="0" + id="EmptyDiamondL-7" + style="overflow:visible"> + <path + id="path3930-7" + d="M 0,-7.0710768 -7.0710894,0 0,7.0710589 7.0710462,0 0,-7.0710768 z" + style="fill:#ffffff;fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none" + transform="scale(0.8,0.8)" /> + </marker> + </defs> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + gridtolerance="10000" + guidetolerance="10" + objecttolerance="10" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="1.0716799" + inkscape:cx="460.27913" + inkscape:cy="148.01364" + inkscape:document-units="px" + inkscape:current-layer="layer1" + showgrid="false" + inkscape:window-width="1862" + inkscape:window-height="1019" + inkscape:window-x="20" + inkscape:window-y="89" + showguides="true" + inkscape:guide-bbox="true" + inkscape:window-maximized="0" /> + <metadata + id="metadata7"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <dc:title></dc:title> + </cc:Work> + </rdf:RDF> + </metadata> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1" + transform="translate(472.44407,-697.53823)"> + <flowRoot + xml:space="preserve" + id="flowRoot3229" + style="font-size:40px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans" + transform="translate(2.0918751e-6,-6.0000008)"><flowRegion + id="flowRegion3231"><rect + id="rect3233" + width="125.74072" + height="40.5849" + x="388.45547" + y="279.5423" /></flowRegion><flowPara + id="flowPara3235" /></flowRoot> <g + id="g5867" + transform="translate(6.7062969,-7.6922472)"> + <rect + rx="3.4968286" + ry="5.2462597" + y="713.31403" + x="-472.05276" + height="363.61459" + width="393.78473" + id="rect3609" + style="fill:#e4fae3;fill-opacity:0.65882353;stroke:#8eff89;stroke-width:0.78260708;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <text + transform="scale(1.0000266,0.9999734)" + id="text3601" + y="742.43872" + x="-275.16165" + style="font-size:38.71272278px;font-style:normal;font-weight:normal;text-align:center;text-anchor:middle;fill:#035800;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + id="tspan3605" + style="font-size:27.09890556px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;text-anchor:middle;fill:#035800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans" + y="742.43872" + x="-275.16165" + sodipodi:role="line"><tspan + id="tspan2508" + style="font-weight:bold">API Extractor</tspan></tspan></text> + <g + transform="matrix(0.9678438,0,0,0.9677923,-587.62742,-106.48682)" + id="g3763"> + <rect + style="fill:#bff3bc;fill-opacity:1;stroke:#0af400;stroke-width:0.79775763;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + id="rect3737" + width="244.82956" + height="101.59812" + x="267.06232" + y="905.13727" + ry="3.1522403" + rx="2.4096873" /> + <text + xml:space="preserve" + style="font-size:40px;font-style:normal;font-weight:normal;text-align:center;text-anchor:middle;fill:#035800;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans" + x="389.39117" + y="931.86993" + id="text3739"><tspan + sodipodi:role="line" + x="389.39117" + y="931.86993" + style="font-size:22px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;text-anchor:middle;fill:#035800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans Bold" + id="tspan3741">ApiExtractor</tspan><tspan + id="tspan2523" + sodipodi:role="line" + x="389.39117" + y="953.38947" + style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;text-anchor:middle;fill:#035800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans">commands the parsing and</tspan><tspan + id="tspan2517" + sodipodi:role="line" + x="389.39117" + y="973.38947" + style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;text-anchor:middle;fill:#035800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans">building of the data model</tspan><tspan + id="tspan2519" + sodipodi:role="line" + x="389.39117" + y="993.38947" + style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;text-anchor:middle;fill:#035800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans">and calls the user generators</tspan></text> + </g> + <rect + rx="2.1814992" + ry="5.2485871" + y="713.45312" + x="219.72128" + height="363.77597" + width="274.11292" + id="rect9190" + style="fill:#b8d1f1;fill-opacity:0.51184836;stroke:#0045a4;stroke-width:0.6182732;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <text + transform="scale(1.0000266,0.9999734)" + id="text9192" + y="742.66901" + x="357.65579" + style="font-size:38.71272278px;font-style:normal;font-weight:normal;text-align:center;text-anchor:middle;fill:#002e7a;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + id="tspan9194" + style="font-size:27.09890556px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;text-anchor:middle;fill:#002e7a;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans" + y="742.66901" + x="357.65579" + sodipodi:role="line"><tspan + id="tspan2512" + style="font-weight:bold;fill:#002e7a;fill-opacity:1">front-end</tspan><tspan + id="tspan2514" + style="font-size:22px;fill:#002e7a;fill-opacity:1" /></tspan></text> + <rect + rx="2.2192271" + ry="5.2485123" + y="713.23639" + x="-68.659073" + height="363.77075" + width="278.85358" + id="rect9190-9" + style="fill:#cbe990;fill-opacity:0.51184836;stroke:#6ca400;stroke-width:0.62359226;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <text + transform="scale(1.0000266,0.9999734)" + id="text9192-3" + y="741.71094" + x="70.291061" + style="font-size:38.71272278px;font-style:normal;font-weight:normal;text-align:center;text-anchor:middle;fill:#050800;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + id="tspan9194-7" + style="font-size:26px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;text-anchor:middle;fill:#050800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans" + y="741.71094" + x="70.291061" + sodipodi:role="line">Generator Runner</tspan></text> + <g + transform="matrix(0.9678438,0,0,0.9677923,-687.04869,-241.74888)" + id="g9234-4"> + <rect + style="fill:#addc52;fill-opacity:1;stroke:#6ca400;stroke-width:0.73640609;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + id="rect9206-4" + width="218.17299" + height="83.517967" + x="694.6994" + y="1044.8701" + ry="2.5912752" + rx="2.4978092" /> + <text + xml:space="preserve" + style="font-size:40px;font-style:normal;font-weight:normal;text-align:center;text-anchor:middle;fill:#035800;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans" + x="803.78589" + y="1072.3693" + id="text9208-3"><tspan + sodipodi:role="line" + x="803.78589" + y="1072.3693" + style="font-size:22px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;text-anchor:middle;fill:#050800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans Bold" + id="tspan9210-0">Generator</tspan><tspan + id="tspan9222-8" + sodipodi:role="line" + x="803.78589" + y="1093.8888" + style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;text-anchor:middle;fill:#050800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans">base class for front-end</tspan><tspan + id="tspan3946" + sodipodi:role="line" + x="803.78589" + y="1113.8888" + style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;text-anchor:middle;fill:#050800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans">output classes</tspan></text> + </g> + <g + transform="matrix(0.9678438,0,0,0.9677923,-726.09128,-46.791689)" + id="g10497-6"> + <rect + style="fill:#89b3e7;fill-opacity:1;stroke:#0049a4;stroke-width:1.04736876;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + id="rect10444-8" + width="256.05252" + height="143.95157" + x="990.81482" + y="843.58032" + ry="4.4663219" + rx="2.9314826" /> + <text + xml:space="preserve" + style="font-size:40px;font-style:normal;font-weight:normal;text-align:center;text-anchor:middle;fill:#002758;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans" + x="1118.0945" + y="873.04047" + id="text10446-8"><tspan + sodipodi:role="line" + x="1118.0945" + y="873.04047" + style="font-size:22px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;text-anchor:middle;fill:#002758;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans Bold" + id="tspan10448-4">SpecificGenerator</tspan><tspan + id="tspan4063" + sodipodi:role="line" + x="1118.0945" + y="894.56" + style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;text-anchor:middle;fill:#002758;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans">generators written for any</tspan><tspan + id="tspan5381" + sodipodi:role="line" + x="1118.0945" + y="914.56" + style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;text-anchor:middle;fill:#002758;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans">desired output,</tspan><tspan + id="tspan4065" + sodipodi:role="line" + x="1118.0945" + y="934.56" + style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;text-anchor:middle;fill:#002758;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans"> e.g.: HppGenerator,</tspan><tspan + id="tspan4071" + sodipodi:role="line" + x="1118.0945" + y="954.56" + style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;text-anchor:middle;fill:#002758;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans">CppGenerator,</tspan><tspan + id="tspan4073" + sodipodi:role="line" + x="1118.0945" + y="974.56" + style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;text-anchor:middle;fill:#002758;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans">ConverterGenerator</tspan></text> + </g> + <path + sodipodi:nodetypes="cc" + transform="translate(109.91989,748.26874)" + id="path4056" + d="m -201.98482,41.728896 76.97065,5e-6" + style="fill:none;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:6, 1;stroke-dashoffset:0" /> + <path + sodipodi:nodetypes="cc" + id="path4056-2" + d="m 197.04022,787.89746 35.38656,0" + style="fill:none;stroke:#000000;stroke-width:1;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;marker-start:url(#EmptyTriangleInL)" /> + <g + transform="matrix(0.9678438,0,0,0.9677923,-1010.4541,91.401187)" + id="g10497"> + <rect + style="fill:#addc52;fill-opacity:1;stroke:#6ca400;stroke-width:0.88060772;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + id="rect10444" + width="256.21927" + height="101.69494" + x="990.73145" + y="843.49695" + ry="3.1552441" + rx="2.9333918" /> + <text + xml:space="preserve" + style="font-size:40px;font-style:normal;font-weight:normal;text-align:start;text-anchor:start;fill:#035800;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans" + x="1012.22" + y="870.08466" + id="text10446"><tspan + sodipodi:role="line" + x="1012.22" + y="870.08466" + style="font-size:22px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:start;text-anchor:start;fill:#050800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans Bold" + id="tspan10448">Generator App</tspan><tspan + id="tspan10456" + sodipodi:role="line" + x="1012.22" + y="891.60419" + style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;text-anchor:start;fill:#050800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans">* loads generators</tspan><tspan + id="tspan5353" + sodipodi:role="line" + x="1012.22" + y="911.60419" + style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;text-anchor:start;fill:#050800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans">* setup API Extractor</tspan><tspan + id="tspan5355" + sodipodi:role="line" + x="1012.22" + y="931.60419" + style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;text-anchor:start;fill:#050800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans">* executes each generator</tspan></text> + </g> + <path + sodipodi:nodetypes="cc" + id="path4056-9" + d="m 72.409302,850.57374 0,56.99122" + style="fill:none;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:6, 1;stroke-dashoffset:0" /> + <path + sodipodi:nodetypes="ccc" + id="path4056-2-0" + d="m -86.437722,825.54499 52.188784,0 0.06367,81.67009" + style="fill:none;stroke:#000000;stroke-width:1;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;marker-start:url(#EmptyDiamondL)" /> + <path + sodipodi:nodetypes="cc" + id="path4056-91" + d="m -394.83596,853.70064 0,121.42437" + style="fill:none;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:6, 1;stroke-dashoffset:0" /> + <g + transform="matrix(0.9678438,0,0,0.9677923,-707.18032,-153.53291)" + id="g3809"> + <rect + style="fill:#bff3bc;fill-opacity:1;stroke:#0af400;stroke-width:1.00168562;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + id="rect3785" + width="332.48172" + height="82.830231" + x="302.83319" + y="1068.9153" + ry="3.1461167" + rx="3.8065021" /> + <text + xml:space="preserve" + style="font-size:40px;font-style:normal;font-weight:normal;text-align:center;text-anchor:middle;fill:#035800;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans" + x="469.03497" + y="1095.5493" + id="text3787"><tspan + id="tspan3791" + sodipodi:role="line" + x="469.03497" + y="1095.5493" + style="font-size:22px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;text-anchor:middle;fill:#035800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans Bold">AbstractMetaBuilder</tspan><tspan + sodipodi:role="line" + x="469.03497" + y="1117.0688" + style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;text-anchor:middle;fill:#035800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans" + id="tspan3807">builds the data model with information</tspan><tspan + id="tspan2545" + sodipodi:role="line" + x="469.03497" + y="1137.0688" + style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;text-anchor:middle;fill:#035800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans">from headers and binding directives</tspan><tspan + id="tspan3795" + sodipodi:role="line" + x="469.03497" + y="1157.0688" + style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;text-anchor:middle;fill:#035800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans" /></text> + </g> + <g + transform="matrix(0.9678438,0,0,0.9677923,-755.89347,194.37862)" + id="g3709"> + <rect + style="fill:#bff3bc;fill-opacity:1;stroke:#0af400;stroke-width:0.69825613;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + id="rect2821" + width="198.90968" + height="93.892342" + x="305.2475" + y="807.38849" + ry="2.6812849" + rx="2.1703238" /> + <text + xml:space="preserve" + style="font-size:40px;font-style:normal;font-weight:normal;text-align:center;text-anchor:middle;fill:#035800;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans" + x="405.17499" + y="831.81903" + id="text3611"><tspan + id="tspan3687" + sodipodi:role="line" + x="405.17499" + y="831.81903" + style="font-size:22px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;text-anchor:middle;fill:#035800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans Bold">TypeDatabase</tspan><tspan + id="tspan5641" + sodipodi:role="line" + x="405.17499" + y="853.33856" + style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;text-anchor:middle;fill:#035800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans">parses typesystem</tspan><tspan + id="tspan3689" + sodipodi:role="line" + x="405.17499" + y="873.33856" + style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;text-anchor:middle;fill:#035800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans">and stores information</tspan></text> + </g> + <g + transform="matrix(0.9678438,0,0,0.9677923,-589.50555,-13.923919)" + id="g3728"> + <rect + style="fill:#bff3bc;fill-opacity:1;stroke:#0af400;stroke-width:0.54871088;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + id="rect3625" + width="117.15066" + height="86.355225" + x="133.25664" + y="809.36938" + ry="2.6793056" + rx="1.3412292" /> + <text + xml:space="preserve" + style="font-size:40px;font-style:normal;font-weight:normal;text-align:center;text-anchor:middle;fill:#035800;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans" + x="191.58197" + y="838.75159" + id="text3627"><tspan + sodipodi:role="line" + x="191.58197" + y="838.75159" + style="font-size:22px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;text-anchor:middle;fill:#035800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans Bold" + id="tspan3631">Parser</tspan><tspan + id="tspan3695" + sodipodi:role="line" + x="191.58197" + y="860.27112" + style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;text-anchor:middle;fill:#035800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans">parses the</tspan><tspan + id="tspan3697" + sodipodi:role="line" + x="191.58197" + y="880.27112" + style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;text-anchor:middle;fill:#035800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans">lib headers</tspan></text> + </g> + <path + sodipodi:nodetypes="ccc" + id="path4056-2-0-1" + d="m 197.39006,961.71122 158.27877,0 0.19429,-51.88885" + style="fill:none;stroke:#000000;stroke-width:1.38812411;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:8.32874408, 1.38812401;stroke-dashoffset:0;marker-start:none" /> + </g> + </g> +</svg> diff --git a/sources/shiboken2/doc/overview.rst b/sources/shiboken2/doc/overview.rst new file mode 100644 index 000000000..5f50610ff --- /dev/null +++ b/sources/shiboken2/doc/overview.rst @@ -0,0 +1,46 @@ +.. _gen-overview: + +****************** +Generator Overview +****************** + +In a few words, the Generator is a utility that parses a collection of header and +typesystem files, generating other files (code, documentation, etc.) as result. + +Creating new bindings +===================== + +.. figure:: images/bindinggen-development.png + :scale: 80 + :align: center + + Creating new bindings + +Each module of the generator system has an specific role. + +1. Provide enough data about the classes and functions. +2. Generate valid code, with modifications from typesystems and injected codes. +3. Modify the API to expose the objects in a way that fits you target language best. +4. Insert customizations where handwritten code is needed. + +.. figure:: images/boostqtarch.png + :scale: 80 + :align: center + + Runtime architecture + +The newly created binding will run on top of Boost.Python library which takes +care of interfacing Python and the underlying C++ library. + +Handwritten inputs +================== + +Creating new bindings involves creating two pieces of "code": the typesystem and +the inject code. + +:typesystem: XML files that provides the developer with a tool to customize the + way that the generators will see the classes and functions. For + example, functions can be renamed, have its signature changed and + many other actions. +:inject code: allows the developer to insert handwritten code where the generated + code is not suitable or needs some customization. diff --git a/sources/shiboken2/doc/ownership.rst b/sources/shiboken2/doc/ownership.rst new file mode 100644 index 000000000..69791f855 --- /dev/null +++ b/sources/shiboken2/doc/ownership.rst @@ -0,0 +1,153 @@ +**************** +Object ownership +**************** + +One of the main things a binding developer should have in mind is +how the C++ instances lives will cope with Python's reference count. +The last thing you want is to crash a program due to a segfault +when your C++ instance was deleted and the +wrapper object tries to access the invalid memory there. + +In this section we'll show how |project| deals with object ownership +and parentship, taking advantage of the information provided by the +APIExtractor. + +Ownership basics +================ + +As any python binding, |project|-based bindings uses reference counting +to handle the life of the wrapper object (the Python object that contains the +C++ object, do not confuse with the *wrapped* C++ object). +When a reference count reaches zero, the wrapper is deleted by Python garbage +collector and tries to delete the wrapped instance, but sometimes the wrapped +C++ object is already deleted, or maybe the C++ object should not be freed after +the Python wrapper go out of scope and die, because C++ is already taking care of +the wrapped instance. + +In order to handle this, you should tell the +generator whether the instance's ownership belongs to the binding or +to the C++ Library. When belonging to the binding, we are sure that the C++ object +won't be deleted by C++ code and we can call the C++ destructor when the refcount +reaches 0. Otherwise, instances owned by C++ code can be destroyed arbitrarily, +without notifying the Python wrapper of its destruction. + +Invalidating objects +==================== + +To prevent segfaults and double frees, the wrapper objects are invalidated. +An invalidated can't be passed as argument or have an attributte or method accessed. +Trying to do this will raise RuntimeError. + +The following situations can invalidate an object: + +C++ taking ownership +-------------------- + + When an object is passed to a function or method that takes ownership of it, the wrapper + is invalidated as we can't be sure of when the object is destroyed, unless it has a + :ref:`virtual destructor <ownership-virt-method>` or the transfer is due to the special case + of :ref:`parent ownership <ownership-parent>`. + + Besides being passed as argument, the callee object can have its ownership changed, like + the `setParent` method in Qt's `QObject`. + +Invalidate after use +-------------------- + + Objects marked with *invalidate-after-use* in the type system description always are + virtual method arguments provided by a C++ originated call. They should be + invalidated right after the Python function returns. + +.. _ownership-virt-method: + +Objects with virtual methods +---------------------------- + + A little bit of implementation details: + virtual methods are supported by creating a C++ class, the **shell**, that inherits + from the class with virtual methods, the native one, and override those methods to check if + any derived class in Python also override it. + + If the class has a virtual destructor (and C++ classes with virtual methods should have), this + C++ instance invalidates the wrapper only when the overriden destructor is called. + + One exception to this rule is when the object is created in C++, like in a + factory method. This way the wrapped object is a C++ instance of the native + class, not the shell one, and we cannot know when it is destroyed. + +.. _ownership-parent: + +Parent-child relationship +========================= + +One special type of ownership is the parent-child relationship. +Being a child of an object means that when the object's parent dies, +the C++ instance also dies, so the Python references will be invalidated. +Qt's QObject system, for example, implements this behavior, but this is valid +for any C++ library with similar behavior. + +.. _ownership-parent-heuristics: + +Parentship heuristics +--------------------- + + As the parent-child relationship is very common, |project| tries to automatically + infer what methods falls into the parent-child scheme, adding the extra + directives related to ownership. + + This heuristic will be triggered when generating code for a method and: + + * The function is a constructor. + * The argument name is `parent`. + * The argument type is a pointer to an object. + + When triggered, the heuristic will set the argument named "parent" + as the parent of the object being created by the constructor. + + The main focus of this process was to remove a lot of hand written code from + type system when binding Qt libraries. For Qt, this heuristic works in all cases, + but be aware that it might not when binding your own libraries. + + To activate this heuristic, use the :ref:`--enable-parent-ctor-heuristic <parent-heuristic>` + command line switch. + +.. _return-value-heuristics: + +Return value heuristics +----------------------- + + When enabled, object returned as pointer in C++ will become child of the object on which the method + was called. + + To activate this heuristic, use the :ref:`--enable-return-value-heuristic <return-heuristic>` + +Common pitfalls +=============== + +Not saving unowned objects references +------------------------------------- + + Sometimes when you pass an instance as argument to a method and the receiving + instance will need that object to live indifinitely, but will not take ownership + of the argument instance. In this case, you should hold a reference to the argument + instance. + + For example, let's say that you have a renderer class that will use a source class + in a setSource method but will not take ownership of it. The following code is wrong, + because when `render` is called the `Source` object created during the call to `setSource` + is already destroyed. + + .. code-block:: python + + renderer.setModel(Source()) + renderer.render() + + To solve this, you should hold a reference to the source object, like in + + .. code-block:: python + + source = Source() + renderer.setSource(source) + renderer.render() + + diff --git a/sources/shiboken2/doc/projectfile.rst b/sources/shiboken2/doc/projectfile.rst new file mode 100644 index 000000000..6c9808da4 --- /dev/null +++ b/sources/shiboken2/doc/projectfile.rst @@ -0,0 +1,65 @@ +.. _project-file: + +******************** +Binding Project File +******************** + +Instead of directing the Generator behaviour via command line, the binding developer +can write a text project file describing the same information, and avoid the hassle +of a long stream of command line arguments. + +.. _project-file-structure: + +The project file structure +========================== + +Here follows a comprehensive example of a generator project file. + + .. code-block:: ini + + [generator-project] + generator-set = path/to/generator/CHOICE_GENERATOR + header-file = DIR/global.h" /> + typesystem-file = DIR/typesystem_for_your_binding.xml + output-directory location="OUTPUTDIR" /> + include-path = path/to/library/being/wrapped/headers/1 + include-path = path/to/library/being/wrapped/headers/2 + typesystem-path = path/to/directory/containing/type/system/files/1 + typesystem-path = path/to/directory/containing/type/system/files/2 + enable-parent-ctor-heuristic + + +Project file tags +================= + +The generator project file tags are in direct relation to the +:ref:`command line arguments <command-line>`. All of the current command line +options provided by |project| were already seen on the :ref:`project-file-structure`, +for new command line options provided by additional generator modules (e.g.: qtdoc, +Shiboken) could also be used in the generator project file following simple conversion rules. + +For tags without options, just write as an empty tag without any attributes. Example: + + .. code-block:: bash + + --BOOLEAN-ARGUMENT + +becomes + + .. code-block:: ini + + BOOLEAN-ARGUMENT + +and + + .. code-block:: bash + + --VALUE-ARGUMENT=VALUE + +becomes + + .. code-block:: ini + + VALUE-ARGUMENT = VALUE + + diff --git a/sources/shiboken2/doc/sequenceprotocol.rst b/sources/shiboken2/doc/sequenceprotocol.rst new file mode 100644 index 000000000..587c0f95b --- /dev/null +++ b/sources/shiboken2/doc/sequenceprotocol.rst @@ -0,0 +1,23 @@ +Sequence Protocol +----------------- + +Support for the sequence protocol is achieved adding functions with special names, this is done using the add-function tag. + +The special function names are: + + ============= =============================================== ==================== =================== + Function name Parameters Return type CPython equivalent + ============= =============================================== ==================== =================== + __len__ PyObject* self Py_ssize_t PySequence_Size + __getitem__ PyObject* self, Py_ssize_t _i PyObject* PySequence_GetItem + __setitem__ PyObject* self, Py_ssize_t _i, PyObject* _value int PySequence_SetItem + __contains__ PyObject* self, PyObject* _value int PySequence_Contains + __concat__ PyObject* self, PyObject* _other PyObject* PySequence_Concat + ============= =============================================== ==================== =================== + +You just need to inform the function name to the add-function tag, without any parameter or return type information, when you do it, |project| will create a C function with parameters and return type definied by the table above. + +The function needs to follow the same semantics of the *CPython equivalent* function, the only way to do it is using the :doc:`inject-code <codeinjectionsemantics>` tag. + +A concrete exemple how to add sequence protocol support to a class can be found on shiboken tests, more precisely in the definition of the Str class in ``tests/samplebinding/typesystem_sample.xml``. + diff --git a/sources/shiboken2/doc/shiboken2.1 b/sources/shiboken2/doc/shiboken2.1 new file mode 100644 index 000000000..e017bd9a9 --- /dev/null +++ b/sources/shiboken2/doc/shiboken2.1 @@ -0,0 +1,73 @@ +.TH SHIBOKEN "1" "March 2010" "shiboken v0.2.0" "User Commands" +.SH NAME +shiboken \- CPython bindings generator for C++ libraries +.SH DESCRIPTION +.SS "Usage:" +.IP +shiboken [options] header\-file typesystem\-file +.SS "General options:" +.TP +\fB\-\-debug\-level\fR=\fI[sparse\fR|medium|full] +Set the debug level +.TP +\fB\-\-documentation\-only\fR +Do not generates any code, just the documentation +.TP +\fB\-\-generatorSet\fR +generatorSet to be used. e.g. qtdoc +.TP +\fB\-\-help\fR +Display this help and exit +.TP +\fB\-\-include\-paths=\fR<path>[:<path>:...] +Include paths used by the C++ parser +.TP +\fB\-\-license\-file\fR=\fI[licensefile]\fR +File used for copyright headers of generated files +.TP +\fB\-\-no\-suppress\-warnings\fR +Show all warnings +.TP +\fB\-\-output\-directory\fR=\fI[dir]\fR +The directory where the generated files will be written +.TP +\fB\-\-silent\fR +Avoid printing any message +.TP +\fB\-\-typesystem\-paths=\fR<path>[:<path>:...] +Paths used when searching for typesystems +.TP +\fB\-\-version\fR +Output version information and exit +.SS "Shiboken options:" +.TP +\fB\-\-disable\-verbose\-error\-messages\fR +Disable verbose error messages. Turn the python code hard to debug but safe few kB on the generated bindings. +.TP +\fB\-\-enable\-parent\-ctor\-heuristic\fR +Enable heuristics to detect parent relationship on constructors. +.TP +\fB\-\-enable\-pyside\-extensions\fR +Enable PySide extensions, such as support for signal/slots, use this if you are creating a binding for a Qt\-based library. +.TP +\fB\-\-enable\-return\-value\-heuristic\fR +Enable heuristics to detect parent relationship on return values (USE WITH CAUTION!) +.SS "Shiboken options:" +.TP +\fB\-\-disable\-verbose\-error\-messages\fR +Disable verbose error messages. Turn the python code hard to debug but safe few kB on the generated bindings. +.TP +\fB\-\-enable\-parent\-ctor\-heuristic\fR +Enable heuristics to detect parent relationship on constructors. +.TP +\fB\-\-enable\-pyside\-extensions\fR +Enable PySide extensions, such as support for signal/slots, use this if you are creating a binding for a Qt\-based library. +.TP +\fB\-\-enable\-return\-value\-heuristic\fR +Enable heuristics to detect parent relationship on return values (USE WITH CAUTION!) +.SH COPYRIGHT +Copyright \(co 2016 The Qt Company Ltd. +.SH AUTHOR +.PP +This manpage was written for Debian, starting with a help2man output, by +Didier Raboud <didier@raboud.com>, on the 26. March 2010. diff --git a/sources/shiboken2/doc/shibokenmodule.rst b/sources/shiboken2/doc/shibokenmodule.rst new file mode 100644 index 000000000..150998ccd --- /dev/null +++ b/sources/shiboken2/doc/shibokenmodule.rst @@ -0,0 +1,79 @@ +.. module:: shiboken + +.. |maya| unicode:: Maya U+2122 + +Shiboken module +*************** + +Functions +^^^^^^^^^ + +.. container:: function_list + + * def :meth:`isValid<shiboken.isValid>` (obj) + * def :meth:`wrapInstance<shiboken.wrapInstance>` (address, type) + * def :meth:`getCppPointer<shiboken.getCppPointer>` (obj) + * def :meth:`delete<shiboken.delete>` (obj) + * def :meth:`isOwnedByPython<shiboken.isOwnedByPython>` (obj) + * def :meth:`wasCreatedByPython<shiboken.wasCreatedByPython>` (obj) + * def :meth:`dump<shiboken.dump>` (obj) + +Detailed description +^^^^^^^^^^^^^^^^^^^^ + +This Python module can be used 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. + +Some function description refer to "Shiboken based objects", wich means +Python objects instances of any Python Type created using Shiboken. + + +.. function:: 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. + +.. function:: 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 doesn't point to a C++ object of given type + the behavior is undefined. + +.. function:: getCppPointer(obj) + + Returns a tuple of longs that contain the memory addresses of the + C++ instances wrapped by the given object. + +.. function:: delete(obj) + + Deletes the C++ object wrapped by the given Python object. + +.. function:: 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. + +.. function:: wasCreatedByPython(obj) + + Returns true if the given Python object was created by Python. + +.. function:: 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. diff --git a/sources/shiboken2/doc/typeconverters.rst b/sources/shiboken2/doc/typeconverters.rst new file mode 100644 index 000000000..3779b26d7 --- /dev/null +++ b/sources/shiboken2/doc/typeconverters.rst @@ -0,0 +1,288 @@ +**************************** +User Defined Type Conversion +**************************** + +In the process of creating Python bindings of a C++ library, most of the C++ classes will have wrappers representing them in Python land. But there may be other classes that are very simple and/or have a Python type as a direct counter part. (Example: a "Complex" class, that represents complex numbers, has a Python equivalent in the "complex" type.) Such classes, instead of getting a Python wrapper, normally have conversions rules, from Python to C++ and vice-versa. + + .. code-block:: c++ + + // C++ class + struct Complex { + Complex(double real, double imag); + double real() const; + double imag() const; + }; + + // Converting from C++ to Python using the CPython API: + PyObject* pyCpxObj = PyComplex_FromDoubles(complex.real(), complex.imag()); + + // Converting from Python to C++: + double real = PyComplex_RealAsDouble(pyCpxObj); + double imag = PyComplex_ImagAsDouble(pyCpxObj); + Complex cpx(real, imag); + + +For the user defined conversion code to be inserted in the proper places, the "<conversion-rule>" tag must be used. + + .. code-block:: xml + + <primitive-type name="Complex" target-lang-api-name="PyComplex"> + <include file-name="complex.h" location="global"/> + + <conversion-rule> + + <native-to-target> + return PyComplex_FromDoubles(%in.real(), %in.imag()); + </native-to-target> + + <target-to-native> + <!-- The 'check' attribute can be derived from the 'type' attribute, + it is defined here to test the CHECKTYPE type system variable. --> + <add-conversion type="PyComplex" check="%CHECKTYPE[Complex](%in)"> + double real = PyComplex_RealAsDouble(%in); + double imag = PyComplex_ImagAsDouble(%in); + %out = %OUTTYPE(real, imag); + </add-conversion> + </target-to-native> + + </conversion-rule> + + </primitive-type> + + +The details will be given later, but the gist of it are the tags +`<native-to-target> <http://www.pyside.org/docs/apiextractor/typesystem_conversionrule.html#native-to-target>`_, +which has only one conversion from C++ to Python, and +`<target-to-native> <http://www.pyside.org/docs/apiextractor/typesystem_conversionrule.html#target-to-native>`_, +that may define the conversion of multiple Python types to C++'s "Complex" type. + +.. image:: images/converter.png + :height: 240px + :align: center + +|project| expects the code for `<native-to-target> <http://www.pyside.org/docs/apiextractor/typesystem_conversionrule.html#native-to-target>`_, +to directly return the Python result of the conversion, and the added conversions inside the +`<target-to-native> <http://www.pyside.org/docs/apiextractor/typesystem_conversionrule.html#target-to-native>`_ +must attribute the Python to C++ conversion result to the :ref:`%out <out>` variable. + + +Expanding on the last example, if the binding developer want a Python 2-tuple of numbers to be accepted +by wrapped C++ functions with "Complex" arguments, an +`<add-conversion> <http://www.pyside.org/docs/apiextractor/typesystem_conversionrule.html#add-conversion>`_ +tag and a custom check must be added. Here's how to do it: + + .. code-block:: xml + + <!-- Code injection at module level. --> + <inject-code class="native" position="beginning"> + static bool Check2TupleOfNumbers(PyObject* pyIn) { + if (!PySequence_Check(pyIn) || !(PySequence_Size(pyIn) == 2)) + return false; + Shiboken::AutoDecRef pyReal(PySequence_GetItem(pyIn, 0)); + if (!SbkNumber_Check(pyReal)) + return false; + Shiboken::AutoDecRef pyImag(PySequence_GetItem(pyIn, 1)); + if (!SbkNumber_Check(pyImag)) + return false; + return true; + } + </inject-code> + + <primitive-type name="Complex" target-lang-api-name="PyComplex"> + <include file-name="complex.h" location="global"/> + + <conversion-rule> + + <native-to-target> + return PyComplex_FromDoubles(%in.real(), %in.imag()); + </native-to-target> + + <target-to-native> + + <add-conversion type="PyComplex"> + double real = PyComplex_RealAsDouble(%in); + double imag = PyComplex_ImagAsDouble(%in); + %out = %OUTTYPE(real, imag); + </add-conversion> + + <add-conversion type="PySequence" check="Check2TupleOfNumbers(%in)"> + Shiboken::AutoDecRef pyReal(PySequence_GetItem(%in, 0)); + Shiboken::AutoDecRef pyImag(PySequence_GetItem(%in, 1)); + double real = %CONVERTTOCPP[double](pyReal); + double imag = %CONVERTTOCPP[double](pyImag); + %out = %OUTTYPE(real, imag); + </add-conversion> + + </target-to-native> + + </conversion-rule> + + </primitive-type> + + + +.. _container_conversions: + +Container Conversions +===================== + +Converters for +`<container-type> <http://www.pyside.org/docs/apiextractor/typesystem_specifying_types.html#container-type>`_ +are pretty much the same as for other type, except that they make use of the type system variables +:ref:`%INTYPE_# <intype_n>` and :ref:`%OUTTYPE_# <outtype_n>`. |project| combines the conversion code for +containers with the conversion defined (or automatically generated) for the containees. + + + .. code-block:: xml + + <container-type name="std::map" type="map"> + <include file-name="map" location="global"/> + + <conversion-rule> + + <native-to-target> + PyObject* %out = PyDict_New(); + %INTYPE::const_iterator it = %in.begin(); + for (; it != %in.end(); ++it) { + %INTYPE_0 key = it->first; + %INTYPE_1 value = it->second; + PyDict_SetItem(%out, + %CONVERTTOPYTHON[%INTYPE_0](key), + %CONVERTTOPYTHON[%INTYPE_1](value)); + } + return %out; + </native-to-target> + + <target-to-native> + + <add-conversion type="PyDict"> + PyObject* key; + PyObject* value; + Py_ssize_t pos = 0; + while (PyDict_Next(%in, &pos, &key, &value)) { + %OUTTYPE_0 cppKey = %CONVERTTOCPP[%OUTTYPE_0](key); + %OUTTYPE_1 cppValue = %CONVERTTOCPP[%OUTTYPE_1](value); + %out.insert(%OUTTYPE::value_type(cppKey, cppValue)); + } + </add-conversion> + + </target-to-native> + </conversion-rule> + </container-type> + + +.. _variables_and_functions: + +Variables & Functions +===================== + + +.. _in: + +**%in** + + Variable replaced by the C++ input variable. + + +.. _out: + +**%out** + + Variable replaced by the C++ output variable. Needed to convey the + result of a Python to C++ conversion. + + +.. _intype: + +**%INTYPE** + + Used in Python to C++ conversions. It is replaced by the name of type for + which the conversion is being defined. Don't use the type's name directly. + + +.. _intype_n: + +**%INTYPE_#** + + Replaced by the name of the #th type used in a container. + + +.. _outtype: + +**%OUTTYPE** + + Used in Python to C++ conversions. It is replaced by the name of type for + which the conversion is being defined. Don't use the type's name directly. + + +.. _outtype_n: + +**%OUTTYPE_#** + + Replaced by the name of the #th type used in a container. + + +.. _checktype: + +**%CHECKTYPE[CPPTYPE]** + + Replaced by a |project| type checking function for a Python variable. + The C++ type is indicated by ``CPPTYPE``. + + +.. _oldconverters: + +Converting The Old Converters +============================= + +If you use |project| for your bindings, and has defined some type conversions +using the ``Shiboken::Converter`` template, then you must update your converters +to the new scheme. + +Previously your conversion rules were declared in one line, like this: + + + .. code-block:: xml + + <primitive-type name="Complex" target-lang-api-name="PyComplex"> + <include file-name="complex.h" location="global"/> + <conversion-rule file="complex_conversions.h"/> + </primitive-type> + + +And implemented in a separate C++ file, like this: + + + .. code-block:: c++ + + namespace Shiboken { + template<> struct Converter<Complex> + { + static inline bool checkType(PyObject* pyObj) { + return PyComplex_Check(pyObj); + } + static inline bool isConvertible(PyObject* pyObj) { + return PyComplex_Check(pyObj); + } + static inline PyObject* toPython(void* cppobj) { + return toPython(*reinterpret_cast<Complex*>(cppobj)); + } + static inline PyObject* toPython(const Complex& cpx) { + return PyComplex_FromDoubles(cpx.real(), cpx.imag()); + } + static inline Complex toCpp(PyObject* pyobj) { + double real = PyComplex_RealAsDouble(pyobj); + double imag = PyComplex_ImagAsDouble(pyobj); + return Complex(real, imag); + } + }; + } + + +In this case, the parts of the implementation that will be used in the new conversion-rule +are the ones in the two last method ``static inline PyObject* toPython(const Complex& cpx)`` +and ``static inline Complex toCpp(PyObject* pyobj)``. The ``isConvertible`` method is gone, +and the ``checkType`` is now an attribute of the +`<add-conversion> <http://www.pyside.org/docs/apiextractor/typesystem_conversionrule.html#add-conversion>`_ +tag. Refer back to the first example in this page and you will be able to correlate the above template +with the new scheme of conversion rule definition. diff --git a/sources/shiboken2/doc/typesystemvariables.rst b/sources/shiboken2/doc/typesystemvariables.rst new file mode 100644 index 000000000..205430550 --- /dev/null +++ b/sources/shiboken2/doc/typesystemvariables.rst @@ -0,0 +1,336 @@ +********************* +Type System Variables +********************* + +User written code can be placed in arbitrary places using the +:doc:`inject-code <codeinjectionsemantics>` tag. To ease the binding developer +work, the injected code can make use of special variables that will be replaced +by the correct values. This also shields the developer from some |project| +implementation specifics. + + +.. _variables: + +Variables +========= + + +.. _cpp_return_argument: + +**%0** + + Replaced by the C++ return variable of the Python method/function wrapper. + + +.. _arg_number: + +**%#** + + Replaced by the name of a C++ argument in the position indicated by ``#``. + The argument counting starts with ``%1``, since ``%0`` represents the return + variable name. If the number indicates a variable that was removed in the + type system description, but there is a default value for it, this value will + be used. Consider this example: + + .. code-block:: c++ + + void argRemoval(int a0, int a1 = 123); + + + .. code-block:: xml + + <modify-function signature="argRemoval(int, int)"> + <modify-argument index="2"> + <remove-argument/> + </modify-argument> + </modify-function> + + The ``%1`` will be replaced by the C++ argument name, and ``%2`` will get the + value ``123``. + + +.. _argument_names: + +**%ARGUMENT_NAMES** + + Replaced by a comma separated list with the names of all C++ arguments that + were not removed on the type system description for the method/function. When + the removed argument has a default value (original or provided in the type + system), this value will be inserted in the argument list. If you want to remove + the argument so completely that it doesn't appear in any form on the + ``%ARGUMENT_NAMES`` replacement, don't forget to remove also its default value + with the `<remove-default-expression/> + <http://www.pyside.org/docs/apiextractor/typesystem_arguments.html#remove-default-expression>`_ + type system tag. + + Take the following method and related type system description as an example: + + .. code-block:: c++ + + void argRemoval(int a0, Point a1 = Point(1, 2), bool a2 = true, Point a3 = Point(3, 4), int a4 = 56); + + + .. code-block:: xml + + <modify-function signature="argRemoval(int, Point, bool, Point, int)"> + <modify-argument index="2"> + <remove-argument/> + <replace-default-expression with="Point(6, 9)"/> + </modify-argument> + <modify-argument index="4"> + <remove-argument/> + </modify-argument> + </modify-function> + + As seen on the XML description, the function's ``a1`` and ``a3`` arguments + were removed. If any ``inject-code`` for this function uses ``%ARGUMENT_NAMES`` + the resulting list will be the equivalent of using individual argument type + system variables this way: + + .. code-block:: c++ + + %1, Point(6, 9), %3, Point(3, 4), %5 + + +.. _arg_type: + +**%ARG#_TYPE** + + Replaced by the type of a C++ argument in the position indicated by ``#``. + The argument counting starts with ``%1``, since ``%0`` represents the return + variable in other contexts, but ``%ARG0_TYPE`` will not translate to the + return type, as this is already done by the + :ref:`%RETURN_TYPE <return_type>` variable. + Example: + + .. code-block:: c++ + + void argRemoval(int a0, int a1 = 123); + + + .. code-block:: xml + + <modify-function signature="argRemoval(int, int)"> + <modify-argument index="2"> + <remove-argument/> + </modify-argument> + </modify-function> + + The ``%1`` will be replaced by the C++ argument name, and ``%2`` will get the + value ``123``. + + +.. _converttocpp: + +**%CONVERTTOCPP[CPPTYPE]** + + Replaced by a |project| conversion call that converts a Python variable + to a C++ variable of the type indicated by ``CPPTYPE``. + + +.. _converttopython: + +**%CONVERTTOPYTHON[CPPTYPE]** + + Replaced by a |project| conversion call that converts a C++ variable of the + type indicated by ``CPPTYPE`` to the proper Python object. + + +.. _isconvertible: + +**%ISCONVERTIBLE[CPPTYPE]** + + Replaced by a |project| "isConvertible" call that checks if a Python + variable is convertible (via an implicit conversion or cast operator call) + to a C++ variable of the type indicated by ``CPPTYPE``. + + +.. _checktype: + +**%CHECKTYPE[CPPTYPE]** + + Replaced by a |project| "checkType" call that verifies if a Python + if of the type indicated by ``CPPTYPE``. + + +.. _cppself: + +**%CPPSELF** + + Replaced by the wrapped C++ object instance that owns the method in which the + code with this variable was inserted. + +.. _cpptype: + +**%CPPTYPE** + + Replaced by the original name of the C++ class, without any namespace prefix, + that owns the method in which the code with this variable was inserted. It will + work on class level code injections also. Notice that ``CPPTYPE`` differs from + the :ref:`%TYPE <type>` variable, for this latter may be translated to the original + C++ class name or to the C++ wrapper class name. + + Namespaces will are treated as classes, so ``CPPTYPE`` will work for them and their + enclosed functions as well. + +.. _function_name: + +**%FUNCTION_NAME** + + Replaced by the name of a function or method. + + + +.. _py_return_argument: + +**%PYARG_0** + + Replaced by the name of the Python return variable of the Python method/function wrapper. + + +.. _pyarg: + +**%PYARG_#** + + Similar to ``%#``, but is replaced by the Python arguments (PyObjects) + received by the Python wrapper method. + + If used in the context of a native code injection, i.e. in a virtual method + override, ``%PYARG_#`` will be translated to one item of the Python tuple + holding the arguments that should be passed to the Python override for this + virtual method. + + The example + + .. code-block:: c++ + + long a = PyInt_AS_LONG(%PYARG_1); + + + is equivalent of + + .. code-block:: c++ + + long a = PyInt_AS_LONG(PyTuple_GET_ITEM(%PYTHON_ARGUMENTS, 0)); + + + The generator tries to be smart with attributions, but it will work for the + only simplest cases. + + This example + + .. code-block:: c++ + + Py_DECREF(%PYARG_1); + %PYARG_1 = PyInt_FromLong(10); + + + is equivalent of + + .. code-block:: c++ + + Py_DECREF(PyTuple_GET_ITEM(%PYTHON_ARGUMENTS, 0)); + PyTuple_SET_ITEM(%PYTHON_ARGUMENTS, 0, PyInt_FromLong(10)); + + +.. _pyself: + +**%PYSELF** + + Replaced by the Python wrapper variable (a PyObject) representing the instance + bounded to the Python wrapper method which receives the custom code. + + +.. _python_arguments: + +**%PYTHON_ARGUMENTS** + + Replaced by the pointer to the Python tuple with Python objects converted from + the C++ arguments received on the binding override of a virtual method. + This tuple is the same passed as arguments to the Python method overriding the + C++ parent's one. + + +.. _python_method_override: + +**%PYTHON_METHOD_OVERRIDE** + + This variable is used only on :ref:`native method code injections + <codeinjecting_method_native>`, i.e. on the binding overrides for C++ virtual + methods. It is replaced by a pointer to the Python method override. + + +.. _pythontypeobject: + +**%PYTHONTYPEOBJECT** + + Replaced by the Python type object for the context in which it is inserted: + method or class modification. + + +.. _beginallowthreads: + +**%BEGIN_ALLOW_THREADS** + + Replaced by a thread state saving procedure. + Must match with a :ref:`%END_ALLOW_THREADS <endallowthreads>` variable. + + +.. _endallowthreads: + +**%END_ALLOW_THREADS** + + Replaced by a thread state restoring procedure. + Must match with a :ref:`%BEGIN_ALLOW_THREADS <beginallowthreads>` variable. + + +.. _return_type: + +**%RETURN_TYPE** + + Replaced by the type returned by a function or method. + + +.. _type: + +**%TYPE** + + Replaced by the name of the class to which a function belongs. May be used + in code injected at method or class level. + + +.. _example: + +Example +======= + +Just to illustrate the usage of the variables described in the previous +sections, below is an excerpt from the type system description of a |project| +test. It changes a method that received ``argc/argv`` arguments into something +that expects a Python sequence instead. + + .. code-block:: xml + + <modify-function signature="overloadedMethod(int, char**)"> + <modify-argument index="1"> + <replace-type modified-type="PySequence" /> + </modify-argument> + <modify-argument index="2"> + <remove-argument /> + </modify-argument> + <inject-code class="target" position="beginning"> + int argc; + char** argv; + if (!PySequence_to_argc_argv(%PYARG_1, &argc, &argv)) { + PyErr_SetString(PyExc_TypeError, "error"); + return 0; + } + %RETURN_TYPE foo = %CPPSELF.%FUNCTION_NAME(argc, argv); + %0 = %CONVERTTOPYTHON[%RETURN_TYPE](foo); + + for (int i = 0; i < argc; ++i) + delete[] argv[i]; + delete[] argv; + </inject-code> + </modify-function> + diff --git a/sources/shiboken2/doc/wordsofadvice.rst b/sources/shiboken2/doc/wordsofadvice.rst new file mode 100644 index 000000000..b66799338 --- /dev/null +++ b/sources/shiboken2/doc/wordsofadvice.rst @@ -0,0 +1,109 @@ +.. _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. |
