diff options
Diffstat (limited to 'python/sip/doc')
| -rw-r--r-- | python/sip/doc/default.css | 229 | ||||
| -rw-r--r-- | python/sip/doc/sipref.html | 5281 | ||||
| -rw-r--r-- | python/sip/doc/sipref.txt | 5353 |
3 files changed, 10863 insertions, 0 deletions
diff --git a/python/sip/doc/default.css b/python/sip/doc/default.css new file mode 100644 index 00000000..5e077213 --- /dev/null +++ b/python/sip/doc/default.css @@ -0,0 +1,229 @@ +/* +:Author: David Goodger +:Contact: goodger@users.sourceforge.net +:date: $Date$ +:version: $Revision$ +:copyright: This stylesheet has been placed in the public domain. + +Default cascading style sheet for the HTML output of Docutils. +*/ + +.first { + margin-top: 0 } + +.last { + margin-bottom: 0 } + +a.toc-backref { + text-decoration: none ; + color: black } + +dt { + font-weight: bold } + +dd { + margin-bottom: 1.5em } + +div.abstract { + margin: 2em 5em } + +div.abstract p.topic-title { + font-weight: bold ; + text-align: center } + +div.attention, div.caution, div.danger, div.error, div.hint, +div.important, div.note, div.tip, div.warning, div.admonition { + margin: 2em ; + border: medium outset ; + padding: 1em } + +div.attention p.admonition-title, div.caution p.admonition-title, +div.danger p.admonition-title, div.error p.admonition-title, +div.warning p.admonition-title { + color: red ; + font-weight: bold ; + font-family: sans-serif } + +div.hint p.admonition-title, div.important p.admonition-title, +div.note p.admonition-title, div.tip p.admonition-title, +div.admonition p.admonition-title { + font-weight: bold ; + font-family: sans-serif } + +div.dedication { + margin: 2em 5em ; + text-align: center ; + font-style: italic } + +div.dedication p.topic-title { + font-weight: bold ; + font-style: normal } + +div.figure { + margin-left: 2em } + +div.footer, div.header { + font-size: smaller } + +div.sidebar { + margin-left: 1em ; + border: medium outset ; + padding: 0em 1em ; + background-color: #ffffee ; + width: 40% ; + float: right ; + clear: right } + +div.sidebar p.rubric { + font-family: sans-serif ; + font-size: medium } + +div.system-messages { + margin: 5em } + +div.system-messages h1 { + color: red } + +div.system-message { + border: medium outset ; + padding: 1em } + +div.system-message p.system-message-title { + color: red ; + font-weight: bold } + +div.topic { + margin: 2em } + +h1.title { + text-align: center } + +h2.subtitle { + text-align: center } + +hr { + width: 75% } + +ol.simple, ul.simple { + margin-bottom: 1em } + +ol.arabic { + list-style: decimal } + +ol.loweralpha { + list-style: lower-alpha } + +ol.upperalpha { + list-style: upper-alpha } + +ol.lowerroman { + list-style: lower-roman } + +ol.upperroman { + list-style: upper-roman } + +p.attribution { + text-align: right ; + margin-left: 50% } + +p.caption { + font-style: italic } + +p.credits { + font-style: italic ; + font-size: smaller } + +p.label { + white-space: nowrap } + +p.rubric { + font-weight: bold ; + font-size: larger ; + color: maroon ; + text-align: center } + +p.sidebar-title { + font-family: sans-serif ; + font-weight: bold ; + font-size: larger } + +p.sidebar-subtitle { + font-family: sans-serif ; + font-weight: bold } + +p.topic-title { + font-weight: bold } + +pre.address { + margin-bottom: 0 ; + margin-top: 0 ; + font-family: serif ; + font-size: 100% } + +pre.line-block { + font-family: serif ; + font-size: 100% } + +pre.literal-block, pre.doctest-block { + margin-left: 2em ; + margin-right: 2em ; + background-color: #eeeeee } + +span.classifier { + font-family: sans-serif ; + font-style: oblique } + +span.classifier-delimiter { + font-family: sans-serif ; + font-weight: bold } + +span.interpreted { + font-family: sans-serif } + +span.option { + white-space: nowrap } + +span.option-argument { + font-style: italic } + +span.pre { + white-space: pre } + +span.problematic { + color: red } + +table { + margin-top: 0.5em ; + margin-bottom: 0.5em } + +table.citation { + border-left: solid thin gray ; + padding-left: 0.5ex } + +table.docinfo { + margin: 2em 4em } + +table.footnote { + border-left: solid thin black ; + padding-left: 0.5ex } + +td, th { + padding-left: 0.5em ; + padding-right: 0.5em ; + vertical-align: top } + +th.docinfo-name, th.field-name { + font-weight: bold ; + text-align: left ; + white-space: nowrap } + +h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt { + font-size: 100% } + +/* +tt { + background-color: #eeeeee } +*/ + +ul.auto-toc { + list-style-type: none } diff --git a/python/sip/doc/sipref.html b/python/sip/doc/sipref.html new file mode 100644 index 00000000..850fe61f --- /dev/null +++ b/python/sip/doc/sipref.html @@ -0,0 +1,5281 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> +<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" /> +<title>SIP - A Tool for Generating Python Bindings for C and C++ Libraries</title> +<meta name="copyright" content="Copyright (c) 2007 Riverbank Computing Limited" /> +<style type="text/css"> + +/* +:Author: David Goodger +:Contact: goodger@users.sourceforge.net +:Date: $Date$ +:Revision: $Revision$ +:Copyright: This stylesheet has been placed in the public domain. + +Default cascading style sheet for the HTML output of Docutils. + +See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to +customize this style sheet. +*/ + +/* used to remove borders from tables and images */ +.borderless, table.borderless td, table.borderless th { + border: 0 } + +table.borderless td, table.borderless th { + /* Override padding for "table.docutils td" with "! important". + The right padding separates the table cells. */ + padding: 0 0.5em 0 0 ! important } + +.first { + /* Override more specific margin styles with "! important". */ + margin-top: 0 ! important } + +.last, .with-subtitle { + margin-bottom: 0 ! important } + +.hidden { + display: none } + +a.toc-backref { + text-decoration: none ; + color: black } + +blockquote.epigraph { + margin: 2em 5em ; } + +dl.docutils dd { + margin-bottom: 0.5em } + +/* Uncomment (and remove this text!) to get bold-faced definition list terms +dl.docutils dt { + font-weight: bold } +*/ + +div.abstract { + margin: 2em 5em } + +div.abstract p.topic-title { + font-weight: bold ; + text-align: center } + +div.admonition, div.attention, div.caution, div.danger, div.error, +div.hint, div.important, div.note, div.tip, div.warning { + margin: 2em ; + border: medium outset ; + padding: 1em } + +div.admonition p.admonition-title, div.hint p.admonition-title, +div.important p.admonition-title, div.note p.admonition-title, +div.tip p.admonition-title { + font-weight: bold ; + font-family: sans-serif } + +div.attention p.admonition-title, div.caution p.admonition-title, +div.danger p.admonition-title, div.error p.admonition-title, +div.warning p.admonition-title { + color: red ; + font-weight: bold ; + font-family: sans-serif } + +/* Uncomment (and remove this text!) to get reduced vertical space in + compound paragraphs. +div.compound .compound-first, div.compound .compound-middle { + margin-bottom: 0.5em } + +div.compound .compound-last, div.compound .compound-middle { + margin-top: 0.5em } +*/ + +div.dedication { + margin: 2em 5em ; + text-align: center ; + font-style: italic } + +div.dedication p.topic-title { + font-weight: bold ; + font-style: normal } + +div.figure { + margin-left: 2em ; + margin-right: 2em } + +div.footer, div.header { + clear: both; + font-size: smaller } + +div.line-block { + display: block ; + margin-top: 1em ; + margin-bottom: 1em } + +div.line-block div.line-block { + margin-top: 0 ; + margin-bottom: 0 ; + margin-left: 1.5em } + +div.sidebar { + margin-left: 1em ; + border: medium outset ; + padding: 1em ; + background-color: #ffffee ; + width: 40% ; + float: right ; + clear: right } + +div.sidebar p.rubric { + font-family: sans-serif ; + font-size: medium } + +div.system-messages { + margin: 5em } + +div.system-messages h1 { + color: red } + +div.system-message { + border: medium outset ; + padding: 1em } + +div.system-message p.system-message-title { + color: red ; + font-weight: bold } + +div.topic { + margin: 2em } + +h1.section-subtitle, h2.section-subtitle, h3.section-subtitle, +h4.section-subtitle, h5.section-subtitle, h6.section-subtitle { + margin-top: 0.4em } + +h1.title { + text-align: center } + +h2.subtitle { + text-align: center } + +hr.docutils { + width: 75% } + +img.align-left { + clear: left } + +img.align-right { + clear: right } + +ol.simple, ul.simple { + margin-bottom: 1em } + +ol.arabic { + list-style: decimal } + +ol.loweralpha { + list-style: lower-alpha } + +ol.upperalpha { + list-style: upper-alpha } + +ol.lowerroman { + list-style: lower-roman } + +ol.upperroman { + list-style: upper-roman } + +p.attribution { + text-align: right ; + margin-left: 50% } + +p.caption { + font-style: italic } + +p.credits { + font-style: italic ; + font-size: smaller } + +p.label { + white-space: nowrap } + +p.rubric { + font-weight: bold ; + font-size: larger ; + color: maroon ; + text-align: center } + +p.sidebar-title { + font-family: sans-serif ; + font-weight: bold ; + font-size: larger } + +p.sidebar-subtitle { + font-family: sans-serif ; + font-weight: bold } + +p.topic-title { + font-weight: bold } + +pre.address { + margin-bottom: 0 ; + margin-top: 0 ; + font-family: serif ; + font-size: 100% } + +pre.literal-block, pre.doctest-block { + margin-left: 2em ; + margin-right: 2em ; + background-color: #eeeeee } + +span.classifier { + font-family: sans-serif ; + font-style: oblique } + +span.classifier-delimiter { + font-family: sans-serif ; + font-weight: bold } + +span.interpreted { + font-family: sans-serif } + +span.option { + white-space: nowrap } + +span.pre { + white-space: pre } + +span.problematic { + color: red } + +span.section-subtitle { + /* font-size relative to parent (h1..h6 element) */ + font-size: 80% } + +table.citation { + border-left: solid 1px gray; + margin-left: 1px } + +table.docinfo { + margin: 2em 4em } + +table.docutils { + margin-top: 0.5em ; + margin-bottom: 0.5em } + +table.footnote { + border-left: solid 1px black; + margin-left: 1px } + +table.docutils td, table.docutils th, +table.docinfo td, table.docinfo th { + padding-left: 0.5em ; + padding-right: 0.5em ; + vertical-align: top } + +table.docutils th.field-name, table.docinfo th.docinfo-name { + font-weight: bold ; + text-align: left ; + white-space: nowrap ; + padding-left: 0 } + +h1 tt.docutils, h2 tt.docutils, h3 tt.docutils, +h4 tt.docutils, h5 tt.docutils, h6 tt.docutils { + font-size: 100% } + +tt.docutils { + background-color: #eeeeee } + +ul.auto-toc { + list-style-type: none } + +</style> +</head> +<body> +<div class="document" id="sip-a-tool-for-generating-python-bindings-for-c-and-c-libraries"> +<h1 class="title">SIP - A Tool for Generating Python Bindings for C and C++ Libraries</h1> +<h2 class="subtitle" id="reference-guide">Reference Guide</h2> +<table class="docinfo" frame="void" rules="none"> +<col class="docinfo-name" /> +<col class="docinfo-content" /> +<tbody valign="top"> +<tr><th class="docinfo-name">Contact:</th> +<td><a class="first last reference" href="mailto:info@riverbankcomputing.co.uk">info@riverbankcomputing.co.uk</a></td></tr> +<tr><th class="docinfo-name">Version:</th> +<td>4.6</td></tr> +<tr><th class="docinfo-name">Copyright:</th> +<td>Copyright (c) 2007 Riverbank Computing Limited</td></tr> +</tbody> +</table> +<div class="contents topic"> +<p class="topic-title first"><a id="contents" name="contents">Contents</a></p> +<ul class="auto-toc simple"> +<li><a class="reference" href="#introduction" id="id22" name="id22">1 Introduction</a><ul class="auto-toc"> +<li><a class="reference" href="#license" id="id23" name="id23">1.1 License</a></li> +<li><a class="reference" href="#features" id="id24" name="id24">1.2 Features</a></li> +<li><a class="reference" href="#sip-components" id="id25" name="id25">1.3 SIP Components</a></li> +<li><a class="reference" href="#qt-support" id="id26" name="id26">1.4 Qt Support</a></li> +</ul> +</li> +<li><a class="reference" href="#potential-incompatibilities-with-earlier-versions" id="id27" name="id27">2 Potential Incompatibilities with Earlier Versions</a><ul class="auto-toc"> +<li><a class="reference" href="#sip-v4-4" id="id28" name="id28">2.1 SIP v4.4</a></li> +</ul> +</li> +<li><a class="reference" href="#installing-sip" id="id29" name="id29">3 Installing SIP</a><ul class="auto-toc"> +<li><a class="reference" href="#downloading-sip" id="id30" name="id30">3.1 Downloading SIP</a></li> +<li><a class="reference" href="#configuring-sip" id="id31" name="id31">3.2 Configuring SIP</a><ul class="auto-toc"> +<li><a class="reference" href="#configuring-sip-using-mingw" id="id32" name="id32">3.2.1 Configuring SIP Using MinGW</a></li> +<li><a class="reference" href="#configuring-sip-using-the-borland-c-compiler" id="id33" name="id33">3.2.2 Configuring SIP Using the Borland C++ Compiler</a></li> +</ul> +</li> +<li><a class="reference" href="#building-sip" id="id34" name="id34">3.3 Building SIP</a></li> +</ul> +</li> +<li><a class="reference" href="#using-sip" id="id35" name="id35">4 Using SIP</a><ul class="auto-toc"> +<li><a class="reference" href="#a-simple-c-example" id="id36" name="id36">4.1 A Simple C++ Example</a></li> +<li><a class="reference" href="#id7" id="id37" name="id37">4.2 A Simple C Example</a></li> +<li><a class="reference" href="#a-more-complex-c-example" id="id38" name="id38">4.3 A More Complex C++ Example</a></li> +<li><a class="reference" href="#ownership-of-objects" id="id39" name="id39">4.4 Ownership of Objects</a></li> +<li><a class="reference" href="#support-for-wide-characters" id="id40" name="id40">4.5 Support for Wide Characters</a></li> +<li><a class="reference" href="#the-python-global-interpreter-lock" id="id41" name="id41">4.6 The Python Global Interpreter Lock</a></li> +</ul> +</li> +<li><a class="reference" href="#the-sip-command-line" id="id42" name="id42">5 The SIP Command Line</a></li> +<li><a class="reference" href="#sip-specification-files" id="id43" name="id43">6 SIP Specification Files</a><ul class="auto-toc"> +<li><a class="reference" href="#syntax-definition" id="id44" name="id44">6.1 Syntax Definition</a></li> +<li><a class="reference" href="#variable-numbers-of-arguments" id="id45" name="id45">6.2 Variable Numbers of Arguments</a></li> +<li><a class="reference" href="#additional-sip-types" id="id46" name="id46">6.3 Additional SIP Types</a><ul class="auto-toc"> +<li><a class="reference" href="#sip-anyslot" id="id47" name="id47">6.3.1 SIP_ANYSLOT</a></li> +<li><a class="reference" href="#sip-pycallable" id="id48" name="id48">6.3.2 SIP_PYCALLABLE</a></li> +<li><a class="reference" href="#sip-pydict" id="id49" name="id49">6.3.3 SIP_PYDICT</a></li> +<li><a class="reference" href="#sip-pylist" id="id50" name="id50">6.3.4 SIP_PYLIST</a></li> +<li><a class="reference" href="#sip-pyobject" id="id51" name="id51">6.3.5 SIP_PYOBJECT</a></li> +<li><a class="reference" href="#sip-pyslice" id="id52" name="id52">6.3.6 SIP_PYSLICE</a></li> +<li><a class="reference" href="#sip-pytuple" id="id53" name="id53">6.3.7 SIP_PYTUPLE</a></li> +<li><a class="reference" href="#sip-pytype" id="id54" name="id54">6.3.8 SIP_PYTYPE</a></li> +<li><a class="reference" href="#sip-qobject" id="id55" name="id55">6.3.9 SIP_QOBJECT</a></li> +<li><a class="reference" href="#sip-rxobj-con" id="id56" name="id56">6.3.10 SIP_RXOBJ_CON</a></li> +<li><a class="reference" href="#sip-rxobj-dis" id="id57" name="id57">6.3.11 SIP_RXOBJ_DIS</a></li> +<li><a class="reference" href="#sip-signal" id="id58" name="id58">6.3.12 SIP_SIGNAL</a></li> +<li><a class="reference" href="#sip-slot" id="id59" name="id59">6.3.13 SIP_SLOT</a></li> +<li><a class="reference" href="#sip-slot-con" id="id60" name="id60">6.3.14 SIP_SLOT_CON</a></li> +<li><a class="reference" href="#sip-slot-dis" id="id61" name="id61">6.3.15 SIP_SLOT_DIS</a></li> +</ul> +</li> +</ul> +</li> +<li><a class="reference" href="#sip-directives" id="id62" name="id62">7 SIP Directives</a><ul class="auto-toc"> +<li><a class="reference" href="#accesscode" id="id63" name="id63">7.1 %AccessCode</a></li> +<li><a class="reference" href="#bigetcharbuffercode" id="id64" name="id64">7.2 %BIGetCharBufferCode</a></li> +<li><a class="reference" href="#bigetreadbuffercode" id="id65" name="id65">7.3 %BIGetReadBufferCode</a></li> +<li><a class="reference" href="#bigetsegcountcode" id="id66" name="id66">7.4 %BIGetSegCountCode</a></li> +<li><a class="reference" href="#bigetwritebuffercode" id="id67" name="id67">7.5 %BIGetWriteBufferCode</a></li> +<li><a class="reference" href="#cmodule" id="id68" name="id68">7.6 %CModule</a></li> +<li><a class="reference" href="#convertfromtypecode" id="id69" name="id69">7.7 %ConvertFromTypeCode</a></li> +<li><a class="reference" href="#converttosubclasscode" id="id70" name="id70">7.8 %ConvertToSubClassCode</a></li> +<li><a class="reference" href="#converttotypecode" id="id71" name="id71">7.9 %ConvertToTypeCode</a></li> +<li><a class="reference" href="#copying" id="id72" name="id72">7.10 %Copying</a></li> +<li><a class="reference" href="#doc" id="id73" name="id73">7.11 %Doc</a></li> +<li><a class="reference" href="#end" id="id74" name="id74">7.12 %End</a></li> +<li><a class="reference" href="#exception" id="id75" name="id75">7.13 %Exception</a></li> +<li><a class="reference" href="#exporteddoc" id="id76" name="id76">7.14 %ExportedDoc</a></li> +<li><a class="reference" href="#exportedheadercode" id="id77" name="id77">7.15 %ExportedHeaderCode</a></li> +<li><a class="reference" href="#feature" id="id78" name="id78">7.16 %Feature</a></li> +<li><a class="reference" href="#gcclearcode" id="id79" name="id79">7.17 %GCClearCode</a></li> +<li><a class="reference" href="#gctraversecode" id="id80" name="id80">7.18 %GCTraverseCode</a></li> +<li><a class="reference" href="#getcode" id="id81" name="id81">7.19 %GetCode</a></li> +<li><a class="reference" href="#if" id="id82" name="id82">7.20 %If</a></li> +<li><a class="reference" href="#import" id="id83" name="id83">7.21 %Import</a></li> +<li><a class="reference" href="#include" id="id84" name="id84">7.22 %Include</a></li> +<li><a class="reference" href="#id14" id="id85" name="id85">7.23 %License</a></li> +<li><a class="reference" href="#mappedtype" id="id86" name="id86">7.24 %MappedType</a></li> +<li><a class="reference" href="#methodcode" id="id87" name="id87">7.25 %MethodCode</a></li> +<li><a class="reference" href="#module" id="id88" name="id88">7.26 %Module</a></li> +<li><a class="reference" href="#modulecode" id="id89" name="id89">7.27 %ModuleCode</a></li> +<li><a class="reference" href="#moduleheadercode" id="id90" name="id90">7.28 %ModuleHeaderCode</a></li> +<li><a class="reference" href="#optionalinclude" id="id91" name="id91">7.29 %OptionalInclude</a></li> +<li><a class="reference" href="#platforms" id="id92" name="id92">7.30 %Platforms</a></li> +<li><a class="reference" href="#postinitialisationcode" id="id93" name="id93">7.31 %PostInitialisationCode</a></li> +<li><a class="reference" href="#preinitialisationcode" id="id94" name="id94">7.32 %PreInitialisationCode</a></li> +<li><a class="reference" href="#raisecode" id="id95" name="id95">7.33 %RaiseCode</a></li> +<li><a class="reference" href="#setcode" id="id96" name="id96">7.34 %SetCode</a></li> +<li><a class="reference" href="#sipoptions" id="id97" name="id97">7.35 %SIPOptions</a></li> +<li><a class="reference" href="#timeline" id="id98" name="id98">7.36 %Timeline</a></li> +<li><a class="reference" href="#typecode" id="id99" name="id99">7.37 %TypeCode</a></li> +<li><a class="reference" href="#typeheadercode" id="id100" name="id100">7.38 %TypeHeaderCode</a></li> +<li><a class="reference" href="#unitcode" id="id101" name="id101">7.39 %UnitCode</a></li> +<li><a class="reference" href="#virtualcatchercode" id="id102" name="id102">7.40 %VirtualCatcherCode</a></li> +</ul> +</li> +<li><a class="reference" href="#sip-annotations" id="id103" name="id103">8 SIP Annotations</a><ul class="auto-toc"> +<li><a class="reference" href="#argument-annotations" id="id104" name="id104">8.1 Argument Annotations</a><ul class="auto-toc"> +<li><a class="reference" href="#allownone" id="id105" name="id105">8.1.1 AllowNone</a></li> +<li><a class="reference" href="#array" id="id106" name="id106">8.1.2 Array</a></li> +<li><a class="reference" href="#arraysize" id="id107" name="id107">8.1.3 ArraySize</a></li> +<li><a class="reference" href="#constrained" id="id108" name="id108">8.1.4 Constrained</a></li> +<li><a class="reference" href="#getwrapper" id="id109" name="id109">8.1.5 GetWrapper</a></li> +<li><a class="reference" href="#in" id="id110" name="id110">8.1.6 In</a></li> +<li><a class="reference" href="#out" id="id111" name="id111">8.1.7 Out</a></li> +<li><a class="reference" href="#transfer" id="id112" name="id112">8.1.8 Transfer</a></li> +<li><a class="reference" href="#transferback" id="id113" name="id113">8.1.9 TransferBack</a></li> +<li><a class="reference" href="#transferthis" id="id114" name="id114">8.1.10 TransferThis</a></li> +</ul> +</li> +<li><a class="reference" href="#class-annotations" id="id115" name="id115">8.2 Class Annotations</a><ul class="auto-toc"> +<li><a class="reference" href="#abstract" id="id116" name="id116">8.2.1 Abstract</a></li> +<li><a class="reference" href="#delaydtor" id="id117" name="id117">8.2.2 DelayDtor</a></li> +<li><a class="reference" href="#external" id="id118" name="id118">8.2.3 External</a></li> +<li><a class="reference" href="#nodefaultctors" id="id119" name="id119">8.2.4 NoDefaultCtors</a></li> +<li><a class="reference" href="#pyname" id="id120" name="id120">8.2.5 PyName</a></li> +</ul> +</li> +<li><a class="reference" href="#enum-annotations" id="id121" name="id121">8.3 Enum Annotations</a><ul class="auto-toc"> +<li><a class="reference" href="#id17" id="id122" name="id122">8.3.1 PyName</a></li> +</ul> +</li> +<li><a class="reference" href="#exception-annotations" id="id123" name="id123">8.4 Exception Annotations</a><ul class="auto-toc"> +<li><a class="reference" href="#id18" id="id124" name="id124">8.4.1 PyName</a></li> +</ul> +</li> +<li><a class="reference" href="#function-annotations" id="id125" name="id125">8.5 Function Annotations</a><ul class="auto-toc"> +<li><a class="reference" href="#autogen" id="id126" name="id126">8.5.1 AutoGen</a></li> +<li><a class="reference" href="#default" id="id127" name="id127">8.5.2 Default</a></li> +<li><a class="reference" href="#factory" id="id128" name="id128">8.5.3 Factory</a></li> +<li><a class="reference" href="#holdgil" id="id129" name="id129">8.5.4 HoldGIL</a></li> +<li><a class="reference" href="#newthread" id="id130" name="id130">8.5.5 NewThread</a></li> +<li><a class="reference" href="#noderived" id="id131" name="id131">8.5.6 NoDerived</a></li> +<li><a class="reference" href="#numeric" id="id132" name="id132">8.5.7 Numeric</a></li> +<li><a class="reference" href="#posthook" id="id133" name="id133">8.5.8 PostHook</a></li> +<li><a class="reference" href="#prehook" id="id134" name="id134">8.5.9 PreHook</a></li> +<li><a class="reference" href="#id19" id="id135" name="id135">8.5.10 PyName</a></li> +<li><a class="reference" href="#releasegil" id="id136" name="id136">8.5.11 ReleaseGIL</a></li> +<li><a class="reference" href="#id20" id="id137" name="id137">8.5.12 TransferBack</a></li> +</ul> +</li> +<li><a class="reference" href="#license-annotations" id="id138" name="id138">8.6 License Annotations</a><ul class="auto-toc"> +<li><a class="reference" href="#licensee" id="id139" name="id139">8.6.1 Licensee</a></li> +<li><a class="reference" href="#signature" id="id140" name="id140">8.6.2 Signature</a></li> +<li><a class="reference" href="#timestamp" id="id141" name="id141">8.6.3 Timestamp</a></li> +<li><a class="reference" href="#type" id="id142" name="id142">8.6.4 Type</a></li> +</ul> +</li> +<li><a class="reference" href="#variable-annotations" id="id143" name="id143">8.7 Variable Annotations</a><ul class="auto-toc"> +<li><a class="reference" href="#id21" id="id144" name="id144">8.7.1 PyName</a></li> +</ul> +</li> +</ul> +</li> +<li><a class="reference" href="#sip-api-for-handwritten-code" id="id145" name="id145">9 SIP API for Handwritten Code</a><ul class="auto-toc"> +<li><a class="reference" href="#sip-api-major-nr" id="id146" name="id146">9.1 SIP_API_MAJOR_NR</a></li> +<li><a class="reference" href="#sip-api-minor-nr" id="id147" name="id147">9.2 SIP_API_MINOR_NR</a></li> +<li><a class="reference" href="#sip-block-threads" id="id148" name="id148">9.3 SIP_BLOCK_THREADS</a></li> +<li><a class="reference" href="#sip-ssize-t" id="id149" name="id149">9.4 SIP_SSIZE_T</a></li> +<li><a class="reference" href="#sip-unblock-threads" id="id150" name="id150">9.5 SIP_UNBLOCK_THREADS</a></li> +<li><a class="reference" href="#sip-version" id="id151" name="id151">9.6 SIP_VERSION</a></li> +<li><a class="reference" href="#sip-version-str" id="id152" name="id152">9.7 SIP_VERSION_STR</a></li> +<li><a class="reference" href="#sipbadcatcherresult" id="id153" name="id153">9.8 sipBadCatcherResult()</a></li> +<li><a class="reference" href="#sipbadlengthforslice" id="id154" name="id154">9.9 sipBadLengthForSlice()</a></li> +<li><a class="reference" href="#sipbuildresult" id="id155" name="id155">9.10 sipBuildResult()</a></li> +<li><a class="reference" href="#sipcallmethod" id="id156" name="id156">9.11 sipCallMethod()</a></li> +<li><a class="reference" href="#sipcanconverttoinstance" id="id157" name="id157">9.12 sipCanConvertToInstance()</a></li> +<li><a class="reference" href="#sipcanconverttomappedtype" id="id158" name="id158">9.13 sipCanConvertToMappedType()</a></li> +<li><a class="reference" href="#sipclassname" id="id159" name="id159">9.14 sipClassName()</a></li> +<li><a class="reference" href="#sipconnectrx" id="id160" name="id160">9.15 sipConnectRx()</a></li> +<li><a class="reference" href="#sipconvertfrominstance" id="id161" name="id161">9.16 sipConvertFromInstance()</a></li> +<li><a class="reference" href="#sipconvertfrommappedtype" id="id162" name="id162">9.17 sipConvertFromMappedType()</a></li> +<li><a class="reference" href="#sipconvertfromnamedenum" id="id163" name="id163">9.18 sipConvertFromNamedEnum()</a></li> +<li><a class="reference" href="#sipconvertfromnewinstance" id="id164" name="id164">9.19 sipConvertFromNewInstance()</a></li> +<li><a class="reference" href="#sipconvertfromsequenceindex" id="id165" name="id165">9.20 sipConvertFromSequenceIndex()</a></li> +<li><a class="reference" href="#sipconvertfromsliceobject" id="id166" name="id166">9.21 sipConvertFromSliceObject()</a></li> +<li><a class="reference" href="#sipconverttocpp" id="id167" name="id167">9.22 sipConvertToCpp()</a></li> +<li><a class="reference" href="#sipconverttoinstance" id="id168" name="id168">9.23 sipConvertToInstance()</a></li> +<li><a class="reference" href="#sipconverttomappedtype" id="id169" name="id169">9.24 sipConvertToMappedType()</a></li> +<li><a class="reference" href="#sipdisconnectrx" id="id170" name="id170">9.25 sipDisconnectRx()</a></li> +<li><a class="reference" href="#sipemitsignal" id="id171" name="id171">9.26 sipEmitSignal()</a></li> +<li><a class="reference" href="#sipexportsymbol" id="id172" name="id172">9.27 sipExportSymbol()</a></li> +<li><a class="reference" href="#sipfindclass" id="id173" name="id173">9.28 sipFindClass()</a></li> +<li><a class="reference" href="#sipfindmappedtype" id="id174" name="id174">9.29 sipFindMappedType()</a></li> +<li><a class="reference" href="#sipfindnamedenum" id="id175" name="id175">9.30 sipFindNamedEnum()</a></li> +<li><a class="reference" href="#sipforceconverttoinstance" id="id176" name="id176">9.31 sipForceConvertToInstance()</a></li> +<li><a class="reference" href="#sipforceconverttomappedtype" id="id177" name="id177">9.32 sipForceConvertToMappedType()</a></li> +<li><a class="reference" href="#sipfree" id="id178" name="id178">9.33 sipFree()</a></li> +<li><a class="reference" href="#sipgetsender" id="id179" name="id179">9.34 sipGetSender()</a></li> +<li><a class="reference" href="#sipgetwrapper" id="id180" name="id180">9.35 sipGetWrapper()</a></li> +<li><a class="reference" href="#sipimportsymbol" id="id181" name="id181">9.36 sipImportSymbol()</a></li> +<li><a class="reference" href="#sipinttypeclassmap" id="id182" name="id182">9.37 sipIntTypeClassMap</a></li> +<li><a class="reference" href="#sipissubclassinstance" id="id183" name="id183">9.38 sipIsSubClassInstance()</a></li> +<li><a class="reference" href="#siplong-asunsignedlong" id="id184" name="id184">9.39 sipLong_AsUnsignedLong()</a></li> +<li><a class="reference" href="#sipmalloc" id="id185" name="id185">9.40 sipMalloc()</a></li> +<li><a class="reference" href="#sipmapinttoclass" id="id186" name="id186">9.41 sipMapIntToClass()</a></li> +<li><a class="reference" href="#sipmapstringtoclass" id="id187" name="id187">9.42 sipMapStringToClass()</a></li> +<li><a class="reference" href="#sipparseresult" id="id188" name="id188">9.43 sipParseResult()</a></li> +<li><a class="reference" href="#sipreleaseinstance" id="id189" name="id189">9.44 sipReleaseInstance()</a></li> +<li><a class="reference" href="#sipreleasemappedtype" id="id190" name="id190">9.45 sipReleaseMappedType()</a></li> +<li><a class="reference" href="#sipstringtypeclassmap" id="id191" name="id191">9.46 sipStringTypeClassMap</a></li> +<li><a class="reference" href="#siptransfer" id="id192" name="id192">9.47 sipTransfer()</a></li> +<li><a class="reference" href="#siptransferback" id="id193" name="id193">9.48 sipTransferBack()</a></li> +<li><a class="reference" href="#siptransferto" id="id194" name="id194">9.49 sipTransferTo()</a></li> +<li><a class="reference" href="#sipwrapper" id="id195" name="id195">9.50 sipWrapper</a></li> +<li><a class="reference" href="#sipwrapper-check" id="id196" name="id196">9.51 sipWrapper_Check()</a></li> +<li><a class="reference" href="#sipwrappertype" id="id197" name="id197">9.52 sipWrapperType</a></li> +<li><a class="reference" href="#generated-type-convertors" id="id198" name="id198">9.53 Generated Type Convertors</a></li> +<li><a class="reference" href="#generated-type-objects" id="id199" name="id199">9.54 Generated Type Objects</a></li> +<li><a class="reference" href="#generated-named-enum-type-objects" id="id200" name="id200">9.55 Generated Named Enum Type Objects</a></li> +<li><a class="reference" href="#generated-derived-classes" id="id201" name="id201">9.56 Generated Derived Classes</a></li> +<li><a class="reference" href="#generated-exception-objects" id="id202" name="id202">9.57 Generated Exception Objects</a></li> +</ul> +</li> +<li><a class="reference" href="#using-the-sip-module-in-applications" id="id203" name="id203">10 Using the SIP Module in Applications</a></li> +<li><a class="reference" href="#the-sip-build-system" id="id204" name="id204">11 The SIP Build System</a><ul class="auto-toc"> +<li><a class="reference" href="#sipconfig-functions" id="id205" name="id205">11.1 <tt class="docutils literal"><span class="pre">sipconfig</span></tt> Functions</a></li> +<li><a class="reference" href="#sipconfig-classes" id="id206" name="id206">11.2 <tt class="docutils literal"><span class="pre">sipconfig</span></tt> Classes</a></li> +</ul> +</li> +<li><a class="reference" href="#building-your-extension-with-distutils" id="id207" name="id207">12 Building Your Extension with distutils</a></li> +<li><a class="reference" href="#builtin-modules-and-custom-interpreters" id="id208" name="id208">13 Builtin Modules and Custom Interpreters</a></li> +</ul> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id22" id="introduction" name="introduction">1 Introduction</a></h1> +<p>This is the reference guide for SIP 4.6. SIP is a tool for +automatically generating <a class="reference" href="http://www.python.org">Python</a> bindings for C and +C++ libraries. SIP was originally developed in 1998 for +<a class="reference" href="http://www.riverbankcomputing.co.uk/pyqt/">PyQt</a> - the Python bindings for +the Qt GUI toolkit - but is suitable for generating bindings for any C or C++ +library.</p> +<p>This version of SIP generates bindings for Python v2.3 or later.</p> +<p>There are many other similar tools available. One of the original such tools +is <a class="reference" href="http://www.swig.org">SWIG</a> and, in fact, SIP is so called because it +started out as a small SWIG. Unlike SWIG, SIP is specifically designed for +bringing together Python and C/C++ and goes to great lengths to make the +integration as tight as possible.</p> +<p>The homepage for SIP is <a class="reference" href="http://www.riverbankcomputing.co.uk/sip/">http://www.riverbankcomputing.co.uk/sip/</a>. Here you +will always find the latest stable version, current development snapshots, and +the latest version of this documentation.</p> +<div class="section"> +<h2><a class="toc-backref" href="#id23" id="license" name="license">1.1 License</a></h2> +<p>SIP is licensed under the same terms as Python itself. SIP places no +restrictions on the license you may apply to the bindings you create.</p> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id24" id="features" name="features">1.2 Features</a></h2> +<p>SIP, and the bindings it produces, have the following features.</p> +<blockquote> +<ul class="simple"> +<li>bindings are fast to load and minimise memory consumption especially when +only a small sub-set of a large library is being used</li> +<li>automatic conversion between standard Python and C/C++ data types</li> +<li>overloading of functions and methods with different argument signatures</li> +<li>access to a C++ class's protected methods</li> +<li>the ability to define a Python class that is a sub-class of a C++ class, +including abstract C++ classes</li> +<li>Python sub-classes can implement the <tt class="docutils literal"><span class="pre">__dtor__(self)</span></tt> method which +will be called from the C++ class's virtual destructor</li> +<li>support for ordinary C++ functions, class methods, static class methods, +virtual class methods and abstract class methods</li> +<li>the ability to re-implement C++ virtual and abstract methods in Python</li> +<li>support for global and class variables</li> +<li>support for global and class operators</li> +<li>support for C++ namespaces</li> +<li>support for C++ templates</li> +<li>support for C++ exceptions and wrapping them as Python exceptions</li> +<li>the ability to define mappings between C++ classes and similar Python +data types that are automatically invoked</li> +<li>the ability to automatically exploit any available run time type +information to ensure that the class of a Python instance object matches +the class of the corresponding C++ instance</li> +<li>full support of the Python global interpreter lock, including the ability +to specify that a C++ function of method may block, therefore allowing +the lock to be released and other Python threads to run</li> +<li>support for the concept of ownership of a C++ instance (i.e. what part of +the code is responsible for calling the instance's destructor) and how +the ownership may change during the execution of an application</li> +<li>the ability to generate bindings for a C++ class library that itself is +built on another C++ class library which also has had bindings generated +so that the different bindings integrate and share code properly</li> +<li>a sophisticated versioning system that allows the full lifetime of a C++ +class library, including any platform specific or optional features, to +be described in a single set of specification files</li> +<li>the ability to include documentation in the specification files which can +be extracted and subsequently processed by external tools</li> +<li>the ability to include copyright notices and licensing information in the +specification files that is automatically included in all generated +source code</li> +<li>a build system, written in Python, that you can extend to configure, +compile and install your own bindings without worrying about platform +specific issues</li> +<li>support for building your extensions using distutils</li> +<li>SIP, and the bindings it produces, runs under UNIX, Linux, Windows and +MacOS/X</li> +</ul> +</blockquote> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id25" id="sip-components" name="sip-components">1.3 SIP Components</a></h2> +<p>SIP comprises a number of different components.</p> +<blockquote> +<ul class="simple"> +<li>The SIP code generator (<tt class="docutils literal"><span class="pre">sip</span></tt> or <tt class="docutils literal"><span class="pre">sip.exe</span></tt>). This processes <tt class="docutils literal"><span class="pre">.sip</span></tt> +specification files and generates C or C++ bindings. It is covered in +detail in <a class="reference" href="#using-sip">Using SIP</a>.</li> +<li>The SIP header file (<tt class="docutils literal"><span class="pre">sip.h</span></tt>). This contains definitions and data +structures needed by the generated C and C++ code.</li> +<li>The SIP module (<tt class="docutils literal"><span class="pre">sip.so</span></tt> or <tt class="docutils literal"><span class="pre">sip.pyd</span></tt>). This is a Python extension +module that is imported automatically by SIP generated bindings and +provides them with some common utility functions. See also <a class="reference" href="#using-the-sip-module-in-applications">Using the +SIP Module in Applications</a>.</li> +<li>The SIP build system (<tt class="docutils literal"><span class="pre">sipconfig.py</span></tt>). This is a pure Python module +that is created when SIP is configured and encapsulates all the necessary +information about your system including relevant directory names, +compiler and linker flags, and version numbers. It also includes several +Python classes and functions which help you write configuration scripts +for your own bindings. It is covered in detail in <a class="reference" href="#the-sip-build-system">The SIP Build +System</a>.</li> +<li>The SIP distutils extension (<tt class="docutils literal"><span class="pre">sipdistutils.py</span></tt>). This is a distutils +extension that can be used to build your extension modules using +distutils and is an alternative to writing configuration scripts with the +SIP build system. This can be as simple as adding your .sip files to the +list of files needed to build the extension module. It is covered in +detail in <a class="reference" href="#building-your-extension-with-distutils">Building Your Extension with distutils</a>.</li> +</ul> +</blockquote> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id26" id="qt-support" name="qt-support">1.4 Qt Support</a></h2> +<p>SIP has specific support for the creation of bindings based on Trolltech's Qt +toolkit.</p> +<p>The SIP code generator understands the signal/slot type safe callback mechanism +that Qt uses to connect objects together. This allows applications to define +new Python signals, and allows any Python callable object to be used as a slot.</p> +<p>SIP itself does not require Qt to be installed.</p> +</div> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id27" id="potential-incompatibilities-with-earlier-versions" name="potential-incompatibilities-with-earlier-versions">2 Potential Incompatibilities with Earlier Versions</a></h1> +<div class="section"> +<h2><a class="toc-backref" href="#id28" id="sip-v4-4" name="sip-v4-4">2.1 SIP v4.4</a></h2> +<blockquote> +<ul class="simple"> +<li>The <tt class="docutils literal"><span class="pre">SIP_BUILD</span></tt> C preprocessor symbol has been removed.</li> +<li><a class="reference" href="#sipconverttocpp">sipConvertToCpp()</a>, <a class="reference" href="#sipissubclassinstance">sipIsSubClassInstance()</a> and the old <a class="reference" href="#generated-type-convertors">Generated +Type Convertors</a> have been deprecated. The functions +<a class="reference" href="#sipcanconverttoinstance">sipCanConvertToInstance()</a>, <a class="reference" href="#sipconverttoinstance">sipConvertToInstance()</a>, +<a class="reference" href="#sipforceconverttoinstance">sipForceConvertToInstance()</a>, <a class="reference" href="#sipconvertfrominstance">sipConvertFromInstance()</a>, +<a class="reference" href="#sipconvertfromnewinstance">sipConvertFromNewInstance()</a>, <a class="reference" href="#sipcanconverttomappedtype">sipCanConvertToMappedType()</a>, +<a class="reference" href="#sipconverttomappedtype">sipConvertToMappedType()</a>, <a class="reference" href="#sipforceconverttomappedtype">sipForceConvertToMappedType()</a> and +<a class="reference" href="#sipconvertfrommappedtype">sipConvertFromMappedType()</a> should be used instead. Handwritten +<a class="reference" href="#convertfromtypecode">%ConvertFromTypeCode</a> and <a class="reference" href="#converttotypecode">%ConvertToTypeCode</a> now has the +responsibility for using these to implement the <tt class="docutils literal"><span class="pre">Transfer</span></tt> and +<tt class="docutils literal"><span class="pre">TransferBack</span></tt> annotations.</li> +</ul> +</blockquote> +</div> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id29" id="installing-sip" name="installing-sip">3 Installing SIP</a></h1> +<div class="section"> +<h2><a class="toc-backref" href="#id30" id="downloading-sip" name="downloading-sip">3.1 Downloading SIP</a></h2> +<p>You can get the latest release of the SIP source code from +<a class="reference" href="http://www.riverbankcomputing.co.uk/sip/download.php">http://www.riverbankcomputing.co.uk/sip/download.php</a>.</p> +<p>SIP is also included with all of the major Linux distributions. However, it +may be a version or two out of date.</p> +<p>You may also find more up to date pre-compiled binaries on +<a class="reference" href="http://sourceforge.net/project/showfiles.php?group_id=61057">SourceForge</a>.</p> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id31" id="configuring-sip" name="configuring-sip">3.2 Configuring SIP</a></h2> +<p>After unpacking the source package (either a <tt class="docutils literal"><span class="pre">.tar.gz</span></tt> or a <tt class="docutils literal"><span class="pre">.zip</span></tt> file +depending on your platform) you should then check for any <tt class="docutils literal"><span class="pre">README</span></tt> files +that relate to your platform.</p> +<p>Next you need to configure SIP by executing the <tt class="docutils literal"><span class="pre">configure.py</span></tt> script. For +example:</p> +<pre class="literal-block"> +python configure.py +</pre> +<p>This assumes that the Python interpreter is on your path. Something like the +following may be appropriate on Windows:</p> +<pre class="literal-block"> +c:\python25\python configure.py +</pre> +<p>If you have multiple versions of Python installed then make sure you use the +interpreter for which you wish SIP to generate bindings for.</p> +<p>The full set of command line options is:</p> +<table class="docutils option-list" frame="void" rules="none"> +<col class="option" /> +<col class="description" /> +<tbody valign="top"> +<tr><td class="option-group"> +<kbd><span class="option">-h</span></kbd></td> +<td>Display a help message.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">-a</span></kbd></td> +<td>Export all symbols in any SIP generated module and the SIP module +itself. This was the default behaviour of SIP prior to v4.2. +Normally only a module's inititialisation function is exported. This +option is deprecated as the <tt class="docutils literal"><span class="pre">ModuleMakefile</span></tt> class of <a class="reference" href="#the-sip-build-system">The SIP Build +System</a> allows this to be specified on a per module basis.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">-b <var>dir</var></span></kbd></td> +<td>The SIP code generator will be installed in the directory <tt class="docutils literal"><span class="pre">dir</span></tt>.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">-d <var>dir</var></span></kbd></td> +<td>The SIP module will be installed in the directory <tt class="docutils literal"><span class="pre">dir</span></tt>.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">-e <var>dir</var></span></kbd></td> +<td>The SIP header file will be installed in the directory <tt class="docutils literal"><span class="pre">dir</span></tt>.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">-k</span></kbd></td> +<td>The SIP module will be built as a static library. This is useful when +building the SIP module as a Python builtin (see +<a class="reference" href="#builtin-modules-and-custom-interpreters">Builtin Modules and Custom Interpreters</a>).</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">-n</span></kbd></td> +<td>The SIP code generator and module will be built as universal binaries +under MacOS/X.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">-p <var>plat</var></span></kbd></td> +<td>Explicitly specify the platform/compiler to be used by the build +system, otherwise a platform specific default will be used. The +<tt class="docutils literal"><span class="pre">-h</span></tt> option will display all the supported platform/compilers and +the default.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">-u</span></kbd></td> +<td>The SIP module will be built with debugging symbols.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">-v <var>dir</var></span></kbd></td> +<td>By default <tt class="docutils literal"><span class="pre">.sip</span></tt> files will be installed in the directory <tt class="docutils literal"><span class="pre">dir</span></tt>.</td></tr> +</tbody> +</table> +<p>The configure.py script takes many other options that allows the build system +to be finely tuned. These are of the form <tt class="docutils literal"><span class="pre">name=value</span></tt> or <tt class="docutils literal"><span class="pre">name+=value</span></tt>. +The <tt class="docutils literal"><span class="pre">-h</span></tt> option will display each supported <tt class="docutils literal"><span class="pre">name</span></tt>, although not all are +applicable to all platforms.</p> +<p>The <tt class="docutils literal"><span class="pre">name=value</span></tt> form means that <tt class="docutils literal"><span class="pre">value</span></tt> will replace the existing value of +<tt class="docutils literal"><span class="pre">name</span></tt>.</p> +<p>The <tt class="docutils literal"><span class="pre">name+=value</span></tt> form means that <tt class="docutils literal"><span class="pre">value</span></tt> will be appended to the existing +value of <tt class="docutils literal"><span class="pre">name</span></tt>.</p> +<p>For example, the following will disable support for C++ exceptions (and so +reduce the size of module binaries) when used with GCC:</p> +<pre class="literal-block"> +python configure.py CXXFLAGS+=-fno-exceptions +</pre> +<p>A pure Python module called <tt class="docutils literal"><span class="pre">sipconfig.py</span></tt> is generated by <tt class="docutils literal"><span class="pre">configure.py</span></tt>. +This defines each <tt class="docutils literal"><span class="pre">name</span></tt> and its corresponding <tt class="docutils literal"><span class="pre">value</span></tt>. Looking at it will +give you a good idea of how the build system uses the different options. It is +covered in detail in <a class="reference" href="#the-sip-build-system">The SIP Build System</a>.</p> +<div class="section"> +<h3><a class="toc-backref" href="#id32" id="configuring-sip-using-mingw" name="configuring-sip-using-mingw">3.2.1 Configuring SIP Using MinGW</a></h3> +<p>SIP, and the modules it generates, can be built with MinGW, the Windows port of +GCC. You must use the <tt class="docutils literal"><span class="pre">-p</span></tt> command line option to specify the correct +platform. For example:</p> +<pre class="literal-block"> +c:\python25\python configure.py -p win32-g++ +</pre> +</div> +<div class="section"> +<h3><a class="toc-backref" href="#id33" id="configuring-sip-using-the-borland-c-compiler" name="configuring-sip-using-the-borland-c-compiler">3.2.2 Configuring SIP Using the Borland C++ Compiler</a></h3> +<p>SIP, and the modules it generates, can be built with the free Borland C++ +compiler. You must use the <tt class="docutils literal"><span class="pre">-p</span></tt> command line option to specify the correct +platform. For example:</p> +<pre class="literal-block"> +c:\python25\python configure.py -p win32-borland +</pre> +<p>You must also make sure you have a Borland-compatible version of the Python +library. If you are using the standard Python distribution (built using the +Microsoft compiler) then you must convert the format of the Python library. +For example:</p> +<pre class="literal-block"> +coff2omf python25.lib python25_bcpp.lib +</pre> +</div> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id34" id="building-sip" name="building-sip">3.3 Building SIP</a></h2> +<p>The next step is to build SIP by running your platform's <tt class="docutils literal"><span class="pre">make</span></tt> command. For +example:</p> +<pre class="literal-block"> +make +</pre> +<p>The final step is to install SIP by running the following command:</p> +<pre class="literal-block"> +make install +</pre> +<p>(Depending on your system you may require root or administrator privileges.)</p> +<p>This will install the various SIP components.</p> +</div> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id35" id="using-sip" name="using-sip">4 Using SIP</a></h1> +<p>Bindings are generated by the SIP code generator from a number of specification +files, typically with a <tt class="docutils literal"><span class="pre">.sip</span></tt> extension. Specification files look very +similar to C and C++ header files, but often with additional information (in +the form of a <em>directive</em> or an <em>annotation</em>) and code so that the bindings +generated can be finely tuned.</p> +<div class="section"> +<h2><a class="toc-backref" href="#id36" id="a-simple-c-example" name="a-simple-c-example">4.1 A Simple C++ Example</a></h2> +<p>We start with a simple example. Let's say you have a (fictional) C++ library +that implements a single class called <tt class="docutils literal"><span class="pre">Word</span></tt>. The class has one constructor +that takes a <tt class="docutils literal"><span class="pre">\0</span></tt> terminated character string as its single argument. The +class has one method called <tt class="docutils literal"><span class="pre">reverse()</span></tt> which takes no arguments and returns +a <tt class="docutils literal"><span class="pre">\0</span></tt> terminated character string. The interface to the class is defined in +a header file called <tt class="docutils literal"><span class="pre">word.h</span></tt> which might look something like this:</p> +<pre class="literal-block"> +// Define the interface to the word library. + +class Word { + const char *the_word; + +public: + Word(const char *w); + + char *reverse() const; +}; +</pre> +<p>The corresponding SIP specification file would then look something like this:</p> +<pre class="literal-block"> +// Define the SIP wrapper to the word library. + +%Module word 0 + +class Word { + +%TypeHeaderCode +#include <word.h> +%End + +public: + Word(const char *w); + + char *reverse() const; +}; +</pre> +<p>Obviously a SIP specification file looks very much like a C++ (or C) header +file, but SIP does not include a full C++ parser. Let's look at the +differences between the two files.</p> +<blockquote> +<ul class="simple"> +<li>The <a class="reference" href="#module">%Module</a> directive has been added <a class="footnote-reference" href="#id4" id="id1" name="id1">[1]</a>. This is used to name the +Python module that is being created and to give it a <em>generation</em> number. +In this example these are <tt class="docutils literal"><span class="pre">word</span></tt> and <tt class="docutils literal"><span class="pre">0</span></tt> respectively. The +generation number is effectively the version number of the module.</li> +<li>The <a class="reference" href="#typeheadercode">%TypeHeaderCode</a> directive has been added. The text between this +and the following <a class="reference" href="#end">%End</a> directive is included literally in the code +that SIP generates. Normally it is used, as in this case, to +<tt class="docutils literal"><span class="pre">#include</span></tt> the corresponding C++ (or C) header file <a class="footnote-reference" href="#id5" id="id2" name="id2">[2]</a>.</li> +<li>The declaration of the private variable <tt class="docutils literal"><span class="pre">this_word</span></tt> has been removed. +SIP does not support access to either private or protected instance +variables.</li> +</ul> +</blockquote> +<p>If we want to we can now generate the C++ code in the current directory by +running the following command:</p> +<pre class="literal-block"> +sip -c . word.sip +</pre> +<p>However, that still leaves us with the task of compiling the generated code and +linking it against all the necessary libraries. It's much easier to use the +SIP build system to do the whole thing.</p> +<p>Using the SIP build system is simply a matter of writing a small Python script. +In this simple example we will assume that the <tt class="docutils literal"><span class="pre">word</span></tt> library we are wrapping +and it's header file are installed in standard system locations and will be +found by the compiler and linker without having to specify any additional +flags. In a more realistic example your Python script may take command line +options, or search a set of directories to deal with different configurations +and installations.</p> +<p>This is the simplest script (conventionally called <tt class="docutils literal"><span class="pre">configure.py</span></tt>):</p> +<pre class="literal-block"> +import os +import sipconfig + +# The name of the SIP build file generated by SIP and used by the build +# system. +build_file = "word.sbf" + +# Get the SIP configuration information. +config = sipconfig.Configuration() + +# Run SIP to generate the code. +os.system(" ".join([config.sip_bin, "-c", ".", "-b", build_file, "word.sip"])) + +# Create the Makefile. +makefile = sipconfig.SIPModuleMakefile(config, build_file) + +# Add the library we are wrapping. The name doesn't include any platform +# specific prefixes or extensions (e.g. the "lib" prefix on UNIX, or the +# ".dll" extension on Windows). +makefile.extra_libs = ["word"] + +# Generate the Makefile itself. +makefile.generate() +</pre> +<p>Hopefully this script is self-documenting. The key parts are the +<tt class="docutils literal"><span class="pre">Configuration</span></tt> and <tt class="docutils literal"><span class="pre">SIPModuleMakefile</span></tt> classes. The build system contains +other Makefile classes, for example to build programs or to call other +Makefiles in sub-directories.</p> +<p>After running the script (using the Python interpreter the extension module is +being created for) the generated C++ code and <tt class="docutils literal"><span class="pre">Makefile</span></tt> will be in the +current directory.</p> +<p>To compile and install the extension module, just run the following +commands <a class="footnote-reference" href="#id6" id="id3" name="id3">[3]</a>:</p> +<pre class="literal-block"> +make +make install +</pre> +<p>That's all there is to it.</p> +<p>See <a class="reference" href="#building-your-extension-with-distutils">Building Your Extension with distutils</a> for an example of how to build +this example using distutils.</p> +<table class="docutils footnote" frame="void" id="id4" rules="none"> +<colgroup><col class="label" /><col /></colgroup> +<tbody valign="top"> +<tr><td class="label"><a class="fn-backref" href="#id1" name="id4">[1]</a></td><td>All SIP directives start with a <tt class="docutils literal"><span class="pre">%</span></tt> as the first non-whitespace +character of a line.</td></tr> +</tbody> +</table> +<table class="docutils footnote" frame="void" id="id5" rules="none"> +<colgroup><col class="label" /><col /></colgroup> +<tbody valign="top"> +<tr><td class="label"><a class="fn-backref" href="#id2" name="id5">[2]</a></td><td>SIP includes many code directives like this. They differ in where the +supplied code is placed by SIP in the generated code.</td></tr> +</tbody> +</table> +<table class="docutils footnote" frame="void" id="id6" rules="none"> +<colgroup><col class="label" /><col /></colgroup> +<tbody valign="top"> +<tr><td class="label"><a class="fn-backref" href="#id3" name="id6">[3]</a></td><td>On Windows you might run <tt class="docutils literal"><span class="pre">nmake</span></tt> or <tt class="docutils literal"><span class="pre">mingw32-make</span></tt> instead.</td></tr> +</tbody> +</table> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id37" id="id7" name="id7">4.2 A Simple C Example</a></h2> +<p>Let's now look at a very similar example of wrapping a fictional C library:</p> +<pre class="literal-block"> +/* Define the interface to the word library. */ + +struct Word { + const char *the_word; +}; + +struct Word *create_word(const char *w); +char *reverse(struct Word *word); +</pre> +<p>The corresponding SIP specification file would then look something like this:</p> +<pre class="literal-block"> +/* Define the SIP wrapper to the word library. */ + +%CModule word 0 + +struct Word { + +%TypeHeaderCode +#include <word.h> +%End + + const char *the_word; +}; + +struct Word *create_word(const char *w) /Factory/; +char *reverse(struct Word *word); +</pre> +<p>Again, let's look at the differences between the two files.</p> +<blockquote> +<ul class="simple"> +<li>The <a class="reference" href="#cmodule">%CModule</a> directive has been added. This has the same syntax as +the <a class="reference" href="#module">%Module</a> directive used in the previous example but tells SIP that +the library being wrapped is implemented in C rather than C++.</li> +<li>The <a class="reference" href="#typeheadercode">%TypeHeaderCode</a> directive has been added.</li> +<li>The <a class="reference" href="#factory">Factory</a> annotation has been added to the <tt class="docutils literal"><span class="pre">create_word()</span></tt> function. +This tells SIP that a newly created structure is being returned and it is +owned by Python.</li> +</ul> +</blockquote> +<p>The <tt class="docutils literal"><span class="pre">configure.py</span></tt> build system script described in the previous example can +be used for this example without change.</p> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id38" id="a-more-complex-c-example" name="a-more-complex-c-example">4.3 A More Complex C++ Example</a></h2> +<p>In this last example we will wrap a fictional C++ library that contains a class +that is derived from a Qt class. This will demonstrate how SIP allows a class +hierarchy to be split across multiple Python extension modules, and will +introduce SIP's versioning system.</p> +<p>The library contains a single C++ class called <tt class="docutils literal"><span class="pre">Hello</span></tt> which is derived from +Qt's <tt class="docutils literal"><span class="pre">QLabel</span></tt> class. It behaves just like <tt class="docutils literal"><span class="pre">QLabel</span></tt> except that the text +in the label is hard coded to be <tt class="docutils literal"><span class="pre">Hello</span> <span class="pre">World</span></tt>. To make the example more +interesting we'll also say that the library only supports Qt v3.0 and later, +and also includes a function called <tt class="docutils literal"><span class="pre">setDefault()</span></tt> that is not implemented +in the Windows version of the library.</p> +<p>The <tt class="docutils literal"><span class="pre">hello.h</span></tt> header file looks something like this:</p> +<pre class="literal-block"> +// Define the interface to the hello library. + +#include <qlabel.h> +#include <qwidget.h> +#include <qstring.h> + +class Hello : public QLabel { + // This is needed by the Qt Meta-Object Compiler. + Q_OBJECT + +public: + Hello(QWidget *parent, const char *name = 0, WFlags f = 0); + +private: + // Prevent instances from being copied. + Hello(const Hello &); + Hello &operator=(const Hello &); +}; + +#if !defined(Q_OS_WIN) +void setDefault(const QString &def); +#endif +</pre> +<p>The corresponding SIP specification file would then look something like this:</p> +<pre class="literal-block"> +// Define the SIP wrapper to the hello library. + +%Module hello 0 + +%Import qt/qtmod.sip + +%If (Qt_3_0_0 -) + +class Hello : QLabel { + +%TypeHeaderCode +#include <hello.h> +%End + +public: + Hello(QWidget *parent /TransferThis/, const char *name = 0, WFlags f = 0); + +private: + Hello(const Hello &); +}; + +%If (!WS_WIN) +void setDefault(const QString &def); +%End + +%End +</pre> +<p>Again we look at the differences, but we'll skip those that we've looked at in +previous examples.</p> +<blockquote> +<ul class="simple"> +<li>The <a class="reference" href="#import">%Import</a> directive has been added to specify that we are extending +the class hierarchy defined in the file <tt class="docutils literal"><span class="pre">qt/qtmod.sip</span></tt>. This file is +part of PyQt. The build system will take care of finding the file's +exact location.</li> +<li>The <a class="reference" href="#if">%If</a> directive has been added to specify that +everything <a class="footnote-reference" href="#id11" id="id8" name="id8">[4]</a> up to the matching <a class="reference" href="#end">%End</a> directive only applies to Qt +v3.0 and later. <tt class="docutils literal"><span class="pre">Qt_3_0_0</span></tt> is a <em>tag</em> defined in <tt class="docutils literal"><span class="pre">qtmod.sip</span></tt> <a class="footnote-reference" href="#id12" id="id9" name="id9">[5]</a> +using the <a class="reference" href="#timeline">%Timeline</a> directive. <a class="reference" href="#timeline">%Timeline</a> is used to define a tag +for each version of a library's API you are wrapping allowing you to +maintain all the different versions in a single SIP specification. The +build system provides support to <tt class="docutils literal"><span class="pre">configure.py</span></tt> scripts for working out +the correct tags to use according to which version of the library is +actually installed.</li> +<li>The <tt class="docutils literal"><span class="pre">public</span></tt> keyword used in defining the super-classes has been +removed. This is not supported by SIP.</li> +<li>The <a class="reference" href="#transferthis">TransferThis</a> annotation has been added to the first argument +of the constructor. It specifies that if the argument is not 0 (i.e. the +<tt class="docutils literal"><span class="pre">Hello</span></tt> instance being constructed has a parent) then ownership of the +instance is transferred from Python to C++. It is needed because Qt +maintains objects (i.e. instances derived from the <tt class="docutils literal"><span class="pre">QObject</span></tt> class) in +a hierachy. When an object is destroyed all of its children are also +automatically destroyed. It is important, therefore, that the Python +garbage collector doesn't also try and destroy them. This is covered in +more detail in <a class="reference" href="#ownership-of-objects">Ownership of Objects</a>. SIP provides many other +annotations that can be applied to arguments, functions and classes. +Multiple annotations are separated by commas. Annotations may have +values.</li> +<li>The <tt class="docutils literal"><span class="pre">=</span></tt> operator has been removed. This operator is not supported by +SIP.</li> +<li>The <a class="reference" href="#if">%If</a> directive has been added to specify that everything up to the +matching <a class="reference" href="#end">%End</a> directive does not apply to Windows. <tt class="docutils literal"><span class="pre">WS_WIN</span></tt> is +another tag defined by PyQt, this time using the <a class="reference" href="#platforms">%Platforms</a> directive. +Tags defined by the <a class="reference" href="#platforms">%Platforms</a> directive are mutually exclusive, i.e. +only one may be valid at a time <a class="footnote-reference" href="#id13" id="id10" name="id10">[6]</a>.</li> +</ul> +</blockquote> +<p>One question you might have at this point is why bother to define the private +copy constructor when it can never be called from Python? The answer is to +prevent the automatic generation of a public copy constructor.</p> +<p>We now look at the <tt class="docutils literal"><span class="pre">configure.py</span></tt> script. This is a little different to the +script in the previous examples for two related reasons.</p> +<p>Firstly, PyQt includes a pure Python module called <tt class="docutils literal"><span class="pre">pyqtconfig</span></tt> that extends +the SIP build system for modules, like our example, that build on top of PyQt. +It deals with the details of which version of Qt is being used (i.e. it +determines what the correct tags are) and where it is installed. This is +called a module's configuration module.</p> +<p>Secondly, we generate a configuration module (called <tt class="docutils literal"><span class="pre">helloconfig</span></tt>) for our +own <tt class="docutils literal"><span class="pre">hello</span></tt> module. There is no need to do this, but if there is a chance +that somebody else might want to extend your C++ library then it would make +life easier for them.</p> +<p>Now we have two scripts. First the <tt class="docutils literal"><span class="pre">configure.py</span></tt> script:</p> +<pre class="literal-block"> +import os +import sipconfig +import pyqtconfig + +# The name of the SIP build file generated by SIP and used by the build +# system. +build_file = "hello.sbf" + +# Get the PyQt configuration information. +config = pyqtconfig.Configuration() + +# Get the extra SIP flags needed by the imported qt module. Note that +# this normally only includes those flags (-x and -t) that relate to SIP's +# versioning system. +qt_sip_flags = config.pyqt_qt_sip_flags + +# Run SIP to generate the code. Note that we tell SIP where to find the qt +# module's specification files using the -I flag. +os.system(" ".join([config.sip_bin, "-c", ".", "-b", build_file, "-I", config.pyqt_sip_dir, qt_sip_flags, "hello.sip"])) + +# We are going to install the SIP specification file for this module and +# its configuration module. +installs = [] + +installs.append(["hello.sip", os.path.join(config.default_sip_dir, "hello")]) + +installs.append(["helloconfig.py", config.default_mod_dir]) + +# Create the Makefile. The QtModuleMakefile class provided by the +# pyqtconfig module takes care of all the extra preprocessor, compiler and +# linker flags needed by the Qt library. +makefile = pyqtconfig.QtModuleMakefile( + configuration=config, + build_file=build_file, + installs=installs +) + +# Add the library we are wrapping. The name doesn't include any platform +# specific prefixes or extensions (e.g. the "lib" prefix on UNIX, or the +# ".dll" extension on Windows). +makefile.extra_libs = ["hello"] + +# Generate the Makefile itself. +makefile.generate() + +# Now we create the configuration module. This is done by merging a Python +# dictionary (whose values are normally determined dynamically) with a +# (static) template. +content = { + # Publish where the SIP specifications for this module will be + # installed. + "hello_sip_dir": config.default_sip_dir, + + # Publish the set of SIP flags needed by this module. As these are the + # same flags needed by the qt module we could leave it out, but this + # allows us to change the flags at a later date without breaking + # scripts that import the configuration module. + "hello_sip_flags": qt_sip_flags +} + +# This creates the helloconfig.py module from the helloconfig.py.in +# template and the dictionary. +sipconfig.create_config_module("helloconfig.py", "helloconfig.py.in", content) +</pre> +<p>Next we have the <tt class="docutils literal"><span class="pre">helloconfig.py.in</span></tt> template script:</p> +<pre class="literal-block"> +import pyqtconfig + +# These are installation specific values created when Hello was configured. +# The following line will be replaced when this template is used to create +# the final configuration module. +# @SIP_CONFIGURATION@ + +class Configuration(pyqtconfig.Configuration): + """The class that represents Hello configuration values. + """ + def __init__(self, sub_cfg=None): + """Initialise an instance of the class. + + sub_cfg is the list of sub-class configurations. It should be None + when called normally. + """ + # This is all standard code to be copied verbatim except for the + # name of the module containing the super-class. + if sub_cfg: + cfg = sub_cfg + else: + cfg = [] + + cfg.append(_pkg_config) + + pyqtconfig.Configuration.__init__(self, cfg) + +class HelloModuleMakefile(pyqtconfig.QtModuleMakefile): + """The Makefile class for modules that %Import hello. + """ + def finalise(self): + """Finalise the macros. + """ + # Make sure our C++ library is linked. + self.extra_libs.append("hello") + + # Let the super-class do what it needs to. + pyqtconfig.QtModuleMakefile.finalise(self) +</pre> +<p>Again, we hope that the scripts are self documenting.</p> +<table class="docutils footnote" frame="void" id="id11" rules="none"> +<colgroup><col class="label" /><col /></colgroup> +<tbody valign="top"> +<tr><td class="label"><a class="fn-backref" href="#id8" name="id11">[4]</a></td><td>Some parts of a SIP specification aren't subject to version control.</td></tr> +</tbody> +</table> +<table class="docutils footnote" frame="void" id="id12" rules="none"> +<colgroup><col class="label" /><col /></colgroup> +<tbody valign="top"> +<tr><td class="label"><a class="fn-backref" href="#id9" name="id12">[5]</a></td><td>Actually in <tt class="docutils literal"><span class="pre">versions.sip</span></tt>. PyQt uses the <a class="reference" href="#include">%Include</a> directive to +split the SIP specification for Qt across a large number of separate +<tt class="docutils literal"><span class="pre">.sip</span></tt> files.</td></tr> +</tbody> +</table> +<table class="docutils footnote" frame="void" id="id13" rules="none"> +<colgroup><col class="label" /><col /></colgroup> +<tbody valign="top"> +<tr><td class="label"><a class="fn-backref" href="#id10" name="id13">[6]</a></td><td>Tags can also be defined by the <a class="reference" href="#feature">%Feature</a> directive. These tags are +not mutually exclusive, i.e. any number may be valid at a time.</td></tr> +</tbody> +</table> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id39" id="ownership-of-objects" name="ownership-of-objects">4.4 Ownership of Objects</a></h2> +<p>When a C++ instance is wrapped a corresponding Python object is created. The +Python object behaves as you would expect in regard to garbage collection - it +is garbage collected when its reference count reaches zero. What then happens +to the corresponding C++ instance? The obvious answer might be that the +instance's destructor is called. However the library API may say that when the +instance is passed to a particular function, the library takes ownership of the +instance, i.e. responsibility for calling the instance's destructor is +transferred from the SIP generated module to the library.</p> +<p>Ownership of an instance may also be associated with another instance. The +implication being that the owned instance will automatically be destroyed if +the owning instance is destroyed. SIP keeps track of these relationships to +ensure that Python's cyclic garbage collector can detect and break any +reference cycles between the owning and owned instances. The association is +implemented as the owning instance taking a reference to the owned instance.</p> +<p>The <a class="reference" href="#transferthis">TransferThis</a>, <a class="reference" href="#transfer">Transfer</a> and TransferBack annotations are used to specify +where, and it what direction, transfers of ownership happen. It is very +important that these are specified correctly to avoid crashes (where both +Python and C++ call the destructor) and memory leaks (where neither Python and +C++ call the destructor).</p> +<p>This applies equally to C structures where the structure is returned to the +heap using the <tt class="docutils literal"><span class="pre">free()</span></tt> function.</p> +<p>See also <a class="reference" href="#siptransferto">sipTransferTo()</a> and <a class="reference" href="#siptransferback">sipTransferBack()</a>.</p> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id40" id="support-for-wide-characters" name="support-for-wide-characters">4.5 Support for Wide Characters</a></h2> +<p>SIP v4.6 introduced support for wide characters (i.e. the <tt class="docutils literal"><span class="pre">wchar_t</span></tt> type). +Python's C API includes support for converting between unicode objects and wide +character strings and arrays. When converting from a unicode object to wide +characters SIP creates the string or array on the heap (using memory allocated +using <a class="reference" href="#sipmalloc">sipMalloc()</a>). This then raises the problem of how this memory is +subsequently freed.</p> +<p>The following describes how SIP handles this memory in the different situations +where this is an issue.</p> +<blockquote> +<ul class="simple"> +<li>When a wide string or array is passed to a function or method then the +memory is freed (using <a class="reference" href="#sipfree">sipFree()</a>) after than function or method +returns.</li> +<li>When a wide string or array is returned from a virtual method then SIP +does not free the memory until the next time the method is called.</li> +<li>When an assignment is made to a wide string or array instance variable +then SIP does not first free the instance's current string or array.</li> +</ul> +</blockquote> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id41" id="the-python-global-interpreter-lock" name="the-python-global-interpreter-lock">4.6 The Python Global Interpreter Lock</a></h2> +<p>Python's Global Interpretor Lock (GIL) must be acquired before calls can be +made to the Python API. It should also be released when a potentially +blocking call to C/C++ library is made in order to allow other Python threads +to be executed. In addition, some C/C++ libraries may implement their own +locking strategies that conflict with the GIL causing application deadlocks. +SIP provides ways of specifying when the GIL is released and acquired to +ensure that locking problems can be avoided.</p> +<p>SIP always ensures that the GIL is acquired before making calls to the Python +API. By default SIP does not release the GIL when making calls to the C/C++ +library being wrapped. The <a class="reference" href="#releasegil">ReleaseGIL</a> annotation can be used to override +this behaviour when required.</p> +<p>If SIP is given the <tt class="docutils literal"><span class="pre">-g</span></tt> command line option then the default behaviour is +changed and SIP releases the GIL every time is makes calls to the C/C++ +library being wrapped. The <a class="reference" href="#holdgil">HoldGIL</a> annotation can be used to override this +behaviour when required.</p> +</div> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id42" id="the-sip-command-line" name="the-sip-command-line">5 The SIP Command Line</a></h1> +<p>The syntax of the SIP command line is:</p> +<pre class="literal-block"> +sip [options] [specification] +</pre> +<p><tt class="docutils literal"><span class="pre">specification</span></tt> is the name of the specification file for the module. If it +is omitted then <tt class="docutils literal"><span class="pre">stdin</span></tt> is used.</p> +<p>The full set of command line options is:</p> +<table class="docutils option-list" frame="void" rules="none"> +<col class="option" /> +<col class="description" /> +<tbody valign="top"> +<tr><td class="option-group"> +<kbd><span class="option">-h</span></kbd></td> +<td>Display a help message.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">-V</span></kbd></td> +<td>Display the SIP version number.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">-a <var>file</var></span></kbd></td> +<td>The name of the QScintilla API file to generate. This file contains a +description of the module API in a form that the QScintilla editor +component can use for auto-completion and call tips. (The file may +also be used by the SciTE editor but must be sorted first.) By default +the file is not generated.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">-b <var>file</var></span></kbd></td> +<td>The name of the build file to generate. This file contains the +information about the module needed by the SIP build system to generate +a platform and compiler specific Makefile for the module. By default +the file is not generated.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">-c <var>dir</var></span></kbd></td> +<td>The name of the directory (which must exist) into which all of the +generated C or C++ code is placed. By default no code is generated.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">-d <var>file</var></span></kbd></td> +<td>The name of the documentation file to generate. Documentation is +included in specification files using the <a class="reference" href="#doc">%Doc</a> and <a class="reference" href="#exporteddoc">%ExportedDoc</a> +directives. By default the file is not generated.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">-e</span></kbd></td> +<td>Support for C++ exceptions is enabled. This causes all calls to C++ +code to be enclosed in <tt class="docutils literal"><span class="pre">try</span></tt>/<tt class="docutils literal"><span class="pre">catch</span></tt> blocks and C++ exceptions to +be converted to Python exceptions. By default exception support is +disabled.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">-g</span></kbd></td> +<td>The Python GIL is released before making any calls to the C/C++ library +being wrapped and reacquired afterwards. See <a class="reference" href="#the-python-global-interpreter-lock">The Python Global +Interpreter Lock</a> and the <a class="reference" href="#releasegil">ReleaseGIL</a> and <a class="reference" href="#holdgil">HoldGIL</a> annotations.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">-I <var>dir</var></span></kbd></td> +<td>The directory is added to the list of directories searched when looking +for a specification file given in an <a class="reference" href="#include">%Include</a> or <a class="reference" href="#import">%Import</a> +directive. This option may be given any number of times.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">-j <var>number</var></span></kbd></td> +<td>The generated code is split into the given number of files. This make +it easier to use the parallel build facility of most modern +implementations of <tt class="docutils literal"><span class="pre">make</span></tt>. By default 1 file is generated for each C +structure or C++ class.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">-r</span></kbd></td> +<td>Debugging statements that trace the execution of the bindings are +automatically generated. By default the statements are not generated.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">-s <var>suffix</var></span></kbd></td> +<td>The suffix to use for generated C or C++ source files. By default +<tt class="docutils literal"><span class="pre">.c</span></tt> is used for C and <tt class="docutils literal"><span class="pre">.cpp</span></tt> for C++.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">-t <var>tag</var></span></kbd></td> +<td>The SIP version tag (declared using a <a class="reference" href="#timeline">%Timeline</a> directive) or the +SIP platform tag (declared using the <a class="reference" href="#platforms">%Platforms</a> directive) to +generate code for. This option may be given any number of times so +long as the tags do not conflict.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">-w</span></kbd></td> +<td>The display of warning messages is enabled. By default warning +messages are disabled.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">-x <var>feature</var></span></kbd></td> +<td>The feature (declared using the <a class="reference" href="#feature">%Feature</a> directive) is disabled.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">-z <var>file</var></span></kbd></td> +<td>The name of a file containing more command line options.</td></tr> +</tbody> +</table> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id43" id="sip-specification-files" name="sip-specification-files">6 SIP Specification Files</a></h1> +<p>A SIP specification consists of some C/C++ type and function declarations and +some directives. The declarations may contain annotations which provide SIP +with additional information that cannot be expressed in C/C++. SIP does not +include a full C/C++ parser.</p> +<p>It is important to understand that a SIP specification describes the Python +API, i.e. the API available to the Python programmer when they <tt class="docutils literal"><span class="pre">import</span></tt> the +generated module. It does not have to accurately represent the underlying +C/C++ library. There is nothing wrong with omitting functions that make +little sense in a Python context, or adding functions implemented with +handwritten code that have no C/C++ equivalent. It is even possible (and +sometimes necessary) to specify a different super-class hierarchy for a C++ +class. All that matters is that the generated code compiles properly.</p> +<p>In most cases the Python API matches the C/C++ API. In some cases handwritten +code (see <a class="reference" href="#methodcode">%MethodCode</a>) is used to map from one to the other without SIP +having to know the details itself. However, there are a few cases where SIP +generates a thin wrapper around a C++ method or constructor (see <a class="reference" href="#generated-derived-classes">Generated +Derived Classes</a>) and needs to know the exact C++ signature. To deal with +these cases SIP allows two signatures to be specified. For example:</p> +<pre class="literal-block"> +class Klass +{ +public: + // The Python signature is a tuple, but the underlying C++ signature + // is a 2 element array. + Klass(SIP_PYTUPLE) [(int *)]; +%MethodCode + int iarr[2]; + + if (PyArg_ParseTuple(a0, "ii", &iarr[0], &iarr[1])) + { + // Note that we use the SIP generated derived class + // constructor. + Py_BEGIN_ALLOW_THREADS + sipCpp = new sipKlass(iarr); + Py_END_ALLOW_THREADS + } +%End +}; +</pre> +<div class="section"> +<h2><a class="toc-backref" href="#id44" id="syntax-definition" name="syntax-definition">6.1 Syntax Definition</a></h2> +<p>The following is a semi-formal description of the syntax of a specification +file.</p> +<pre class="literal-block"> +<em>specification</em> ::= {<em>module-statement</em>} + +<em>module-statement</em> ::= [<em>module-directive</em> | <em>statement</em>] + +<em>module-directive</em> ::= [<a class="reference" href="#cmodule">%CModule</a> | <a class="reference" href="#copying">%Copying</a> | <a class="reference" href="#doc">%Doc</a> | + <a class="reference" href="#exporteddoc">%ExportedDoc</a> | <a class="reference" href="#exportedheadercode">%ExportedHeaderCode</a> | <a class="reference" href="#feature">%Feature</a> | + <a class="reference" href="#import">%Import</a> | <a class="reference" href="#include">%Include</a> | <a class="reference" href="#id14">%License</a> | <a class="reference" href="#mappedtype">%MappedType</a> | + <em>mapped-type-template</em> | <a class="reference" href="#module">%Module</a> | <a class="reference" href="#modulecode">%ModuleCode</a> | + <a class="reference" href="#moduleheadercode">%ModuleHeaderCode</a> | <a class="reference" href="#optionalinclude">%OptionalInclude</a> | <a class="reference" href="#platforms">%Platforms</a> | + <a class="reference" href="#preinitialisationcode">%PreInitialisationCode</a> | <a class="reference" href="#postinitialisationcode">%PostInitialisationCode</a> | + <em>sip-option-list</em> | <a class="reference" href="#timeline">%Timeline</a> | <a class="reference" href="#unitcode">%UnitCode</a>] + +<em>sip-option-list</em> :: <a class="reference" href="#sipoptions">%SIPOptions</a> <tt class="docutils literal"><span class="pre">(</span></tt> <em>option-list</em> <tt class="docutils literal"><span class="pre">)</span></tt> + +<em>option-list</em> ::= <em>option</em> [<tt class="docutils literal"><span class="pre">,</span></tt> <em>option-list</em>] + +<em>statement</em> :: [<em>class-statement</em> | <em>function</em> | <em>variable</em>] + +<em>class-statement</em> :: [<a class="reference" href="#if">%If</a> | <em>class</em> | <em>class-template</em> | <em>enum</em> | + <em>namespace</em> | <em>opaque-class</em> | <em>operator</em> | <em>struct</em> | <em>typedef</em> | + <em>exception</em>] + +<em>class</em> ::= <tt class="docutils literal"><span class="pre">class</span></tt> <em>name</em> [<tt class="docutils literal"><span class="pre">:</span></tt> <em>super-classes</em>] [<em>class-annotations</em>] + <tt class="docutils literal"><span class="pre">{</span></tt> {<em>class-line</em>} <tt class="docutils literal"><span class="pre">};</span></tt> + +<em>super-classes</em> ::= <em>name</em> [<tt class="docutils literal"><span class="pre">,</span></tt> <em>super-classes</em>] + +<em>class-line</em> ::= [<em>class-statement</em> | <a class="reference" href="#bigetreadbuffercode">%BIGetReadBufferCode</a> | + <a class="reference" href="#bigetwritebuffercode">%BIGetWriteBufferCode</a> | <a class="reference" href="#bigetsegcountcode">%BIGetSegCountCode</a> | + <a class="reference" href="#bigetcharbuffercode">%BIGetCharBufferCode</a> | <a class="reference" href="#converttosubclasscode">%ConvertToSubClassCode</a> | + <a class="reference" href="#converttotypecode">%ConvertToTypeCode</a> | <a class="reference" href="#gcclearcode">%GCClearCode</a> | <a class="reference" href="#gctraversecode">%GCTraverseCode</a> | + <a class="reference" href="#typecode">%TypeCode</a> | <a class="reference" href="#typeheadercode">%TypeHeaderCode</a> | <em>constructor</em> | <em>destructor</em> | + <em>method</em> | <em>static-method</em> | <em>virtual-method</em> | <em>special-method</em> | + <em>operator</em> | <em>virtual-operator</em> | <em>class-variable</em> | <tt class="docutils literal"><span class="pre">public:</span></tt> | + <tt class="docutils literal"><span class="pre">public</span> <span class="pre">slots:</span></tt> | <tt class="docutils literal"><span class="pre">protected:</span></tt> | <tt class="docutils literal"><span class="pre">protected</span> <span class="pre">slots:</span></tt> | + <tt class="docutils literal"><span class="pre">private:</span></tt> | <tt class="docutils literal"><span class="pre">private</span> <span class="pre">slots:</span></tt> | <tt class="docutils literal"><span class="pre">signals:</span></tt>] + +<em>constructor</em> ::= [<tt class="docutils literal"><span class="pre">explicit</span></tt>] <em>name</em> <tt class="docutils literal"><span class="pre">(</span></tt> [<em>argument-list</em>] <tt class="docutils literal"><span class="pre">)</span></tt> + [<em>exceptions</em>] [<em>function-annotations</em>] + [<em>c++-constructor-signature</em>] <tt class="docutils literal"><span class="pre">;</span></tt> [<a class="reference" href="#methodcode">%MethodCode</a>] + +<em>c++-constructor-signature</em> ::= <tt class="docutils literal"><span class="pre">[(</span></tt> [<em>argument-list</em>] <tt class="docutils literal"><span class="pre">)]</span></tt> + +<em>destructor</em> ::= [<tt class="docutils literal"><span class="pre">virtual</span></tt>] <tt class="docutils literal"><span class="pre">~</span></tt> <em>name</em> <tt class="docutils literal"><span class="pre">()</span></tt> [<em>exceptions</em>] [<tt class="docutils literal"><span class="pre">=</span> <span class="pre">0</span></tt>] + [<em>function-annotations</em>] <tt class="docutils literal"><span class="pre">;</span></tt> [<a class="reference" href="#methodcode">%MethodCode</a>] + [<a class="reference" href="#virtualcatchercode">%VirtualCatcherCode</a>] + +<em>method</em> ::= <em>type</em> <em>name</em> <tt class="docutils literal"><span class="pre">(</span></tt> [<em>argument-list</em>] <tt class="docutils literal"><span class="pre">)</span></tt> [<tt class="docutils literal"><span class="pre">const</span></tt>] + [<em>exceptions</em>] [<tt class="docutils literal"><span class="pre">=</span> <span class="pre">0</span></tt>] [<em>function-annotations</em>] [<em>c++-signature</em>] + <tt class="docutils literal"><span class="pre">;</span></tt> [<a class="reference" href="#methodcode">%MethodCode</a>] + +<em>c++-signature</em> ::= <tt class="docutils literal"><span class="pre">[</span></tt> <em>type</em> <tt class="docutils literal"><span class="pre">(</span></tt> [<em>argument-list</em>] <tt class="docutils literal"><span class="pre">)]</span></tt> + +<em>static-method</em> ::= <tt class="docutils literal"><span class="pre">static</span></tt> <em>function</em> + +<em>virtual-method</em> ::= <tt class="docutils literal"><span class="pre">virtual</span></tt> <em>type</em> <em>name</em> <tt class="docutils literal"><span class="pre">(</span></tt> [<em>argument-list</em>] <tt class="docutils literal"><span class="pre">)</span></tt> + [<tt class="docutils literal"><span class="pre">const</span></tt>] [<em>exceptions</em>] [<tt class="docutils literal"><span class="pre">=</span> <span class="pre">0</span></tt>] [<em>function-annotations</em>] + [<em>c++-signature</em>] <tt class="docutils literal"><span class="pre">;</span></tt> [<a class="reference" href="#methodcode">%MethodCode</a>] [<a class="reference" href="#virtualcatchercode">%VirtualCatcherCode</a>] + +<em>special-method</em> ::= <em>type</em> <em>special-method-name</em> + <tt class="docutils literal"><span class="pre">(</span></tt> [<em>argument-list</em>] <tt class="docutils literal"><span class="pre">)</span></tt> [<em>function-annotations</em>] <tt class="docutils literal"><span class="pre">;</span></tt> + [<a class="reference" href="#methodcode">%MethodCode</a>] + +<em>special-method-name</em> ::= [ <tt class="docutils literal"><span class="pre">__abs__</span></tt> | <tt class="docutils literal"><span class="pre">__add__</span></tt> | <tt class="docutils literal"><span class="pre">__and__</span></tt> | + <tt class="docutils literal"><span class="pre">__call__</span></tt> | <tt class="docutils literal"><span class="pre">__cmp__</span></tt> | <tt class="docutils literal"><span class="pre">__contains__</span></tt> | <tt class="docutils literal"><span class="pre">__delitem__</span></tt> | + <tt class="docutils literal"><span class="pre">__div__</span></tt> | <tt class="docutils literal"><span class="pre">__eq__</span></tt> | <tt class="docutils literal"><span class="pre">__float__</span></tt> | <tt class="docutils literal"><span class="pre">__ge__</span></tt> | + <tt class="docutils literal"><span class="pre">__getitem__</span></tt> | <tt class="docutils literal"><span class="pre">__gt__</span></tt> | <tt class="docutils literal"><span class="pre">__hash__</span></tt> | <tt class="docutils literal"><span class="pre">__iadd__</span></tt> | + <tt class="docutils literal"><span class="pre">__iand__</span></tt> | <tt class="docutils literal"><span class="pre">__idiv__</span></tt> | <tt class="docutils literal"><span class="pre">__ilshift__</span></tt> | <tt class="docutils literal"><span class="pre">__imod__</span></tt> | + <tt class="docutils literal"><span class="pre">__imul__</span></tt> | <tt class="docutils literal"><span class="pre">__int__</span></tt> | <tt class="docutils literal"><span class="pre">__invert__</span></tt> | <tt class="docutils literal"><span class="pre">__ior__</span></tt> | + <tt class="docutils literal"><span class="pre">__irshift__</span></tt> | <tt class="docutils literal"><span class="pre">__isub__</span></tt> | <tt class="docutils literal"><span class="pre">__ixor__</span></tt> | <tt class="docutils literal"><span class="pre">__le__</span></tt> | + <tt class="docutils literal"><span class="pre">__len__</span></tt> | <tt class="docutils literal"><span class="pre">__long__</span></tt> | <tt class="docutils literal"><span class="pre">__lshift__</span></tt> | <tt class="docutils literal"><span class="pre">__lt__</span></tt> | + <tt class="docutils literal"><span class="pre">__mod__</span></tt> | <tt class="docutils literal"><span class="pre">__mul__</span></tt> | <tt class="docutils literal"><span class="pre">__ne__</span></tt> | <tt class="docutils literal"><span class="pre">__neg__</span></tt> | + <tt class="docutils literal"><span class="pre">__nonzero__</span></tt> | <tt class="docutils literal"><span class="pre">__or__</span></tt> | <tt class="docutils literal"><span class="pre">__pos__</span></tt> | <tt class="docutils literal"><span class="pre">__repr__</span></tt> | + <tt class="docutils literal"><span class="pre">__rshift__</span></tt> | <tt class="docutils literal"><span class="pre">__setitem__</span></tt> | <tt class="docutils literal"><span class="pre">__str__</span></tt> | <tt class="docutils literal"><span class="pre">__sub__</span></tt> | + <tt class="docutils literal"><span class="pre">__xor__</span></tt>] + +<em>operator</em> ::= <em>operator-type</em> + <tt class="docutils literal"><span class="pre">(</span></tt> [<em>argument-list</em>] <tt class="docutils literal"><span class="pre">)</span></tt> [<tt class="docutils literal"><span class="pre">const</span></tt>] [<em>exceptions</em>] + [<em>function-annotations</em>] <tt class="docutils literal"><span class="pre">;</span></tt> [<a class="reference" href="#methodcode">%MethodCode</a>] + +<em>virtual-operator</em> ::= <tt class="docutils literal"><span class="pre">virtual</span></tt> <em>operator-type</em> + <tt class="docutils literal"><span class="pre">(</span></tt> [<em>argument-list</em>] <tt class="docutils literal"><span class="pre">)</span></tt> [<tt class="docutils literal"><span class="pre">const</span></tt>] [<em>exceptions</em>] [<tt class="docutils literal"><span class="pre">=</span> <span class="pre">0</span></tt>] + [<em>function-annotations</em>] <tt class="docutils literal"><span class="pre">;</span></tt> [<a class="reference" href="#methodcode">%MethodCode</a>] + [<a class="reference" href="#virtualcatchercode">%VirtualCatcherCode</a>] + +<em>operatator-type</em> ::= [ <em>operator-function</em> | <em>operator-cast</em> ] + +<em>operator-function</em> ::= <em>type</em> <tt class="docutils literal"><span class="pre">operator</span></tt> <em>operator-name</em> + +<em>operator-cast</em> ::= <tt class="docutils literal"><span class="pre">operator</span></tt> <em>type</em> + +<em>operator-name</em> ::= [<tt class="docutils literal"><span class="pre">+</span></tt> | <tt class="docutils literal"><span class="pre">-</span></tt> | <tt class="docutils literal"><span class="pre">*</span></tt> | <tt class="docutils literal"><span class="pre">/</span></tt> | <tt class="docutils literal"><span class="pre">%</span></tt> | <tt class="docutils literal"><span class="pre">&</span></tt> | + <tt class="docutils literal"><span class="pre">|</span></tt> | <tt class="docutils literal"><span class="pre">^</span></tt> | <tt class="docutils literal"><span class="pre"><<</span></tt> | <tt class="docutils literal"><span class="pre">>></span></tt> | <tt class="docutils literal"><span class="pre">+=</span></tt> | <tt class="docutils literal"><span class="pre">-=</span></tt> | <tt class="docutils literal"><span class="pre">*=</span></tt> | + <tt class="docutils literal"><span class="pre">/=</span></tt> | <tt class="docutils literal"><span class="pre">%=</span></tt> | <tt class="docutils literal"><span class="pre">&=</span></tt> | <tt class="docutils literal"><span class="pre">|=</span></tt> | <tt class="docutils literal"><span class="pre">^=</span></tt> | <tt class="docutils literal"><span class="pre"><<=</span></tt> | <tt class="docutils literal"><span class="pre">>>=</span></tt> | + <tt class="docutils literal"><span class="pre">~</span></tt> | <tt class="docutils literal"><span class="pre">()</span></tt> | <tt class="docutils literal"><span class="pre">[]</span></tt> | <tt class="docutils literal"><span class="pre"><</span></tt> | <tt class="docutils literal"><span class="pre"><=</span></tt> | <tt class="docutils literal"><span class="pre">==</span></tt> | <tt class="docutils literal"><span class="pre">!=</span></tt> | + <tt class="docutils literal"><span class="pre">></span></tt> | <tt class="docutils literal"><span class="pre">>>=</span></tt>] + +<em>class-variable</em> ::= [<tt class="docutils literal"><span class="pre">static</span></tt>] <em>variable</em> + +<em>class-template</em> :: = <tt class="docutils literal"><span class="pre">template</span></tt> <tt class="docutils literal"><span class="pre"><</span></tt> <em>type-list</em> <tt class="docutils literal"><span class="pre">></span></tt> <em>class</em> + +<em>mapped-type-template</em> :: = <tt class="docutils literal"><span class="pre">template</span></tt> <tt class="docutils literal"><span class="pre"><</span></tt> <em>type-list</em> <tt class="docutils literal"><span class="pre">></span></tt> + <a class="reference" href="#mappedtype">%MappedType</a> + +<em>enum</em> ::= <tt class="docutils literal"><span class="pre">enum</span></tt> [<em>name</em>] [<em>enum-annotations</em>] <tt class="docutils literal"><span class="pre">{</span></tt> {<em>enum-line</em>} <tt class="docutils literal"><span class="pre">};</span></tt> + +<em>enum-line</em> ::= [<a class="reference" href="#if">%If</a> | <em>name</em> [<em>enum-annotations</em>] <tt class="docutils literal"><span class="pre">,</span></tt> + +<em>function</em> ::= <em>type</em> <em>name</em> <tt class="docutils literal"><span class="pre">(</span></tt> [<em>argument-list</em>] <tt class="docutils literal"><span class="pre">)</span></tt> [<em>exceptions</em>] + [<em>function-annotations</em>] <tt class="docutils literal"><span class="pre">;</span></tt> [<a class="reference" href="#methodcode">%MethodCode</a>] + +<em>namespace</em> ::= <tt class="docutils literal"><span class="pre">namespace</span></tt> <em>name</em> <tt class="docutils literal"><span class="pre">{</span></tt> {<em>namespace-line</em>} <tt class="docutils literal"><span class="pre">};</span></tt> + +<em>namespace-line</em> ::= [<a class="reference" href="#typeheadercode">%TypeHeaderCode</a> | <em>statement</em>] + +<em>opaque-class</em> ::= <tt class="docutils literal"><span class="pre">class</span></tt> <em>scoped-name</em> <tt class="docutils literal"><span class="pre">;</span></tt> + +<em>struct</em> ::= <tt class="docutils literal"><span class="pre">struct</span></tt> <em>name</em> <tt class="docutils literal"><span class="pre">{</span></tt> {<em>class-line</em>} <tt class="docutils literal"><span class="pre">};</span></tt> + +<em>typedef</em> ::= <tt class="docutils literal"><span class="pre">typedef</span></tt> [<em>typed-name</em> | <em>function-pointer</em>] <tt class="docutils literal"><span class="pre">;</span></tt> + +<em>variable</em>::= <em>typed-name</em> [<em>variable-annotations</em>] <tt class="docutils literal"><span class="pre">;</span></tt> [<a class="reference" href="#accesscode">%AccessCode</a>] + [<a class="reference" href="#getcode">%GetCode</a>] [<a class="reference" href="#setcode">%SetCode</a>] + +<em>exception</em> ::= <a class="reference" href="#exception">%Exception</a> <em>exception-name</em> [<em>exception-base</em>] <tt class="docutils literal"><span class="pre">{</span></tt> + [<a class="reference" href="#typeheadercode">%TypeHeaderCode</a>] <a class="reference" href="#raisecode">%RaiseCode</a> <cite>};`</cite> + +<em>exception-name</em> ::= <em>scoped-name</em> + +<em>exception-base</em> ::= <tt class="docutils literal"><span class="pre">(</span></tt> [<em>exception-name</em> | <em>python-exception</em>] <tt class="docutils literal"><span class="pre">)</span></tt> + +<em>python-exception</em> ::= [<tt class="docutils literal"><span class="pre">SIP_Exception</span></tt> | <tt class="docutils literal"><span class="pre">SIP_StopIteration</span></tt> | + <tt class="docutils literal"><span class="pre">SIP_StandardError</span></tt> | <tt class="docutils literal"><span class="pre">SIP_ArithmeticError</span></tt> | + <tt class="docutils literal"><span class="pre">SIP_LookupError</span></tt> | <tt class="docutils literal"><span class="pre">SIP_AssertionError</span></tt> | + <tt class="docutils literal"><span class="pre">SIP_AttributeError</span></tt> | <tt class="docutils literal"><span class="pre">SIP_EOFError</span></tt> | + <tt class="docutils literal"><span class="pre">SIP_FloatingPointError</span></tt> | <tt class="docutils literal"><span class="pre">SIP_EnvironmentError</span></tt> | + <tt class="docutils literal"><span class="pre">SIP_IOError</span></tt> | <tt class="docutils literal"><span class="pre">SIP_OSError</span></tt> | <tt class="docutils literal"><span class="pre">SIP_ImportError</span></tt> | + <tt class="docutils literal"><span class="pre">SIP_IndexError</span></tt> | <tt class="docutils literal"><span class="pre">SIP_KeyError</span></tt> | <tt class="docutils literal"><span class="pre">SIP_KeyboardInterrupt</span></tt> | + <tt class="docutils literal"><span class="pre">SIP_MemoryError</span></tt> | <tt class="docutils literal"><span class="pre">SIP_NameError</span></tt> | <tt class="docutils literal"><span class="pre">SIP_OverflowError</span></tt> | + <tt class="docutils literal"><span class="pre">SIP_RuntimeError</span></tt> | <tt class="docutils literal"><span class="pre">SIP_NotImplementedError</span></tt> | + <tt class="docutils literal"><span class="pre">SIP_SyntaxError</span></tt> | <tt class="docutils literal"><span class="pre">SIP_IndentationError</span></tt> | <tt class="docutils literal"><span class="pre">SIP_TabError</span></tt> | + <tt class="docutils literal"><span class="pre">SIP_ReferenceError</span></tt> | <tt class="docutils literal"><span class="pre">SIP_SystemError</span></tt> | <tt class="docutils literal"><span class="pre">SIP_SystemExit</span></tt> | + <tt class="docutils literal"><span class="pre">SIP_TypeError</span></tt> | <tt class="docutils literal"><span class="pre">SIP_UnboundLocalError</span></tt> | + <tt class="docutils literal"><span class="pre">SIP_UnicodeError</span></tt> | <tt class="docutils literal"><span class="pre">SIP_UnicodeEncodeError</span></tt> | + <tt class="docutils literal"><span class="pre">SIP_UnicodeDecodeError</span></tt> | <tt class="docutils literal"><span class="pre">SIP_UnicodeTranslateError</span></tt> | + <tt class="docutils literal"><span class="pre">SIP_ValueError</span></tt> | <tt class="docutils literal"><span class="pre">SIP_ZeroDivisionError</span></tt> | + <tt class="docutils literal"><span class="pre">SIP_WindowsError</span></tt> | <tt class="docutils literal"><span class="pre">SIP_VMSError</span></tt>] + +<em>exceptions</em> ::= <tt class="docutils literal"><span class="pre">throw</span> <span class="pre">(</span></tt> [<em>exception-list</em>] <tt class="docutils literal"><span class="pre">)</span></tt> + +<em>exception-list</em> ::= <em>scoped-name</em> [<tt class="docutils literal"><span class="pre">,</span></tt> <em>exception-list</em>] + +<em>argument-list</em> ::= <em>argument</em> [<tt class="docutils literal"><span class="pre">,</span></tt> <em>argument-list</em>] [<tt class="docutils literal"><span class="pre">,</span></tt> <tt class="docutils literal"><span class="pre">...</span></tt>] + +<em>argument</em> ::= [<em>type</em> [<em>name</em>] [<em>argument-annotations</em>] + [<em>default-value</em>] | <a class="reference" href="#sip-anyslot">SIP_ANYSLOT</a> [<em>default-value</em>] | <a class="reference" href="#sip-qobject">SIP_QOBJECT</a> | + <a class="reference" href="#sip-rxobj-con">SIP_RXOBJ_CON</a> | <a class="reference" href="#sip-rxobj-dis">SIP_RXOBJ_DIS</a> | <a class="reference" href="#sip-signal">SIP_SIGNAL</a> [<em>default-value</em>] | + <a class="reference" href="#sip-slot">SIP_SLOT</a> [<em>default-value</em>] | <a class="reference" href="#sip-slot-con">SIP_SLOT_CON</a> | <a class="reference" href="#sip-slot-dis">SIP_SLOT_DIS</a>] + +<em>default-value</em> ::= <tt class="docutils literal"><span class="pre">=</span></tt> <em>expression</em> + +<em>expression</em> ::= [<em>value</em> | <em>value</em> <em>binary-operator</em> <em>expression</em>] + +<em>value</em> ::= [<em>unary-operator</em>] <em>simple-value</em> + +<em>simple-value</em> ::= [<em>scoped-name</em> | <em>function-call</em> | <em>real-value</em> | + <em>integer-value</em> | <em>boolean-value</em> | <em>string-value</em> | + <em>character-value</em>] + +<em>typed-name</em>::= <em>type</em> <em>name</em> + +<em>function-pointer</em>::= <em>type</em> <tt class="docutils literal"><span class="pre">(*</span></tt> <em>name</em> <tt class="docutils literal"><span class="pre">)(</span></tt> [<em>type-list</em>] <tt class="docutils literal"><span class="pre">)</span></tt> + +<em>type-list</em> ::= <em>type</em> [<tt class="docutils literal"><span class="pre">,</span></tt> <em>type-list</em>] + +<em>function-call</em> ::= <em>scoped-name</em> <tt class="docutils literal"><span class="pre">(</span></tt> [<em>value-list</em>] <tt class="docutils literal"><span class="pre">)</span></tt> + +<em>value-list</em> ::= <em>value</em> [<tt class="docutils literal"><span class="pre">,</span></tt> <em>value-list</em>] + +<em>real-value</em> ::= a floating point number + +<em>integer-value</em> ::= a number + +<em>boolean-value</em> ::= [<tt class="docutils literal"><span class="pre">true</span></tt> | <tt class="docutils literal"><span class="pre">false</span></tt>] + +<em>string-value</em> ::= <tt class="docutils literal"><span class="pre">"</span></tt> {<em>character</em>} <tt class="docutils literal"><span class="pre">"</span></tt> + +<em>character-value</em> ::= <tt class="docutils literal"><span class="pre">`</span></tt> <em>character</em> <tt class="docutils literal"><span class="pre">`</span></tt> + +<em>unary-operator</em> ::= [<tt class="docutils literal"><span class="pre">!</span></tt> | <tt class="docutils literal"><span class="pre">~</span></tt> | <tt class="docutils literal"><span class="pre">-</span></tt> | <tt class="docutils literal"><span class="pre">+</span></tt>] + +<em>binary-operator</em> ::= [<tt class="docutils literal"><span class="pre">-</span></tt> | <tt class="docutils literal"><span class="pre">+</span></tt> | <tt class="docutils literal"><span class="pre">*</span></tt> | <tt class="docutils literal"><span class="pre">/</span></tt> | <tt class="docutils literal"><span class="pre">&</span></tt> | <tt class="docutils literal"><span class="pre">|</span></tt>] + +<em>argument-annotations</em> ::= see <a class="reference" href="#argument-annotations">Argument Annotations</a> + +<em>class-annotations</em> ::= see <a class="reference" href="#class-annotations">Class Annotations</a> + +<em>enum-annotations</em> ::= see <a class="reference" href="#enum-annotations">Enum Annotations</a> + +<em>function-annotations</em> ::= see <a class="reference" href="#function-annotations">Function Annotations</a> + +<em>variable-annotations</em> ::= see <a class="reference" href="#variable-annotations">Variable Annotations</a> + +<em>type</em> ::= [<tt class="docutils literal"><span class="pre">const</span></tt>] <em>base-type</em> {<tt class="docutils literal"><span class="pre">*</span></tt>} [<tt class="docutils literal"><span class="pre">&</span></tt>] + +<em>type-list</em> ::= <em>type</em> [<tt class="docutils literal"><span class="pre">,</span></tt> <em>type-list</em>] + +<em>base-type</em> ::= [<em>scoped-name</em> | <em>template</em> | <tt class="docutils literal"><span class="pre">struct</span></tt> <em>scoped-name</em> | + <tt class="docutils literal"><span class="pre">short</span></tt> | <tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">short</span></tt> | <tt class="docutils literal"><span class="pre">int</span></tt> | <tt class="docutils literal"><span class="pre">unsigned</span></tt> | + <tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">int</span></tt> | <tt class="docutils literal"><span class="pre">long</span></tt> | <tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">long</span></tt> | <tt class="docutils literal"><span class="pre">float</span></tt> | + <tt class="docutils literal"><span class="pre">double</span></tt> | <tt class="docutils literal"><span class="pre">bool</span></tt> | <tt class="docutils literal"><span class="pre">char</span></tt> | <tt class="docutils literal"><span class="pre">signed</span> <span class="pre">char</span></tt> | + <tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">char</span></tt> | <tt class="docutils literal"><span class="pre">void</span></tt> | <tt class="docutils literal"><span class="pre">wchar_t</span></tt> | <a class="reference" href="#sip-pycallable">SIP_PYCALLABLE</a> | + <a class="reference" href="#sip-pydict">SIP_PYDICT</a> | <a class="reference" href="#sip-pylist">SIP_PYLIST</a> | <a class="reference" href="#sip-pyobject">SIP_PYOBJECT</a> | <a class="reference" href="#sip-pyslice">SIP_PYSLICE</a> | + <a class="reference" href="#sip-pytuple">SIP_PYTUPLE</a> | <a class="reference" href="#sip-pytype">SIP_PYTYPE</a>] + +<em>scoped-name</em> ::= <em>name</em> [<tt class="docutils literal"><span class="pre">::</span></tt> <em>scoped-name</em>] + +<em>template</em> ::= <em>scoped-name</em> <tt class="docutils literal"><span class="pre"><</span></tt> <em>type-list</em> <tt class="docutils literal"><span class="pre">></span></tt> + +<em>name</em> ::= _A-Za-z {_A-Za-z0-9} +</pre> +<p>Here is a short list of differences between C++ and the subset supported by +SIP that might trip you up.</p> +<blockquote> +<ul class="simple"> +<li>SIP does not support the use of <tt class="docutils literal"><span class="pre">[]</span></tt> in types. Use pointers instead.</li> +<li>A global <tt class="docutils literal"><span class="pre">operator</span></tt> can only be defined if its first argument is a +class or a named enum that has been wrapped in the same module.</li> +<li>Variables declared outside of a class are effectively read-only.</li> +<li>A class's list of super-classes doesn't not include any access specifier +(e.g. <tt class="docutils literal"><span class="pre">public</span></tt>).</li> +</ul> +</blockquote> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id45" id="variable-numbers-of-arguments" name="variable-numbers-of-arguments">6.2 Variable Numbers of Arguments</a></h2> +<p>SIP supports the use of <tt class="docutils literal"><span class="pre">...</span></tt> as the last part of a function signature. Any +remaining arguments are collected as a Python tuple.</p> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id46" id="additional-sip-types" name="additional-sip-types">6.3 Additional SIP Types</a></h2> +<p>SIP supports a number of additional data types that can be used in Python +signatures.</p> +<div class="section"> +<h3><a class="toc-backref" href="#id47" id="sip-anyslot" name="sip-anyslot">6.3.1 SIP_ANYSLOT</a></h3> +<p>This is both a <tt class="docutils literal"><span class="pre">const</span> <span class="pre">char</span> <span class="pre">*</span></tt> and a <tt class="docutils literal"><span class="pre">PyObject</span> <span class="pre">*</span></tt> that is used as the type +of the member instead of <tt class="docutils literal"><span class="pre">const</span> <span class="pre">char</span> <span class="pre">*</span></tt> in functions that implement the +connection or disconnection of an explicitly generated signal to a slot. +Handwritten code must be provided to interpret the conversion correctly.</p> +</div> +<div class="section"> +<h3><a class="toc-backref" href="#id48" id="sip-pycallable" name="sip-pycallable">6.3.2 SIP_PYCALLABLE</a></h3> +<p>This is a <tt class="docutils literal"><span class="pre">PyObject</span> <span class="pre">*</span></tt> that is a Python callable object.</p> +</div> +<div class="section"> +<h3><a class="toc-backref" href="#id49" id="sip-pydict" name="sip-pydict">6.3.3 SIP_PYDICT</a></h3> +<p>This is a <tt class="docutils literal"><span class="pre">PyObject</span> <span class="pre">*</span></tt> that is a Python dictionary object.</p> +</div> +<div class="section"> +<h3><a class="toc-backref" href="#id50" id="sip-pylist" name="sip-pylist">6.3.4 SIP_PYLIST</a></h3> +<p>This is a <tt class="docutils literal"><span class="pre">PyObject</span> <span class="pre">*</span></tt> that is a Python list object.</p> +</div> +<div class="section"> +<h3><a class="toc-backref" href="#id51" id="sip-pyobject" name="sip-pyobject">6.3.5 SIP_PYOBJECT</a></h3> +<p>This is a <tt class="docutils literal"><span class="pre">PyObject</span> <span class="pre">*</span></tt> of any Python type.</p> +</div> +<div class="section"> +<h3><a class="toc-backref" href="#id52" id="sip-pyslice" name="sip-pyslice">6.3.6 SIP_PYSLICE</a></h3> +<p>This is a <tt class="docutils literal"><span class="pre">PyObject</span> <span class="pre">*</span></tt> that is a Python slice object.</p> +</div> +<div class="section"> +<h3><a class="toc-backref" href="#id53" id="sip-pytuple" name="sip-pytuple">6.3.7 SIP_PYTUPLE</a></h3> +<p>This is a <tt class="docutils literal"><span class="pre">PyObject</span> <span class="pre">*</span></tt> that is a Python tuple object.</p> +</div> +<div class="section"> +<h3><a class="toc-backref" href="#id54" id="sip-pytype" name="sip-pytype">6.3.8 SIP_PYTYPE</a></h3> +<p>This is a <tt class="docutils literal"><span class="pre">PyObject</span> <span class="pre">*</span></tt> that is a Python type object.</p> +</div> +<div class="section"> +<h3><a class="toc-backref" href="#id55" id="sip-qobject" name="sip-qobject">6.3.9 SIP_QOBJECT</a></h3> +<p>This is a <tt class="docutils literal"><span class="pre">QObject</span> <span class="pre">*</span></tt> that is a C++ instance of a class derived from Qt's +<tt class="docutils literal"><span class="pre">QObject</span></tt> class.</p> +</div> +<div class="section"> +<h3><a class="toc-backref" href="#id56" id="sip-rxobj-con" name="sip-rxobj-con">6.3.10 SIP_RXOBJ_CON</a></h3> +<p>This is a <tt class="docutils literal"><span class="pre">QObject</span> <span class="pre">*</span></tt> that is a C++ instance of a class derived from Qt's +<tt class="docutils literal"><span class="pre">QObject</span></tt> class. It is used as the type of the receiver instead of <tt class="docutils literal"><span class="pre">const</span> +<span class="pre">QObject</span> <span class="pre">*</span></tt> in functions that implement a connection to a slot.</p> +</div> +<div class="section"> +<h3><a class="toc-backref" href="#id57" id="sip-rxobj-dis" name="sip-rxobj-dis">6.3.11 SIP_RXOBJ_DIS</a></h3> +<p>This is a <tt class="docutils literal"><span class="pre">QObject</span> <span class="pre">*</span></tt> that is a C++ instance of a class derived from Qt's +<tt class="docutils literal"><span class="pre">QObject</span></tt> class. It is used as the type of the receiver instead of <tt class="docutils literal"><span class="pre">const</span> +<span class="pre">QObject</span> <span class="pre">*</span></tt> in functions that implement a disconnection from a slot.</p> +</div> +<div class="section"> +<h3><a class="toc-backref" href="#id58" id="sip-signal" name="sip-signal">6.3.12 SIP_SIGNAL</a></h3> +<p>This is a <tt class="docutils literal"><span class="pre">const</span> <span class="pre">char</span> <span class="pre">*</span></tt> that is used as the type of the signal instead of +<tt class="docutils literal"><span class="pre">const</span> <span class="pre">char</span> <span class="pre">*</span></tt> in functions that implement the connection or disconnection +of an explicitly generated signal to a slot.</p> +</div> +<div class="section"> +<h3><a class="toc-backref" href="#id59" id="sip-slot" name="sip-slot">6.3.13 SIP_SLOT</a></h3> +<p>This is a <tt class="docutils literal"><span class="pre">const</span> <span class="pre">char</span> <span class="pre">*</span></tt> that is used as the type of the member instead of +<tt class="docutils literal"><span class="pre">const</span> <span class="pre">char</span> <span class="pre">*</span></tt> in functions that implement the connection or disconnection +of an explicitly generated signal to a slot.</p> +</div> +<div class="section"> +<h3><a class="toc-backref" href="#id60" id="sip-slot-con" name="sip-slot-con">6.3.14 SIP_SLOT_CON</a></h3> +<p>This is a <tt class="docutils literal"><span class="pre">const</span> <span class="pre">char</span> <span class="pre">*</span></tt> that is used as the type of the member instead of +<tt class="docutils literal"><span class="pre">const</span> <span class="pre">char</span> <span class="pre">*</span></tt> in functions that implement the connection of an internally +generated signal to a slot. The type includes a comma separated list of types +that is the C++ signature of of the signal.</p> +<p>To take an example, <tt class="docutils literal"><span class="pre">QAccel::connectItem()</span></tt> connects an internally generated +signal to a slot. The signal is emitted when the keyboard accelerator is +activated and it has a single integer argument that is the ID of the +accelerator. The C++ signature is:</p> +<pre class="literal-block"> +bool connectItem(int id, const QObject *receiver, const char *member); +</pre> +<p>The corresponding SIP specification is:</p> +<pre class="literal-block"> +bool connectItem(int, SIP_RXOBJ_CON, SIP_SLOT_CON(int)); +</pre> +</div> +<div class="section"> +<h3><a class="toc-backref" href="#id61" id="sip-slot-dis" name="sip-slot-dis">6.3.15 SIP_SLOT_DIS</a></h3> +<p>This is a <tt class="docutils literal"><span class="pre">const</span> <span class="pre">char</span> <span class="pre">*</span></tt> that is used as the type of the member instead of +<tt class="docutils literal"><span class="pre">const</span> <span class="pre">char</span> <span class="pre">*</span></tt> in functions that implement the disconnection of an +internally generated signal to a slot. The type includes a comma separated +list of types that is the C++ signature of of the signal.</p> +</div> +</div> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id62" id="sip-directives" name="sip-directives">7 SIP Directives</a></h1> +<p>In this section we describe each of the directives that can be used in +specification files. All directives begin with <tt class="docutils literal"><span class="pre">%</span></tt> as the first +non-whitespace character in a line.</p> +<p>Some directives have arguments or contain blocks of code or documentation. In +the following descriptions these are shown in <em>italics</em>. Optional arguments +are enclosed in [<em>brackets</em>].</p> +<p>Some directives are used to specify handwritten code. Handwritten code must +not define names that start with the prefix <tt class="docutils literal"><span class="pre">sip</span></tt>.</p> +<div class="section"> +<h2><a class="toc-backref" href="#id63" id="accesscode" name="accesscode">7.1 %AccessCode</a></h2> +<pre class="literal-block"> +%AccessCode + <em>code</em> +%End +</pre> +<p>This directive is used immediately after the declaration of an instance of a +wrapped class or structure, or a pointer to such an instance. You use it to +provide handwritten code that overrides the default behaviour.</p> +<p>For example:</p> +<pre class="literal-block"> +class Klass; + +Klass *klassInstance; +%AccessCode + // In this contrived example the C++ library we are wrapping defines + // klassInstance as Klass ** (which SIP doesn't support) so we + // explicitly dereference it. + if (klassInstance && *klassInstance) + return *klassInstance; + + // This will get converted to None. + return 0; +%End +</pre> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id64" id="bigetcharbuffercode" name="bigetcharbuffercode">7.2 %BIGetCharBufferCode</a></h2> +<pre class="literal-block"> +%BIGetCharBufferCode + <em>code</em> +%End +</pre> +<p>This directive (along with <a class="reference" href="#bigetreadbuffercode">%BIGetReadBufferCode</a>, <a class="reference" href="#bigetsegcountcode">%BIGetSegCountCode</a> and +<a class="reference" href="#bigetwritebuffercode">%BIGetWriteBufferCode</a>) is used to specify code that implements Python's +buffer interface. See the section <a class="reference" href="http://www.python.org/dev/doc/devel/api/buffer-structs.html">Buffer Object Structures</a> for the +details.</p> +<p>The following variables are made available to the handwritten code:</p> +<dl class="docutils"> +<dt><em>type</em> *sipCpp</dt> +<dd>This is a pointer to the structure or class instance. Its <em>type</em> is a +pointer to the structure or class.</dd> +<dt>void **sipPtrPtr</dt> +<dd>This is the pointer used to return the address of the character buffer.</dd> +<dt>SIP_SSIZE_T sipRes</dt> +<dd>The handwritten code should set this to the length of the character buffer +or -1 if there was an error.</dd> +<dt>SIP_SSIZE_T sipSegment</dt> +<dd>This is the number of the segment of the character buffer.</dd> +<dt>PyObject *sipSelf</dt> +<dd>This is the Python object that wraps the the structure or class instance, +i.e. <tt class="docutils literal"><span class="pre">self</span></tt>.</dd> +</dl> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id65" id="bigetreadbuffercode" name="bigetreadbuffercode">7.3 %BIGetReadBufferCode</a></h2> +<pre class="literal-block"> +%BIGetReadBufferCode + <em>code</em> +%End +</pre> +<p>This directive (along with <a class="reference" href="#bigetcharbuffercode">%BIGetCharBufferCode</a>, <a class="reference" href="#bigetsegcountcode">%BIGetSegCountCode</a> and +<a class="reference" href="#bigetwritebuffercode">%BIGetWriteBufferCode</a>) is used to specify code that implements Python's +buffer interface.</p> +<p>The following variables are made available to the handwritten code:</p> +<dl class="docutils"> +<dt><em>type</em> *sipCpp</dt> +<dd>This is a pointer to the structure or class instance. Its <em>type</em> is a +pointer to the structure or class.</dd> +<dt>void **sipPtrPtr</dt> +<dd>This is the pointer used to return the address of the read buffer.</dd> +<dt>SIP_SSIZE_T sipRes</dt> +<dd>The handwritten code should set this to the length of the read buffer or +-1 if there was an error.</dd> +<dt>SIP_SSIZE_T sipSegment</dt> +<dd>This is the number of the segment of the read buffer.</dd> +<dt>PyObject *sipSelf</dt> +<dd>This is the Python object that wraps the the structure or class instance, +i.e. <tt class="docutils literal"><span class="pre">self</span></tt>.</dd> +</dl> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id66" id="bigetsegcountcode" name="bigetsegcountcode">7.4 %BIGetSegCountCode</a></h2> +<pre class="literal-block"> +%BIGetSegCountCode + <em>code</em> +%End +</pre> +<p>This directive (along with <a class="reference" href="#bigetcharbuffercode">%BIGetCharBufferCode</a>, <a class="reference" href="#bigetreadbuffercode">%BIGetReadBufferCode</a> and +<a class="reference" href="#bigetwritebuffercode">%BIGetWriteBufferCode</a>) is used to specify code that implements Python's +buffer interface.</p> +<p>The following variables are made available to the handwritten code:</p> +<dl class="docutils"> +<dt><em>type</em> *sipCpp</dt> +<dd>This is a pointer to the structure or class instance. Its <em>type</em> is a +pointer to the structure or class.</dd> +<dt>SIP_SSIZE_T *sipLenPtr</dt> +<dd>This is the pointer used to return the total length in bytes of all +segments of the buffer.</dd> +<dt>SIP_SSIZE_T sipRes</dt> +<dd>The handwritten code should set this to the number of segments that make +up the buffer.</dd> +<dt>PyObject *sipSelf</dt> +<dd>This is the Python object that wraps the the structure or class instance, +i.e. <tt class="docutils literal"><span class="pre">self</span></tt>.</dd> +</dl> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id67" id="bigetwritebuffercode" name="bigetwritebuffercode">7.5 %BIGetWriteBufferCode</a></h2> +<pre class="literal-block"> +%BIGetWriteBufferCode + <em>code</em> +%End +</pre> +<p>This directive (along with <a class="reference" href="#bigetcharbuffercode">%BIGetCharBufferCode</a>, <a class="reference" href="#bigetreadbuffercode">%BIGetReadBufferCode</a> +and <a class="reference" href="#bigetsegcountcode">%BIGetSegCountCode</a> is used to specify code that implements Python's +buffer interface.</p> +<p>The following variables are made available to the handwritten code:</p> +<dl class="docutils"> +<dt><em>type</em> *sipCpp</dt> +<dd>This is a pointer to the structure or class instance. Its <em>type</em> is a +pointer to the structure or class.</dd> +<dt>void **sipPtrPtr</dt> +<dd>This is the pointer used to return the address of the write buffer.</dd> +<dt>SIP_SSIZE_T sipRes</dt> +<dd>The handwritten code should set this to the length of the write buffer or +-1 if there was an error.</dd> +<dt>SIP_SSIZE_T sipSegment</dt> +<dd>This is the number of the segment of the write buffer.</dd> +<dt>PyObject *sipSelf</dt> +<dd>This is the Python object that wraps the the structure or class instance, +i.e. <tt class="docutils literal"><span class="pre">self</span></tt>.</dd> +</dl> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id68" id="cmodule" name="cmodule">7.6 %CModule</a></h2> +<pre class="literal-block"> +%CModule <em>name</em> [<em>version</em>] +</pre> +<p>This directive is used to identify that the library being wrapped is a C +library and to define the name of the module and it's optional version number.</p> +<p>See the <a class="reference" href="#module">%Module</a> directive for an explanation of the version number.</p> +<p>For example:</p> +<pre class="literal-block"> +%CModule dbus 1 +</pre> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id69" id="convertfromtypecode" name="convertfromtypecode">7.7 %ConvertFromTypeCode</a></h2> +<pre class="literal-block"> +%ConvertFromTypeCode + <em>code</em> +%End +</pre> +<p>This directive is used as part of the <a class="reference" href="#mappedtype">%MappedType</a> directive to specify the +handwritten code that converts an instance of a mapped type to a Python +object.</p> +<p>The following variables are made available to the handwritten code:</p> +<dl class="docutils"> +<dt><em>type</em> *sipCpp</dt> +<dd>This is a pointer to the instance of the mapped type to be converted. It +will never be zero as the conversion from zero to <tt class="docutils literal"><span class="pre">Py_None</span></tt> is handled +before the handwritten code is called.</dd> +<dt>PyObject *sipTransferObj</dt> +<dd>This specifies any desired ownership changes to the returned object. If it +is <tt class="docutils literal"><span class="pre">NULL</span></tt> then the ownership should be left unchanged. If it is +<tt class="docutils literal"><span class="pre">Py_None</span></tt> then ownership should be transferred to Python. Otherwise +ownership should be transferred to C/C++ and the returned object associated +with <em>sipTransferObj</em>. The code can choose to interpret these changes in +any way. For example, if the code is converting a C++ container of wrapped +classes to a Python list it is likely that the ownership changes should be +made to each element of the list.</dd> +</dl> +<p>The handwritten code must explicitly return a <tt class="docutils literal"><span class="pre">PyObject</span> <span class="pre">*</span></tt>. If there was an +error then a Python exception must be raised and <tt class="docutils literal"><span class="pre">NULL</span></tt> returned.</p> +<p>The following example converts a <tt class="docutils literal"><span class="pre">QList<QWidget</span> <span class="pre">*></span></tt> instance to a Python +list of <tt class="docutils literal"><span class="pre">QWidget</span></tt> instances:</p> +<pre class="literal-block"> +%ConvertFromTypeCode + PyObject *l; + + // Create the Python list of the correct length. + if ((l = PyList_New(sipCpp -> size())) == NULL) + return NULL; + + // Go through each element in the C++ instance and convert it to a + // wrapped QWidget. + for (int i = 0; i < sipCpp -> size(); ++i) + { + QWidget *w = sipCpp -> at(i); + PyObject *wobj; + + // Get the Python wrapper for the QWidget instance, creating a new + // one if necessary, and handle any ownership transfer. + if ((wobj = sipConvertFromInstance(w, sipClass_QWidget, sipTransferObj)) == NULL) + { + // There was an error so garbage collect the Python list. + Py_DECREF(l); + return NULL; + } + + // Add the wrapper to the list. + PyList_SET_ITEM(l, i, wobj); + } + + // Return the Python list. + return l; +%End +</pre> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id70" id="converttosubclasscode" name="converttosubclasscode">7.8 %ConvertToSubClassCode</a></h2> +<pre class="literal-block"> +%ConvertToSubClassCode + <em>code</em> +%End +</pre> +<p>When SIP needs to wrap a C++ class instance it first checks to make sure it +hasn't already done so. If it has then it just returns a new reference to the +corresponding Python object. Otherwise it creates a new Python object of the +appropriate type. In C++ a function may be defined to return an instance of a +certain class, but can often return a sub-class instead.</p> +<p>This directive is used to specify handwritten code that exploits any available +real-time type information (RTTI) to see if there is a more specific Python +type that can be used when wrapping the C++ instance. The RTTI may be +provided by the compiler or by the C++ instance itself.</p> +<p>The directive is included in the specification of one of the classes that the +handwritten code handles the type conversion for. It doesn't matter which +one, but a sensible choice would be the one at the root of that class +hierarchy in the module.</p> +<p>Note that if a class hierarchy extends over a number of modules then this +directive should be used in each of those modules to handle the part of the +hierarchy defined in that module. SIP will ensure that the different pieces +of code are called in the right order to determine the most specific Python +type to use.</p> +<p>The following variables are made available to the handwritten code:</p> +<dl class="docutils"> +<dt><em>type</em> *sipCpp</dt> +<dd>This is a pointer to the C++ class instance.</dd> +<dt>void **sipCppRet</dt> +<dd>When the sub-class is derived from more than one super-class then it is +possible that the C++ address of the instance as the sub-class is +different to that of the super-class. If so, then this must be set to the +C++ address of the instance when cast (usually using <tt class="docutils literal"><span class="pre">static_cast</span></tt>) +from the super-class to the sub-class.</dd> +<dt>sipWrapperType *sipClass</dt> +<dd>The handwritten code must set this to the SIP generated Python type object +that corresponds to the class instance. (The type object for class +<tt class="docutils literal"><span class="pre">Klass</span></tt> is <tt class="docutils literal"><span class="pre">sipClass_Klass</span></tt>.) If the RTTI of the class instance isn't +recognised then <tt class="docutils literal"><span class="pre">sipClass</span></tt> must be set to <tt class="docutils literal"><span class="pre">NULL</span></tt>. The code doesn't +have to recognise the exact class, only the most specific sub-class that +it can.</dd> +</dl> +<p>The handwritten code must not explicitly return.</p> +<p>The following example shows the sub-class conversion code for <tt class="docutils literal"><span class="pre">QEvent</span></tt> based +class hierarchy in PyQt:</p> +<pre class="literal-block"> +class QEvent +{ +%ConvertToSubClassCode + // QEvent sub-classes provide a unique type ID. + switch (sipCpp -> type()) + { + case QEvent::Timer: + sipClass = sipClass_QTimerEvent; + break; + + case QEvent::KeyPress: + case QEvent::KeyRelease: + sipClass = sipClass_QKeyEvent; + break; + + // Skip the remaining event types to keep the example short. + + default: + // We don't recognise the type. + sipClass = NULL; + } +%End + + // The rest of the class specification. + +}; +</pre> +<p>The SIP API includes the <a class="reference" href="#sipmapinttoclass">sipMapIntToClass()</a> and <a class="reference" href="#sipmapstringtoclass">sipMapStringToClass()</a> +functions that convert integer and string based RTTI to Python type objects +based on ordered lookup tables.</p> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id71" id="converttotypecode" name="converttotypecode">7.9 %ConvertToTypeCode</a></h2> +<pre class="literal-block"> +%ConvertToTypeCode + <em>code</em> +%End +</pre> +<p>This directive is used to specify the handwritten code that converts a Python +object to a mapped type instance and to handle any ownership transfers. It is +used as part of the <a class="reference" href="#mappedtype">%MappedType</a> directive and as part of a class +specification. The code is also called to determine if the Python object is of +the correct type prior to conversion.</p> +<p>When used as part of a class specification it can automatically convert +additional types of Python object. For example, PyQt uses it in the +specification of the <tt class="docutils literal"><span class="pre">QString</span></tt> class to allow Python string objects and +unicode objects to be used wherever <tt class="docutils literal"><span class="pre">QString</span></tt> instances are expected.</p> +<p>The following variables are made available to the handwritten code:</p> +<dl class="docutils"> +<dt>int *sipIsErr</dt> +<dd>If this is <tt class="docutils literal"><span class="pre">NULL</span></tt> then the code is being asked to check the type of the +Python object. The check must not have any side effects. Otherwise the +code is being asked to convert the Python object and a non-zero value +should be returned through this pointer if an error occurred during the +conversion.</dd> +<dt>PyObject *sipPy</dt> +<dd>This is the Python object to be converted.</dd> +<dt><em>type</em> **sipCppPtr</dt> +<dd>This is a pointer through which the address of the mapped type instance (or +zero if appropriate) is returned. Its value is undefined if <tt class="docutils literal"><span class="pre">sipIsErr</span></tt> +is <tt class="docutils literal"><span class="pre">NULL</span></tt>.</dd> +<dt>PyObject *sipTransferObj</dt> +<dd>This specifies any desired ownership changes to <em>sipPy</em>. If it is <tt class="docutils literal"><span class="pre">NULL</span></tt> +then the ownership should be left unchanged. If it is <tt class="docutils literal"><span class="pre">Py_None</span></tt> then +ownership should be transferred to Python. Otherwise ownership should be +transferred to C/C++ and <em>sipPy</em> associated with <em>sipTransferObj</em>. The +code can choose to interpret these changes in any way.</dd> +</dl> +<p>The handwritten code must explicitly return an <tt class="docutils literal"><span class="pre">int</span></tt> the meaning of which +depends on the value of <tt class="docutils literal"><span class="pre">sipIsErr</span></tt>.</p> +<p>If <tt class="docutils literal"><span class="pre">sipIsErr</span></tt> is <tt class="docutils literal"><span class="pre">NULL</span></tt> then a non-zero value is returned if the Python +object has a type that can be converted to the mapped type. Otherwise zero is +returned.</p> +<p>If <tt class="docutils literal"><span class="pre">sipIsErr</span></tt> is not <tt class="docutils literal"><span class="pre">NULL</span></tt> then a combination of the following flags is +returned.</p> +<blockquote> +<ul class="simple"> +<li><tt class="docutils literal"><span class="pre">SIP_TEMPORARY</span></tt> is set to indicate that the returned instance is a +temporary and should be released to avoid a memory leak.</li> +<li><tt class="docutils literal"><span class="pre">SIP_DERIVED_CLASS</span></tt> is set to indicate that the type of the +returned instance is a derived class. See <a class="reference" href="#generated-derived-classes">Generated Derived +Classes</a>.</li> +</ul> +</blockquote> +<p>The following example converts a Python list of <tt class="docutils literal"><span class="pre">QPoint</span></tt> instances to a +<tt class="docutils literal"><span class="pre">QList<QPoint></span></tt> instance:</p> +<pre class="literal-block"> +%ConvertToTypeCode + // See if we are just being asked to check the type of the Python + // object. + if (!sipIsErr) + { + // Checking whether or not None has been passed instead of a list + // has already been done. + if (!PyList_Check(sipPy)) + return 0; + + // Check the type of each element. We specify SIP_NOT_NONE to + // disallow None because it is a list of QPoint, not of a pointer + // to a QPoint, so None isn't appropriate. + for (int i = 0; i < PyList_GET_SIZE(sipPy); ++i) + if (!sipCanConvertToInstance(PyList_GET_ITEM(sipPy, i), + sipClass_QPoint, SIP_NOT_NONE)) + return 0; + + // The type is valid. + return 1; + } + + // Create the instance on the heap. + QList<QPoint> *ql = new QList<QPoint>; + + for (int i = 0; i < PyList_GET_SIZE(sipPy); ++i) + { + QPoint *qp; + int state; + + // Get the address of the element's C++ instance. Note that, in + // this case, we don't apply any ownership changes to the list + // elements, only to the list itself. + qp = reinterpret_cast<QPoint *>(sipConvertToInstance( + PyList_GET_ITEM(sipPy, i), + sipClass_QPoint, 0, + SIP_NOT_NONE, + &state, sipIsErr)); + + // Deal with any errors. + if (*sipIsErr) + { + sipReleaseInstance(qp, sipClass_QPoint, state); + + // Tidy up. + delete ql; + + // There is no temporary instance. + return 0; + } + + ql -> append(*qp); + + // A copy of the QPoint was appended to the list so we no longer + // need it. It may be a temporary instance that should be + // destroyed, or a wrapped instance that should not be destroyed. + // sipReleaseInstance() will do the right thing. + sipReleaseInstance(qp, sipClass_QPoint, state); + } + + // Return the instance. + *sipCppPtr = ql; + + // The instance should be regarded as temporary (and be destroyed as + // soon as it has been used) unless it has been transferred from + // Python. sipGetState() is a convenience function that implements + // this common transfer behaviour. + return sipGetState(sipTransferObj); +%End +</pre> +<p>When used in a class specification the handwritten code replaces the code that +would normally be automatically generated. This means that the handwritten +code must also handle instances of the class itself and not just the additional +types that are being supported. This should be done by making calls to +<a class="reference" href="#sipcanconverttoinstance">sipCanConvertToInstance()</a> to check the object type and +<a class="reference" href="#sipconverttoinstance">sipConvertToInstance()</a> to convert the object. The <tt class="docutils literal"><span class="pre">SIP_NO_CONVERTORS</span></tt> +flag <em>must</em> be passed to both these functions to prevent recursive calls to the +handwritten code.</p> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id72" id="copying" name="copying">7.10 %Copying</a></h2> +<pre class="literal-block"> +%Copying + <em>text</em> +%End +</pre> +<p>This directive is used to specify some arbitrary text that will be included at +the start of all source files generated by SIP. It is normally used to +include copyright and licensing terms.</p> +<p>For example:</p> +<pre class="literal-block"> +%Copying +Copyright (c) 2007 Riverbank Computing Limited +%End +</pre> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id73" id="doc" name="doc">7.11 %Doc</a></h2> +<pre class="literal-block"> +%Doc + <em>text</em> +%End +</pre> +<p>This directive is used to specify some arbitrary text that will be extracted +by SIP when the <tt class="docutils literal"><span class="pre">-d</span></tt> command line option is used. The directive can be +specified any number of times and SIP will concatenate all the separate pieces +of text in the order that it sees them.</p> +<p>Documentation that is specified using this directive is local to the module in +which it appears. It is ignored by modules that <a class="reference" href="#import">%Import</a> it. Use the +<a class="reference" href="#exporteddoc">%ExportedDoc</a> directive for documentation that should be included by all +modules that <a class="reference" href="#import">%Import</a> this one.</p> +<p>For example:</p> +<pre class="literal-block"> +%Doc +<h1>An Example</h1> +<p> +This fragment of documentation is HTML and is local to the module in +which it is defined. +</p> +%End +</pre> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id74" id="end" name="end">7.12 %End</a></h2> +<p>This isn't a directive in itself, but is used to terminate a number of +directives that allow a block of handwritten code or text to be specified.</p> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id75" id="exception" name="exception">7.13 %Exception</a></h2> +<pre class="literal-block"> +%Exception <em>name</em> [(<em>base-exception)] +{ + [*header-code</em>] + <em>raise-code</em> +}; +</pre> +<p>This directive is used to define new Python exceptions, or to provide a stub +for existing Python exceptions. It allows handwritten code to be provided +that implements the translation between C++ exceptions and Python exceptions. +The arguments to <tt class="docutils literal"><span class="pre">throw</span> <span class="pre">()</span></tt> specifiers must either be names of classes or the +names of Python exceptions defined by this directive.</p> +<p><em>name</em> is the name of the exception.</p> +<p><em>base-exception</em> is the optional base exception. This may be either one of +the standard Python exceptions or one defined with a previous <a class="reference" href="#exception">%Exception</a> +directive.</p> +<p><em>header-code</em> is the optional <a class="reference" href="#typeheadercode">%TypeHeaderCode</a> used to specify any external +interface to the exception being defined.</p> +<p><em>raise-code</em> is the <a class="reference" href="#raisecode">%RaiseCode</a> used to specify the handwritten code that +converts a reference to the C++ exception to the Python exception.</p> +<p>For example:</p> +<pre class="literal-block"> +%Exception std::exception(SIP_Exception) /PyName=StdException/ +{ +%TypeHeaderCode +#include <exception> +%End +%RaiseCode + const char *detail = sipExceptionReference.what(); + + SIP_BLOCK_THREADS + PyErr_SetString(sipException_StdException, detail); + SIP_UNBLOCK_THREADS +%End +}; +</pre> +<p>In this example we map the standard C++ exception to a new Python exception. +The new exception is called <tt class="docutils literal"><span class="pre">StdException</span></tt> and is derived from the standard +Python exception <tt class="docutils literal"><span class="pre">Exception</span></tt>.</p> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id76" id="exporteddoc" name="exporteddoc">7.14 %ExportedDoc</a></h2> +<pre class="literal-block"> +%ExportedDoc + <em>text</em> +%End +</pre> +<p>This directive is used to specify some arbitrary text that will be extracted +by SIP when the <tt class="docutils literal"><span class="pre">-d</span></tt> command line option is used. The directive can be +specified any number of times and SIP will concatenate all the separate pieces +of text in the order that it sees them.</p> +<p>Documentation that is specified using this directive will also be included by +modules that <a class="reference" href="#import">%Import</a> it.</p> +<p>For example:</p> +<pre class="literal-block"> +%ExportedDoc +========== +An Example +========== + +This fragment of documentation is reStructuredText and will appear in the +module in which it is defined and all modules that %Import it. +%End +</pre> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id77" id="exportedheadercode" name="exportedheadercode">7.15 %ExportedHeaderCode</a></h2> +<pre class="literal-block"> +%ExportedHeaderCode + <em>code</em> +%End +</pre> +<p>This directive is used to specify handwritten code, typically the declarations +of types, that is placed in a header file that is included by all generated +code for all modules. It should not include function declarations because +Python modules should not explicitly call functions in another Python module.</p> +<p>See also <a class="reference" href="#modulecode">%ModuleCode</a> and <a class="reference" href="#moduleheadercode">%ModuleHeaderCode</a>.</p> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id78" id="feature" name="feature">7.16 %Feature</a></h2> +<pre class="literal-block"> +%Feature <em>name</em> +</pre> +<p>This directive is used to declare a feature. Features (along with +<a class="reference" href="#platforms">%Platforms</a> and <a class="reference" href="#timeline">%Timeline</a>) are used by the <a class="reference" href="#if">%If</a> directive to control +whether or not parts of a specification are processed or ignored.</p> +<p>Features are mutually independent of each other - any combination of features +may be enabled or disable. By default all features are enabled. The SIP +<tt class="docutils literal"><span class="pre">-x</span></tt> command line option is used to disable a feature.</p> +<p>If a feature is enabled then SIP will automatically generate a corresponding C +preprocessor symbol for use by handwritten code. The symbol is the name of +the feature prefixed by <tt class="docutils literal"><span class="pre">SIP_FEATURE_</span></tt>.</p> +<p>For example:</p> +<pre class="literal-block"> +%Feature FOO_SUPPORT + +%If (FOO_SUPPORT) +void foo(); +%End +</pre> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id79" id="gcclearcode" name="gcclearcode">7.17 %GCClearCode</a></h2> +<pre class="literal-block"> +%GCClearCode + <em>code</em> +%End +</pre> +<p>Python has a cyclic garbage collector which can identify and release unneeded +objects even when their reference counts are not zero. If a wrapped C +structure or C++ class keeps its own reference to a Python object then, if the +garbage collector is to do its job, it needs to provide some handwritten code +to traverse and potentially clear those embedded references.</p> +<p>See the section <em>Supporting cyclic garbage collection</em> in <a class="reference" href="http://www.python.org/dev/doc/devel/ext/">Embedding and +Extending the Python Interpreter</a> +for the details.</p> +<p>This directive is used to specify the code that clears any embedded references. +(See <a class="reference" href="#gctraversecode">%GCTraverseCode</a> for specifying the code that traverses any embedded +references.)</p> +<p>The following variables are made available to the handwritten code:</p> +<dl class="docutils"> +<dt><em>type</em> *sipCpp</dt> +<dd>This is a pointer to the structure or class instance. Its <em>type</em> is a +pointer to the structure or class.</dd> +<dt>int sipRes</dt> +<dd>The handwritten code should set this to the result to be returned.</dd> +</dl> +<p>The following simplified example is taken from PyQt. The <tt class="docutils literal"><span class="pre">QCustomEvent</span></tt> +class allows arbitary data to be attached to the event. In PyQt this data is +always a Python object and so should be handled by the garbage collector:</p> +<pre class="literal-block"> +%GCClearCode + PyObject *obj; + + // Get the object. + obj = reinterpret_cast<PyObject *>(sipCpp -> data()); + + // Clear the pointer. + sipCpp -> setData(0); + + // Clear the reference. + Py_XDECREF(obj); + + // Report no error. + sipRes = 0; +%End +</pre> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id80" id="gctraversecode" name="gctraversecode">7.18 %GCTraverseCode</a></h2> +<pre class="literal-block"> +%GCTraverseCode + <em>code</em> +%End +</pre> +<p>This directive is used to specify the code that traverses any embedded +references for Python's cyclic garbage collector. (See <a class="reference" href="#gcclearcode">%GCClearCode</a> for a +full explanation.)</p> +<p>The following variables are made available to the handwritten code:</p> +<dl class="docutils"> +<dt><em>type</em> *sipCpp</dt> +<dd>This is a pointer to the structure or class instance. Its <em>type</em> is a +pointer to the structure or class.</dd> +<dt>visitproc sipVisit</dt> +<dd>This is the visit function provided by the garbage collector.</dd> +<dt>void *sipArg</dt> +<dd>This is the argument to the visit function provided by the garbage +collector.</dd> +<dt>int sipRes</dt> +<dd>The handwritten code should set this to the result to be returned.</dd> +</dl> +<p>The following simplified example is taken from PyQt's <tt class="docutils literal"><span class="pre">QCustomEvent</span></tt> class:</p> +<pre class="literal-block"> +%GCTraverseCode + PyObject *obj; + + // Get the object. + obj = reinterpret_cast<PyObject *>(sipCpp -> data()); + + // Call the visit function if there was an object. + if (obj) + sipRes = sipVisit(obj, sipArg); + else + sipRes = 0; +%End +</pre> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id81" id="getcode" name="getcode">7.19 %GetCode</a></h2> +<pre class="literal-block"> +%GetCode + <em>code</em> +%End +</pre> +<p>This directive is used after the declaration of a C++ class variable or C +structure member to specify handwritten code to convert it to a Python object. +It is usually used to handle types that SIP cannot deal with automatically.</p> +<p>The following variables are made available to the handwritten code:</p> +<dl class="docutils"> +<dt><em>type</em> *sipCpp</dt> +<dd>This is a pointer to the structure or class instance. Its <em>type</em> is a +pointer to the structure or class. It is not made available if the +variable being wrapped is a static class variable.</dd> +<dt>PyObject *sipPy</dt> +<dd>The handwritten code must set this to the Python representation of the +class variable or structure member. If there is an error then the code +must raise an exception and set this to <tt class="docutils literal"><span class="pre">NULL</span></tt>.</dd> +</dl> +<p>For example:</p> +<pre class="literal-block"> +struct Entity +{ + /* + * In this contrived example the C library we are wrapping actually + * defines this as char buffer[100] which SIP cannot handle + * automatically. + */ + char *buffer; +%GetCode + sipPy = PyString_FromStringAndSize(sipCpp -> buffer, 100); +%End +%SetCode + char *ptr; + int length; + + if (PyString_AsStringAndSize(sipPy, &ptr, &length) == -1) + sipErr = 1; + else if (length != 100) + { + /* + * Raise an exception because the length isn't exactly right. + */ + + PyErr_SetString(PyExc_ValueError, "an Entity.buffer must be exactly 100 bytes"); + sipErr = 1; + } + else + memcpy(sipCpp -> buffer, ptr, 100); +%End +} +</pre> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id82" id="if" name="if">7.20 %If</a></h2> +<pre class="literal-block"> +%If (<em>expression</em>) + <em>specification</em> +%End +</pre> +<p>where</p> +<pre class="literal-block"> +<em>expression</em> ::= [<em>ored-qualifiers</em> | <em>range</em>] + +<em>ored-qualifiers</em> ::= [<em>qualifier</em> | <em>qualifier</em> <tt class="docutils literal"><span class="pre">||</span></tt> <em>ored-qualifiers</em>] + +<em>qualifier</em> ::= [<tt class="docutils literal"><span class="pre">!</span></tt>] [<em>feature</em> | <em>platform</em>] + +<em>range</em> ::= [<em>version</em>] <tt class="docutils literal"><span class="pre">-</span></tt> [<em>version</em>] +</pre> +<p>This directive is used in conjunction with features (see <a class="reference" href="#feature">%Feature</a>), +platforms (see <a class="reference" href="#platforms">%Platforms</a>) and versions (see <a class="reference" href="#timeline">%Timeline</a>) to control +whether or not parts of a specification are processed or not.</p> +<p>A <em>range</em> of versions means all versions starting with the lower bound up to +but excluding the upper bound. If the lower bound is omitted then it is +interpreted as being before the earliest version. If the upper bound is +omitted then it is interpreted as being after the latest version.</p> +<p>For example:</p> +<pre class="literal-block"> +%Feature SUPPORT_FOO +%Platforms {WIN32_PLATFORM POSIX_PLATFORM MACOS_PLATFORM} +%Timeline {V1_0 V1_1 V2_0 V3_0} + +%If (!SUPPORT_FOO) + // Process this if the SUPPORT_FOO feature is disabled. +%End + +%If (POSIX_PLATFORM || MACOS_PLATFORM) + // Process this if either the POSIX_PLATFORM or MACOS_PLATFORM + // platforms are enabled. +%End + +%If (V1_0 - V2_0) + // Process this if either V1_0 or V1_1 is enabled. +%End + +%If (V2_0 - ) + // Process this if either V2_0 or V3_0 is enabled. +%End + +%If ( - ) + // Always process this. +%End +</pre> +<p>Note that this directive is not implemented as a preprocessor. Only the +following parts of a specification are affected by it:</p> +<blockquote> +<ul class="simple"> +<li><tt class="docutils literal"><span class="pre">class</span></tt></li> +<li><a class="reference" href="#convertfromtypecode">%ConvertFromTypeCode</a></li> +<li><a class="reference" href="#converttosubclasscode">%ConvertToSubClassCode</a></li> +<li><a class="reference" href="#converttotypecode">%ConvertToTypeCode</a></li> +<li><tt class="docutils literal"><span class="pre">enum</span></tt></li> +<li><a class="reference" href="#exportedheadercode">%ExportedHeaderCode</a></li> +<li>functions</li> +<li><a class="reference" href="#gcclearcode">%GCClearCode</a></li> +<li><a class="reference" href="#gctraversecode">%GCTraverseCode</a></li> +<li><a class="reference" href="#if">%If</a></li> +<li><a class="reference" href="#mappedtype">%MappedType</a></li> +<li><a class="reference" href="#methodcode">%MethodCode</a></li> +<li><a class="reference" href="#modulecode">%ModuleCode</a></li> +<li><a class="reference" href="#moduleheadercode">%ModuleHeaderCode</a></li> +<li><tt class="docutils literal"><span class="pre">namespace</span></tt></li> +<li><a class="reference" href="#postinitialisationcode">%PostInitialisationCode</a></li> +<li><a class="reference" href="#preinitialisationcode">%PreInitialisationCode</a></li> +<li><tt class="docutils literal"><span class="pre">struct</span></tt></li> +<li><tt class="docutils literal"><span class="pre">typedef</span></tt></li> +<li><a class="reference" href="#typecode">%TypeCode</a></li> +<li><a class="reference" href="#typeheadercode">%TypeHeaderCode</a></li> +<li><a class="reference" href="#unitcode">%UnitCode</a></li> +<li>variables</li> +<li><a class="reference" href="#virtualcatchercode">%VirtualCatcherCode</a></li> +</ul> +</blockquote> +<p>Also note that the only way to specify the logical and of qualifiers is to use +nested <a class="reference" href="#if">%If</a> directives.</p> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id83" id="import" name="import">7.21 %Import</a></h2> +<pre class="literal-block"> +%Import <em>filename</em> +</pre> +<p>This directive is used to import the specification of another module. This is +needed if the current module makes use of any types defined in the imported +module, e.g. as an argument to a function, or to sub-class.</p> +<p>If <em>filename</em> cannot be opened then SIP prepends <em>filename</em> with the name of +the directory containing the current specification file (i.e. the one +containing the <a class="reference" href="#import">%Import</a> directive) and tries again. If this also fails then +SIP prepends <em>filename</em> with each of the directories, in turn, specified by +the <tt class="docutils literal"><span class="pre">-I</span></tt> command line option.</p> +<p>For example:</p> +<pre class="literal-block"> +%Import qt/qtmod.sip +</pre> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id84" id="include" name="include">7.22 %Include</a></h2> +<pre class="literal-block"> +%Include <em>filename</em> +</pre> +<p>This directive is used to include contents of another file as part of the +specification of the current module. It is the equivalent of the C +preprocessor's <tt class="docutils literal"><span class="pre">#include</span></tt> directive and is used to structure a large module +specification into manageable pieces.</p> +<p><a class="reference" href="#include">%Include</a> follows the same search process as <a class="reference" href="#import">%Import</a> when trying to open +<em>filename</em>.</p> +<p>For example:</p> +<pre class="literal-block"> +%Include qwidget.sip +</pre> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id85" id="id14" name="id14">7.23 %License</a></h2> +<pre class="literal-block"> +%License /<em>license-annotations</em>/ +</pre> +<p>This directive is used to specify the contents of an optional license +dictionary. The license dictionary is called <tt class="docutils literal"><span class="pre">__license__</span></tt> and is stored in +the module dictionary. The elements of the dictionary are specified using the +<a class="reference" href="#licensee">Licensee</a>, <a class="reference" href="#signature">Signature</a>, <a class="reference" href="#timestamp">Timestamp</a> and <a class="reference" href="#type">Type</a> annotations. Only the <a class="reference" href="#type">Type</a> +annotation is compulsory.</p> +<p>Note that this directive isn't an attempt to impose any licensing restrictions +on a module. It is simply a method for easily embedding licensing information +in a module so that it is accessible to Python scripts.</p> +<p>For example:</p> +<pre class="literal-block"> +%License /Type="GPL"/ +</pre> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id86" id="mappedtype" name="mappedtype">7.24 %MappedType</a></h2> +<pre class="literal-block"> +template<<em>type-list</em>> +%MappedType <em>type</em> +{ + [<em>header-code</em>] + [<em>convert-to-code</em>] + [<em>convert-from-code</em>] +}; + +%MappedType <em>type</em> +{ + [<em>header-code</em>] + [<em>convert-to-code</em>] + [<em>convert-from-code</em>] +}; +</pre> +<p>This directive is used to define an automatic mapping between a C or C++ type +and a Python type. It can be used as part of a template, or to map a specific +type.</p> +<p>When used as part of a template <em>type</em> cannot itself refer to a template. Any +occurrences of any of the type names (but not any <tt class="docutils literal"><span class="pre">*</span></tt> or <tt class="docutils literal"><span class="pre">&</span></tt>) in +<em>type-list</em> will be replaced by the actual type names used when the template is +instantiated. Template mapped types are instantiated automatically as required +(unlike template classes which are only instantiated using <tt class="docutils literal"><span class="pre">typedef</span></tt>).</p> +<p>Any explicit mapped type will be used in preference to any template that maps +the same type, ie. a template will not be automatically instantiated if there +is an explicit mapped type.</p> +<p><em>header-code</em> is the <a class="reference" href="#typeheadercode">%TypeHeaderCode</a> used to specify the library interface +to the type being mapped.</p> +<p><em>convert-to-code</em> is the <a class="reference" href="#converttotypecode">%ConvertToTypeCode</a> used to specify the handwritten +code that converts a Python object to an instance of the mapped type.</p> +<p><em>convert-from-code</em> is the <a class="reference" href="#convertfromtypecode">%ConvertFromTypeCode</a> used to specify the +handwritten code that converts an instance of the mapped type to a Python +object.</p> +<p>For example:</p> +<pre class="literal-block"> +template<Type *> +%MappedType QList +{ +%TypeHeaderCode +// Include the library interface to the type being mapped. +#include <qlist.h> +%End + +%ConvertToTypeCode + // See if we are just being asked to check the type of the Python + // object. + if (sipIsErr == NULL) + { + // Check it is a list. + if (!PyList_Check(sipPy)) + return 0; + + // Now check each element of the list is of the type we expect. + // The template is for a pointer type so we don't disallow None. + for (int i = 0; i < PyList_GET_SIZE(sipPy); ++i) + if (!sipCanConvertToInstance(PyList_GET_ITEM(sipPy, i), + sipClass_Type, 0)) + return 0; + + return 1; + } + + // Create the instance on the heap. + QList<Type *> *ql = new QList<Type *>; + + for (int i = 0; i < PyList_GET_SIZE(sipPy); ++i) + { + // Use the SIP API to convert the Python object to the + // corresponding C++ instance. Note that we apply any ownership + // transfer to the list itself, not the individual elements. + Type *t = reinterpret_cast<Type *>(sipConvertToInstance( + PyList_GET_ITEM(sipPy, i), + sipClass_Type, 0, 0, 0, + sipIsErr)); + + if (*sipIsErr) + { + // Tidy up. + delete ql; + + // There is nothing on the heap. + return 0; + } + + // Add the pointer to the C++ instance. + ql -> append(t); + } + + // Return the instance on the heap. + *sipCppPtr = ql; + + // Apply the normal transfer. + return sipGetState(sipTransferObj); +%End + +%ConvertFromTypeCode + PyObject *l; + + // Create the Python list of the correct length. + if ((l = PyList_New(sipCpp -> size())) == NULL) + return NULL; + + // Go through each element in the C++ instance and convert it to the + // corresponding Python object. + for (int i = 0; i < sipCpp -> size(); ++i) + { + Type *t = sipCpp -> at(i); + PyObject *tobj; + + if ((tobj = sipConvertFromInstance(t, sipClass_Type, sipTransferObj)) == NULL) + { + // There was an error so garbage collect the Python list. + Py_DECREF(l); + return NULL; + } + + PyList_SET_ITEM(l, i, tobj); + } + + // Return the Python list. + return l; +%End +} +</pre> +<p>Using this we can use, for example, <tt class="docutils literal"><span class="pre">QList<QObject</span> <span class="pre">*></span></tt> throughout the +module's specification files (and in any module that imports this one). The +generated code will automatically map this to and from a Python list of QObject +instances when appropriate.</p> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id87" id="methodcode" name="methodcode">7.25 %MethodCode</a></h2> +<pre class="literal-block"> +%MethodCode + <em>code</em> +%End +</pre> +<p>This directive is used as part of the specification of a global function, class +method, operator, constructor or destructor to specify handwritten code that +replaces the normally generated call to the function being wrapped. It is +usually used to handle argument types and results that SIP cannot deal with +automatically.</p> +<p>The specified code is embedded in-line after the function's arguments have +been successfully converted from Python objects to their C or C++ equivalents. +The specified code must not include any <tt class="docutils literal"><span class="pre">return</span></tt> statements.</p> +<p>In the context of a destructor the specified code is embedded in-line in the +Python type's deallocation function. Unlike other contexts it supplements +rather than replaces the normally generated code, so it must not include code +to return the C structure or C++ class instance to the heap. The code is only +called if ownership of the structure or class is with Python.</p> +<p>The specified code must also handle the Python Global Interpreter Lock (GIL). +If compatibility with SIP v3.x is required then the GIL must be released +immediately before the C++ call and reacquired immediately afterwards as shown +in this example fragment:</p> +<pre class="literal-block"> +Py_BEGIN_ALLOW_THREADS +sipCpp -> foo(); +Py_END_ALLOW_THREADS +</pre> +<p>If compatibility with SIP v3.x is not required then this is optional but +should be done if the C++ function might block the current thread or take a +significant amount of time to execute. (See <a class="reference" href="#the-python-global-interpreter-lock">The Python Global Interpreter +Lock</a> and the <a class="reference" href="#releasegil">ReleaseGIL</a> and <a class="reference" href="#holdgil">HoldGIL</a> annotations.)</p> +<p>The following variables are made available to the handwritten code:</p> +<dl class="docutils"> +<dt><em>type</em> a0</dt> +<dd><p class="first">There is a variable for each argument of the Python signature (excluding +any <tt class="docutils literal"><span class="pre">self</span></tt> argument) named <tt class="docutils literal"><span class="pre">a0</span></tt>, <tt class="docutils literal"><span class="pre">a1</span></tt>, etc. The <em>type</em> of the +variable is the same as the type defined in the specification with the +following exceptions:</p> +<ul class="simple"> +<li>if the argument is only used to return a value (e.g. it is an <tt class="docutils literal"><span class="pre">int</span> <span class="pre">*</span></tt> +without an <a class="reference" href="#in">In</a> annotation) then the type has one less level of +indirection (e.g. it will be an <tt class="docutils literal"><span class="pre">int</span></tt>)</li> +<li>if the argument is a structure or class (or a reference or a pointer to a +structure or class) then <em>type</em> will always be a pointer to the structure +or class.</li> +</ul> +<p class="last">Note that handwritten code for destructors never has any arguments.</p> +</dd> +<dt>PyObject *a0Wrapper</dt> +<dd>This variable is made available only if the corresponding argument wraps a +C structure or C++ class instance and the <a class="reference" href="#getwrapper">GetWrapper</a> annotation is +specified. The variable is a pointer to the Python object that wraps the +argument.</dd> +<dt><em>type</em> *sipCpp</dt> +<dd>If the directive is used in the context of a class constructor then this +must be set by the handwritten code to the constructed instance. In any +other context then this is a pointer to the C structure or C++ class +instance. Its <em>type</em> is a pointer to the structure or class.</dd> +<dt>int sipIsErr</dt> +<dd><p class="first">The handwritten code should set this to a non-zero value, and raise an +appropriate Python exception, if an error is detected.</p> +<p class="last"><tt class="docutils literal"><span class="pre">sipIsErr</span></tt> is not provided for destructors.</p> +</dd> +<dt><em>type</em> sipRes</dt> +<dd><p class="first">The handwritten code should set this to the result to be returned. The +<em>type</em> of the variable is the same as the type defined in the Python +signature in the specification with the following exception:</p> +<ul class="simple"> +<li>if the argument is a structure or class (or a reference or a pointer to a +structure or class) then <em>type</em> will always be a pointer to the structure +or class.</li> +</ul> +<p class="last"><tt class="docutils literal"><span class="pre">sipRes</span></tt> is not provided for inplace operators (e.g. <tt class="docutils literal"><span class="pre">+=</span></tt> or +<tt class="docutils literal"><span class="pre">__imul__</span></tt>) as their results are handled automatically, nor for class +constructors.</p> +</dd> +<dt>PyObject *sipSelf</dt> +<dd>If the directive is used in the context of a class constructor or method +then this is the Python object that wraps the the structure or class +instance, i.e. <tt class="docutils literal"><span class="pre">self</span></tt>.</dd> +<dt>bool sipSelfWasArg</dt> +<dd><p class="first">This is only made available for non-abstract, virtual methods. It is set +if <tt class="docutils literal"><span class="pre">self</span></tt> was explicitly passed as the first argument of the method +rather than being bound to the method. In other words, the call was:</p> +<pre class="literal-block"> +Klass.foo(self, ...) +</pre> +<p>rather than:</p> +<pre class="last literal-block"> +self.foo(...) +</pre> +</dd> +</dl> +<p>The following is a complete example:</p> +<pre class="literal-block"> +class Klass +{ +public: + virtual int foo(SIP_PYTUPLE); +%MethodCode + // The C++ API takes a 2 element array of integers but passing a + // two element tuple is more Pythonic. + + int iarr[2]; + + if (PyArg_ParseTuple(a0, "ii", &iarr[0], &iarr[1])) + { + Py_BEGIN_ALLOW_THREADS + sipRes = sipSelfWasArg ? sipCpp -> Klass::foo(iarr) + : sipCpp -> foo(iarr); + Py_END_ALLOW_THREADS + } + else + { + // PyArg_ParseTuple() will have raised the exception. + sipIsErr = 1; + } +%End +}; +</pre> +<p>As the example is a virtual method <a class="footnote-reference" href="#id16" id="id15" name="id15">[7]</a>, note the use of <tt class="docutils literal"><span class="pre">sipSelfWasArg</span></tt> to +determine exactly which implementation of <tt class="docutils literal"><span class="pre">foo()</span></tt> to call.</p> +<p>If a method is in the <tt class="docutils literal"><span class="pre">protected</span></tt> section of a C++ class then the call +should instead be:</p> +<pre class="literal-block"> +sipRes = sipCpp -> sipProtectVirt_foo(sipSelfWasArg, iarr); +</pre> +<p>If a method is in the <tt class="docutils literal"><span class="pre">protected</span></tt> section of a C++ class but is not virtual +then the call should instead be:</p> +<pre class="literal-block"> +sipRes = sipCpp -> sipProtect_foo(iarr); +</pre> +<table class="docutils footnote" frame="void" id="id16" rules="none"> +<colgroup><col class="label" /><col /></colgroup> +<tbody valign="top"> +<tr><td class="label"><a class="fn-backref" href="#id15" name="id16">[7]</a></td><td>See <a class="reference" href="#virtualcatchercode">%VirtualCatcherCode</a> for a description of how SIP generated code +handles the reimplementation of C++ virtual methods in Python.</td></tr> +</tbody> +</table> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id88" id="module" name="module">7.26 %Module</a></h2> +<pre class="literal-block"> +%Module <em>name</em> [<em>version</em>] +</pre> +<p>This directive is used to identify that the library being wrapped is a C++ +library and to define the name of the module and it's optional version number.</p> +<p>The name may contain periods to specify that the module is part of a Python +package.</p> +<p>The optional version number is useful if you (or others) might create other +modules that build on this module, i.e. if another module might <a class="reference" href="#import">%Import</a> +this module. Under the covers, a module exports an API that is used by modules +that <a class="reference" href="#import">%Import</a> it and the API is given a version number. A module built on +that module knows the version number of the API that it is expecting. If, +when the modules are imported at run-time, the version numbers do not match +then a Python exception is raised. The dependent module must then be re-built +using the correct specification files for the base module.</p> +<p>The version number should be incremented whenever a module is changed. Some +changes don't affect the exported API, but it is good practice to change the +version number anyway.</p> +<p>For example:</p> +<pre class="literal-block"> +%Module qt 5 +</pre> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id89" id="modulecode" name="modulecode">7.27 %ModuleCode</a></h2> +<pre class="literal-block"> +%ModuleCode + <em>code</em> +%End +</pre> +<p>This directive is used to specify handwritten code, typically the +implementations of utility functions, that can be called by other handwritten +code in the module.</p> +<p>For example:</p> +<pre class="literal-block"> +%ModuleCode +// Print an object on stderr for debugging purposes. +void dump_object(PyObject *o) +{ + PyObject_Print(o, stderr, 0); + fprintf(stderr, "\n"); +} +%End +</pre> +<p>See also <a class="reference" href="#exportedheadercode">%ExportedHeaderCode</a> and <a class="reference" href="#moduleheadercode">%ModuleHeaderCode</a>.</p> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id90" id="moduleheadercode" name="moduleheadercode">7.28 %ModuleHeaderCode</a></h2> +<pre class="literal-block"> +%ModuleHeaderCode + <em>code</em> +%End +</pre> +<p>This directive is used to specify handwritten code, typically the declarations +of utility functions, that is placed in a header file that is included by all +generated code for the same module.</p> +<p>For example:</p> +<pre class="literal-block"> +%ModuleHeaderCode +void dump_object(PyObject *o); +%End +</pre> +<p>See also <a class="reference" href="#exportedheadercode">%ExportedHeaderCode</a> and <a class="reference" href="#modulecode">%ModuleCode</a>.</p> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id91" id="optionalinclude" name="optionalinclude">7.29 %OptionalInclude</a></h2> +<pre class="literal-block"> +%OptionalInclude <em>filename</em> +</pre> +<p>This directive is identical to the <a class="reference" href="#include">%Include</a> directive except that SIP +silently continues processing if <em>filename</em> could not be opened.</p> +<p>For example:</p> +<pre class="literal-block"> +%OptionalInclude license.sip +</pre> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id92" id="platforms" name="platforms">7.30 %Platforms</a></h2> +<pre class="literal-block"> +%Platforms {<em>name</em> <em>name</em> ...} +</pre> +<p>This directive is used to declare a set of platforms. Platforms (along with +<a class="reference" href="#feature">%Feature</a> and <a class="reference" href="#timeline">%Timeline</a>) are used by the <a class="reference" href="#if">%If</a> directive to control +whether or not parts of a specification are processed or ignored.</p> +<p>Platforms are mutually exclusive - only one platform can be enabled at a time. +By default all platforms are disabled. The SIP <tt class="docutils literal"><span class="pre">-t</span></tt> command line option is +used to enable a platform.</p> +<p>For example:</p> +<pre class="literal-block"> +%Platforms {WIN32_PLATFORM POSIX_PLATFORM MACOS_PLATFORM} + +%If (WIN32_PLATFORM) +void undocumented(); +%End + +%If (POSIX_PLATFORM) +void documented(); +%End +</pre> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id93" id="postinitialisationcode" name="postinitialisationcode">7.31 %PostInitialisationCode</a></h2> +<pre class="literal-block"> +%PostInitialisationCode + <em>code</em> +%End +</pre> +<p>This directive is used to specify handwritten code that is embedded in-line +at the very end of the generated module initialisation code.</p> +<p>The following variables are made available to the handwritten code:</p> +<dl class="docutils"> +<dt>PyObject *sipModule</dt> +<dd>This is the module object returned by <tt class="docutils literal"><span class="pre">Py_InitModule()</span></tt>.</dd> +<dt>PyObject *sipModuleDict</dt> +<dd>This is the module's dictionary object returned by <tt class="docutils literal"><span class="pre">Py_ModuleGetDict()</span></tt>.</dd> +</dl> +<p>For example:</p> +<pre class="literal-block"> +%PostInitialisationCode + // The code will be executed when the module is first imported and + // after all other initialisation has been completed. +%End +</pre> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id94" id="preinitialisationcode" name="preinitialisationcode">7.32 %PreInitialisationCode</a></h2> +<pre class="literal-block"> +%PreInitialisationCode + <em>code</em> +%End +</pre> +<p>This directive is used to specify handwritten code that is embedded in-line +at the very start of the generated module initialisation code.</p> +<p>For example:</p> +<pre class="literal-block"> +%PreInitialisationCode + // The code will be executed when the module is first imported and + // before other initialisation has been completed. +%End +</pre> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id95" id="raisecode" name="raisecode">7.33 %RaiseCode</a></h2> +<pre class="literal-block"> +%RaiseCode + <em>code</em> +%End +</pre> +<p>This directive is used as part of the definition of an exception using the +<a class="reference" href="#exception">%Exception</a> directive to specify handwritten code that raises a Python +exception when a C++ exception has been caught. The code is embedded in-line +as the body of a C++ <tt class="docutils literal"><span class="pre">catch</span> <span class="pre">()</span></tt> clause.</p> +<p>The specified code must handle the Python Global Interpreter Lock (GIL) if +necessary. The GIL must be acquired before any calls to the Python API and +released after the last call as shown in this example fragment:</p> +<pre class="literal-block"> +SIP_BLOCK_THREADS +PyErr_SetNone(PyErr_Exception); +SIP_UNBLOCK_THREADS +</pre> +<p>Finally, the specified code must not include any <tt class="docutils literal"><span class="pre">return</span></tt> statements.</p> +<p>The following variable is made available to the handwritten code:</p> +<dl class="docutils"> +<dt><em>type</em> &sipExceptionRef</dt> +<dd>This is a reference to the caught C++ exception. The <em>type</em> of the +reference is the same as the type defined in the <tt class="docutils literal"><span class="pre">throw</span> <span class="pre">()</span></tt> specifier.</dd> +</dl> +<p>See the <a class="reference" href="#exception">%Exception</a> directive for an example.</p> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id96" id="setcode" name="setcode">7.34 %SetCode</a></h2> +<pre class="literal-block"> +%SetCode + <em>code</em> +%End +</pre> +<p>This directive is used after the declaration of a C++ class variable or C +structure member to specify handwritten code to convert it from a Python +object. It is usually used to handle types that SIP cannot deal with +automatically.</p> +<p>The following variables are made available to the handwritten code:</p> +<dl class="docutils"> +<dt><em>type</em> *sipCpp</dt> +<dd>This is a pointer to the structure or class instance. Its <em>type</em> is a +pointer to the structure or class. It is not made available if the +variable being wrapped is a static class variable.</dd> +<dt>int sipErr</dt> +<dd>If the conversion failed then the handwritten code should raise a Python +exception and set this to a non-zero value. Its initial value will be +automatically set to zero.</dd> +<dt>PyObject *sipPy</dt> +<dd>This is the Python object that the handwritten code should convert.</dd> +</dl> +<p>See the <a class="reference" href="#getcode">%GetCode</a> directive for an example.</p> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id97" id="sipoptions" name="sipoptions">7.35 %SIPOptions</a></h2> +<p>This directive sets one or more options that controls different aspects of +SIP's behaviour. In this version all the available options are provided +specifically to support PyQt and so are not documented.</p> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id98" id="timeline" name="timeline">7.36 %Timeline</a></h2> +<pre class="literal-block"> +%Timeline {<em>name</em> <em>name</em> ...} +</pre> +<p>This directive is used to declare a set of versions released over a period of +time. Versions (along with <a class="reference" href="#feature">%Feature</a> and <a class="reference" href="#platforms">%Platforms</a>) are used by the +<a class="reference" href="#if">%If</a> directive to control whether or not parts of a specification are +processed or ignored.</p> +<p>Versions are mutually exclusive - only one version can be enabled at a time. +By default all versions are disabled. The SIP <tt class="docutils literal"><span class="pre">-t</span></tt> command line option is +used to enable a version.</p> +<p>For example:</p> +<pre class="literal-block"> +%Timeline {V1_0 V1_1 V2_0 V3_0} + +%If (V1_0 - V2_0) +void foo(); +%End + +%If (V2_0 -) +void foo(int = 0); +%End +</pre> +<p><a class="reference" href="#timeline">%Timeline</a> can be used any number of times in a module to allow multiple +libraries to be wrapped in the same module.</p> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id99" id="typecode" name="typecode">7.37 %TypeCode</a></h2> +<pre class="literal-block"> +%TypeCode + <em>code</em> +%End +</pre> +<p>This directive is used as part of the specification of a C structure or a C++ +class to specify handwritten code, typically the implementations of utility +functions, that can be called by other handwritten code in the structure or +class.</p> +<p>For example:</p> +<pre class="literal-block"> +class Klass +{ +%TypeCode +// Print an instance on stderr for debugging purposes. +static void dump_klass(const Klass *k) +{ + fprintf(stderr,"Klass %s at %p\n", k -> name(), k); +} +%End + + // The rest of the class specification. + +}; +</pre> +<p>Because the scope of the code is normally within the generated file that +implements the type, any utility functions would normally be declared +<tt class="docutils literal"><span class="pre">static</span></tt>. However a naming convention should still be adopted to prevent +clashes of function names within a module in case the SIP <tt class="docutils literal"><span class="pre">-j</span></tt> command line +option is used.</p> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id100" id="typeheadercode" name="typeheadercode">7.38 %TypeHeaderCode</a></h2> +<pre class="literal-block"> +%TypeHeaderCode + <em>code</em> +%End +</pre> +<p>This directive is used to specify handwritten code that defines the interface +to a C or C++ type being wrapped, either a structure, a class, or a template. +It is used within a class definition or a <a class="reference" href="#mappedtype">%MappedType</a> directive.</p> +<p>Normally <em>code</em> will be a pre-processor <tt class="docutils literal"><span class="pre">#include</span></tt> statement.</p> +<p>For example:</p> +<pre class="literal-block"> +// Wrap the Klass class. +class Klass +{ +%TypeHeaderCode +#include <klass.h> +%End + + // The rest of the class specification. +}; +</pre> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id101" id="unitcode" name="unitcode">7.39 %UnitCode</a></h2> +<pre class="literal-block"> +%UnitCode + <em>code</em> +%End +</pre> +<p>This directive is used to specify handwritten code that it included at the very +start of a generated compilation unit (ie. C or C++ source file). It is +typically used to <tt class="docutils literal"><span class="pre">#include</span></tt> a C++ precompiled header file.</p> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id102" id="virtualcatchercode" name="virtualcatchercode">7.40 %VirtualCatcherCode</a></h2> +<pre class="literal-block"> +%VirtualCatcherCode + <em>code</em> +%End +</pre> +<p>For most classes there are corresponding <a class="reference" href="#generated-derived-classes">generated derived classes</a> that +contain reimplementations of the class's virtual methods. These methods (which +SIP calls catchers) determine if there is a corresponding Python +reimplementation and call it if so. If there is no Python reimplementation +then the method in the original class is called instead.</p> +<p>This directive is used to specify handwritten code that replaces the normally +generated call to the Python reimplementation and the handling of any returned +results. It is usually used to handle argument types and results that SIP +cannot deal with automatically.</p> +<p>This directive can also be used in the context of a class destructor to +specify handwritten code that is embedded in-line in the internal derived +class's destructor.</p> +<p>In the context of a method the Python Global Interpreter Lock (GIL) is +automatically acquired before the specified code is executed and automatically +released afterwards.</p> +<p>In the context of a destructor the specified code must handle the GIL. The +GIL must be acquired before any calls to the Python API and released after the +last call as shown in this example fragment:</p> +<pre class="literal-block"> +SIP_BLOCK_THREADS +Py_DECREF(obj); +SIP_UNBLOCK_THREADS +</pre> +<p>The following variables are made available to the handwritten code in the +context of a method:</p> +<dl class="docutils"> +<dt><em>type</em> a0</dt> +<dd>There is a variable for each argument of the C++ signature named <tt class="docutils literal"><span class="pre">a0</span></tt>, +<tt class="docutils literal"><span class="pre">a1</span></tt>, etc. The <em>type</em> of the variable is the same as the type defined in +the specification.</dd> +<dt>int sipIsErr</dt> +<dd>The handwritten code should set this to a non-zero value, and raise an +appropriate Python exception, if an error is detected.</dd> +<dt>PyObject *sipMethod</dt> +<dd>This object is the Python reimplementation of the virtual C++ method. It +is normally passed to <a class="reference" href="#sipcallmethod">sipCallMethod()</a>.</dd> +<dt><em>type</em> sipRes</dt> +<dd>The handwritten code should set this to the result to be returned. The +<em>type</em> of the variable is the same as the type defined in the C++ signature +in the specification.</dd> +</dl> +<p>No variables are made available in the context of a destructor.</p> +<p>For example:</p> +<pre class="literal-block"> +class Klass +{ +public: + virtual int foo(SIP_PYTUPLE) [int (int *)]; +%MethodCode + // The C++ API takes a 2 element array of integers but passing a + // two element tuple is more Pythonic. + + int iarr[2]; + + if (PyArg_ParseTuple(a0, "ii", &iarr[0], &iarr[1])) + { + Py_BEGIN_ALLOW_THREADS + sipRes = sipCpp -> Klass::foo(iarr); + Py_END_ALLOW_THREADS + } + else + { + // PyArg_ParseTuple() will have raised the exception. + sipIsErr = 1; + } +%End +%VirtualCatcherCode + // Convert the 2 element array of integers to the two element + // tuple. + + PyObject *result; + + result = sipCallMethod(&sipIsErr, sipMethod, "ii", a0[0], a0[1]); + + if (result != NULL) + { + // Convert the result to the C++ type. + sipParseResult(&sipIsErr, sipMethod, result, "i", &sipRes); + + Py_DECREF(result); + } +%End +}; +</pre> +</div> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id103" id="sip-annotations" name="sip-annotations">8 SIP Annotations</a></h1> +<p>In this section we describe each of the annotations that can be used in +specification files.</p> +<p>Annotations can either be argument annotations, class annotations, enum +annotations, exception annotations, function annotations, license annotations, +or variable annotations depending on the context in which they can be used.</p> +<p>Annotations are placed between forward slashes (<tt class="docutils literal"><span class="pre">/</span></tt>). Multiple annotations +are comma separated within the slashes.</p> +<p>Annotations have a type and, possibly, a value. The type determines the +format of the value. The name of an annotation and its value are separated by +<tt class="docutils literal"><span class="pre">=</span></tt>.</p> +<p>Annotations can have one of the following types:</p> +<dl class="docutils"> +<dt>boolean</dt> +<dd>This type of annotation has no value and is implicitly true.</dd> +<dt>name</dt> +<dd>The value is a name that is compatible with a C/C++ identifier. In some +cases the value is optional.</dd> +<dt>string</dt> +<dd>The value is a double quoted string.</dd> +</dl> +<p>The following example shows argument and function annotations:</p> +<pre class="literal-block"> +void exec(QWidget * /Transfer/) /ReleaseGIL, PyName=call_exec/; +</pre> +<p>Note that the current version of SIP does not complain about unknown +annotations, or annotations used out of their correct context.</p> +<div class="section"> +<h2><a class="toc-backref" href="#id104" id="argument-annotations" name="argument-annotations">8.1 Argument Annotations</a></h2> +<div class="section"> +<h3><a class="toc-backref" href="#id105" id="allownone" name="allownone">8.1.1 AllowNone</a></h3> +<p>This boolean annotation specifies that the value of the corresponding argument +(which should be either <a class="reference" href="#sip-pycallable">SIP_PYCALLABLE</a>, <a class="reference" href="#sip-pydict">SIP_PYDICT</a>, <a class="reference" href="#sip-pylist">SIP_PYLIST</a>, +<a class="reference" href="#sip-pyslice">SIP_PYSLICE</a>, <a class="reference" href="#sip-pytuple">SIP_PYTUPLE</a> or <a class="reference" href="#sip-pytype">SIP_PYTYPE</a>) may be <tt class="docutils literal"><span class="pre">None</span></tt>.</p> +</div> +<div class="section"> +<h3><a class="toc-backref" href="#id106" id="array" name="array">8.1.2 Array</a></h3> +<p>This boolean annotation specifies that the corresponding argument (which +should be either <tt class="docutils literal"><span class="pre">char</span> <span class="pre">*</span></tt> or <tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">char</span> <span class="pre">*</span></tt>) refers to an array +rather than a <tt class="docutils literal"><span class="pre">'\0'</span></tt> terminated string. There must be a corresponding +argument with the <a class="reference" href="#arraysize">ArraySize</a> annotation specified. The annotation may only be +specified once in a list of arguments.</p> +</div> +<div class="section"> +<h3><a class="toc-backref" href="#id107" id="arraysize" name="arraysize">8.1.3 ArraySize</a></h3> +<p>This boolean annotation specifies that the corresponding argument (which +should be either <tt class="docutils literal"><span class="pre">short</span></tt>, <tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">short</span></tt>, <tt class="docutils literal"><span class="pre">int</span></tt>, <tt class="docutils literal"><span class="pre">unsigned</span></tt>, +<tt class="docutils literal"><span class="pre">long</span></tt> or <tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">long</span></tt>) refers to the size of an array. There must be +a corresponding argument with the <a class="reference" href="#array">Array</a> annotation specified. The annotation +may only be specified once in a list of arguments.</p> +</div> +<div class="section"> +<h3><a class="toc-backref" href="#id108" id="constrained" name="constrained">8.1.4 Constrained</a></h3> +<p>Python will automatically convert between certain compatible types. For +example, if a floating pointer number is expected and an integer supplied, +then the integer will be converted appropriately. This can cause problems +when wrapping C or C++ functions with similar signatures. For example:</p> +<pre class="literal-block"> +// The wrapper for this function will also accept an integer argument +// which Python will automatically convert to a floating point number. +void foo(double); + +// The wrapper for this function will never get used. +void foo(int); +</pre> +<p>This boolean annotation specifies that the corresponding argument (which +should be either <tt class="docutils literal"><span class="pre">bool</span></tt>, <tt class="docutils literal"><span class="pre">int</span></tt>, <tt class="docutils literal"><span class="pre">float</span></tt>, <tt class="docutils literal"><span class="pre">double</span></tt> or a wrapped class) +must match the type without any automatic conversions. In the context of a +wrapped class the invocation of any <a class="reference" href="#converttotypecode">%ConvertToTypeCode</a> is suppressed.</p> +<p>The following example gets around the above problem:</p> +<pre class="literal-block"> +// The wrapper for this function will only accept floating point numbers. +void foo(double /Constrained/); + +// The wrapper for this function will be used for anything that Python can +// convert to an integer, except for floating point numbers. +void foo(int); +</pre> +</div> +<div class="section"> +<h3><a class="toc-backref" href="#id109" id="getwrapper" name="getwrapper">8.1.5 GetWrapper</a></h3> +<p>This boolean annotation is only ever used in conjunction with handwritten code +specified with the <a class="reference" href="#methodcode">%MethodCode</a> directive. It causes an extra variable to +be generated for the corresponding argument (which should be a wrapped C +structure or C++ class instance) which is a pointer to the Python object that +wraps the argument.</p> +<p>See the <a class="reference" href="#methodcode">%MethodCode</a> directive for more detail.</p> +</div> +<div class="section"> +<h3><a class="toc-backref" href="#id110" id="in" name="in">8.1.6 In</a></h3> +<p>This boolean annotation is used to specify that the corresponding argument +(which should be a pointer type) is used to pass a value to the function.</p> +<p>For pointers to wrapped C structures or C++ class instances, <tt class="docutils literal"><span class="pre">char</span> <span class="pre">*</span></tt> and +<tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">char</span> <span class="pre">*</span></tt> then this annotation is assumed unless the <a class="reference" href="#out">Out</a> annotation +is specified.</p> +<p>For pointers to other types then this annotation must be explicitly specified +if required. The argument will be dereferenced to obtain the actual value.</p> +<p>Both <a class="reference" href="#in">In</a> and <a class="reference" href="#out">Out</a> may be specified for the same argument.</p> +</div> +<div class="section"> +<h3><a class="toc-backref" href="#id111" id="out" name="out">8.1.7 Out</a></h3> +<p>This boolean annotation is used to specify that the corresponding argument +(which should be a pointer type) is used by the function to return a value as +an element of a tuple.</p> +<p>For pointers to wrapped C structures or C++ class instances, <tt class="docutils literal"><span class="pre">char</span> <span class="pre">*</span></tt> and +<tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">char</span> <span class="pre">*</span></tt> then this annotation must be explicitly specified if +required.</p> +<p>For pointers to other types then this annotation is assumed unless the <a class="reference" href="#in">In</a> +annotation is specified.</p> +<p>Both <a class="reference" href="#in">In</a> and <a class="reference" href="#out">Out</a> may be specified for the same argument.</p> +</div> +<div class="section"> +<h3><a class="toc-backref" href="#id112" id="transfer" name="transfer">8.1.8 Transfer</a></h3> +<p>This boolean annotation is used to specify that ownership of the corresponding +argument (which should be a wrapped C structure or C++ class instance) is +transferred from Python to C++. In addition, if the argument is of a class +method, then it is associated with the class instance with regard to the +cyclic garbage collector.</p> +<p>See <a class="reference" href="#ownership-of-objects">Ownership of Objects</a> for more detail.</p> +</div> +<div class="section"> +<h3><a class="toc-backref" href="#id113" id="transferback" name="transferback">8.1.9 TransferBack</a></h3> +<p>This boolean annotation is used to specify that ownership of the corresponding +argument (which should be a wrapped C structure or C++ class instance) is +transferred back to Python from C++. In addition, any association of the +argument with regard to the cyclic garbage collector with another instance is +removed.</p> +<p>Note that this can also be used as a function annotation.</p> +<p>See <a class="reference" href="#ownership-of-objects">Ownership of Objects</a> for more detail.</p> +</div> +<div class="section"> +<h3><a class="toc-backref" href="#id114" id="transferthis" name="transferthis">8.1.10 TransferThis</a></h3> +<p>This boolean annotation is only used in C++ constructors or methods. In the +context of a constructor or factory method it specifies that ownership of the +instance being created is transferred from Python to C++ if the corresponding +argument (which should be a wrapped C structure or C++ class instance) is not +<tt class="docutils literal"><span class="pre">None</span></tt>. In addition, the newly created instance is associated with the +argument with regard to the cyclic garbage collector.</p> +<p>In the context of a non-factory method it specifies that ownership of <tt class="docutils literal"><span class="pre">this</span></tt> +is transferred from Python to C++ if the corresponding argument is not +<tt class="docutils literal"><span class="pre">None</span></tt>. If it is <tt class="docutils literal"><span class="pre">None</span></tt> then ownership is transferred to Python.</p> +<p>The annotation may be used more that once, in which case ownership is +transferred to last instance that is not <tt class="docutils literal"><span class="pre">None</span></tt>.</p> +<p>See <a class="reference" href="#ownership-of-objects">Ownership of Objects</a> for more detail.</p> +</div> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id115" id="class-annotations" name="class-annotations">8.2 Class Annotations</a></h2> +<div class="section"> +<h3><a class="toc-backref" href="#id116" id="abstract" name="abstract">8.2.1 Abstract</a></h3> +<p>This boolean annotation is used to specify that the class has additional pure +virtual methods that have not been specified and so it cannot be instantiated +or sub-classed from Python.</p> +</div> +<div class="section"> +<h3><a class="toc-backref" href="#id117" id="delaydtor" name="delaydtor">8.2.2 DelayDtor</a></h3> +<p>This boolean annotation is used to specify that the class's destructor should +not be called until the Python interpreter exits. It would normally only be +applied to singleton classes.</p> +<p>When the Python interpreter exits the order in which any wrapped instances are +garbage collected is unpredictable. However, the underlying C or C++ instances +may need to be destroyed in a certain order. If this annotation is specified +then when the wrapped instance is garbage collected the C or C++ instance is +not destroyed but instead added to a list of delayed instances. When the +interpreter exits then the function <tt class="docutils literal"><span class="pre">sipDelayedDtors</span></tt> is called with the +list of delayed instances. <tt class="docutils literal"><span class="pre">sipDelayedDtors</span></tt> can then choose to call (or +ignore) the destructors in any desired order.</p> +<p>The <tt class="docutils literal"><span class="pre">sipDelayedDtors</span></tt> function must be specified using the <a class="reference" href="#modulecode">%ModuleCode</a> +directive. It's signature is as follows:</p> +<pre class="literal-block"> +static void sipDelayedDtors(const sipDelayedDtor *dd_list); +</pre> +<p><tt class="docutils literal"><span class="pre">dd_list</span></tt> is the linked list of delayed instances. The following fields are +defined.</p> +<dl class="docutils"> +<dt>const char *dd_name</dt> +<dd>This is the name of the class excluding any package or module name.</dd> +<dt>void *dd_ptr</dt> +<dd>This is the address of the C or C++ instance to be destroyed. It's exact +type depends on the value of <tt class="docutils literal"><span class="pre">dd_isderived</span></tt>.</dd> +<dt>int dd_isderived</dt> +<dd>This is non-zero if the type of <tt class="docutils literal"><span class="pre">dd_ptr</span></tt> is actually the generated +derived class. This allows the correct destructor to be called. See +<a class="reference" href="#generated-derived-classes">Generated Derived Classes</a>.</dd> +<dt>sipDelayedDtor *dd_next</dt> +<dd>This is the address of the next entry in the list or zero if this is the +last one.</dd> +</dl> +<p>Note that the above applies only to C and C++ instances that are owned by +Python.</p> +</div> +<div class="section"> +<h3><a class="toc-backref" href="#id118" id="external" name="external">8.2.3 External</a></h3> +<p>This boolean annotation is used to specify that the class is defined in another +module. Declarations of external classes are private to the module in which +they appear.</p> +</div> +<div class="section"> +<h3><a class="toc-backref" href="#id119" id="nodefaultctors" name="nodefaultctors">8.2.4 NoDefaultCtors</a></h3> +<p>This boolean annotation is used to suppress the automatic generation of default +constructors for the class.</p> +</div> +<div class="section"> +<h3><a class="toc-backref" href="#id120" id="pyname" name="pyname">8.2.5 PyName</a></h3> +<p>This name annotation specifies an alternative name for the class being wrapped +which is used when it is referred to from Python. It is required when a class +name is the same as a Python keyword. It may also be used to avoid name +clashes with other objects (e.g. enums, exceptions, functions) that have the +same name in the same C++ scope.</p> +</div> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id121" id="enum-annotations" name="enum-annotations">8.3 Enum Annotations</a></h2> +<div class="section"> +<h3><a class="toc-backref" href="#id122" id="id17" name="id17">8.3.1 PyName</a></h3> +<p>This name annotation specifies an alternative name for the enum or enum member +being wrapped which is used when it is referred to from Python. It is required +when an enum or enum member name is the same as a Python keyword. It may also +be used to avoid name clashes with other objects (e.g. classes, exceptions, +functions) that have the same name in the same C++ scope.</p> +</div> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id123" id="exception-annotations" name="exception-annotations">8.4 Exception Annotations</a></h2> +<div class="section"> +<h3><a class="toc-backref" href="#id124" id="id18" name="id18">8.4.1 PyName</a></h3> +<p>This name annotation specifies an alternative name for the exception being +defined which is used when it is referred to from Python. It is required when +an exception name is the same as a Python keyword. It may also be used to +avoid name clashes with other objects (e.g. classes, enums, functions) that +have the same name.</p> +</div> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id125" id="function-annotations" name="function-annotations">8.5 Function Annotations</a></h2> +<div class="section"> +<h3><a class="toc-backref" href="#id126" id="autogen" name="autogen">8.5.1 AutoGen</a></h3> +<p>This optional name annotation is used with class methods to specify that the +method be automatically included in all sub-classes. The value is the name of +a feature (specified using the <a class="reference" href="#feature">%Feature</a> directive) which must be enabled +for the method to be generated.</p> +</div> +<div class="section"> +<h3><a class="toc-backref" href="#id127" id="default" name="default">8.5.2 Default</a></h3> +<p>This boolean annotation is only used with C++ constructors. Sometimes SIP +needs to create a class instance. By default it uses a constructor with no +compulsory arguments if one is specified. (SIP will automatically generate a +constructor with no arguments if no constructors are specified.) This +annotation is used to explicitly specify which constructor to use. Zero is +passed as the value of any arguments to the constructor.</p> +</div> +<div class="section"> +<h3><a class="toc-backref" href="#id128" id="factory" name="factory">8.5.3 Factory</a></h3> +<p>This boolean annotation specifies that the value returned by the function +(which should be a wrapped C structure or C++ class instance) is a newly +created instance and is owned by Python.</p> +<p>See <a class="reference" href="#ownership-of-objects">Ownership of Objects</a> for more detail.</p> +</div> +<div class="section"> +<h3><a class="toc-backref" href="#id129" id="holdgil" name="holdgil">8.5.4 HoldGIL</a></h3> +<p>This boolean annotation specifies that the Python Global Interpreter Lock (GIL) +is not released before the call to the underlying C or C++ function. See +<a class="reference" href="#the-python-global-interpreter-lock">The Python Global Interpreter Lock</a> and the <a class="reference" href="#releasegil">ReleaseGIL</a> annotation.</p> +</div> +<div class="section"> +<h3><a class="toc-backref" href="#id130" id="newthread" name="newthread">8.5.5 NewThread</a></h3> +<p>This boolean annotation specifies that the function will create a new thread.</p> +</div> +<div class="section"> +<h3><a class="toc-backref" href="#id131" id="noderived" name="noderived">8.5.6 NoDerived</a></h3> +<p>This boolean annotation is only used with C++ constructors. In many cases SIP +generates a derived class for each class being wrapped (see <a class="reference" href="#generated-derived-classes">Generated Derived +Classes</a>). This derived class contains constructors with the same C++ +signatures as the class being wrapped. Sometimes you may want to define a +Python constructor that has no corresponding C++ constructor. This annotation +is used to suppress the generation of the constructor in the derived class.</p> +</div> +<div class="section"> +<h3><a class="toc-backref" href="#id132" id="numeric" name="numeric">8.5.7 Numeric</a></h3> +<p>This boolean annotation specifies that the operator should be interpreted as a +numeric operator rather than a sequence operator. Python uses the <tt class="docutils literal"><span class="pre">+</span></tt> +operator for adding numbers and concatanating sequences, and the <tt class="docutils literal"><span class="pre">*</span></tt> operator +for multiplying numbers and repeating sequences. SIP tries to work out which +is meant by looking at other operators that have been defined for the type. +If it finds either <tt class="docutils literal"><span class="pre">-</span></tt>, <tt class="docutils literal"><span class="pre">-=</span></tt>, <tt class="docutils literal"><span class="pre">/</span></tt>, <tt class="docutils literal"><span class="pre">/=</span></tt>, <tt class="docutils literal"><span class="pre">%</span></tt> or <tt class="docutils literal"><span class="pre">%=</span></tt> defined then +it assumes that <tt class="docutils literal"><span class="pre">+</span></tt>, <tt class="docutils literal"><span class="pre">+=</span></tt>, <tt class="docutils literal"><span class="pre">*</span></tt> and <tt class="docutils literal"><span class="pre">*=</span></tt> should be numeric operators. +Otherwise, if it finds either <tt class="docutils literal"><span class="pre">[]</span></tt>, <tt class="docutils literal"><span class="pre">__getitem__()</span></tt>, <tt class="docutils literal"><span class="pre">__setitem__()</span></tt> or +<tt class="docutils literal"><span class="pre">__delitem__()</span></tt> defined then it assumes that they should be sequence +operators. This annotation is used to force SIP to treat the operator as +numeric.</p> +</div> +<div class="section"> +<h3><a class="toc-backref" href="#id133" id="posthook" name="posthook">8.5.8 PostHook</a></h3> +<p>This name annotation is used to specify the name of a Python builtin that is +called immediately after the call to the underlying C or C++ function or any +handwritten code. The builtin is not called if an error occurred. It is +primarily used to integrate with debuggers.</p> +</div> +<div class="section"> +<h3><a class="toc-backref" href="#id134" id="prehook" name="prehook">8.5.9 PreHook</a></h3> +<p>This name annotation is used to specify the name of a Python builtin that is +called immediately after the function's arguments have been successfully +parsed and before the call to the underlying C or C++ function or any +handwritten code. It is primarily used to integrate with debuggers.</p> +</div> +<div class="section"> +<h3><a class="toc-backref" href="#id135" id="id19" name="id19">8.5.10 PyName</a></h3> +<p>This name annotation specifies an alternative name for the function being +wrapped which is used when it is referred to from Python. It is required when +a function or method name is the same as a Python keyword. It may also be used +to avoid name clashes with other objects (e.g. classes, enums, exceptions) that +have the same name in the same C++ scope.</p> +</div> +<div class="section"> +<h3><a class="toc-backref" href="#id136" id="releasegil" name="releasegil">8.5.11 ReleaseGIL</a></h3> +<p>This boolean annotation specifies that the Python Global Interpreter Lock (GIL) +is released before the call to the underlying C or C++ function and reacquired +afterwards. It should be used for functions that might block or take a +significant amount of time to execute. See <a class="reference" href="#the-python-global-interpreter-lock">The Python Global Interpreter +Lock</a> and the <a class="reference" href="#holdgil">HoldGIL</a> annotation.</p> +</div> +<div class="section"> +<h3><a class="toc-backref" href="#id137" id="id20" name="id20">8.5.12 TransferBack</a></h3> +<p>This boolean annotation specifies that ownership of the value returned by the +function (which should be a wrapped C structure or C++ class instance) is +transferred back to Python from C++. Normally returned values (unless they are +new references to already wrapped values) are owned by C++. In addition, any +association of the returned value with regard to the cyclic garbage collector +with another instance is removed.</p> +<p>Note that this can also be used as an argument annotation.</p> +<p>See <a class="reference" href="#ownership-of-objects">Ownership of Objects</a> for more detail.</p> +</div> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id138" id="license-annotations" name="license-annotations">8.6 License Annotations</a></h2> +<div class="section"> +<h3><a class="toc-backref" href="#id139" id="licensee" name="licensee">8.6.1 Licensee</a></h3> +<p>This optional string annotation specifies the license's licensee. No +restrictions are placed on the contents of the string.</p> +<p>See the <a class="reference" href="#id14">%License</a> directive.</p> +</div> +<div class="section"> +<h3><a class="toc-backref" href="#id140" id="signature" name="signature">8.6.2 Signature</a></h3> +<p>This optional string annotation specifies the license's signature. No +restrictions are placed on the contents of the string.</p> +<p>See the <a class="reference" href="#id14">%License</a> directive.</p> +</div> +<div class="section"> +<h3><a class="toc-backref" href="#id141" id="timestamp" name="timestamp">8.6.3 Timestamp</a></h3> +<p>This optional string annotation specifies the license's timestamp. No +restrictions are placed on the contents of the string.</p> +<p>See the <a class="reference" href="#id14">%License</a> directive.</p> +</div> +<div class="section"> +<h3><a class="toc-backref" href="#id142" id="type" name="type">8.6.4 Type</a></h3> +<p>This string annotation specifies the license's type. No restrictions are +placed on the contents of the string.</p> +<p>See the <a class="reference" href="#id14">%License</a> directive.</p> +</div> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id143" id="variable-annotations" name="variable-annotations">8.7 Variable Annotations</a></h2> +<div class="section"> +<h3><a class="toc-backref" href="#id144" id="id21" name="id21">8.7.1 PyName</a></h3> +<p>This name annotation specifies an alternative name for the variable being +wrapped which is used when it is referred to from Python. It is required when +a variable name is the same as a Python keyword. It may also be used to avoid +name clashes with other objects (e.g. classes, functions) that have the same +name in the same C++ scope.</p> +</div> +</div> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id145" id="sip-api-for-handwritten-code" name="sip-api-for-handwritten-code">9 SIP API for Handwritten Code</a></h1> +<p>In this section we describe the API that can be used by handwritten code in +specification files.</p> +<div class="section"> +<h2><a class="toc-backref" href="#id146" id="sip-api-major-nr" name="sip-api-major-nr">9.1 SIP_API_MAJOR_NR</a></h2> +<p>This is a C preprocessor symbol that defines the major number of the SIP API. +Its value is a number. There is no direct relationship between this and the +SIP version number.</p> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id147" id="sip-api-minor-nr" name="sip-api-minor-nr">9.2 SIP_API_MINOR_NR</a></h2> +<p>This is a C preprocessor symbol that defines the minor number of the SIP API. +Its value is a number. There is no direct relationship between this and the +SIP version number.</p> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id148" id="sip-block-threads" name="sip-block-threads">9.3 SIP_BLOCK_THREADS</a></h2> +<p>This is a C preprocessor macro that will make sure the Python Global +Interpreter Lock (GIL) is acquired. Python API calls must only be made when +the GIL has been acquired. There must be a corresponding +<a class="reference" href="#sip-unblock-threads">SIP_UNBLOCK_THREADS</a> at the same lexical scope.</p> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id149" id="sip-ssize-t" name="sip-ssize-t">9.4 SIP_SSIZE_T</a></h2> +<p>This is a C preprocessor macro that is defined as <tt class="docutils literal"><span class="pre">Py_ssize_t</span></tt> for Python +v2.5 and later, and as <tt class="docutils literal"><span class="pre">int</span></tt> for earlier versions of Python. It makes it +easier to write PEP 353 compliant handwritten code.</p> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id150" id="sip-unblock-threads" name="sip-unblock-threads">9.5 SIP_UNBLOCK_THREADS</a></h2> +<p>This is a C preprocessor macro that will restore the Python Global Interpreter +Lock (GIL) to the state it was prior to the corresponding <a class="reference" href="#sip-block-threads">SIP_BLOCK_THREADS</a>.</p> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id151" id="sip-version" name="sip-version">9.6 SIP_VERSION</a></h2> +<p>This is a C preprocessor symbol that defines the SIP version number +represented as a 3 part hexadecimal number (e.g. v4.0.0 is represented as +<tt class="docutils literal"><span class="pre">0x040000</span></tt>).</p> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id152" id="sip-version-str" name="sip-version-str">9.7 SIP_VERSION_STR</a></h2> +<p>This is a C preprocessor symbol that defines the SIP version number +represented as a string. For development snapshots it will start with +<tt class="docutils literal"><span class="pre">snapshot-</span></tt>.</p> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id153" id="sipbadcatcherresult" name="sipbadcatcherresult">9.8 sipBadCatcherResult()</a></h2> +<dl class="docutils"> +<dt>void sipBadCatcherResult(PyObject *method)</dt> +<dd>This raises a Python exception when the result of a Python reimplementation +of a C++ method doesn't have the expected type. It is normally called by +handwritten code specified with the <a class="reference" href="#virtualcatchercode">%VirtualCatcherCode</a> directive. +<em>method</em> is the Python method and would normally be the supplied +<tt class="docutils literal"><span class="pre">sipMethod</span></tt>.</dd> +</dl> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id154" id="sipbadlengthforslice" name="sipbadlengthforslice">9.9 sipBadLengthForSlice()</a></h2> +<dl class="docutils"> +<dt>void sipBadLengthForSlice(SIP_SSIZE_T seqlen, SIP_SSIZE_T slicelen)</dt> +<dd>This raises a Python exception when the length of a slice object is +inappropriate for a sequence-like object. It is normally called by +handwritten code specified for <tt class="docutils literal"><span class="pre">__setitem__()</span></tt> methods. <em>seqlen</em> is the +length of the sequence. <em>slicelen</em> is the length of the slice. With +versions of Python prior to v2.5 the arguments have type <tt class="docutils literal"><span class="pre">int</span></tt>.</dd> +</dl> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id155" id="sipbuildresult" name="sipbuildresult">9.10 sipBuildResult()</a></h2> +<dl class="docutils"> +<dt>PyObject *sipBuildResult(int *iserr, const char *format, ...)</dt> +<dd><p class="first">This creates a Python object based on a format string and associated +values in a similar way to the Python <tt class="docutils literal"><span class="pre">Py_BuildValue()</span></tt> function. If +there was an error then <tt class="docutils literal"><span class="pre">NULL</span></tt> is returned and a Python exception is +raised. If <em>iserr</em> is not <tt class="docutils literal"><span class="pre">NULL</span></tt> then the location it points to is set +to a non-zero value. <em>format</em> is the string of format characters.</p> +<p>If <em>format</em> begins and ends with parentheses then a tuple of objects is +created. If <em>format</em> contains more than one format character then +parentheses must be specified.</p> +<p>In the following description the first letter is the format character, the +entry in parentheses is the Python object type that the format character +will create, and the entry in brackets are the types of the C/C++ values +to be passed.</p> +<dl class="last docutils"> +<dt><tt class="docutils literal"><span class="pre">a</span></tt> (string) [char *, int]</dt> +<dd>Convert a C/C++ character array and its length to a Python string. If +the array is <tt class="docutils literal"><span class="pre">NULL</span></tt> then the length is ignored and the result is +<tt class="docutils literal"><span class="pre">Py_None</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">b</span></tt> (boolean) [int]</dt> +<dd>Convert a C/C++ <tt class="docutils literal"><span class="pre">int</span></tt> to a Python boolean.</dd> +<dt><tt class="docutils literal"><span class="pre">c</span></tt> (string) [char]</dt> +<dd>Convert a C/C++ <tt class="docutils literal"><span class="pre">char</span></tt> to a Python string.</dd> +<dt><tt class="docutils literal"><span class="pre">d</span></tt> (float) [double]</dt> +<dd>Convert a C/C++ <tt class="docutils literal"><span class="pre">double</span></tt> to a Python floating point number.</dd> +<dt><tt class="docutils literal"><span class="pre">e</span></tt> (integer) [enum]</dt> +<dd>Convert an anonymous C/C++ <tt class="docutils literal"><span class="pre">enum</span></tt> to a Python integer.</dd> +<dt><tt class="docutils literal"><span class="pre">f</span></tt> (float) [float]</dt> +<dd>Convert a C/C++ <tt class="docutils literal"><span class="pre">float</span></tt> to a Python floating point number.</dd> +<dt><tt class="docutils literal"><span class="pre">h</span></tt> (integer) [short]</dt> +<dd>Convert a C/C++ <tt class="docutils literal"><span class="pre">short</span></tt> to a Python integer.</dd> +<dt><tt class="docutils literal"><span class="pre">i</span></tt> (integer) [int]</dt> +<dd>Convert a C/C++ <tt class="docutils literal"><span class="pre">int</span></tt> to a Python integer.</dd> +<dt><tt class="docutils literal"><span class="pre">l</span></tt> (long) [long]</dt> +<dd>Convert a C/C++ <tt class="docutils literal"><span class="pre">long</span></tt> to a Python integer.</dd> +<dt><tt class="docutils literal"><span class="pre">m</span></tt> (long) [unsigned long]</dt> +<dd>Convert a C/C++ <tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">long</span></tt> to a Python long.</dd> +<dt><tt class="docutils literal"><span class="pre">n</span></tt> (long) [long long]</dt> +<dd>Convert a C/C++ <tt class="docutils literal"><span class="pre">long</span> <span class="pre">long</span></tt> to a Python long.</dd> +<dt><tt class="docutils literal"><span class="pre">o</span></tt> (long) [unsigned long long]</dt> +<dd>Convert a C/C++ <tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">long</span> <span class="pre">long</span></tt> to a Python long.</dd> +<dt><tt class="docutils literal"><span class="pre">s</span></tt> (string) [char *]</dt> +<dd>Convert a C/C++ <tt class="docutils literal"><span class="pre">'\0'</span></tt> terminated string to a Python string. If the +string pointer is <tt class="docutils literal"><span class="pre">NULL</span></tt> then the result is <tt class="docutils literal"><span class="pre">Py_None</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">t</span></tt> (long) [unsigned short]</dt> +<dd>Convert a C/C++ <tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">short</span></tt> to a Python long.</dd> +<dt><tt class="docutils literal"><span class="pre">u</span></tt> (long) [unsigned int]</dt> +<dd>Convert a C/C++ <tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">int</span></tt> to a Python long.</dd> +<dt><tt class="docutils literal"><span class="pre">w</span></tt> (unicode) [wchar_t]</dt> +<dd>Convert a C/C++ wide character to a Python unicode object.</dd> +<dt><tt class="docutils literal"><span class="pre">x</span></tt> (unicode) [wchar_t *]</dt> +<dd>Convert a C/C++ <tt class="docutils literal"><span class="pre">L'\0'</span></tt> terminated wide character string to a Python +unicode object. If the string pointer is <tt class="docutils literal"><span class="pre">NULL</span></tt> then the result is +<tt class="docutils literal"><span class="pre">Py_None</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">A</span></tt> (unicode) [wchar_t *, int]</dt> +<dd>Convert a C/C++ wide character array and its length to a Python unicode +object. If the array is <tt class="docutils literal"><span class="pre">NULL</span></tt> then the length is ignored and the +result is <tt class="docutils literal"><span class="pre">Py_None</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">B</span></tt> (wrapped instance) [<em>type</em> *, sipWrapperType *, PyObject *]</dt> +<dd>Convert a new C structure or a new C++ class instance to a Python class +instance object. Ownership of the structure or instance is determined +by the <tt class="docutils literal"><span class="pre">PyObject</span> <span class="pre">*</span></tt> argument. If it is <tt class="docutils literal"><span class="pre">NULL</span></tt> and the instance has +already been wrapped then the ownership is unchanged. If it is +<tt class="docutils literal"><span class="pre">NULL</span></tt> or <tt class="docutils literal"><span class="pre">Py_None</span></tt> then ownership will be with Python. Otherwise +ownership will be with C/C++ and the instance associated with the +<tt class="docutils literal"><span class="pre">PyObject</span> <span class="pre">*</span></tt> argument. The Python class is influenced by any +applicable <a class="reference" href="#converttosubclasscode">%ConvertToSubClassCode</a> code.</dd> +<dt><tt class="docutils literal"><span class="pre">C</span></tt> (wrapped instance) [<em>type</em> *, sipWrapperType *, PyObject *]</dt> +<dd>Convert a C structure or a C++ class instance to a Python class +instance object. If the structure or class instance has already been +wrapped then the result is a new reference to the existing class +instance object. Ownership of the structure or instance is determined +by the <tt class="docutils literal"><span class="pre">PyObject</span> <span class="pre">*</span></tt> argument. If it is <tt class="docutils literal"><span class="pre">NULL</span></tt> and the instance has +already been wrapped then the ownership is unchanged. If it is +<tt class="docutils literal"><span class="pre">NULL</span></tt> and the instance is newly wrapped then ownership will be with +C/C++. If it is <tt class="docutils literal"><span class="pre">Py_None</span></tt> then ownership is transferred to Python +via a call to <a class="reference" href="#siptransferback">sipTransferBack()</a>. Otherwise ownership is transferred +to C/C++ and the instance associated with the <tt class="docutils literal"><span class="pre">PyObject</span> <span class="pre">*</span></tt> argument +via a call to <a class="reference" href="#siptransferto">sipTransferTo()</a>. The Python class is influenced by +any applicable <a class="reference" href="#converttosubclasscode">%ConvertToSubClassCode</a> code.</dd> +<dt><tt class="docutils literal"><span class="pre">D</span></tt> (object) [<em>type</em> *, const sipMappedType *, PyObject *]</dt> +<dd>Convert a C structure or a C++ class instance wrapped as a mapped type +to a Python object. Ownership of the structure or instance is +determined by the <tt class="docutils literal"><span class="pre">PyObject</span> <span class="pre">*</span></tt> argument. If it is <tt class="docutils literal"><span class="pre">NULL</span></tt> then the +ownership is unchanged. If it is <tt class="docutils literal"><span class="pre">Py_None</span></tt> then ownership is +transferred to Python via a call to <a class="reference" href="#siptransferback">sipTransferBack()</a>. Otherwise +ownership is transferred to C/C++ and the instance associated with the +<tt class="docutils literal"><span class="pre">PyObject</span> <span class="pre">*</span></tt> argument via a call to <a class="reference" href="#siptransferto">sipTransferTo()</a>.</dd> +<dt><tt class="docutils literal"><span class="pre">E</span></tt> (wrapped enum) [enum, PyTypeObject *]</dt> +<dd>Convert a named C/C++ <tt class="docutils literal"><span class="pre">enum</span></tt> to an instance of the corresponding +Python named enum type.</dd> +<dt><tt class="docutils literal"><span class="pre">M</span></tt> (wrapped instance) [<em>type</em> *, sipWrapperType *]</dt> +<dd>Convert a C structure or a C++ class instance to a Python class +instance object. If the structure or class instance has already been +wrapped then the result is a new reference to the existing class +instance object. If the instance has already been wrapped then the +ownership is unchanged. If the instance is newly wrapped then +ownership will be with C/C++. The Python class is influenced by any +applicable <a class="reference" href="#converttosubclasscode">%ConvertToSubClassCode</a> code. This is deprecated from +SIP v4.4.</dd> +<dt><tt class="docutils literal"><span class="pre">N</span></tt> (wrapped instance) [<em>type</em> *, sipWrapperType *]</dt> +<dd>Convert a C structure or a C++ class instance to a Python class +instance object. This should not be used if the structure or class +instance might already have been wrapped. Ownership of the structure +or instance will be with Python. The Python class is influenced by +any applicable <a class="reference" href="#converttosubclasscode">%ConvertToSubClassCode</a> code. This is deprecated +from SIP v4.4.</dd> +<dt><tt class="docutils literal"><span class="pre">O</span></tt> (wrapped instance) [<em>type</em> *, sipWrapperType *]</dt> +<dd>Convert a C structure or a C++ class instance to a Python class +instance object. If the structure or class instance has already been +wrapped then the result is a new reference to the existing class +instance object. Ownership of the structure or instance will be with +C/C++. This is deprecated from SIP v4.4.</dd> +<dt><tt class="docutils literal"><span class="pre">P</span></tt> (wrapped instance) [<em>type</em> *, sipWrapperType *]</dt> +<dd>Convert a C structure or a C++ class instance to a Python class +instance object. This should not be used if the structure or class +instance might already have been wrapped. Ownership of the structure +or instance will be with Python. This is deprecated from SIP v4.4.</dd> +<dt><tt class="docutils literal"><span class="pre">R</span></tt> (object) [PyObject *]</dt> +<dd>The result is value passed without any conversions. The reference +count is unaffected, i.e. a reference is taken.</dd> +<dt><tt class="docutils literal"><span class="pre">S</span></tt> (object) [PyObject *]</dt> +<dd>The result is value passed without any conversions. The reference +count is incremented.</dd> +<dt><tt class="docutils literal"><span class="pre">T</span></tt> (object) [void *, PyObject *(*)(void *cppptr)]</dt> +<dd>Convert a C structure or a C++ class instance to a Python object using +a convertor function. See <a class="reference" href="#generated-type-convertors">Generated Type Convertors</a>. This is +deprecated from SIP v4.4.</dd> +<dt><tt class="docutils literal"><span class="pre">V</span></tt> (sip.voidptr) [void *]</dt> +<dd>Convert a C/C++ <tt class="docutils literal"><span class="pre">void</span> <span class="pre">*</span></tt> Python <tt class="docutils literal"><span class="pre">sip.voidptr</span></tt> object.</dd> +</dl> +</dd> +</dl> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id156" id="sipcallmethod" name="sipcallmethod">9.11 sipCallMethod()</a></h2> +<dl class="docutils"> +<dt>PyObject *sipCallMethod(int *iserr, PyObject *method, const char *format, ...)</dt> +<dd><p class="first">This calls a Python method passing a tuple of arguments based on a format +string and associated values in a similar way to the Python +<tt class="docutils literal"><span class="pre">PyObject_CallObject()</span></tt> function. If there was an error then <tt class="docutils literal"><span class="pre">NULL</span></tt> is +returned and a Python exception is raised. If <em>iserr</em> is not <tt class="docutils literal"><span class="pre">NULL</span></tt> +then the location it points to is set to a non-zero value. <em>method</em> is the +Python bound method to call. <em>format</em> is the string of format characters +(see <a class="reference" href="#sipbuildresult">sipBuildResult()</a>).</p> +<p class="last">This is normally called by handwritten code specified with the +<a class="reference" href="#virtualcatchercode">%VirtualCatcherCode</a> directive with <em>method</em> being the supplied +<tt class="docutils literal"><span class="pre">sipMethod</span></tt>.</p> +</dd> +</dl> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id157" id="sipcanconverttoinstance" name="sipcanconverttoinstance">9.12 sipCanConvertToInstance()</a></h2> +<dl class="docutils"> +<dt>int sipCanConvertToInstance(PyObject *obj, sipWrapperType *type, int flags)</dt> +<dd><p class="first">This returns a non-zero value if a Python object can be converted to an +instance of a C structure or C++ class. <em>obj</em> is the Python object. +<em>type</em> is the generated type corresponding to the C/C++ type being checked. +<em>flags</em> is any combination of the following values used to fine tune the +check.</p> +<blockquote class="last"> +<ul class="simple"> +<li><tt class="docutils literal"><span class="pre">SIP_NOT_NONE</span></tt> causes the check to fail if <em>obj</em> is <tt class="docutils literal"><span class="pre">None</span></tt>.</li> +<li><tt class="docutils literal"><span class="pre">SIP_NO_CONVERTORS</span></tt> suppresses the use of of any +<a class="reference" href="#converttotypecode">%ConvertToTypeCode</a> for <em>type</em>.</li> +</ul> +</blockquote> +</dd> +</dl> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id158" id="sipcanconverttomappedtype" name="sipcanconverttomappedtype">9.13 sipCanConvertToMappedType()</a></h2> +<dl class="docutils"> +<dt>int sipCanConvertToMappedType(PyObject *obj, const sipMappedType *mt, int flags)</dt> +<dd><p class="first">This returns a non-zero value if a Python object can be converted to an +instance of a C structure or C++ class which has been implemented as a +mapped type. <em>obj</em> is the Python object. <em>mt</em> is an opaque structure +returned by <a class="reference" href="#sipfindmappedtype">sipFindMappedType()</a>. <em>flags</em> is any combination of the +following values used to fine tune the check.</p> +<blockquote class="last"> +<ul class="simple"> +<li><tt class="docutils literal"><span class="pre">SIP_NOT_NONE</span></tt> causes the check to fail if <em>obj</em> is <tt class="docutils literal"><span class="pre">None</span></tt>.</li> +</ul> +</blockquote> +</dd> +</dl> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id159" id="sipclassname" name="sipclassname">9.14 sipClassName()</a></h2> +<dl class="docutils"> +<dt>PyObject *sipClassName(PyObject *obj)</dt> +<dd>This returns the class name of a wrapped instance as a Python string. It +comes with a reference.</dd> +</dl> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id160" id="sipconnectrx" name="sipconnectrx">9.15 sipConnectRx()</a></h2> +<dl class="docutils"> +<dt>PyObject *sipConnectRx(PyObject *sender, const char *signal, PyObject *receiver, const char *slot, int type)</dt> +<dd>This connects a signal to a signal or slot and returns <tt class="docutils literal"><span class="pre">Py_True</span></tt> if the +signal was connected or <tt class="docutils literal"><span class="pre">Py_False</span></tt> if not. If there was some other +error then a Python exception is raised and <tt class="docutils literal"><span class="pre">NULL</span></tt> is returned. <em>sender</em> +is the wrapped <tt class="docutils literal"><span class="pre">QObject</span></tt> derived instance that emits the signal. +<em>signal</em> is the typed name of the signal. <em>receiver</em> is the wrapped +<tt class="docutils literal"><span class="pre">QObject</span></tt> derived instance or Python callable that the signal is +connected to. <em>slot</em> is the typed name of the slot, or <tt class="docutils literal"><span class="pre">NULL</span></tt> if +<em>receiver</em> is a Python callable. <em>type</em> is the type of connection and is +cast from Qt::ConnectionType. It is normally only used by PyQt to +implement <tt class="docutils literal"><span class="pre">QObject.connect()</span></tt>.</dd> +</dl> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id161" id="sipconvertfrominstance" name="sipconvertfrominstance">9.16 sipConvertFromInstance()</a></h2> +<dl class="docutils"> +<dt>PyObject *sipConvertFromInstance(void *cpp, sipWrapperType *type, PyObject *transferObj)</dt> +<dd>Convert a C structure or a C++ class instance to a Python class instance +object. <em>cpp</em> is the C/C++ instance. If the instance has already been +wrapped then the result is a new reference to the existing instance object. +<em>type</em> is the generated type corresponding to the C/C++ type. +<em>transferObj</em> controls the ownership of the returned value. If the +structure or class instance has already been wrapped then the result is a +new reference to the existing class instance object. If it is <tt class="docutils literal"><span class="pre">NULL</span></tt> and +the instance has already been wrapped then the ownership is unchanged. If +it is <tt class="docutils literal"><span class="pre">NULL</span></tt> and the instance is newly wrapped then ownership will be +with C/C++. If it is <tt class="docutils literal"><span class="pre">Py_None</span></tt> then ownership is transferred to Python +via a call to <a class="reference" href="#siptransferback">sipTransferBack()</a>. Otherwise ownership is transferred to +C/C++ and the instance associated with <em>transferObj</em> via a call to +<a class="reference" href="#siptransferto">sipTransferTo()</a>. The Python class is influenced by any applicable +<a class="reference" href="#converttosubclasscode">%ConvertToSubClassCode</a> code.</dd> +</dl> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id162" id="sipconvertfrommappedtype" name="sipconvertfrommappedtype">9.17 sipConvertFromMappedType()</a></h2> +<dl class="docutils"> +<dt>PyObject *sipConvertFromMappedType(void *cpp, const sipMappedType *mt, PyObject *transferObj)</dt> +<dd>Convert a C structure or a C++ class instance wrapped as a mapped type to a +Python object. <em>cpp</em> is the C/C++ instance. <em>mt</em> is the opaque structure +returned by <a class="reference" href="#sipfindmappedtype">sipFindMappedType()</a>. <em>transferObj</em> controls any ownership +changes to <em>obj</em>. If it is <tt class="docutils literal"><span class="pre">NULL</span></tt> then the ownership is unchanged. If +it is <tt class="docutils literal"><span class="pre">Py_None</span></tt> then ownership is transferred to Python via a call to +<a class="reference" href="#siptransferback">sipTransferBack()</a>. Otherwise ownership is transferred to C/C++ and the +instance associated with the <tt class="docutils literal"><span class="pre">PyObject</span> <span class="pre">*</span></tt> argument via a call to +<a class="reference" href="#siptransferto">sipTransferTo()</a>.</dd> +</dl> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id163" id="sipconvertfromnamedenum" name="sipconvertfromnamedenum">9.18 sipConvertFromNamedEnum()</a></h2> +<dl class="docutils"> +<dt>PyObject *sipConvertFromNamedEnum(int eval, PyTypeObject *type)</dt> +<dd>Convert a named C/C++ <tt class="docutils literal"><span class="pre">enum</span></tt> to an instance of the corresponding Python +named enum type. <em>eval</em> is the enumerated value to convert. <em>type</em> is the +generated Python type object (see <a class="reference" href="#generated-named-enum-type-objects">Generated Named Enum Type Objects</a>).</dd> +</dl> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id164" id="sipconvertfromnewinstance" name="sipconvertfromnewinstance">9.19 sipConvertFromNewInstance()</a></h2> +<dl class="docutils"> +<dt>PyObject *sipConvertFromNewInstance(void *cpp, sipWrapperType *type, PyObject *transferObj)</dt> +<dd>Convert a new C structure or a new C++ class instance to a Python class +instance object. <em>cpp</em> is the C/C++ instance. <em>type</em> is the generated +type corresponding to the C/C++ type. <em>transferObj</em> controls the ownership +of the returned value. If it is <tt class="docutils literal"><span class="pre">NULL</span></tt> or <tt class="docutils literal"><span class="pre">Py_None</span></tt> then ownership +will be with Python. Otherwise ownership will be with C/C++ and the +instance associated with <em>transferObj</em>. The Python class is influenced by +any applicable <a class="reference" href="#converttosubclasscode">%ConvertToSubClassCode</a> code.</dd> +</dl> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id165" id="sipconvertfromsequenceindex" name="sipconvertfromsequenceindex">9.20 sipConvertFromSequenceIndex()</a></h2> +<dl class="docutils"> +<dt>SIP_SSIZE_T sipConvertFromSequenceIndex(SIP_SSIZE_T idx, SIP_SSIZE_T len)</dt> +<dd>This converts a Python sequence index (i.e. where a negative value refers +to the offset from the end of the sequence) to a C/C++ array index. If the +index was out of range then a negative value is returned and a Python +exception raised. With versions of Python prior to v2.5 the result and the +arguments have type <tt class="docutils literal"><span class="pre">int</span></tt>.</dd> +</dl> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id166" id="sipconvertfromsliceobject" name="sipconvertfromsliceobject">9.21 sipConvertFromSliceObject()</a></h2> +<dl class="docutils"> +<dt>int sipConvertFromSliceObject(PyObject *slice, SIP_SSIZE_T length, SIP_SSIZE_T *start, SIP_SSIZE_T *stop, SIP_SSIZE_T *step, SIP_SSIZE_T *slicelength)</dt> +<dd>This is a thin wrapper around the Python <tt class="docutils literal"><span class="pre">PySlice_GetIndicesEx()</span></tt> +function provided to make it easier to write handwritten code that is +compatible with SIP v3.x and versions of Python earlier that v2.3.</dd> +</dl> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id167" id="sipconverttocpp" name="sipconverttocpp">9.22 sipConvertToCpp()</a></h2> +<dl class="docutils"> +<dt>void *sipConvertToCpp(PyObject *obj, sipWrapperType *type, int *iserr)</dt> +<dd><p class="first">This function is deprecated from SIP v4.4. It is equivalent to:</p> +<pre class="last literal-block"> +sipConvertToInstance(obj, type, NULL, SIP_NO_CONVERTORS, NULL, iserr); +</pre> +</dd> +</dl> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id168" id="sipconverttoinstance" name="sipconverttoinstance">9.23 sipConvertToInstance()</a></h2> +<dl class="docutils"> +<dt>void *sipConvertToInstance(PyObject *obj, sipWrapperType *type, PyObject *transferObj, int flags, int *state, int *iserr)</dt> +<dd><p class="first">This converts a Python object to an instance of a C structure or C++ class +assuming that a previous call to <a class="reference" href="#sipcanconverttoinstance">sipCanConvertToInstance()</a> has been +successful. <em>obj</em> is the Python object. <em>type</em> is the generated type +corresponding to the C/C++ type returned. It may be any class in the +object's class hierarchy. <em>transferObj</em> controls any ownership changes to +<em>obj</em>. If it is <tt class="docutils literal"><span class="pre">NULL</span></tt> then the ownership is unchanged. If it is +<tt class="docutils literal"><span class="pre">Py_None</span></tt> then ownership is transferred to Python via a call to +<a class="reference" href="#siptransferback">sipTransferBack()</a>. Otherwise ownership is transferred to C/C++ and +<em>obj</em> associated with <em>transferObj</em> via a call to <a class="reference" href="#siptransferto">sipTransferTo()</a>. +<em>flags</em> is any combination of the following values used to fine tune the +check.</p> +<blockquote> +<ul class="simple"> +<li><tt class="docutils literal"><span class="pre">SIP_NOT_NONE</span></tt> causes the check to fail if <em>obj</em> is <tt class="docutils literal"><span class="pre">None</span></tt>.</li> +<li><tt class="docutils literal"><span class="pre">SIP_NO_CONVERTORS</span></tt> suppresses the use of of any +<a class="reference" href="#converttotypecode">%ConvertToTypeCode</a> for <em>type</em>.</li> +</ul> +</blockquote> +<p class="last">If <em>state</em> is not <tt class="docutils literal"><span class="pre">NULL</span></tt> then the location it points to is set to +describe the state of the returned C/C++ instance and is the value returned +by any <a class="reference" href="#converttotypecode">%ConvertToTypeCode</a>. The calling code must then release the value +at some point to prevent a memory leak by calling <a class="reference" href="#sipreleaseinstance">sipReleaseInstance()</a>. +If there is an error then the location <em>iserr</em> points to is set to a +non-zero value. If it was initially a non-zero value then the conversion +isn't attempted in the first place. (This allows several calls to be made +that share the same error flag so that it only needs to be tested once +rather than after each call.)</p> +</dd> +</dl> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id169" id="sipconverttomappedtype" name="sipconverttomappedtype">9.24 sipConvertToMappedType()</a></h2> +<dl class="docutils"> +<dt>void *sipConvertToMappedType(PyObject *obj, const sipMappedType *mt, PyObject *transferObj, int flags, int *state, int *iserr)</dt> +<dd><p class="first">This converts a Python object to an instance of a C structure or C++ +class that is implemented as a mapped type assuming that a previous call to +<a class="reference" href="#sipcanconverttomappedtype">sipCanConvertToMappedType()</a> has been successful. <em>obj</em> is the Python +object. <em>mt</em> is the opaque structure returned by <a class="reference" href="#sipfindmappedtype">sipFindMappedType()</a>. +<em>transferObj</em> controls any ownership changes to <em>obj</em>. If it is <tt class="docutils literal"><span class="pre">NULL</span></tt> +then the ownership is unchanged. If it is <tt class="docutils literal"><span class="pre">Py_None</span></tt> then ownership is +transferred to Python via a call to <a class="reference" href="#siptransferback">sipTransferBack()</a>. Otherwise +ownership is transferred to C/C++ and <em>obj</em> associated with <em>transferObj</em> +via a call to <a class="reference" href="#siptransferto">sipTransferTo()</a>. <em>flags</em> is any combination of the +following values used to fine tune the check.</p> +<blockquote> +<ul class="simple"> +<li><tt class="docutils literal"><span class="pre">SIP_NOT_NONE</span></tt> causes the check to fail if <em>obj</em> is <tt class="docutils literal"><span class="pre">None</span></tt>.</li> +</ul> +</blockquote> +<p class="last">If <em>state</em> is not <tt class="docutils literal"><span class="pre">NULL</span></tt> then the location it points to is set to +describe the state of the returned C/C++ instance and is the value returned +by any <a class="reference" href="#converttotypecode">%ConvertToTypeCode</a>. The calling code must then release the value +at some point to prevent a memory leak by calling +<a class="reference" href="#sipreleasemappedtype">sipReleaseMappedType()</a>. If there is an error then the location <em>iserr</em> +points to is set to a non-zero value. If it was initially a non-zero value +then the conversion isn't attempted in the first place. (This allows +several calls to be made that share the same error flag so that it only +needs to be tested once rather than after each call.)</p> +</dd> +</dl> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id170" id="sipdisconnectrx" name="sipdisconnectrx">9.25 sipDisconnectRx()</a></h2> +<dl class="docutils"> +<dt>PyObject *sipDisconnectRx(PyObject *sender, const char *signal, PyObject *receiver, const char *slot)</dt> +<dd>This disconnects a signal from a signal or slot and returns <tt class="docutils literal"><span class="pre">Py_True</span></tt> if +the signal was disconnected or <tt class="docutils literal"><span class="pre">Py_False</span></tt> if not. If there was some +other error then a Python exception is raised and <tt class="docutils literal"><span class="pre">NULL</span></tt> is returned. +<em>sender</em> is the wrapped <tt class="docutils literal"><span class="pre">QObject</span></tt> derived instance that emits the signal. +<em>signal</em> is the typed name of the signal. <em>receiver</em> is the wrapped +<tt class="docutils literal"><span class="pre">QObject</span></tt> derived instance or Python callable that the signal is +connected to. <em>slot</em> is the typed name of the slot, or <tt class="docutils literal"><span class="pre">NULL</span></tt> if +<em>receiver</em> is a Python callable. It is normally only used by PyQt to +implement <tt class="docutils literal"><span class="pre">QObject.disconnect()</span></tt>.</dd> +</dl> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id171" id="sipemitsignal" name="sipemitsignal">9.26 sipEmitSignal()</a></h2> +<dl class="docutils"> +<dt>int sipEmitSignal(PyObject *txobj, const char *signal, PyObject *args)</dt> +<dd>This emits a signal and returns zero if there was no error. If there was +an error then a Python exception is raised and a negative value is +returned. <em>txobj</em> is the wrapped <tt class="docutils literal"><span class="pre">QObject</span></tt> derived instance that emits +the signal. <em>signal</em> is the typed name of the signal. <em>args</em> is a Python +tuple of the signal arguments. It is normally only used by PyQt to +implement <tt class="docutils literal"><span class="pre">QObject.emit()</span></tt>.</dd> +</dl> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id172" id="sipexportsymbol" name="sipexportsymbol">9.27 sipExportSymbol()</a></h2> +<dl class="docutils"> +<dt>int sipExportSymbol(const char *name, void *sym)</dt> +<dd>Python does not allow extension modules to directly access symbols in +another extension module. This exports a symbol, referenced by a name, +that can subsequently be imported, using <a class="reference" href="#sipimportsymbol">sipImportSymbol()</a>, by another +module. <em>name</em> is the name of the symbol and <em>sym</em> is its value. Zero is +returned if there was no error. A negative value is returned if <em>name</em> is +already associated with a symbol or there was some other error.</dd> +</dl> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id173" id="sipfindclass" name="sipfindclass">9.28 sipFindClass()</a></h2> +<dl class="docutils"> +<dt>sipWrapperType *sipFindClass(const char *type)</dt> +<dd>This returns a pointer to the generated type corresponding to a C/C++ type. +<em>type</em> is the C/C++ declaration of the type. <tt class="docutils literal"><span class="pre">NULL</span></tt> is returned if the +C/C++ type doesn't exist. The value of the pointer will not change and +may be saved in a static cache.</dd> +</dl> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id174" id="sipfindmappedtype" name="sipfindmappedtype">9.29 sipFindMappedType()</a></h2> +<dl class="docutils"> +<dt>const sipMappedType *sipFindMappedType(const char *type)</dt> +<dd>This returns a pointer to an opaque structure describing a mapped type. +<em>type</em> is the C/C++ declaration of the type. <tt class="docutils literal"><span class="pre">NULL</span></tt> is returned if the +mapped type doesn't exist. The value of the pointer will not change and +may be saved in a static cache.</dd> +</dl> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id175" id="sipfindnamedenum" name="sipfindnamedenum">9.30 sipFindNamedEnum()</a></h2> +<dl class="docutils"> +<dt>PyTypeObject *sipFindNamedEnum(const char *type)</dt> +<dd>This returns a pointer to the generated type corresponding to a named C/C++ +enum. <em>type</em> is the C/C++ declaration of the enum. <tt class="docutils literal"><span class="pre">NULL</span></tt> is returned +if the named C/C++ enum doesn't exist. The value of the pointer will not +change and may be saved in a static cache.</dd> +</dl> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id176" id="sipforceconverttoinstance" name="sipforceconverttoinstance">9.31 sipForceConvertToInstance()</a></h2> +<dl class="docutils"> +<dt>void *sipForceConvertToInstance(PyObject *obj, sipWrapperType *type, PyObject *transferObj, int flags, int *state, int *iserr)</dt> +<dd>This converts a Python object to an instance of a C structure or C++ class +by calling <a class="reference" href="#sipcanconverttoinstance">sipCanConvertToInstance()</a> and, if it is successfull, calling +<a class="reference" href="#sipconverttoinstance">sipConvertToInstance()</a>. See <a class="reference" href="#sipconverttoinstance">sipConvertToInstance()</a> for a full +description of the arguments.</dd> +</dl> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id177" id="sipforceconverttomappedtype" name="sipforceconverttomappedtype">9.32 sipForceConvertToMappedType()</a></h2> +<dl class="docutils"> +<dt>void *sipForceConvertToMappedType(PyObject *obj, const sipMappedType *mt, PyObject *transferObj, int flags, int *state, int *iserr)</dt> +<dd>This converts a Python object to an instance of a C structure or C++ class +which has been implemented as a mapped type by calling +<a class="reference" href="#sipcanconverttomappedtype">sipCanConvertToMappedType()</a> and, if it is successfull, calling +<a class="reference" href="#sipconverttomappedtype">sipConvertToMappedType()</a>. See <a class="reference" href="#sipconverttomappedtype">sipConvertToMappedType()</a> for a full +description of the arguments.</dd> +</dl> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id178" id="sipfree" name="sipfree">9.33 sipFree()</a></h2> +<dl class="docutils"> +<dt>void sipFree(void *mem)</dt> +<dd>This returns an area of memory allocated by <a class="reference" href="#sipmalloc">sipMalloc()</a> to the heap. +<em>mem</em> is a pointer to the area of memory.</dd> +</dl> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id179" id="sipgetsender" name="sipgetsender">9.34 sipGetSender()</a></h2> +<dl class="docutils"> +<dt>const void *sipGetSender()</dt> +<dd>This returns a pointer to the last <tt class="docutils literal"><span class="pre">QObject</span></tt> instance that emitted a Qt +signal. It is normally only used by PyQt to implement +<tt class="docutils literal"><span class="pre">QObject.sender()</span></tt>.</dd> +</dl> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id180" id="sipgetwrapper" name="sipgetwrapper">9.35 sipGetWrapper()</a></h2> +<dl class="docutils"> +<dt>PyObject *sipGetWrapper(void *cppptr, sipWrapperType *type)</dt> +<dd>This returns a borrowed reference to the wrapped instance object for a C +structure or C++ class instance. If the structure or class instance +hasn't been wrapped then <tt class="docutils literal"><span class="pre">NULL</span></tt> is returned (and no Python exception is +raised). <em>cppptr</em> is the pointer to the structure or class instance. +<em>type</em> is the generated type corresponding to the C/C++ type.</dd> +</dl> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id181" id="sipimportsymbol" name="sipimportsymbol">9.36 sipImportSymbol()</a></h2> +<dl class="docutils"> +<dt>void *sipImportSymbol(const char *name)</dt> +<dd>Python does not allow extension modules to directly access symbols in +another extension module. This imports a symbol, referenced by a name, +that has previously been exported, using <a class="reference" href="#sipexportsymbol">sipExportSymbol()</a>, by another +module. <em>name</em> is the name of the symbol. The value of the symbol is +returned if there was no error. <tt class="docutils literal"><span class="pre">NULL</span></tt> is returned if there is no such +symbol.</dd> +</dl> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id182" id="sipinttypeclassmap" name="sipinttypeclassmap">9.37 sipIntTypeClassMap</a></h2> +<p>This C structure is used with <a class="reference" href="#sipmapinttoclass">sipMapIntToClass()</a> to define a mapping +between integer based RTTI and <a class="reference" href="#generated-type-objects">generated type objects</a>. The structure +elements are as follows.</p> +<dl class="docutils"> +<dt>int typeInt</dt> +<dd>The integer RTTI.</dd> +<dt>sipWrapperType **pyType.</dt> +<dd>A pointer to the corresponding Python type object.</dd> +</dl> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id183" id="sipissubclassinstance" name="sipissubclassinstance">9.38 sipIsSubClassInstance()</a></h2> +<dl class="docutils"> +<dt>int sipIsSubClassInstance(PyObject *obj, sipWrapperType *type)</dt> +<dd><p class="first">This function is deprecated from SIP v4.4. It is equivalent to:</p> +<pre class="last literal-block"> +sipCanConvertToInstance(obj, type, SIP_NOT_NONE | SIP_NO_CONVERTORS); +</pre> +</dd> +</dl> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id184" id="siplong-asunsignedlong" name="siplong-asunsignedlong">9.39 sipLong_AsUnsignedLong()</a></h2> +<dl class="docutils"> +<dt>unsigned long sipLong_AsUnsignedLong(PyObject *obj)</dt> +<dd>This function is a thin wrapper around PyLong_AsUnsignedLong() that works +around a bug in Python v2.3.x and earlier when converting integer objects.</dd> +</dl> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id185" id="sipmalloc" name="sipmalloc">9.40 sipMalloc()</a></h2> +<dl class="docutils"> +<dt>void *sipMalloc(size_t nbytes)</dt> +<dd>This allocates an area of memory of size <em>nytes</em> on the heap using the +Python <tt class="docutils literal"><span class="pre">PyMem_Malloc()</span></tt> function. If there was an error then <tt class="docutils literal"><span class="pre">NULL</span></tt> is +returned and a Python exception raised. See <a class="reference" href="#sipfree">sipFree()</a>.</dd> +</dl> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id186" id="sipmapinttoclass" name="sipmapinttoclass">9.41 sipMapIntToClass()</a></h2> +<dl class="docutils"> +<dt>sipWrapperType *sipMapIntToClass(int type, const sipIntTypeClassMap *map, int maplen)</dt> +<dd>This is used in <a class="reference" href="#converttosubclasscode">%ConvertToSubClassCode</a> code as a convenient way of +converting integer based RTTI to the corresponding Python type object. +<em>type</em> is the RTTI. <em>map</em> is the table of known RTTI and the corresponding +type objects (see <a class="reference" href="#sipinttypeclassmap">sipIntTypeClassMap</a>). The entries in the table must be +sorted in ascending order of RTTI. <em>maplen</em> is the number of entries in +the table. The corresponding Python type object is returned, or <tt class="docutils literal"><span class="pre">NULL</span></tt> +if <em>type</em> wasn't in <em>map</em>.</dd> +</dl> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id187" id="sipmapstringtoclass" name="sipmapstringtoclass">9.42 sipMapStringToClass()</a></h2> +<dl class="docutils"> +<dt>sipWrapperType *sipMapStringToClass(char *type, const sipStringTypeClassMap *map, int maplen)</dt> +<dd>This is used in <a class="reference" href="#converttosubclasscode">%ConvertToSubClassCode</a> code as a convenient way of +converting <tt class="docutils literal"><span class="pre">'\0'</span></tt> terminated string based RTTI to the corresponding +Python type object. <em>type</em> is the RTTI. <em>map</em> is the table of known RTTI +and the corresponding type objects (see <a class="reference" href="#sipstringtypeclassmap">sipStringTypeClassMap</a>). The +entries in the table must be sorted in ascending order of RTTI. <em>maplen</em> +is the number of entries in the table. The corresponding Python type +object is returned, or <tt class="docutils literal"><span class="pre">NULL</span></tt> if <em>type</em> wasn't in <em>map</em>.</dd> +</dl> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id188" id="sipparseresult" name="sipparseresult">9.43 sipParseResult()</a></h2> +<dl class="docutils"> +<dt>int sipParseResult(int *iserr, PyObject *method, PyObject *result, const char *format, ...)</dt> +<dd><p class="first">This converts a Python object (usually returned by a method) to C/C++ based +on a format string and associated values in a similar way to the Python +<tt class="docutils literal"><span class="pre">PyArg_ParseTuple()</span></tt> function. If there was an error then a negative +value is returned and a Python exception is raised. If <em>iserr</em> is not +<tt class="docutils literal"><span class="pre">NULL</span></tt> then the location it points to is set to a non-zero value. +<em>method</em> is the Python bound method that returned the <em>result</em> object. +<em>format</em> is the string of format characters.</p> +<p>This is normally called by handwritten code specified with the +<a class="reference" href="#virtualcatchercode">%VirtualCatcherCode</a> directive with <em>method</em> being the supplied +<tt class="docutils literal"><span class="pre">sipMethod</span></tt> and <tt class="docutils literal"><span class="pre">result</span></tt> being the value returned by +<a class="reference" href="#sipcallmethod">sipCallMethod()</a>.</p> +<p>If <em>format</em> begins and ends with parentheses then <em>result</em> must be a Python +tuple and the rest of <em>format</em> is applied to the tuple contents.</p> +<p>In the following description the first letter is the format character, the +entry in parentheses is the Python object type that the format character +will convert, and the entry in brackets are the types of the C/C++ values +to be passed.</p> +<dl class="last docutils"> +<dt><tt class="docutils literal"><span class="pre">a</span></tt> (string) [char **, int *]</dt> +<dd>Convert a Python string to a C/C++ character array and its length. If +the Python object is <tt class="docutils literal"><span class="pre">Py_None</span></tt> then the array and length are <tt class="docutils literal"><span class="pre">NULL</span></tt> +and zero respectively.</dd> +<dt><tt class="docutils literal"><span class="pre">b</span></tt> (integer) [bool *]</dt> +<dd>Convert a Python integer to a C/C++ <tt class="docutils literal"><span class="pre">bool</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">c</span></tt> (string) [char *]</dt> +<dd>Convert a Python string of length 1 to a C/C++ <tt class="docutils literal"><span class="pre">char</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">d</span></tt> (float) [double *]</dt> +<dd>Convert a Python floating point number to a C/C++ <tt class="docutils literal"><span class="pre">double</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">e</span></tt> (integer) [enum *]</dt> +<dd>Convert a Python integer to an anonymous C/C++ <tt class="docutils literal"><span class="pre">enum</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">f</span></tt> (float) [float *]</dt> +<dd>Convert a Python floating point number to a C/C++ <tt class="docutils literal"><span class="pre">float</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">h</span></tt> (integer) [short *]</dt> +<dd>Convert a Python integer to a C/C++ <tt class="docutils literal"><span class="pre">short</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">i</span></tt> (integer) [int *]</dt> +<dd>Convert a Python integer to a C/C++ <tt class="docutils literal"><span class="pre">int</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">l</span></tt> (long) [long *]</dt> +<dd>Convert a Python long to a C/C++ <tt class="docutils literal"><span class="pre">long</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">m</span></tt> (long) [unsigned long *]</dt> +<dd>Convert a Python long to a C/C++ <tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">long</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">n</span></tt> (long) [long long *]</dt> +<dd>Convert a Python long to a C/C++ <tt class="docutils literal"><span class="pre">long</span> <span class="pre">long</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">o</span></tt> (long) [unsigned long long *]</dt> +<dd>Convert a Python long to a C/C++ <tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">long</span> <span class="pre">long</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">s</span></tt> (string) [char **]</dt> +<dd>Convert a Python string to a C/C++ <tt class="docutils literal"><span class="pre">'\0'</span></tt> terminated string. If the +Python object is <tt class="docutils literal"><span class="pre">Py_None</span></tt> then the string is <tt class="docutils literal"><span class="pre">NULL</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">t</span></tt> (long) [unsigned short *]</dt> +<dd>Convert a Python long to a C/C++ <tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">short</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">u</span></tt> (long) [unsigned int *]</dt> +<dd>Convert a Python long to a C/C++ <tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">int</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">w</span></tt> (unicode) [wchar_t *]</dt> +<dd>Convert a Python unicode object of length 1 to a C/C++ wide character.</dd> +<dt><tt class="docutils literal"><span class="pre">x</span></tt> (unicode) [wchar_t **]</dt> +<dd>Convert a Python unicode object to a C/C++ <tt class="docutils literal"><span class="pre">L'\0'</span></tt> terminated wide +character string. If the Python object is <tt class="docutils literal"><span class="pre">Py_None</span></tt> then the string +is <tt class="docutils literal"><span class="pre">NULL</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">A</span></tt> (unicode) [wchar_t **, int *]</dt> +<dd>Convert a Python unicode object to a C/C++ wide character array and its +length. If the Python object is <tt class="docutils literal"><span class="pre">Py_None</span></tt> then the array and length +are <tt class="docutils literal"><span class="pre">NULL</span></tt> and zero respectively.</dd> +<dt><tt class="docutils literal"><span class="pre">Cf</span></tt> (wrapped class) [sipWrapperType *, int *, void **]</dt> +<dd><p class="first">Convert a Python object to a C structure or a C++ class instance and +return its state as described in <a class="reference" href="#sipconverttoinstance">sipConvertToInstance()</a>. <tt class="docutils literal"><span class="pre">f</span></tt> is a +combination of the following flags encoded as an ASCII character by +adding <tt class="docutils literal"><span class="pre">0</span></tt> to the combined value:</p> +<blockquote class="last"> +<p>0x01 disallows the conversion of <tt class="docutils literal"><span class="pre">Py_None</span></tt> to <tt class="docutils literal"><span class="pre">NULL</span></tt></p> +<p>0x02 implements the <a class="reference" href="#factory">Factory</a> annotation</p> +<dl class="docutils"> +<dt>0x04 suppresses the return of the state of the returned C/C++</dt> +<dd>instance. Note that the <tt class="docutils literal"><span class="pre">int</span> <span class="pre">*</span></tt> used to return the state is +not passed if this flag is specified.</dd> +</dl> +</blockquote> +</dd> +<dt><tt class="docutils literal"><span class="pre">Df</span></tt> (mapped type) [const sipMappedType *, int *, void **]</dt> +<dd><p class="first">Convert a Python object to a C structure or a C++ class instance +implemented as a mapped type and return its state as described in +<a class="reference" href="#sipconverttomappedtype">sipConvertToMappedType()</a>. <tt class="docutils literal"><span class="pre">f</span></tt> is a combination of the following +flags encoded as an ASCII character by adding <tt class="docutils literal"><span class="pre">0</span></tt> to the combined +value:</p> +<blockquote class="last"> +<p>0x01 disallows the conversion of <tt class="docutils literal"><span class="pre">Py_None</span></tt> to <tt class="docutils literal"><span class="pre">NULL</span></tt></p> +<p>0x02 implements the <a class="reference" href="#factory">Factory</a> annotation</p> +<dl class="docutils"> +<dt>0x04 suppresses the return of the state of the returned C/C++</dt> +<dd>instance. Note that the <tt class="docutils literal"><span class="pre">int</span> <span class="pre">*</span></tt> used to return the state is +not passed if this flag is specified.</dd> +</dl> +</blockquote> +</dd> +<dt><tt class="docutils literal"><span class="pre">E</span></tt> (wrapped enum) [PyTypeObject *, enum *]</dt> +<dd>Convert a Python named enum type to the corresponding C/C++ <tt class="docutils literal"><span class="pre">enum</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">L</span></tt> (object) [<em>type</em> *(*)(PyObject *obj, int *iserr), void **]</dt> +<dd>Convert a Python object to a C structure or a C++ class instance using +a convertor function. See <a class="reference" href="#generated-type-convertors">Generated Type Convertors</a>. This is +deprecated from SIP v4.4.</dd> +<dt><tt class="docutils literal"><span class="pre">M</span></tt> (object) [<em>type</em> *(*)(PyObject *obj, int *iserr), void **]</dt> +<dd>Convert a Python object to a C structure or a C++ class instance using +a convertor function. If the structure or class instance pointer is +<tt class="docutils literal"><span class="pre">NULL</span></tt> then return an error. See <a class="reference" href="#generated-type-convertors">Generated Type Convertors</a>. This +is deprecated from SIP v4.4.</dd> +<dt><tt class="docutils literal"><span class="pre">N</span></tt> (object) [PyTypeObject *, PyObject **]</dt> +<dd>A Python object is checked to see if it is a certain type and then +returned without any conversions. The reference count is incremented. +The Python object may be <tt class="docutils literal"><span class="pre">Py_None</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">O</span></tt> (object) [PyObject **]</dt> +<dd>A Python object is returned without any conversions. The reference +count is incremented.</dd> +<dt><tt class="docutils literal"><span class="pre">T</span></tt> (object) [PyTypeObject *, PyObject **]</dt> +<dd>A Python object is checked to see if it is a certain type and then +returned without any conversions. The reference count is incremented. +The Python object may not be <tt class="docutils literal"><span class="pre">Py_None</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">V</span></tt> (sip.voidptr) [void *]</dt> +<dd>Convert a Python <tt class="docutils literal"><span class="pre">sip.voidptr</span></tt> object to a C/C++ <tt class="docutils literal"><span class="pre">void</span> <span class="pre">*</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">Z</span></tt> (object) []</dt> +<dd>Check that a Python object is <tt class="docutils literal"><span class="pre">Py_None</span></tt>. No value is returned.</dd> +</dl> +</dd> +</dl> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id189" id="sipreleaseinstance" name="sipreleaseinstance">9.44 sipReleaseInstance()</a></h2> +<dl class="docutils"> +<dt>void sipReleaseInstance(void *cpp, sipWrapperType *type, int state)</dt> +<dd>This destroys a wrapped C/C++ instance if it was a temporary instance. It +is called after a call to either <a class="reference" href="#sipconverttoinstance">sipConvertToInstance()</a> or +<a class="reference" href="#sipforceconverttoinstance">sipForceConvertToInstance()</a>. <em>cpp</em> is the wrapped C/C++ instance. +<em>type</em> is the generated type corresponding to <em>cpp</em>. <em>state</em> describes the +state of the instance.</dd> +</dl> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id190" id="sipreleasemappedtype" name="sipreleasemappedtype">9.45 sipReleaseMappedType()</a></h2> +<dl class="docutils"> +<dt>void sipReleaseMappedType(void *cpp, const sipMappedType *mt, int state)</dt> +<dd>This destroys a wrapped C/C++ mapped type if it was a temporary instance. +It is called after a call to either <a class="reference" href="#sipconverttomappedtype">sipConvertToMappedType()</a> or +<a class="reference" href="#sipforceconverttomappedtype">sipForceConvertToMappedType()</a>. <em>cpp</em> is the wrapped C/C++ instance. +<em>mt</em> is the opaque structure returned by <a class="reference" href="#sipfindmappedtype">sipFindMappedType()</a>. <em>state</em> +describes the state of the instance.</dd> +</dl> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id191" id="sipstringtypeclassmap" name="sipstringtypeclassmap">9.46 sipStringTypeClassMap</a></h2> +<p>This C structure is used with <a class="reference" href="#sipmapstringtoclass">sipMapStringToClass()</a> to define a mapping +between <tt class="docutils literal"><span class="pre">'\0'</span></tt> terminated string based RTTI and <a class="reference" href="#generated-type-objects">generated type objects</a>. +The structure elements are as follows.</p> +<dl class="docutils"> +<dt>char *typeString</dt> +<dd>The <tt class="docutils literal"><span class="pre">'\0'</span></tt> terminated string RTTI.</dd> +<dt>sipWrapperType **pyType.</dt> +<dd>A pointer to the corresponding Python type object.</dd> +</dl> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id192" id="siptransfer" name="siptransfer">9.47 sipTransfer()</a></h2> +<dl class="docutils"> +<dt>void sipTransfer(PyObject *obj, int tocpp)</dt> +<dd><p class="first">This function is deprecated from SIP v4.3. If <em>tocpp</em> is non-zero then the +equivalent call is:</p> +<pre class="literal-block"> +sipTransferTo(obj, obj); +</pre> +<p>If <em>tocpp</em> is zero then the equivalent call is:</p> +<pre class="last literal-block"> +sipTransferBack(obj); +</pre> +</dd> +</dl> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id193" id="siptransferback" name="siptransferback">9.48 sipTransferBack()</a></h2> +<dl class="docutils"> +<dt>void sipTransferBack(PyObject *obj)</dt> +<dd>This transfers ownership of a Python wrapped instance to Python (see +<a class="reference" href="#ownership-of-objects">Ownership of Objects</a>). <em>obj</em> is the wrapped instance. In addition, +any association of the instance with regard to the cyclic garbage +collector with another instance is removed.</dd> +</dl> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id194" id="siptransferto" name="siptransferto">9.49 sipTransferTo()</a></h2> +<dl class="docutils"> +<dt>void sipTransferTo(PyObject *obj, PyObject *owner)</dt> +<dd>This transfers ownership of a Python wrapped instance to C++ (see +<a class="reference" href="#ownership-of-objects">Ownership of Objects</a>). <em>obj</em> is the wrapped instance. <em>owner</em> is an +optional wrapped instance that <em>obj</em> becomes associated with with regard +to the cyclic garbage collector. If <em>owner</em> is <tt class="docutils literal"><span class="pre">NULL</span></tt> then no such +association is made. If <em>owner</em> is the same value as <em>obj</em> then any +reference cycles involving <em>obj</em> can never be detected or broken by the +cyclic garbage collector. Responsibility for calling the C++ instance's +destructor is always transfered to C++.</dd> +</dl> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id195" id="sipwrapper" name="sipwrapper">9.50 sipWrapper</a></h2> +<p>This is a C structure that represents a Python wrapped instance. It is an +extension of the Python <tt class="docutils literal"><span class="pre">PyObject</span></tt> structure and so may be safely cast to +<tt class="docutils literal"><span class="pre">PyObject</span></tt>. It includes a member called <tt class="docutils literal"><span class="pre">user</span></tt> which is of type +<tt class="docutils literal"><span class="pre">PyObject</span> <span class="pre">*</span></tt>. This can be used for any purpose by handwritten code and will +automatically be garbage collected at the appropriate time.</p> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id196" id="sipwrapper-check" name="sipwrapper-check">9.51 sipWrapper_Check()</a></h2> +<dl class="docutils"> +<dt>int sipWrapper_Check(PyObject *obj)</dt> +<dd>This returns a non-zero value if a Python object is a wrapped instance. +<em>obj</em> is the Python object.</dd> +</dl> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id197" id="sipwrappertype" name="sipwrappertype">9.52 sipWrapperType</a></h2> +<p>This is a C structure that represents a SIP generated type object. It is an +extension of the Python <tt class="docutils literal"><span class="pre">PyTypeObject</span></tt> structure (which is itself an +extension of the Python <tt class="docutils literal"><span class="pre">PyObject</span></tt> structure) and so may be safely cast to +<tt class="docutils literal"><span class="pre">PyTypeObject</span></tt> (and <tt class="docutils literal"><span class="pre">PyObject</span></tt>).</p> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id198" id="generated-type-convertors" name="generated-type-convertors">9.53 Generated Type Convertors</a></h2> +<p>These functions are deprecated from SIP v4.4.</p> +<p>SIP generates functions for all types being wrapped (including mapped types +defined with the <a class="reference" href="#mappedtype">%MappedType</a> directive) that convert a Python object to the +C structure or C++ class instance. The name of this convertor is the name of +the structure or class prefixed by <tt class="docutils literal"><span class="pre">sipForceConvertTo_</span></tt>.</p> +<dl class="docutils"> +<dt>void *sipForceConvertTo_*class*(PyObject *obj, int *iserr)</dt> +<dd><em>obj</em> is the Python object to convert. If <em>obj</em> is <tt class="docutils literal"><span class="pre">NULL</span></tt> or the +location pointed to by <em>iserr</em> is non-zero then the conversion is not +attempted and <tt class="docutils literal"><span class="pre">NULL</span></tt> is returned. If there was an error then the +location pointed to by <em>iserr</em> is set to a non-zero value, a Python +exception is raised, and <tt class="docutils literal"><span class="pre">NULL</span></tt> is returned.</dd> +</dl> +<p>SIP also generates functions for mapped types that convert a C structure or +C++ class instance to a Python object. The name of this convertor is the name +of the structure or class prefixed by <tt class="docutils literal"><span class="pre">sipConvertFrom_</span></tt>.</p> +<dl class="docutils"> +<dt>PyObject *sipConvertFrom_*class*(void *cppptr)</dt> +<dd><em>cppptr</em> is a pointer to the C structure or C++ class instance to convert. +If there was an error then <tt class="docutils literal"><span class="pre">NULL</span></tt> is returned and a Python exception +raised.</dd> +</dl> +<p>The convertor functions of all imported types are available to handwritten +code.</p> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id199" id="generated-type-objects" name="generated-type-objects">9.54 Generated Type Objects</a></h2> +<p>SIP generates a type object for each C structure or C++ class being wrapped. +These are <a class="reference" href="#sipwrappertype">sipWrapperType</a> structures and are used extensively by the SIP API.</p> +<p>These objects are named with the structure or class name prefixed by +<tt class="docutils literal"><span class="pre">sipClass_</span></tt>. For example, the type object for class <tt class="docutils literal"><span class="pre">Klass</span></tt> is +<tt class="docutils literal"><span class="pre">sipClass_Klass</span></tt>.</p> +<p>The type objects of all imported classes are available to handwritten code.</p> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id200" id="generated-named-enum-type-objects" name="generated-named-enum-type-objects">9.55 Generated Named Enum Type Objects</a></h2> +<p>SIP generates a type object for each named enum being wrapped. These are +PyTypeObject structures. (Anonymous enums are wrapped as Python integers.)</p> +<p>These objects are named with the fully qualified enum name (i.e. including any +enclosing scope) prefixed by <tt class="docutils literal"><span class="pre">sipEnum_</span></tt>. For example, the type object for +enum <tt class="docutils literal"><span class="pre">Enum</span></tt> defined in class <tt class="docutils literal"><span class="pre">Klass</span></tt> is <tt class="docutils literal"><span class="pre">sipEnum_Klass_Enum</span></tt>.</p> +<p>The type objects of all imported named enums are available to handwritten code.</p> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id201" id="generated-derived-classes" name="generated-derived-classes">9.56 Generated Derived Classes</a></h2> +<p>For most C++ classes being wrapped SIP generates a derived class with the same +name prefixed by <tt class="docutils literal"><span class="pre">sip</span></tt>. For example, the derived class for class <tt class="docutils literal"><span class="pre">Klass</span></tt> +is <tt class="docutils literal"><span class="pre">sipKlass</span></tt>.</p> +<p>If a C++ class doesn't have any virtual or protected methods in it or any of +it's super-class hierarchy, or does not emit any Qt signals, then a derived +class is not generated.</p> +<p>Most of the time handwritten code should ignore the derived classes. The only +exception is that handwritten constructor code specified using the +<a class="reference" href="#methodcode">%MethodCode</a> directive should call the derived class's constructor (which +has the same C++ signature) rather then the wrapped class's constructor.</p> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id202" id="generated-exception-objects" name="generated-exception-objects">9.57 Generated Exception Objects</a></h2> +<p>SIP generates a Python object for each exception defined with the <cite>%Exception_</cite> +directive.</p> +<p>These objects are named with the fully qualified exception name (i.e. including +any enclosing scope) prefixed by <tt class="docutils literal"><span class="pre">sipException_</span></tt>. For example, the type +object for enum <tt class="docutils literal"><span class="pre">Except</span></tt> defined in class <tt class="docutils literal"><span class="pre">Klass</span></tt> is +<tt class="docutils literal"><span class="pre">sipException_Klass_Except</span></tt>.</p> +<p>The objects of all imported exceptions are available to handwritten code.</p> +</div> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id203" id="using-the-sip-module-in-applications" name="using-the-sip-module-in-applications">10 Using the SIP Module in Applications</a></h1> +<p>The main purpose of the SIP module is to provide functionality common to all +SIP generated bindings. It is loaded automatically and most of the time you +will completely ignore it. However, it does expose some functionality that can +be used by applications.</p> +<dl class="docutils"> +<dt>cast(obj, type)</dt> +<dd>This does the Python equivalent of casting a C++ instance to one of its +sub or super-class types. <em>obj</em> is the Python object and <em>type</em> is the +type. A new Python object is returned that wraps the same C++ instance as +<em>obj</em>, but has the type <em>type</em>.</dd> +<dt>delete(obj)</dt> +<dd>For C++ instances this calls the C++ destructor. For C structures it +returns the structure's memory to the heap. <em>obj</em> is the Python object.</dd> +<dt>isdeleted(obj)</dt> +<dd>This returns True if the C++ instance or C structure has been destroyed or +returned to the heap. <em>obj</em> is the Python object.</dd> +<dt>setdeleted(obj)</dt> +<dd>This marks the C++ instance or C structure as having been destroyed or +returned to the heap so that future references to it raise an exception +rather than cause a program crash. Normally SIP handles such things +automatically, but there are circumstances where this isn't possible. +<em>obj</em> is the Python object.</dd> +<dt>settracemask(mask)</dt> +<dd><p class="first">If the bindings have been created with SIP's <tt class="docutils literal"><span class="pre">-r</span></tt> command line option +then the generated code will produce debugging statements that trace the +execution of the code. (It is particularly useful when trying to +understand the operation of a C++ library's virtual function calls.)</p> +<p>Debugging statements are generated at the following points:</p> +<ul class="simple"> +<li>in a C++ virtual function (<em>mask</em> is <tt class="docutils literal"><span class="pre">0x0001</span></tt>)</li> +<li>in a C++ constructor (<em>mask</em> is <tt class="docutils literal"><span class="pre">0x0002</span></tt>)</li> +<li>in a C++ destructor (<em>mask</em> is <tt class="docutils literal"><span class="pre">0x0004</span></tt>)</li> +<li>in a Python type's __init__ method (<em>mask</em> is <tt class="docutils literal"><span class="pre">0x0008</span></tt>)</li> +<li>in a Python type's __del__ method (<em>mask</em> is <tt class="docutils literal"><span class="pre">0x0010</span></tt>)</li> +<li>in a Python type's ordinary method (<em>mask</em> is <tt class="docutils literal"><span class="pre">0x0020</span></tt>).</li> +</ul> +<p class="last">By default the trace mask is zero and all debugging statements are +disabled.</p> +</dd> +<dt>SIP_VERSION</dt> +<dd>This is a Python integer object that represents the SIP version number as +a 3 part hexadecimal number (e.g. v4.0.0 is represented as <tt class="docutils literal"><span class="pre">0x040000</span></tt>). +It was first implemented in SIP v4.2.</dd> +<dt>SIP_VERSION_STR</dt> +<dd>This is a Python string object that defines the SIP version number as +represented as a string. For development snapshots it will start with +<tt class="docutils literal"><span class="pre">snapshot-</span></tt>. It was first implemented in SIP v4.3.</dd> +<dt>transfer(obj, direction)</dt> +<dd><p class="first">This function is deprecated from SIP v4.3. If <em>direction</em> is non-zero then +the equivalent call is:</p> +<pre class="literal-block"> +sip.transferto(obj, None) +</pre> +<p>If <em>direction</em> is zero then the equivalent call is:</p> +<pre class="last literal-block"> +sip.transferback(obj) +</pre> +</dd> +<dt>transferback(obj)</dt> +<dd>This function is a wrapper around <a class="reference" href="#siptransferback">sipTransferBack()</a>.</dd> +<dt>transferto(obj, owner)</dt> +<dd>This function is a wrapper around <a class="reference" href="#siptransferto">sipTransferTo()</a>.</dd> +<dt>unwrapinstance(obj)</dt> +<dd>Return the address, as a number, of the wrapped C/C++ structure or class +instance <em>obj</em>.</dd> +<dt>voidptr</dt> +<dd><p class="first">This is the type object for the type SIP uses to represent a C/C++ +<tt class="docutils literal"><span class="pre">void</span> <span class="pre">*</span></tt>. The type constructor takes a single argument that must either +be another <tt class="docutils literal"><span class="pre">voidptr</span></tt>, <tt class="docutils literal"><span class="pre">None</span></tt>, a Python CObject, or an integer. The +type has the following methods:</p> +<dl class="last docutils"> +<dt>__int__()</dt> +<dd>This returns the pointer as an integer.</dd> +<dt>__hex__()</dt> +<dd>This returns the pointer as a hexadecimal string.</dd> +<dt>ascobject()</dt> +<dd>This returns the pointer as a Python CObject.</dd> +<dt>asstring(nbytes)</dt> +<dd>This returns a copy of the first <em>nbytes</em> of memory at the pointer as a +Python string.</dd> +</dl> +</dd> +<dt>wrapinstance(addr, type)</dt> +<dd>A C/C++ structure or class instance is wrapped and the Python object +created is returned. If the instance has already been wrapped then a new +reference to the existing object is returned. <em>addr</em> is the address of +the instance represented as a number. <em>type</em> is the type of the object +(e.g. <tt class="docutils literal"><span class="pre">qt.QWidget</span></tt>).</dd> +<dt>wrapper</dt> +<dd>This is the type object of the base type of all instances wrapped by SIP.</dd> +<dt>wrappertype</dt> +<dd>This is the type object of the metatype of the <tt class="docutils literal"><span class="pre">wrapper</span></tt> type.</dd> +</dl> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id204" id="the-sip-build-system" name="the-sip-build-system">11 The SIP Build System</a></h1> +<p>The purpose of the build system is to make it easy for you to write +configuration scripts in Python for your own bindings. The build system takes +care of the details of particular combinations of platform and compiler. It +supports over 50 different platform/compiler combinations.</p> +<p>The build system is implemented as a pure Python module called <tt class="docutils literal"><span class="pre">sipconfig</span></tt> +that contains a number of classes and functions. Using this module you can +write bespoke configuration scripts (e.g. PyQt's <tt class="docutils literal"><span class="pre">configure.py</span></tt>) or use it +with other Python based build systems (e.g. +<a class="reference" href="http://www.python.org/sigs/distutils-sig/distutils.html">Distutils</a> and +<a class="reference" href="http://www.scons.org">SCons</a>).</p> +<p>An important feature of SIP is the ability to generate bindings that are built +on top of existing bindings. For example, both +<a class="reference" href="http://www.riverbankcomputing.co.uk/pykde/">PyKDE</a> and +<a class="reference" href="http://pyqwt.sourceforge.net/">PyQwt</a> are built on top of PyQt but all three +packages are maintained by different developers. To make this easier PyQt +includes its own configuration module, <tt class="docutils literal"><span class="pre">pyqtconfig</span></tt>, that contains additional +classes intended to be used by the configuration scripts of bindings built on +top of PyQt. The SIP build system includes facilities that do a lot of the +work of creating these additional configuration modules.</p> +<div class="section"> +<h2><a class="toc-backref" href="#id205" id="sipconfig-functions" name="sipconfig-functions">11.1 <tt class="docutils literal"><span class="pre">sipconfig</span></tt> Functions</a></h2> +<dl class="docutils"> +<dt>create_config_module(module, template, content, macros=None)</dt> +<dd><p class="first">This creates a configuration module (e.g. <tt class="docutils literal"><span class="pre">pyqtconfig</span></tt>) from a template +file and a string.</p> +<p><tt class="docutils literal"><span class="pre">module</span></tt> is the name of the configuration module file to create.</p> +<p><tt class="docutils literal"><span class="pre">template</span></tt> is the name of the template file.</p> +<p><tt class="docutils literal"><span class="pre">content</span></tt> is a string which replaces every occurence of the pattern +<tt class="docutils literal"><span class="pre">@SIP_CONFIGURATION@</span></tt> in the template file. The content string is +usually created from a Python dictionary using +<tt class="docutils literal"><span class="pre">sipconfig.create_content()</span></tt>. <tt class="docutils literal"><span class="pre">content</span></tt> may also be a dictionary, in +which case <tt class="docutils literal"><span class="pre">sipconfig.create_content()</span></tt> is automatically called to +convert it to a string.</p> +<p class="last"><tt class="docutils literal"><span class="pre">macros</span></tt> is an optional dictionary of platform specific build macros. It +is only used if <tt class="docutils literal"><span class="pre">sipconfig.create_content()</span></tt> is called automatically to +convert a <tt class="docutils literal"><span class="pre">content</span></tt> dictionary to a string.</p> +</dd> +<dt>create_content(dict, macros=None)</dt> +<dd><p class="first">This converts a Python dictionary to a string that can be parsed by the +Python interpreter and converted back to an equivalent dictionary. It is +typically used to generate the content string for +<tt class="docutils literal"><span class="pre">sipconfig.create_config_module()</span></tt>.</p> +<p><tt class="docutils literal"><span class="pre">dict</span></tt> is the Python dictionary to convert.</p> +<p><tt class="docutils literal"><span class="pre">macros</span></tt> is the optional dictionary of platform specific build macros.</p> +<p class="last">Returns the dictionary as a string.</p> +</dd> +<dt>create_wrapper(script, wrapper, gui=0)</dt> +<dd><p class="first">This creates a platform dependent executable wrapper around a Python +script.</p> +<p><tt class="docutils literal"><span class="pre">script</span></tt> is the full pathname of the script.</p> +<p><tt class="docutils literal"><span class="pre">wrapper</span></tt> is the pathname of the wrapper to create.</p> +<p><tt class="docutils literal"><span class="pre">gui</span></tt> is non-zero if a GUI enabled version of the interpreter should be +used on platforms that require it.</p> +<p class="last">Returns the platform specific name of the wrapper.</p> +</dd> +<dt>error(msg)</dt> +<dd><p class="first">This displays an error message on <tt class="docutils literal"><span class="pre">stderr</span></tt> and calls <tt class="docutils literal"><span class="pre">sys.exit()</span></tt> with +a value of 1.</p> +<p class="last"><tt class="docutils literal"><span class="pre">msg</span></tt> is the text of the message and should not include any newline +characters.</p> +</dd> +<dt>format(msg, leftmargin=0, rightmargin=78)</dt> +<dd><p class="first">This formats a message by inserting newline characters at appropriate +places.</p> +<p><tt class="docutils literal"><span class="pre">msg</span></tt> is the text of the message and should not include any newline +characters.</p> +<p><tt class="docutils literal"><span class="pre">leftmargin</span></tt> is the optional position of the left margin.</p> +<p class="last"><tt class="docutils literal"><span class="pre">rightmargin</span></tt> is the optional position of the right margin.</p> +</dd> +<dt>inform(msg)</dt> +<dd><p class="first">This displays an information message on <tt class="docutils literal"><span class="pre">stdout</span></tt>.</p> +<p class="last"><tt class="docutils literal"><span class="pre">msg</span></tt> is the text of the message and should not include any newline +characters.</p> +</dd> +<dt>parse_build_macros(filename, names, overrides=None, properties=None)</dt> +<dd><p class="first">This parses a qmake compatible file of build system macros and converts it +to a dictionary. A macro is a name/value pair. The dictionary is returned +or None if any of the overrides was invalid.</p> +<p><tt class="docutils literal"><span class="pre">filename</span></tt> is the name of the file to parse.</p> +<p><tt class="docutils literal"><span class="pre">names</span></tt> is a list of the macro names to extract from the file.</p> +<p><tt class="docutils literal"><span class="pre">overrides</span></tt> is an optional list of macro names and values that modify +those found in the file. They are of the form <em>name=value</em> (in which case +the value replaces the value found in the file) or <em>name+=value</em> (in which +case the value is appended to the value found in the file).</p> +<p class="last"><tt class="docutils literal"><span class="pre">properties</span></tt> is an optional dictionary of property name and values that +are used to resolve any expressions of the form <tt class="docutils literal"><span class="pre">$[name]</span></tt> in the file.</p> +</dd> +<dt>read_version(filename, description, numdefine=None, strdefine=None)</dt> +<dd><p class="first">This extracts version information for a package from a file, usually a C or +C++ header file. The version information must each be specified as a +<tt class="docutils literal"><span class="pre">#define</span></tt> of a numeric (hexadecimal or decimal) value and/or a string +value.</p> +<p><tt class="docutils literal"><span class="pre">filename</span></tt> is the name of the file to read.</p> +<p><tt class="docutils literal"><span class="pre">description</span></tt> is a descriptive name of the package used in error +messages.</p> +<p><tt class="docutils literal"><span class="pre">numdefine</span></tt> is the optional name of the <tt class="docutils literal"><span class="pre">#define</span></tt> of the version as a +number. If it is <tt class="docutils literal"><span class="pre">None</span></tt> then the numeric version is ignored.</p> +<p><tt class="docutils literal"><span class="pre">strdefine</span></tt> is the optional name of the <tt class="docutils literal"><span class="pre">#define</span></tt> of the version as a +string. If it is <tt class="docutils literal"><span class="pre">None</span></tt> then the string version is ignored.</p> +<p class="last">Returns a tuple of the numeric and string versions. <tt class="docutils literal"><span class="pre">sipconfig.error()</span></tt> +is called if either were required but could not be found.</p> +</dd> +<dt>version_to_sip_tag(version, tags, description)</dt> +<dd><p class="first">This converts a version number to a SIP version tag. SIP uses the +<a class="reference" href="#timeline">%Timeline</a> directive to define the chronology of the different versions +of the C/C++ library being wrapped. Typically it is not necessary to +define a version tag for every version of the library, but only for those +versions that affect the library's API as SIP sees it.</p> +<p><tt class="docutils literal"><span class="pre">version</span></tt> is the numeric version number of the C/C++ library being +wrapped. If it is negative then the latest version is assumed. (This is +typically useful if a snapshot is indicated by a negative version number.)</p> +<p><tt class="docutils literal"><span class="pre">tags</span></tt> is the dictionary of SIP version tags keyed by the corresponding +C/C++ library version number. The tag used is the one with the smallest +key (i.e. earliest version) that is greater than <tt class="docutils literal"><span class="pre">version</span></tt>.</p> +<p><tt class="docutils literal"><span class="pre">description</span></tt> is a descriptive name of the C/C++ library used in error +messages.</p> +<p class="last">Returns the SIP version tag. <tt class="docutils literal"><span class="pre">sipconfig.error()</span></tt> is called if the C/C++ +library version number did not correspond to a SIP version tag.</p> +</dd> +<dt>version_to_string(v)</dt> +<dd><p class="first">This converts a 3 part version number encoded as a hexadecimal value to a +string.</p> +<p><tt class="docutils literal"><span class="pre">v</span></tt> is the version number.</p> +<p class="last">Returns a string.</p> +</dd> +</dl> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id206" id="sipconfig-classes" name="sipconfig-classes">11.2 <tt class="docutils literal"><span class="pre">sipconfig</span></tt> Classes</a></h2> +<dl class="docutils"> +<dt>Configuration</dt> +<dd><p class="first">This class encapsulates configuration values that can be accessed as +instance objects. A sub-class may provide a dictionary of additional +configuration values in its constructor the elements of which will have +precedence over the super-class's values.</p> +<p>The following configuration values are provided:</p> +<blockquote> +<dl class="docutils"> +<dt>default_bin_dir</dt> +<dd>The name of the directory where executables should be installed by +default.</dd> +<dt>default_mod_dir</dt> +<dd>The name of the directory where SIP generated modules should be +installed by default.</dd> +<dt>default_sip_dir</dt> +<dd>The name of the base directory where the <tt class="docutils literal"><span class="pre">.sip</span></tt> files for SIP +generated modules should be installed by default. A sub-directory +with the same name as the module should be created and its <tt class="docutils literal"><span class="pre">.sip</span></tt> +files should be installed in the sub-directory. The <tt class="docutils literal"><span class="pre">.sip</span></tt> +files only need to be installed if you might want to build other +bindings based on them.</dd> +<dt>platform</dt> +<dd>The name of the platform/compiler for which the build system has +been configured for.</dd> +<dt>py_conf_inc_dir</dt> +<dd>The name of the directory containing the <tt class="docutils literal"><span class="pre">pyconfig.h</span></tt> header +file.</dd> +<dt>py_inc_dir</dt> +<dd>The name of the directory containing the <tt class="docutils literal"><span class="pre">Python.h</span></tt> header file.</dd> +<dt>py_lib_dir</dt> +<dd>The name of the directory containing the Python interpreter +library.</dd> +<dt>py_version</dt> +<dd>The Python version as a 3 part hexadecimal number (e.g. v2.3.3 is +represented as <tt class="docutils literal"><span class="pre">0x020303</span></tt>).</dd> +<dt>sip_bin</dt> +<dd>The full pathname of the SIP executable.</dd> +<dt>sip_config_args</dt> +<dd>The command line passed to <tt class="docutils literal"><span class="pre">configure.py</span></tt> when SIP was +configured.</dd> +<dt>sip_inc_dir</dt> +<dd>The name of the directory containing the <tt class="docutils literal"><span class="pre">sip.h</span></tt> header file.</dd> +<dt>sip_mod_dir</dt> +<dd>The name of the directory containing the SIP module.</dd> +<dt>sip_version</dt> +<dd>The SIP version as a 3 part hexadecimal number (e.g. v4.0.0 is +represented as <tt class="docutils literal"><span class="pre">0x040000</span></tt>).</dd> +<dt>sip_version_str</dt> +<dd>The SIP version as a string. For development snapshots it will +start with <tt class="docutils literal"><span class="pre">snapshot-</span></tt>.</dd> +<dt>universal</dt> +<dd>The name of the MacOS/X SDK used when creating universal binaries.</dd> +</dl> +</blockquote> +<dl class="last docutils"> +<dt>__init__(self, sub_cfg=None)</dt> +<dd><p class="first">Initialise the instance.</p> +<p class="last"><tt class="docutils literal"><span class="pre">sub_cfg</span></tt> is an optional list of sub-class configurations. It should +only be used by the <tt class="docutils literal"><span class="pre">__init__()</span></tt> method of a sub-class to append its +own dictionary of configuration values before passing the list to its +super-class.</p> +</dd> +<dt>build_macros(self)</dt> +<dd>Return the dictionary of platform specific build macros.</dd> +<dt>set_build_macros(self, macros)</dt> +<dd>Set the dictionary of platform specific build macros to be use when +generating Makefiles. Normally there is no need to change the default +macros.</dd> +</dl> +</dd> +<dt>Makefile</dt> +<dd><p class="first">This class encapsulates a Makefile. It is intended to be sub-classed to +generate Makefiles for particular purposes. It handles all platform and +compiler specific flags, but allows them to be adjusted to suit the +requirements of a particular module or program. These are defined using a +number of macros which can be accessed as instance objects.</p> +<p>The following instance objects are provided to help in fine tuning the +generated Makefile:</p> +<blockquote> +<dl class="docutils"> +<dt>chkdir</dt> +<dd>A string that will check for the existence of a directory.</dd> +<dt>config</dt> +<dd>A reference to the <tt class="docutils literal"><span class="pre">configuration</span></tt> argument that was passed to +the constructor.</dd> +<dt>console</dt> +<dd>A reference to the <tt class="docutils literal"><span class="pre">console</span></tt> argument that was passed to the +constructor.</dd> +<dt>copy</dt> +<dd>A string that will copy a file.</dd> +<dt>extra_cflags</dt> +<dd>A list of additional flags passed to the C compiler.</dd> +<dt>extra_cxxflags</dt> +<dd>A list of additional flags passed to the C++ compiler.</dd> +<dt>extra_defines</dt> +<dd>A list of additional macro names passed to the C/C++ preprocessor.</dd> +<dt>extra_include_dirs</dt> +<dd>A list of additional include directories passed to the C/C++ +preprocessor.</dd> +<dt>extra_lflags</dt> +<dd>A list of additional flags passed to the linker.</dd> +<dt>extra_lib_dirs</dt> +<dd>A list of additional library directories passed to the linker.</dd> +<dt>extra_libs</dt> +<dd>A list of additional libraries passed to the linker. The names of +the libraries must be in platform neutral form (i.e. without any +platform specific prefixes, version numbers or extensions).</dd> +<dt>generator</dt> +<dd>A string that defines the platform specific style of Makefile. The +only supported values are <tt class="docutils literal"><span class="pre">UNIX</span></tt> and something else that is not +<tt class="docutils literal"><span class="pre">UNIX</span></tt>.</dd> +<dt>mkdir</dt> +<dd>A string that will create a directory.</dd> +<dt>rm</dt> +<dd>A string that will remove a file.</dd> +</dl> +</blockquote> +<dl class="last docutils"> +<dt>__init__(self, configuration, console=0, qt=0, opengl=0, python=0, threaded=0, warnings=None, debug=0, dir=None, makefile="Makefile", installs=None, universal='')</dt> +<dd><p class="first">Initialise the instance.</p> +<p><tt class="docutils literal"><span class="pre">configuration</span></tt> is the current configuration and is an instance of +the <tt class="docutils literal"><span class="pre">Configuration</span></tt> class or a sub-class.</p> +<p><tt class="docutils literal"><span class="pre">console</span></tt> is set if the target is a console (rather than GUI) target. +This only affects Windows and is ignored on other platforms.</p> +<p><tt class="docutils literal"><span class="pre">qt</span></tt> is set if the target uses Qt. For Qt v4 a list of Qt libraries +may be specified and a simple non-zero value implies QtCore and QtGui.</p> +<p><tt class="docutils literal"><span class="pre">opengl</span></tt> is set if the target uses OpenGL.</p> +<p><tt class="docutils literal"><span class="pre">python</span></tt> is set if the target uses Python.h.</p> +<p><tt class="docutils literal"><span class="pre">threaded</span></tt> is set if the target requires thread support. It is set +automatically if the target uses Qt and Qt has thread support enabled.</p> +<p><tt class="docutils literal"><span class="pre">warnings</span></tt> is set if compiler warning messages should be enabled. +The default of <tt class="docutils literal"><span class="pre">None</span></tt> means that warnings are enabled for SIP v4.x +and disabled for SIP v3.x.</p> +<p><tt class="docutils literal"><span class="pre">debug</span></tt> is set if debugging symbols should be generated.</p> +<p><tt class="docutils literal"><span class="pre">dir</span></tt> is the name of the directory where build files are read from +and Makefiles are written to. The default of <tt class="docutils literal"><span class="pre">None</span></tt> means the +current directory is used.</p> +<p><tt class="docutils literal"><span class="pre">makefile</span></tt> is the name of the generated Makefile.</p> +<p><tt class="docutils literal"><span class="pre">installs</span></tt> is a list of extra install targets. Each element is a two +part list, the first of which is the source and the second is the +destination. If the source is another list then it is a list of source +files and the destination is a directory.</p> +<p class="last"><tt class="docutils literal"><span class="pre">universal</span></tt> is the name of the SDK if universal binaries are to be +created under MacOS/X.</p> +</dd> +<dt>clean_build_file_objects(self, mfile, build)</dt> +<dd><p class="first">This generates the Makefile commands that will remove any files +generated during the build of the default target.</p> +<p><tt class="docutils literal"><span class="pre">mfile</span></tt> is the Python file object of the Makefile.</p> +<p class="last"><tt class="docutils literal"><span class="pre">build</span></tt> is the dictionary created from parsing the build file.</p> +</dd> +<dt>finalise(self)</dt> +<dd>This is called just before the Makefile is generated to ensure that it +is fully configured. It must be reimplemented by a sub-class.</dd> +<dt>generate(self)</dt> +<dd>This generates the Makefile.</dd> +<dt>generate_macros_and_rules(self, mfile)</dt> +<dd><p class="first">This is the default implementation of the Makefile macros and rules +generation.</p> +<p class="last"><tt class="docutils literal"><span class="pre">mfile</span></tt> is the Python file object of the Makefile.</p> +</dd> +<dt>generate_target_clean(self, mfile)</dt> +<dd><p class="first">This is the default implementation of the Makefile clean target +generation.</p> +<p class="last"><tt class="docutils literal"><span class="pre">mfile</span></tt> is the Python file object of the Makefile.</p> +</dd> +<dt>generate_target_default(self, mfile)</dt> +<dd><p class="first">This is the default implementation of the Makefile default target +generation.</p> +<p class="last"><tt class="docutils literal"><span class="pre">mfile</span></tt> is the Python file object of the Makefile.</p> +</dd> +<dt>generate_target_install(self, mfile)</dt> +<dd><p class="first">This is the default implementation of the Makefile install target +generation.</p> +<p class="last"><tt class="docutils literal"><span class="pre">mfile</span></tt> is the Python file object of the Makefile.</p> +</dd> +<dt>install_file(self, mfile, src, dst, strip=0)</dt> +<dd><p class="first">This generates the Makefile commands to install one or more files to a +directory.</p> +<p><tt class="docutils literal"><span class="pre">mfile</span></tt> is the Python file object of the Makefile.</p> +<p><tt class="docutils literal"><span class="pre">src</span></tt> is the name of a single file to install or a list of a number +of files to install.</p> +<p><tt class="docutils literal"><span class="pre">dst</span></tt> is the name of the destination directory.</p> +<p class="last"><tt class="docutils literal"><span class="pre">strip</span></tt> is set if the files should be stripped of unneeded symbols +after having been installed.</p> +</dd> +<dt>optional_list(self, name)</dt> +<dd><p class="first">This returns an optional Makefile macro as a list.</p> +<p><tt class="docutils literal"><span class="pre">name</span></tt> is the name of the macro.</p> +<p class="last">Returns the macro as a list.</p> +</dd> +<dt>optional_string(self, name, default="")</dt> +<dd><p class="first">This returns an optional Makefile macro as a string.</p> +<p><tt class="docutils literal"><span class="pre">name</span></tt> is the name of the macro.</p> +<p><tt class="docutils literal"><span class="pre">default</span></tt> is the optional default value of the macro.</p> +<p class="last">Returns the macro as a string.</p> +</dd> +<dt>parse_build_file(self, filename)</dt> +<dd><p class="first">This parses a build file (created with the <tt class="docutils literal"><span class="pre">-b</span></tt> SIP command line +option) and converts it to a dictionary. It can also validate an +existing dictionary created through other means.</p> +<p><tt class="docutils literal"><span class="pre">filename</span></tt> is the name of the build file, or is a dictionary to be +validated. A valid dictionary will contain the name of the target to +build (excluding any platform specific extension) keyed by <tt class="docutils literal"><span class="pre">target</span></tt>; +the names of all source files keyed by <tt class="docutils literal"><span class="pre">sources</span></tt>; and, optionally, +the names of all header files keyed by <tt class="docutils literal"><span class="pre">headers</span></tt>.</p> +<p class="last">Returns a dictionary corresponding to the parsed build file.</p> +</dd> +<dt>platform_lib(self, clib, framework=0)</dt> +<dd><p class="first">This converts a library name to a platform specific form.</p> +<p><tt class="docutils literal"><span class="pre">clib</span></tt> is the name of the library in cannonical form.</p> +<p><tt class="docutils literal"><span class="pre">framework</span></tt> is set if the library is implemented as a MacOS +framework.</p> +<p class="last">Return the platform specific name.</p> +</dd> +<dt>ready(self)</dt> +<dd>This is called to ensure that the Makefile is fully configured. It is +normally called automatically when needed.</dd> +<dt>required_string(self, name)</dt> +<dd><p class="first">This returns a required Makefile macro as a string.</p> +<p><tt class="docutils literal"><span class="pre">name</span></tt> is the name of the macro.</p> +<p class="last">Returns the macro as a string. An exception is raised if the macro +does not exist or has an empty value.</p> +</dd> +</dl> +</dd> +<dt>ModuleMakefile(Makefile)</dt> +<dd><p class="first">This class encapsulates a Makefile to build a generic Python extension +module.</p> +<dl class="last docutils"> +<dt>__init__(self, configuration, build_file, install_dir=None, static=0, console=0, opengl=0, threaded=0, warnings=None, debug=0, dir=None, makefile="Makefile", installs=None, strip=1, export_all=0, universal='')</dt> +<dd><p class="first">Initialise the instance.</p> +<p><tt class="docutils literal"><span class="pre">configuration</span></tt> - see <tt class="docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt>.</p> +<p><tt class="docutils literal"><span class="pre">build_file</span></tt> is the name of the build file. Build files are +generated using the <tt class="docutils literal"><span class="pre">-b</span></tt> SIP command line option.</p> +<p><tt class="docutils literal"><span class="pre">install_dir</span></tt> is the name of the directory where the module will be +optionally installed.</p> +<p><tt class="docutils literal"><span class="pre">static</span></tt> is set if the module should be built as a static library +(see <a class="reference" href="#builtin-modules-and-custom-interpreters">Builtin Modules and Custom Interpreters</a>).</p> +<p><tt class="docutils literal"><span class="pre">console</span></tt> - see <tt class="docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt>.</p> +<p><tt class="docutils literal"><span class="pre">qt</span></tt> - see <tt class="docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt>.</p> +<p><tt class="docutils literal"><span class="pre">opengl</span></tt> - see <tt class="docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt>.</p> +<p><tt class="docutils literal"><span class="pre">threaded</span></tt> - see <tt class="docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt>.</p> +<p><tt class="docutils literal"><span class="pre">warnings</span></tt> - see <tt class="docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt>.</p> +<p><tt class="docutils literal"><span class="pre">debug</span></tt> - see <tt class="docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt>.</p> +<p><tt class="docutils literal"><span class="pre">dir</span></tt> - see <tt class="docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt>.</p> +<p><tt class="docutils literal"><span class="pre">makefile</span></tt> - see <tt class="docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt>.</p> +<p><tt class="docutils literal"><span class="pre">installs</span></tt> - see <tt class="docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt>.</p> +<p><tt class="docutils literal"><span class="pre">strip</span></tt> is set if the module should be stripped of unneeded symbols +after installation. It is ignored if either <tt class="docutils literal"><span class="pre">debug</span></tt> or <tt class="docutils literal"><span class="pre">static</span></tt> is +set, or if the platform doesn't support it.</p> +<p class="last"><tt class="docutils literal"><span class="pre">export_all</span></tt> is set if all of the module's symbols should be exported +rather than just the module's initialisation function. Exporting all +symbols increases the size of the module and slows down module load +times but may avoid problems with modules that use C++ exceptions. All +symbols are exported if either <tt class="docutils literal"><span class="pre">debug</span></tt> or <tt class="docutils literal"><span class="pre">static</span></tt> is set, or if +the platform doesn't support it.</p> +</dd> +<dt>finalise(self)</dt> +<dd>This is a reimplementation of <tt class="docutils literal"><span class="pre">sipconfig.Makefile.finalise()</span></tt>.</dd> +<dt>generate_macros_and_rules(self, mfile)</dt> +<dd>This is a reimplementation of +<tt class="docutils literal"><span class="pre">sipconfig.Makefile.generate_macros_and_rules()</span></tt>.</dd> +<dt>generate_target_clean(self, mfile)</dt> +<dd>This is a reimplementation of +<tt class="docutils literal"><span class="pre">sipconfig.Makefile.generate_target_clean()</span></tt>.</dd> +<dt>generate_target_default(self, mfile)</dt> +<dd>This is a reimplementation of +<tt class="docutils literal"><span class="pre">sipconfig.Makefile.generate_target_default()</span></tt>.</dd> +<dt>generate_target_install(self, mfile)</dt> +<dd>This is a reimplementation of +<tt class="docutils literal"><span class="pre">sipconfig.Makefile.generate_target_install()</span></tt>.</dd> +<dt>module_as_lib(self, mname)</dt> +<dd><p class="first">This returns the name of a SIP v3.x module for when it is used as a +library to be linked against. An exception will be raised if it is +used with SIP v4.x modules.</p> +<p><tt class="docutils literal"><span class="pre">mname</span></tt> is the name of the module.</p> +<p class="last">Returns the corresponding library name.</p> +</dd> +</dl> +</dd> +<dt>ParentMakefile(Makefile)</dt> +<dd><p class="first">This class encapsulates a Makefile that sits above a number of other +Makefiles in sub-directories.</p> +<dl class="last docutils"> +<dt>__init__(self, configuration, subdirs, dir=None, makefile="Makefile", installs=None)</dt> +<dd><p class="first">Initialise the instance.</p> +<p><tt class="docutils literal"><span class="pre">configuration</span></tt> - see <tt class="docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt>.</p> +<p><tt class="docutils literal"><span class="pre">subdirs</span></tt> is the sequence of sub-directories.</p> +<p><tt class="docutils literal"><span class="pre">dir</span></tt> - see <tt class="docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt>.</p> +<p><tt class="docutils literal"><span class="pre">makefile</span></tt> - see <tt class="docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt>.</p> +<p class="last"><tt class="docutils literal"><span class="pre">installs</span></tt> - see <tt class="docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt>.</p> +</dd> +<dt>generate_macros_and_rules(self, mfile)</dt> +<dd>This is a reimplementation of +<tt class="docutils literal"><span class="pre">sipconfig.Makefile.generate_macros_and_rules()</span></tt>.</dd> +<dt>generate_target_clean(self, mfile)</dt> +<dd>This is a reimplementation of +<tt class="docutils literal"><span class="pre">sipconfig.Makefile.generate_target_clean()</span></tt>.</dd> +<dt>generate_target_default(self, mfile)</dt> +<dd>This is a reimplementation of +<tt class="docutils literal"><span class="pre">sipconfig.Makefile.generate_target_default()</span></tt>.</dd> +<dt>generate_target_install(self, mfile)</dt> +<dd>This is a reimplementation of +<tt class="docutils literal"><span class="pre">sipconfig.Makefile.generate_target_install()</span></tt>.</dd> +</dl> +</dd> +<dt>ProgramMakefile(Makefile)</dt> +<dd><p class="first">This class encapsulates a Makefile to build an executable program.</p> +<dl class="last docutils"> +<dt>__init__(self, configuration, build_file=None, install_dir=None, console=0, qt=0, opengl=0, python=0, threaded=0, warnings=None, debug=0, dir=None, makefile="Makefile", installs=None, universal='')</dt> +<dd><p class="first">Initialise the instance.</p> +<p><tt class="docutils literal"><span class="pre">configuration</span></tt> - see <tt class="docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt>.</p> +<p><tt class="docutils literal"><span class="pre">build_file</span></tt> is the name of the optional build file. Build files are +generated using the <tt class="docutils literal"><span class="pre">-b</span></tt> SIP command line option.</p> +<p><tt class="docutils literal"><span class="pre">install_dir</span></tt> is the name of the directory where the executable +program will be optionally installed.</p> +<p><tt class="docutils literal"><span class="pre">console</span></tt> - see <tt class="docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt>.</p> +<p><tt class="docutils literal"><span class="pre">qt</span></tt> - see <tt class="docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt>.</p> +<p><tt class="docutils literal"><span class="pre">opengl</span></tt> - see <tt class="docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt>.</p> +<p><tt class="docutils literal"><span class="pre">python</span></tt> - see <tt class="docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt>.</p> +<p><tt class="docutils literal"><span class="pre">threaded</span></tt> - see <tt class="docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt>.</p> +<p><tt class="docutils literal"><span class="pre">warnings</span></tt> - see <tt class="docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt>.</p> +<p><tt class="docutils literal"><span class="pre">debug</span></tt> - see <tt class="docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt>.</p> +<p><tt class="docutils literal"><span class="pre">dir</span></tt> - see <tt class="docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt>.</p> +<p><tt class="docutils literal"><span class="pre">makefile</span></tt> - see <tt class="docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt>.</p> +<p class="last"><tt class="docutils literal"><span class="pre">installs</span></tt> - see <tt class="docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt>.</p> +</dd> +<dt>build_command(self, source)</dt> +<dd><p class="first">This creates a single command line that will create an executable +program from a single source file.</p> +<p><tt class="docutils literal"><span class="pre">source</span></tt> is the name of the source file.</p> +<p class="last">Returns a tuple of the name of the executable that will be created and +the command line.</p> +</dd> +<dt>finalise(self)</dt> +<dd>This is a reimplementation of <tt class="docutils literal"><span class="pre">sipconfig.Makefile.finalise()</span></tt>.</dd> +<dt>generate_macros_and_rules(self, mfile)</dt> +<dd>This is a reimplementation of +<tt class="docutils literal"><span class="pre">sipconfig.Makefile.generate_macros_and_rules()</span></tt>.</dd> +<dt>generate_target_clean(self, mfile)</dt> +<dd>This is a reimplementation of +<tt class="docutils literal"><span class="pre">sipconfig.Makefile.generate_target_clean()</span></tt>.</dd> +<dt>generate_target_default(self, mfile)</dt> +<dd>This is a reimplementation of +<tt class="docutils literal"><span class="pre">sipconfig.Makefile.generate_target_default()</span></tt>.</dd> +<dt>generate_target_install(self, mfile)</dt> +<dd>This is a reimplementation of +<tt class="docutils literal"><span class="pre">sipconfig.Makefile.generate_target_install()</span></tt>.</dd> +</dl> +</dd> +<dt>PythonModuleMakefile(Makefile)</dt> +<dd><p class="first">This class encapsulates a Makefile that installs a pure Python module.</p> +<dl class="last docutils"> +<dt>__init__(self, configuration, dstdir, srcdir=None, dir=None, makefile="Makefile", installs=None)</dt> +<dd><p class="first">Initialise the instance.</p> +<p><tt class="docutils literal"><span class="pre">configuration</span></tt> - see <tt class="docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt>.</p> +<p><tt class="docutils literal"><span class="pre">dstdir</span></tt> is the name of the directory in which the module's Python +code will be installed.</p> +<p><tt class="docutils literal"><span class="pre">srcdir</span></tt> is the name of the directory (relative to <tt class="docutils literal"><span class="pre">dir</span></tt>) +containing the module's Python code. It defaults to the same +directory.</p> +<p><tt class="docutils literal"><span class="pre">dir</span></tt> - see <tt class="docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt>.</p> +<p><tt class="docutils literal"><span class="pre">makefile</span></tt> - see <tt class="docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt>.</p> +<p class="last"><tt class="docutils literal"><span class="pre">installs</span></tt> - see <tt class="docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt>.</p> +</dd> +<dt>generate_macros_and_rules(self, mfile)</dt> +<dd>This is a reimplementation of +<tt class="docutils literal"><span class="pre">sipconfig.Makefile.generate_macros_and_rules()</span></tt>.</dd> +<dt>generate_target_install(self, mfile)</dt> +<dd>This is a reimplementation of +<tt class="docutils literal"><span class="pre">sipconfig.Makefile.generate_target_install()</span></tt>.</dd> +</dl> +</dd> +<dt>SIPModuleMakefile(ModuleMakefile)</dt> +<dd><p class="first">This class encapsulates a Makefile to build a SIP generated Python +extension module.</p> +<dl class="last docutils"> +<dt>finalise(self)</dt> +<dd>This is a reimplementation of <tt class="docutils literal"><span class="pre">sipconfig.Makefile.finalise()</span></tt>.</dd> +</dl> +</dd> +</dl> +</div> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id207" id="building-your-extension-with-distutils" name="building-your-extension-with-distutils">12 Building Your Extension with distutils</a></h1> +<p>To build the example in <a class="reference" href="#a-simple-c-example">A Simple C++ Example</a> using distutils, it is +sufficient to create a standard <tt class="docutils literal"><span class="pre">setup.py</span></tt>, listing <tt class="docutils literal"><span class="pre">word.sip</span></tt> among the +files to build, and hook-up SIP into distutils:</p> +<pre class="literal-block"> +from distutils.core import setup, Extension +import sipdistutils + +setup( + name = 'word', + versione = '1.0', + ext_modules=[ + Extension("word", ["word.sip", "word.cpp"]), + ], + + cmdclass = {'build_ext': sipdistutils.build_ext} +) +</pre> +<p>As we can see, the above is a normal distutils setup script, with just a +special line which is needed so that SIP can see and process <tt class="docutils literal"><span class="pre">word.sip</span></tt>. +Then, running <tt class="docutils literal"><span class="pre">setup.py</span> <span class="pre">build</span></tt> will build our extension module.</p> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id208" id="builtin-modules-and-custom-interpreters" name="builtin-modules-and-custom-interpreters">13 Builtin Modules and Custom Interpreters</a></h1> +<p>Sometimes you want to create a custom Python interpreter with some modules +built in to the interpreter itself rather than being dynamically loaded. To +do this the module must be created as a static library and linked with a +custom stub and the normal Python library.</p> +<p>To build the SIP module as a static library you must pass the <tt class="docutils literal"><span class="pre">-k</span></tt> command +line option to <tt class="docutils literal"><span class="pre">configure.py</span></tt>. You should then build and install SIP as +normal. (Note that, because the module is now a static library, you will not +be able to import it.)</p> +<p>To build a module you have created for your own library you must modify your +own configuration script to pass a non-zero value as the <tt class="docutils literal"><span class="pre">static</span></tt> argument +of the <tt class="docutils literal"><span class="pre">__init__()</span></tt> method of the <tt class="docutils literal"><span class="pre">ModuleMakefile</span></tt> class (or any derived +class you have created). Normally you would make this configurable using a +command line option in the same way that SIP's <tt class="docutils literal"><span class="pre">configure.py</span></tt> handles it.</p> +<p>The next stage is to create a custom stub and a Makefile. The SIP distribution +contains a directory called <tt class="docutils literal"><span class="pre">custom</span></tt> which contains example stubs and a +Python script that will create a correct Makefile. Note that, if your copy of +SIP was part of a standard Linux distribution, the <tt class="docutils literal"><span class="pre">custom</span></tt> directory may +not be installed on your system.</p> +<p>The <tt class="docutils literal"><span class="pre">custom</span></tt> directory contains the following files. They are provided as +examples - each needs to be modified according to your particular +requirements.</p> +<blockquote> +<ul class="simple"> +<li><tt class="docutils literal"><span class="pre">mkcustom.py</span></tt> is a Python script that will create a Makefile which is +then used to build the custom interpreter. Comments in the file describe +how it should be modified.</li> +<li><tt class="docutils literal"><span class="pre">custom.c</span></tt> is a stub for a custom interpreter on Linux/UNIX. It +should also be used for a custom console interpreter on Windows (i.e. +like <tt class="docutils literal"><span class="pre">python.exe</span></tt>). Comments in the file describe how it should be +modified.</li> +<li><tt class="docutils literal"><span class="pre">customw.c</span></tt> is a stub for a custom GUI interpreter on Windows (i.e. +like <tt class="docutils literal"><span class="pre">pythonw.exe</span></tt>). Comments in the file describe how it should be +modified.</li> +</ul> +</blockquote> +<p>Note that this technique does not restrict how the interpreter can be used. +For example, it still allows users to write their own applications that can +import your builtin modules. If you want to prevent users from doing that, +perhaps to protect a proprietary API, then take a look at the +<a class="reference" href="http://www.riverbankcomputing.co.uk/vendorid/">VendorID</a> package.</p> +</div> +</div> +</body> +</html> diff --git a/python/sip/doc/sipref.txt b/python/sip/doc/sipref.txt new file mode 100644 index 00000000..4e14f79e --- /dev/null +++ b/python/sip/doc/sipref.txt @@ -0,0 +1,5353 @@ +===================================================================== + SIP - A Tool for Generating Python Bindings for C and C++ Libraries +===================================================================== + +----------------- + Reference Guide +----------------- + +:Contact: info@riverbankcomputing.co.uk +:Version: 4.6 +:Copyright: Copyright (c) 2007 Riverbank Computing Limited + +.. contents:: +.. section-numbering:: + + +Introduction +============ + +This is the reference guide for SIP 4.6. SIP is a tool for +automatically generating `Python <http://www.python.org>`__ bindings for C and +C++ libraries. SIP was originally developed in 1998 for +`PyQt <http://www.riverbankcomputing.co.uk/pyqt/>`__ - the Python bindings for +the Qt GUI toolkit - but is suitable for generating bindings for any C or C++ +library. + +This version of SIP generates bindings for Python v2.3 or later. + +There are many other similar tools available. One of the original such tools +is `SWIG <http://www.swig.org>`__ and, in fact, SIP is so called because it +started out as a small SWIG. Unlike SWIG, SIP is specifically designed for +bringing together Python and C/C++ and goes to great lengths to make the +integration as tight as possible. + +The homepage for SIP is http://www.riverbankcomputing.co.uk/sip/. Here you +will always find the latest stable version, current development snapshots, and +the latest version of this documentation. + + +License +------- + +SIP is licensed under the same terms as Python itself. SIP places no +restrictions on the license you may apply to the bindings you create. + + +Features +-------- + +SIP, and the bindings it produces, have the following features. + + - bindings are fast to load and minimise memory consumption especially when + only a small sub-set of a large library is being used + + - automatic conversion between standard Python and C/C++ data types + + - overloading of functions and methods with different argument signatures + + - access to a C++ class's protected methods + + - the ability to define a Python class that is a sub-class of a C++ class, + including abstract C++ classes + + - Python sub-classes can implement the ``__dtor__(self)`` method which + will be called from the C++ class's virtual destructor + + - support for ordinary C++ functions, class methods, static class methods, + virtual class methods and abstract class methods + + - the ability to re-implement C++ virtual and abstract methods in Python + + - support for global and class variables + + - support for global and class operators + + - support for C++ namespaces + + - support for C++ templates + + - support for C++ exceptions and wrapping them as Python exceptions + + - the ability to define mappings between C++ classes and similar Python + data types that are automatically invoked + + - the ability to automatically exploit any available run time type + information to ensure that the class of a Python instance object matches + the class of the corresponding C++ instance + + - full support of the Python global interpreter lock, including the ability + to specify that a C++ function of method may block, therefore allowing + the lock to be released and other Python threads to run + + - support for the concept of ownership of a C++ instance (i.e. what part of + the code is responsible for calling the instance's destructor) and how + the ownership may change during the execution of an application + + - the ability to generate bindings for a C++ class library that itself is + built on another C++ class library which also has had bindings generated + so that the different bindings integrate and share code properly + + - a sophisticated versioning system that allows the full lifetime of a C++ + class library, including any platform specific or optional features, to + be described in a single set of specification files + + - the ability to include documentation in the specification files which can + be extracted and subsequently processed by external tools + + - the ability to include copyright notices and licensing information in the + specification files that is automatically included in all generated + source code + + - a build system, written in Python, that you can extend to configure, + compile and install your own bindings without worrying about platform + specific issues + + - support for building your extensions using distutils + + - SIP, and the bindings it produces, runs under UNIX, Linux, Windows and + MacOS/X + + +SIP Components +-------------- + +SIP comprises a number of different components. + + - The SIP code generator (``sip`` or ``sip.exe``). This processes ``.sip`` + specification files and generates C or C++ bindings. It is covered in + detail in `Using SIP`_. + + - The SIP header file (``sip.h``). This contains definitions and data + structures needed by the generated C and C++ code. + + - The SIP module (``sip.so`` or ``sip.pyd``). This is a Python extension + module that is imported automatically by SIP generated bindings and + provides them with some common utility functions. See also `Using the + SIP Module in Applications`_. + + - The SIP build system (``sipconfig.py``). This is a pure Python module + that is created when SIP is configured and encapsulates all the necessary + information about your system including relevant directory names, + compiler and linker flags, and version numbers. It also includes several + Python classes and functions which help you write configuration scripts + for your own bindings. It is covered in detail in `The SIP Build + System`_. + + - The SIP distutils extension (``sipdistutils.py``). This is a distutils + extension that can be used to build your extension modules using + distutils and is an alternative to writing configuration scripts with the + SIP build system. This can be as simple as adding your .sip files to the + list of files needed to build the extension module. It is covered in + detail in `Building Your Extension with distutils`_. + + +Qt Support +---------- + +SIP has specific support for the creation of bindings based on Trolltech's Qt +toolkit. + +The SIP code generator understands the signal/slot type safe callback mechanism +that Qt uses to connect objects together. This allows applications to define +new Python signals, and allows any Python callable object to be used as a slot. + +SIP itself does not require Qt to be installed. + + +Potential Incompatibilities with Earlier Versions +================================================= + +SIP v4.4 +-------- + + - The ``SIP_BUILD`` C preprocessor symbol has been removed. + + - `sipConvertToCpp()`_, `sipIsSubClassInstance()`_ and the old `Generated + Type Convertors`_ have been deprecated. The functions + `sipCanConvertToInstance()`_, `sipConvertToInstance()`_, + `sipForceConvertToInstance()`_, `sipConvertFromInstance()`_, + `sipConvertFromNewInstance()`_, `sipCanConvertToMappedType()`_, + `sipConvertToMappedType()`_, `sipForceConvertToMappedType()`_ and + `sipConvertFromMappedType()`_ should be used instead. Handwritten + `%ConvertFromTypeCode`_ and `%ConvertToTypeCode`_ now has the + responsibility for using these to implement the ``Transfer`` and + ``TransferBack`` annotations. + + +Installing SIP +============== + +Downloading SIP +--------------- + +You can get the latest release of the SIP source code from +http://www.riverbankcomputing.co.uk/sip/download.php. + +SIP is also included with all of the major Linux distributions. However, it +may be a version or two out of date. + +You may also find more up to date pre-compiled binaries on +`SourceForge <http://sourceforge.net/project/showfiles.php?group_id=61057>`_. + + +Configuring SIP +--------------- + +After unpacking the source package (either a ``.tar.gz`` or a ``.zip`` file +depending on your platform) you should then check for any ``README`` files +that relate to your platform. + +Next you need to configure SIP by executing the ``configure.py`` script. For +example:: + + python configure.py + +This assumes that the Python interpreter is on your path. Something like the +following may be appropriate on Windows:: + + c:\python25\python configure.py + +If you have multiple versions of Python installed then make sure you use the +interpreter for which you wish SIP to generate bindings for. + +The full set of command line options is: + +-h Display a help message. +-a Export all symbols in any SIP generated module and the SIP module + itself. This was the default behaviour of SIP prior to v4.2. + Normally only a module's inititialisation function is exported. This + option is deprecated as the ``ModuleMakefile`` class of `The SIP Build + System`_ allows this to be specified on a per module basis. +-b dir The SIP code generator will be installed in the directory ``dir``. +-d dir The SIP module will be installed in the directory ``dir``. +-e dir The SIP header file will be installed in the directory ``dir``. +-k The SIP module will be built as a static library. This is useful when + building the SIP module as a Python builtin (see + `Builtin Modules and Custom Interpreters`_). +-n The SIP code generator and module will be built as universal binaries + under MacOS/X. +-p plat Explicitly specify the platform/compiler to be used by the build + system, otherwise a platform specific default will be used. The + ``-h`` option will display all the supported platform/compilers and + the default. +-u The SIP module will be built with debugging symbols. +-v dir By default ``.sip`` files will be installed in the directory ``dir``. + +The configure.py script takes many other options that allows the build system +to be finely tuned. These are of the form ``name=value`` or ``name+=value``. +The ``-h`` option will display each supported ``name``, although not all are +applicable to all platforms. + +The ``name=value`` form means that ``value`` will replace the existing value of +``name``. + +The ``name+=value`` form means that ``value`` will be appended to the existing +value of ``name``. + +For example, the following will disable support for C++ exceptions (and so +reduce the size of module binaries) when used with GCC:: + + python configure.py CXXFLAGS+=-fno-exceptions + +A pure Python module called ``sipconfig.py`` is generated by ``configure.py``. +This defines each ``name`` and its corresponding ``value``. Looking at it will +give you a good idea of how the build system uses the different options. It is +covered in detail in `The SIP Build System`_. + + +Configuring SIP Using MinGW +*************************** + +SIP, and the modules it generates, can be built with MinGW, the Windows port of +GCC. You must use the ``-p`` command line option to specify the correct +platform. For example:: + + c:\python25\python configure.py -p win32-g++ + + +Configuring SIP Using the Borland C++ Compiler +********************************************** + +SIP, and the modules it generates, can be built with the free Borland C++ +compiler. You must use the ``-p`` command line option to specify the correct +platform. For example:: + + c:\python25\python configure.py -p win32-borland + +You must also make sure you have a Borland-compatible version of the Python +library. If you are using the standard Python distribution (built using the +Microsoft compiler) then you must convert the format of the Python library. +For example:: + + coff2omf python25.lib python25_bcpp.lib + + +Building SIP +------------ + +The next step is to build SIP by running your platform's ``make`` command. For +example:: + + make + +The final step is to install SIP by running the following command:: + + make install + +(Depending on your system you may require root or administrator privileges.) + +This will install the various SIP components. + + +Using SIP +========= + +Bindings are generated by the SIP code generator from a number of specification +files, typically with a ``.sip`` extension. Specification files look very +similar to C and C++ header files, but often with additional information (in +the form of a *directive* or an *annotation*) and code so that the bindings +generated can be finely tuned. + + +A Simple C++ Example +-------------------- + +We start with a simple example. Let's say you have a (fictional) C++ library +that implements a single class called ``Word``. The class has one constructor +that takes a ``\0`` terminated character string as its single argument. The +class has one method called ``reverse()`` which takes no arguments and returns +a ``\0`` terminated character string. The interface to the class is defined in +a header file called ``word.h`` which might look something like this:: + + // Define the interface to the word library. + + class Word { + const char *the_word; + + public: + Word(const char *w); + + char *reverse() const; + }; + +The corresponding SIP specification file would then look something like this:: + + // Define the SIP wrapper to the word library. + + %Module word 0 + + class Word { + + %TypeHeaderCode + #include <word.h> + %End + + public: + Word(const char *w); + + char *reverse() const; + }; + +Obviously a SIP specification file looks very much like a C++ (or C) header +file, but SIP does not include a full C++ parser. Let's look at the +differences between the two files. + + - The `%Module`_ directive has been added [#]_. This is used to name the + Python module that is being created and to give it a *generation* number. + In this example these are ``word`` and ``0`` respectively. The + generation number is effectively the version number of the module. + + - The `%TypeHeaderCode`_ directive has been added. The text between this + and the following `%End`_ directive is included literally in the code + that SIP generates. Normally it is used, as in this case, to + ``#include`` the corresponding C++ (or C) header file [#]_. + + - The declaration of the private variable ``this_word`` has been removed. + SIP does not support access to either private or protected instance + variables. + +If we want to we can now generate the C++ code in the current directory by +running the following command:: + + sip -c . word.sip + +However, that still leaves us with the task of compiling the generated code and +linking it against all the necessary libraries. It's much easier to use the +SIP build system to do the whole thing. + +Using the SIP build system is simply a matter of writing a small Python script. +In this simple example we will assume that the ``word`` library we are wrapping +and it's header file are installed in standard system locations and will be +found by the compiler and linker without having to specify any additional +flags. In a more realistic example your Python script may take command line +options, or search a set of directories to deal with different configurations +and installations. + +This is the simplest script (conventionally called ``configure.py``):: + + import os + import sipconfig + + # The name of the SIP build file generated by SIP and used by the build + # system. + build_file = "word.sbf" + + # Get the SIP configuration information. + config = sipconfig.Configuration() + + # Run SIP to generate the code. + os.system(" ".join([config.sip_bin, "-c", ".", "-b", build_file, "word.sip"])) + + # Create the Makefile. + makefile = sipconfig.SIPModuleMakefile(config, build_file) + + # Add the library we are wrapping. The name doesn't include any platform + # specific prefixes or extensions (e.g. the "lib" prefix on UNIX, or the + # ".dll" extension on Windows). + makefile.extra_libs = ["word"] + + # Generate the Makefile itself. + makefile.generate() + +Hopefully this script is self-documenting. The key parts are the +``Configuration`` and ``SIPModuleMakefile`` classes. The build system contains +other Makefile classes, for example to build programs or to call other +Makefiles in sub-directories. + +After running the script (using the Python interpreter the extension module is +being created for) the generated C++ code and ``Makefile`` will be in the +current directory. + +To compile and install the extension module, just run the following +commands [#]_:: + + make + make install + +That's all there is to it. + +See `Building Your Extension with distutils`_ for an example of how to build +this example using distutils. + +.. [#] All SIP directives start with a ``%`` as the first non-whitespace + character of a line. +.. [#] SIP includes many code directives like this. They differ in where the + supplied code is placed by SIP in the generated code. +.. [#] On Windows you might run ``nmake`` or ``mingw32-make`` instead. + + +A Simple C Example +------------------ + +Let's now look at a very similar example of wrapping a fictional C library:: + + /* Define the interface to the word library. */ + + struct Word { + const char *the_word; + }; + + struct Word *create_word(const char *w); + char *reverse(struct Word *word); + +The corresponding SIP specification file would then look something like this:: + + /* Define the SIP wrapper to the word library. */ + + %CModule word 0 + + struct Word { + + %TypeHeaderCode + #include <word.h> + %End + + const char *the_word; + }; + + struct Word *create_word(const char *w) /Factory/; + char *reverse(struct Word *word); + +Again, let's look at the differences between the two files. + + - The `%CModule`_ directive has been added. This has the same syntax as + the `%Module`_ directive used in the previous example but tells SIP that + the library being wrapped is implemented in C rather than C++. + + - The `%TypeHeaderCode`_ directive has been added. + + - The Factory_ annotation has been added to the ``create_word()`` function. + This tells SIP that a newly created structure is being returned and it is + owned by Python. + +The ``configure.py`` build system script described in the previous example can +be used for this example without change. + + +A More Complex C++ Example +-------------------------- + +In this last example we will wrap a fictional C++ library that contains a class +that is derived from a Qt class. This will demonstrate how SIP allows a class +hierarchy to be split across multiple Python extension modules, and will +introduce SIP's versioning system. + +The library contains a single C++ class called ``Hello`` which is derived from +Qt's ``QLabel`` class. It behaves just like ``QLabel`` except that the text +in the label is hard coded to be ``Hello World``. To make the example more +interesting we'll also say that the library only supports Qt v3.0 and later, +and also includes a function called ``setDefault()`` that is not implemented +in the Windows version of the library. + +The ``hello.h`` header file looks something like this:: + + // Define the interface to the hello library. + + #include <qlabel.h> + #include <qwidget.h> + #include <qstring.h> + + class Hello : public QLabel { + // This is needed by the Qt Meta-Object Compiler. + Q_OBJECT + + public: + Hello(QWidget *parent, const char *name = 0, WFlags f = 0); + + private: + // Prevent instances from being copied. + Hello(const Hello &); + Hello &operator=(const Hello &); + }; + + #if !defined(Q_OS_WIN) + void setDefault(const QString &def); + #endif + +The corresponding SIP specification file would then look something like this:: + + // Define the SIP wrapper to the hello library. + + %Module hello 0 + + %Import qt/qtmod.sip + + %If (Qt_3_0_0 -) + + class Hello : QLabel { + + %TypeHeaderCode + #include <hello.h> + %End + + public: + Hello(QWidget *parent /TransferThis/, const char *name = 0, WFlags f = 0); + + private: + Hello(const Hello &); + }; + + %If (!WS_WIN) + void setDefault(const QString &def); + %End + + %End + +Again we look at the differences, but we'll skip those that we've looked at in +previous examples. + + - The `%Import`_ directive has been added to specify that we are extending + the class hierarchy defined in the file ``qt/qtmod.sip``. This file is + part of PyQt. The build system will take care of finding the file's + exact location. + + - The `%If`_ directive has been added to specify that + everything [#]_ up to the matching `%End`_ directive only applies to Qt + v3.0 and later. ``Qt_3_0_0`` is a *tag* defined in ``qtmod.sip`` [#]_ + using the `%Timeline`_ directive. `%Timeline`_ is used to define a tag + for each version of a library's API you are wrapping allowing you to + maintain all the different versions in a single SIP specification. The + build system provides support to ``configure.py`` scripts for working out + the correct tags to use according to which version of the library is + actually installed. + + - The ``public`` keyword used in defining the super-classes has been + removed. This is not supported by SIP. + + - The TransferThis_ annotation has been added to the first argument + of the constructor. It specifies that if the argument is not 0 (i.e. the + ``Hello`` instance being constructed has a parent) then ownership of the + instance is transferred from Python to C++. It is needed because Qt + maintains objects (i.e. instances derived from the ``QObject`` class) in + a hierachy. When an object is destroyed all of its children are also + automatically destroyed. It is important, therefore, that the Python + garbage collector doesn't also try and destroy them. This is covered in + more detail in `Ownership of Objects`_. SIP provides many other + annotations that can be applied to arguments, functions and classes. + Multiple annotations are separated by commas. Annotations may have + values. + + - The ``=`` operator has been removed. This operator is not supported by + SIP. + + - The `%If`_ directive has been added to specify that everything up to the + matching `%End`_ directive does not apply to Windows. ``WS_WIN`` is + another tag defined by PyQt, this time using the `%Platforms`_ directive. + Tags defined by the `%Platforms`_ directive are mutually exclusive, i.e. + only one may be valid at a time [#]_. + +One question you might have at this point is why bother to define the private +copy constructor when it can never be called from Python? The answer is to +prevent the automatic generation of a public copy constructor. + +We now look at the ``configure.py`` script. This is a little different to the +script in the previous examples for two related reasons. + +Firstly, PyQt includes a pure Python module called ``pyqtconfig`` that extends +the SIP build system for modules, like our example, that build on top of PyQt. +It deals with the details of which version of Qt is being used (i.e. it +determines what the correct tags are) and where it is installed. This is +called a module's configuration module. + +Secondly, we generate a configuration module (called ``helloconfig``) for our +own ``hello`` module. There is no need to do this, but if there is a chance +that somebody else might want to extend your C++ library then it would make +life easier for them. + +Now we have two scripts. First the ``configure.py`` script:: + + import os + import sipconfig + import pyqtconfig + + # The name of the SIP build file generated by SIP and used by the build + # system. + build_file = "hello.sbf" + + # Get the PyQt configuration information. + config = pyqtconfig.Configuration() + + # Get the extra SIP flags needed by the imported qt module. Note that + # this normally only includes those flags (-x and -t) that relate to SIP's + # versioning system. + qt_sip_flags = config.pyqt_qt_sip_flags + + # Run SIP to generate the code. Note that we tell SIP where to find the qt + # module's specification files using the -I flag. + os.system(" ".join([config.sip_bin, "-c", ".", "-b", build_file, "-I", config.pyqt_sip_dir, qt_sip_flags, "hello.sip"])) + + # We are going to install the SIP specification file for this module and + # its configuration module. + installs = [] + + installs.append(["hello.sip", os.path.join(config.default_sip_dir, "hello")]) + + installs.append(["helloconfig.py", config.default_mod_dir]) + + # Create the Makefile. The QtModuleMakefile class provided by the + # pyqtconfig module takes care of all the extra preprocessor, compiler and + # linker flags needed by the Qt library. + makefile = pyqtconfig.QtModuleMakefile( + configuration=config, + build_file=build_file, + installs=installs + ) + + # Add the library we are wrapping. The name doesn't include any platform + # specific prefixes or extensions (e.g. the "lib" prefix on UNIX, or the + # ".dll" extension on Windows). + makefile.extra_libs = ["hello"] + + # Generate the Makefile itself. + makefile.generate() + + # Now we create the configuration module. This is done by merging a Python + # dictionary (whose values are normally determined dynamically) with a + # (static) template. + content = { + # Publish where the SIP specifications for this module will be + # installed. + "hello_sip_dir": config.default_sip_dir, + + # Publish the set of SIP flags needed by this module. As these are the + # same flags needed by the qt module we could leave it out, but this + # allows us to change the flags at a later date without breaking + # scripts that import the configuration module. + "hello_sip_flags": qt_sip_flags + } + + # This creates the helloconfig.py module from the helloconfig.py.in + # template and the dictionary. + sipconfig.create_config_module("helloconfig.py", "helloconfig.py.in", content) + +Next we have the ``helloconfig.py.in`` template script:: + + import pyqtconfig + + # These are installation specific values created when Hello was configured. + # The following line will be replaced when this template is used to create + # the final configuration module. + # @SIP_CONFIGURATION@ + + class Configuration(pyqtconfig.Configuration): + """The class that represents Hello configuration values. + """ + def __init__(self, sub_cfg=None): + """Initialise an instance of the class. + + sub_cfg is the list of sub-class configurations. It should be None + when called normally. + """ + # This is all standard code to be copied verbatim except for the + # name of the module containing the super-class. + if sub_cfg: + cfg = sub_cfg + else: + cfg = [] + + cfg.append(_pkg_config) + + pyqtconfig.Configuration.__init__(self, cfg) + + class HelloModuleMakefile(pyqtconfig.QtModuleMakefile): + """The Makefile class for modules that %Import hello. + """ + def finalise(self): + """Finalise the macros. + """ + # Make sure our C++ library is linked. + self.extra_libs.append("hello") + + # Let the super-class do what it needs to. + pyqtconfig.QtModuleMakefile.finalise(self) + +Again, we hope that the scripts are self documenting. + +.. [#] Some parts of a SIP specification aren't subject to version control. +.. [#] Actually in ``versions.sip``. PyQt uses the `%Include`_ directive to + split the SIP specification for Qt across a large number of separate + ``.sip`` files. +.. [#] Tags can also be defined by the `%Feature`_ directive. These tags are + not mutually exclusive, i.e. any number may be valid at a time. + + +Ownership of Objects +-------------------- + +When a C++ instance is wrapped a corresponding Python object is created. The +Python object behaves as you would expect in regard to garbage collection - it +is garbage collected when its reference count reaches zero. What then happens +to the corresponding C++ instance? The obvious answer might be that the +instance's destructor is called. However the library API may say that when the +instance is passed to a particular function, the library takes ownership of the +instance, i.e. responsibility for calling the instance's destructor is +transferred from the SIP generated module to the library. + +Ownership of an instance may also be associated with another instance. The +implication being that the owned instance will automatically be destroyed if +the owning instance is destroyed. SIP keeps track of these relationships to +ensure that Python's cyclic garbage collector can detect and break any +reference cycles between the owning and owned instances. The association is +implemented as the owning instance taking a reference to the owned instance. + +The TransferThis_, Transfer_ and TransferBack annotations are used to specify +where, and it what direction, transfers of ownership happen. It is very +important that these are specified correctly to avoid crashes (where both +Python and C++ call the destructor) and memory leaks (where neither Python and +C++ call the destructor). + +This applies equally to C structures where the structure is returned to the +heap using the ``free()`` function. + +See also `sipTransferTo()`_ and `sipTransferBack()`_. + + +Support for Wide Characters +--------------------------- + +SIP v4.6 introduced support for wide characters (i.e. the ``wchar_t`` type). +Python's C API includes support for converting between unicode objects and wide +character strings and arrays. When converting from a unicode object to wide +characters SIP creates the string or array on the heap (using memory allocated +using `sipMalloc()`_). This then raises the problem of how this memory is +subsequently freed. + +The following describes how SIP handles this memory in the different situations +where this is an issue. + + - When a wide string or array is passed to a function or method then the + memory is freed (using `sipFree()`_) after than function or method + returns. + + - When a wide string or array is returned from a virtual method then SIP + does not free the memory until the next time the method is called. + + - When an assignment is made to a wide string or array instance variable + then SIP does not first free the instance's current string or array. + + +The Python Global Interpreter Lock +---------------------------------- + +Python's Global Interpretor Lock (GIL) must be acquired before calls can be +made to the Python API. It should also be released when a potentially +blocking call to C/C++ library is made in order to allow other Python threads +to be executed. In addition, some C/C++ libraries may implement their own +locking strategies that conflict with the GIL causing application deadlocks. +SIP provides ways of specifying when the GIL is released and acquired to +ensure that locking problems can be avoided. + +SIP always ensures that the GIL is acquired before making calls to the Python +API. By default SIP does not release the GIL when making calls to the C/C++ +library being wrapped. The ReleaseGIL_ annotation can be used to override +this behaviour when required. + +If SIP is given the ``-g`` command line option then the default behaviour is +changed and SIP releases the GIL every time is makes calls to the C/C++ +library being wrapped. The HoldGIL_ annotation can be used to override this +behaviour when required. + + +The SIP Command Line +==================== + +The syntax of the SIP command line is:: + + sip [options] [specification] + +``specification`` is the name of the specification file for the module. If it +is omitted then ``stdin`` is used. + +The full set of command line options is: + +-h Display a help message. +-V Display the SIP version number. +-a file + The name of the QScintilla API file to generate. This file contains a + description of the module API in a form that the QScintilla editor + component can use for auto-completion and call tips. (The file may + also be used by the SciTE editor but must be sorted first.) By default + the file is not generated. +-b file + The name of the build file to generate. This file contains the + information about the module needed by the SIP build system to generate + a platform and compiler specific Makefile for the module. By default + the file is not generated. +-c dir The name of the directory (which must exist) into which all of the + generated C or C++ code is placed. By default no code is generated. +-d file + The name of the documentation file to generate. Documentation is + included in specification files using the `%Doc`_ and `%ExportedDoc`_ + directives. By default the file is not generated. +-e Support for C++ exceptions is enabled. This causes all calls to C++ + code to be enclosed in ``try``/``catch`` blocks and C++ exceptions to + be converted to Python exceptions. By default exception support is + disabled. +-g The Python GIL is released before making any calls to the C/C++ library + being wrapped and reacquired afterwards. See `The Python Global + Interpreter Lock`_ and the ReleaseGIL_ and HoldGIL_ annotations. +-I dir The directory is added to the list of directories searched when looking + for a specification file given in an `%Include`_ or `%Import`_ + directive. This option may be given any number of times. +-j number + The generated code is split into the given number of files. This make + it easier to use the parallel build facility of most modern + implementations of ``make``. By default 1 file is generated for each C + structure or C++ class. +-r Debugging statements that trace the execution of the bindings are + automatically generated. By default the statements are not generated. +-s suffix + The suffix to use for generated C or C++ source files. By default + ``.c`` is used for C and ``.cpp`` for C++. +-t tag The SIP version tag (declared using a `%Timeline`_ directive) or the + SIP platform tag (declared using the `%Platforms`_ directive) to + generate code for. This option may be given any number of times so + long as the tags do not conflict. +-w The display of warning messages is enabled. By default warning + messages are disabled. +-x feature + The feature (declared using the `%Feature`_ directive) is disabled. +-z file + The name of a file containing more command line options. + + +SIP Specification Files +======================= + +A SIP specification consists of some C/C++ type and function declarations and +some directives. The declarations may contain annotations which provide SIP +with additional information that cannot be expressed in C/C++. SIP does not +include a full C/C++ parser. + +It is important to understand that a SIP specification describes the Python +API, i.e. the API available to the Python programmer when they ``import`` the +generated module. It does not have to accurately represent the underlying +C/C++ library. There is nothing wrong with omitting functions that make +little sense in a Python context, or adding functions implemented with +handwritten code that have no C/C++ equivalent. It is even possible (and +sometimes necessary) to specify a different super-class hierarchy for a C++ +class. All that matters is that the generated code compiles properly. + +In most cases the Python API matches the C/C++ API. In some cases handwritten +code (see `%MethodCode`_) is used to map from one to the other without SIP +having to know the details itself. However, there are a few cases where SIP +generates a thin wrapper around a C++ method or constructor (see `Generated +Derived Classes`_) and needs to know the exact C++ signature. To deal with +these cases SIP allows two signatures to be specified. For example:: + + class Klass + { + public: + // The Python signature is a tuple, but the underlying C++ signature + // is a 2 element array. + Klass(SIP_PYTUPLE) [(int *)]; + %MethodCode + int iarr[2]; + + if (PyArg_ParseTuple(a0, "ii", &iarr[0], &iarr[1])) + { + // Note that we use the SIP generated derived class + // constructor. + Py_BEGIN_ALLOW_THREADS + sipCpp = new sipKlass(iarr); + Py_END_ALLOW_THREADS + } + %End + }; + + +Syntax Definition +----------------- + +The following is a semi-formal description of the syntax of a specification +file. + +.. parsed-literal:: + + *specification* ::= {*module-statement*} + + *module-statement* ::= [*module-directive* | *statement*] + + *module-directive* ::= [`%CModule`_ | `%Copying`_ | `%Doc`_ | + `%ExportedDoc`_ | `%ExportedHeaderCode`_ | `%Feature`_ | + `%Import`_ | `%Include`_ | `%License`_ | `%MappedType`_ | + *mapped-type-template* | `%Module`_ | `%ModuleCode`_ | + `%ModuleHeaderCode`_ | `%OptionalInclude`_ | `%Platforms`_ | + `%PreInitialisationCode`_ | `%PostInitialisationCode`_ | + *sip-option-list* | `%Timeline`_ | `%UnitCode`_] + + *sip-option-list* :: `%SIPOptions`_ ``(`` *option-list* ``)`` + + *option-list* ::= *option* [``,`` *option-list*] + + *statement* :: [*class-statement* | *function* | *variable*] + + *class-statement* :: [`%If`_ | *class* | *class-template* | *enum* | + *namespace* | *opaque-class* | *operator* | *struct* | *typedef* | + *exception*] + + *class* ::= ``class`` *name* [``:`` *super-classes*] [*class-annotations*] + ``{`` {*class-line*} ``};`` + + *super-classes* ::= *name* [``,`` *super-classes*] + + *class-line* ::= [*class-statement* | `%BIGetReadBufferCode`_ | + `%BIGetWriteBufferCode`_ | `%BIGetSegCountCode`_ | + `%BIGetCharBufferCode`_ | `%ConvertToSubClassCode`_ | + `%ConvertToTypeCode`_ | `%GCClearCode`_ | `%GCTraverseCode`_ | + `%TypeCode`_ | `%TypeHeaderCode`_ | *constructor* | *destructor* | + *method* | *static-method* | *virtual-method* | *special-method* | + *operator* | *virtual-operator* | *class-variable* | ``public:`` | + ``public slots:`` | ``protected:`` | ``protected slots:`` | + ``private:`` | ``private slots:`` | ``signals:``] + + *constructor* ::= [``explicit``] *name* ``(`` [*argument-list*] ``)`` + [*exceptions*] [*function-annotations*] + [*c++-constructor-signature*] ``;`` [`%MethodCode`_] + + *c++-constructor-signature* ::= ``[(`` [*argument-list*] ``)]`` + + *destructor* ::= [``virtual``] ``~`` *name* ``()`` [*exceptions*] [``= 0``] + [*function-annotations*] ``;`` [`%MethodCode`_] + [`%VirtualCatcherCode`_] + + *method* ::= *type* *name* ``(`` [*argument-list*] ``)`` [``const``] + [*exceptions*] [``= 0``] [*function-annotations*] [*c++-signature*] + ``;`` [`%MethodCode`_] + + *c++-signature* ::= ``[`` *type* ``(`` [*argument-list*] ``)]`` + + *static-method* ::= ``static`` *function* + + *virtual-method* ::= ``virtual`` *type* *name* ``(`` [*argument-list*] ``)`` + [``const``] [*exceptions*] [``= 0``] [*function-annotations*] + [*c++-signature*] ``;`` [`%MethodCode`_] [`%VirtualCatcherCode`_] + + *special-method* ::= *type* *special-method-name* + ``(`` [*argument-list*] ``)`` [*function-annotations*] ``;`` + [`%MethodCode`_] + + *special-method-name* ::= [ ``__abs__`` | ``__add__`` | ``__and__`` | + ``__call__`` | ``__cmp__`` | ``__contains__`` | ``__delitem__`` | + ``__div__`` | ``__eq__`` | ``__float__`` | ``__ge__`` | + ``__getitem__`` | ``__gt__`` | ``__hash__`` | ``__iadd__`` | + ``__iand__`` | ``__idiv__`` | ``__ilshift__`` | ``__imod__`` | + ``__imul__`` | ``__int__`` | ``__invert__`` | ``__ior__`` | + ``__irshift__`` | ``__isub__`` | ``__ixor__`` | ``__le__`` | + ``__len__`` | ``__long__`` | ``__lshift__`` | ``__lt__`` | + ``__mod__`` | ``__mul__`` | ``__ne__`` | ``__neg__`` | + ``__nonzero__`` | ``__or__`` | ``__pos__`` | ``__repr__`` | + ``__rshift__`` | ``__setitem__`` | ``__str__`` | ``__sub__`` | + ``__xor__``] + + *operator* ::= *operator-type* + ``(`` [*argument-list*] ``)`` [``const``] [*exceptions*] + [*function-annotations*] ``;`` [`%MethodCode`_] + + *virtual-operator* ::= ``virtual`` *operator-type* + ``(`` [*argument-list*] ``)`` [``const``] [*exceptions*] [``= 0``] + [*function-annotations*] ``;`` [`%MethodCode`_] + [`%VirtualCatcherCode`_] + + *operatator-type* ::= [ *operator-function* | *operator-cast* ] + + *operator-function* ::= *type* ``operator`` *operator-name* + + *operator-cast* ::= ``operator`` *type* + + *operator-name* ::= [``+`` | ``-`` | ``*`` | ``/`` | ``%`` | ``&`` | + ``|`` | ``^`` | ``<<`` | ``>>`` | ``+=`` | ``-=`` | ``*=`` | + ``/=`` | ``%=`` | ``&=`` | ``|=`` | ``^=`` | ``<<=`` | ``>>=`` | + ``~`` | ``()`` | ``[]`` | ``<`` | ``<=`` | ``==`` | ``!=`` | + ``>`` | ``>>=``] + + *class-variable* ::= [``static``] *variable* + + *class-template* :: = ``template`` ``<`` *type-list* ``>`` *class* + + *mapped-type-template* :: = ``template`` ``<`` *type-list* ``>`` + `%MappedType`_ + + *enum* ::= ``enum`` [*name*] [*enum-annotations*] ``{`` {*enum-line*} ``};`` + + *enum-line* ::= [`%If`_ | *name* [*enum-annotations*] ``,`` + + *function* ::= *type* *name* ``(`` [*argument-list*] ``)`` [*exceptions*] + [*function-annotations*] ``;`` [`%MethodCode`_] + + *namespace* ::= ``namespace`` *name* ``{`` {*namespace-line*} ``};`` + + *namespace-line* ::= [`%TypeHeaderCode`_ | *statement*] + + *opaque-class* ::= ``class`` *scoped-name* ``;`` + + *struct* ::= ``struct`` *name* ``{`` {*class-line*} ``};`` + + *typedef* ::= ``typedef`` [*typed-name* | *function-pointer*] ``;`` + + *variable*::= *typed-name* [*variable-annotations*] ``;`` [`%AccessCode`_] + [`%GetCode`_] [`%SetCode`_] + + *exception* ::= `%Exception`_ *exception-name* [*exception-base*] ``{`` + [`%TypeHeaderCode`_] `%RaiseCode`_ `};`` + + *exception-name* ::= *scoped-name* + + *exception-base* ::= ``(`` [*exception-name* | *python-exception*] ``)`` + + *python-exception* ::= [``SIP_Exception`` | ``SIP_StopIteration`` | + ``SIP_StandardError`` | ``SIP_ArithmeticError`` | + ``SIP_LookupError`` | ``SIP_AssertionError`` | + ``SIP_AttributeError`` | ``SIP_EOFError`` | + ``SIP_FloatingPointError`` | ``SIP_EnvironmentError`` | + ``SIP_IOError`` | ``SIP_OSError`` | ``SIP_ImportError`` | + ``SIP_IndexError`` | ``SIP_KeyError`` | ``SIP_KeyboardInterrupt`` | + ``SIP_MemoryError`` | ``SIP_NameError`` | ``SIP_OverflowError`` | + ``SIP_RuntimeError`` | ``SIP_NotImplementedError`` | + ``SIP_SyntaxError`` | ``SIP_IndentationError`` | ``SIP_TabError`` | + ``SIP_ReferenceError`` | ``SIP_SystemError`` | ``SIP_SystemExit`` | + ``SIP_TypeError`` | ``SIP_UnboundLocalError`` | + ``SIP_UnicodeError`` | ``SIP_UnicodeEncodeError`` | + ``SIP_UnicodeDecodeError`` | ``SIP_UnicodeTranslateError`` | + ``SIP_ValueError`` | ``SIP_ZeroDivisionError`` | + ``SIP_WindowsError`` | ``SIP_VMSError``] + + *exceptions* ::= ``throw (`` [*exception-list*] ``)`` + + *exception-list* ::= *scoped-name* [``,`` *exception-list*] + + *argument-list* ::= *argument* [``,`` *argument-list*] [``,`` ``...``] + + *argument* ::= [*type* [*name*] [*argument-annotations*] + [*default-value*] | SIP_ANYSLOT_ [*default-value*] | SIP_QOBJECT_ | + SIP_RXOBJ_CON_ | SIP_RXOBJ_DIS_ | SIP_SIGNAL_ [*default-value*] | + SIP_SLOT_ [*default-value*] | SIP_SLOT_CON_ | SIP_SLOT_DIS_] + + *default-value* ::= ``=`` *expression* + + *expression* ::= [*value* | *value* *binary-operator* *expression*] + + *value* ::= [*unary-operator*] *simple-value* + + *simple-value* ::= [*scoped-name* | *function-call* | *real-value* | + *integer-value* | *boolean-value* | *string-value* | + *character-value*] + + *typed-name*::= *type* *name* + + *function-pointer*::= *type* ``(*`` *name* ``)(`` [*type-list*] ``)`` + + *type-list* ::= *type* [``,`` *type-list*] + + *function-call* ::= *scoped-name* ``(`` [*value-list*] ``)`` + + *value-list* ::= *value* [``,`` *value-list*] + + *real-value* ::= a floating point number + + *integer-value* ::= a number + + *boolean-value* ::= [``true`` | ``false``] + + *string-value* ::= ``"`` {*character*} ``"`` + + *character-value* ::= ````` *character* ````` + + *unary-operator* ::= [``!`` | ``~`` | ``-`` | ``+``] + + *binary-operator* ::= [``-`` | ``+`` | ``*`` | ``/`` | ``&`` | ``|``] + + *argument-annotations* ::= see `Argument Annotations`_ + + *class-annotations* ::= see `Class Annotations`_ + + *enum-annotations* ::= see `Enum Annotations`_ + + *function-annotations* ::= see `Function Annotations`_ + + *variable-annotations* ::= see `Variable Annotations`_ + + *type* ::= [``const``] *base-type* {``*``} [``&``] + + *type-list* ::= *type* [``,`` *type-list*] + + *base-type* ::= [*scoped-name* | *template* | ``struct`` *scoped-name* | + ``short`` | ``unsigned short`` | ``int`` | ``unsigned`` | + ``unsigned int`` | ``long`` | ``unsigned long`` | ``float`` | + ``double`` | ``bool`` | ``char`` | ``signed char`` | + ``unsigned char`` | ``void`` | ``wchar_t`` | SIP_PYCALLABLE_ | + SIP_PYDICT_ | SIP_PYLIST_ | SIP_PYOBJECT_ | SIP_PYSLICE_ | + SIP_PYTUPLE_ | SIP_PYTYPE_] + + *scoped-name* ::= *name* [``::`` *scoped-name*] + + *template* ::= *scoped-name* ``<`` *type-list* ``>`` + + *name* ::= _A-Za-z {_A-Za-z0-9} + +Here is a short list of differences between C++ and the subset supported by +SIP that might trip you up. + + - SIP does not support the use of ``[]`` in types. Use pointers instead. + + - A global ``operator`` can only be defined if its first argument is a + class or a named enum that has been wrapped in the same module. + + - Variables declared outside of a class are effectively read-only. + + - A class's list of super-classes doesn't not include any access specifier + (e.g. ``public``). + + +Variable Numbers of Arguments +----------------------------- + +SIP supports the use of ``...`` as the last part of a function signature. Any +remaining arguments are collected as a Python tuple. + + +Additional SIP Types +-------------------- + +SIP supports a number of additional data types that can be used in Python +signatures. + + +SIP_ANYSLOT +*********** + +This is both a ``const char *`` and a ``PyObject *`` that is used as the type +of the member instead of ``const char *`` in functions that implement the +connection or disconnection of an explicitly generated signal to a slot. +Handwritten code must be provided to interpret the conversion correctly. + + +SIP_PYCALLABLE +************** + +This is a ``PyObject *`` that is a Python callable object. + + +SIP_PYDICT +********** + +This is a ``PyObject *`` that is a Python dictionary object. + + +SIP_PYLIST +********** + +This is a ``PyObject *`` that is a Python list object. + + +SIP_PYOBJECT +************ + +This is a ``PyObject *`` of any Python type. + + +SIP_PYSLICE +*********** + +This is a ``PyObject *`` that is a Python slice object. + + +SIP_PYTUPLE +*********** + +This is a ``PyObject *`` that is a Python tuple object. + + +SIP_PYTYPE +********** + +This is a ``PyObject *`` that is a Python type object. + + +SIP_QOBJECT +*********** + +This is a ``QObject *`` that is a C++ instance of a class derived from Qt's +``QObject`` class. + + +SIP_RXOBJ_CON +************* + +This is a ``QObject *`` that is a C++ instance of a class derived from Qt's +``QObject`` class. It is used as the type of the receiver instead of ``const +QObject *`` in functions that implement a connection to a slot. + + +SIP_RXOBJ_DIS +************* + +This is a ``QObject *`` that is a C++ instance of a class derived from Qt's +``QObject`` class. It is used as the type of the receiver instead of ``const +QObject *`` in functions that implement a disconnection from a slot. + + +SIP_SIGNAL +********** + +This is a ``const char *`` that is used as the type of the signal instead of +``const char *`` in functions that implement the connection or disconnection +of an explicitly generated signal to a slot. + + +SIP_SLOT +******** + +This is a ``const char *`` that is used as the type of the member instead of +``const char *`` in functions that implement the connection or disconnection +of an explicitly generated signal to a slot. + + +SIP_SLOT_CON +************ + +This is a ``const char *`` that is used as the type of the member instead of +``const char *`` in functions that implement the connection of an internally +generated signal to a slot. The type includes a comma separated list of types +that is the C++ signature of of the signal. + +To take an example, ``QAccel::connectItem()`` connects an internally generated +signal to a slot. The signal is emitted when the keyboard accelerator is +activated and it has a single integer argument that is the ID of the +accelerator. The C++ signature is:: + + bool connectItem(int id, const QObject *receiver, const char *member); + +The corresponding SIP specification is:: + + bool connectItem(int, SIP_RXOBJ_CON, SIP_SLOT_CON(int)); + + +SIP_SLOT_DIS +************ + +This is a ``const char *`` that is used as the type of the member instead of +``const char *`` in functions that implement the disconnection of an +internally generated signal to a slot. The type includes a comma separated +list of types that is the C++ signature of of the signal. + + +SIP Directives +============== + +In this section we describe each of the directives that can be used in +specification files. All directives begin with ``%`` as the first +non-whitespace character in a line. + +Some directives have arguments or contain blocks of code or documentation. In +the following descriptions these are shown in *italics*. Optional arguments +are enclosed in [*brackets*]. + +Some directives are used to specify handwritten code. Handwritten code must +not define names that start with the prefix ``sip``. + + +%AccessCode +----------- + +.. parsed-literal:: + + %AccessCode + *code* + %End + +This directive is used immediately after the declaration of an instance of a +wrapped class or structure, or a pointer to such an instance. You use it to +provide handwritten code that overrides the default behaviour. + +For example:: + + class Klass; + + Klass *klassInstance; + %AccessCode + // In this contrived example the C++ library we are wrapping defines + // klassInstance as Klass ** (which SIP doesn't support) so we + // explicitly dereference it. + if (klassInstance && *klassInstance) + return *klassInstance; + + // This will get converted to None. + return 0; + %End + + +%BIGetCharBufferCode +-------------------- + +.. parsed-literal:: + + %BIGetCharBufferCode + *code* + %End + +This directive (along with `%BIGetReadBufferCode`_, `%BIGetSegCountCode`_ and +`%BIGetWriteBufferCode`_) is used to specify code that implements Python's +buffer interface. See the section `Buffer Object Structures +<http://www.python.org/dev/doc/devel/api/buffer-structs.html>`__ for the +details. + +The following variables are made available to the handwritten code: + +*type* \*sipCpp + This is a pointer to the structure or class instance. Its *type* is a + pointer to the structure or class. + +void \*\*sipPtrPtr + This is the pointer used to return the address of the character buffer. + +SIP_SSIZE_T sipRes + The handwritten code should set this to the length of the character buffer + or -1 if there was an error. + +SIP_SSIZE_T sipSegment + This is the number of the segment of the character buffer. + +PyObject \*sipSelf + This is the Python object that wraps the the structure or class instance, + i.e. ``self``. + + +%BIGetReadBufferCode +-------------------- + +.. parsed-literal:: + + %BIGetReadBufferCode + *code* + %End + +This directive (along with `%BIGetCharBufferCode`_, `%BIGetSegCountCode`_ and +`%BIGetWriteBufferCode`_) is used to specify code that implements Python's +buffer interface. + +The following variables are made available to the handwritten code: + +*type* \*sipCpp + This is a pointer to the structure or class instance. Its *type* is a + pointer to the structure or class. + +void \*\*sipPtrPtr + This is the pointer used to return the address of the read buffer. + +SIP_SSIZE_T sipRes + The handwritten code should set this to the length of the read buffer or + -1 if there was an error. + +SIP_SSIZE_T sipSegment + This is the number of the segment of the read buffer. + +PyObject \*sipSelf + This is the Python object that wraps the the structure or class instance, + i.e. ``self``. + + +%BIGetSegCountCode +------------------ + +.. parsed-literal:: + + %BIGetSegCountCode + *code* + %End + +This directive (along with `%BIGetCharBufferCode`_, `%BIGetReadBufferCode`_ and +`%BIGetWriteBufferCode`_) is used to specify code that implements Python's +buffer interface. + +The following variables are made available to the handwritten code: + +*type* \*sipCpp + This is a pointer to the structure or class instance. Its *type* is a + pointer to the structure or class. + +SIP_SSIZE_T \*sipLenPtr + This is the pointer used to return the total length in bytes of all + segments of the buffer. + +SIP_SSIZE_T sipRes + The handwritten code should set this to the number of segments that make + up the buffer. + +PyObject \*sipSelf + This is the Python object that wraps the the structure or class instance, + i.e. ``self``. + + +%BIGetWriteBufferCode +--------------------- + +.. parsed-literal:: + + %BIGetWriteBufferCode + *code* + %End + +This directive (along with `%BIGetCharBufferCode`_, `%BIGetReadBufferCode`_ +and `%BIGetSegCountCode`_ is used to specify code that implements Python's +buffer interface. + +The following variables are made available to the handwritten code: + +*type* \*sipCpp + This is a pointer to the structure or class instance. Its *type* is a + pointer to the structure or class. + +void \*\*sipPtrPtr + This is the pointer used to return the address of the write buffer. + +SIP_SSIZE_T sipRes + The handwritten code should set this to the length of the write buffer or + -1 if there was an error. + +SIP_SSIZE_T sipSegment + This is the number of the segment of the write buffer. + +PyObject \*sipSelf + This is the Python object that wraps the the structure or class instance, + i.e. ``self``. + + +%CModule +-------- + +.. parsed-literal:: + + %CModule *name* [*version*] + +This directive is used to identify that the library being wrapped is a C +library and to define the name of the module and it's optional version number. + +See the `%Module`_ directive for an explanation of the version number. + +For example:: + + %CModule dbus 1 + + +%ConvertFromTypeCode +-------------------- + +.. parsed-literal:: + + %ConvertFromTypeCode + *code* + %End + +This directive is used as part of the `%MappedType`_ directive to specify the +handwritten code that converts an instance of a mapped type to a Python +object. + +The following variables are made available to the handwritten code: + +*type* \*sipCpp + This is a pointer to the instance of the mapped type to be converted. It + will never be zero as the conversion from zero to ``Py_None`` is handled + before the handwritten code is called. + +PyObject \*sipTransferObj + This specifies any desired ownership changes to the returned object. If it + is ``NULL`` then the ownership should be left unchanged. If it is + ``Py_None`` then ownership should be transferred to Python. Otherwise + ownership should be transferred to C/C++ and the returned object associated + with *sipTransferObj*. The code can choose to interpret these changes in + any way. For example, if the code is converting a C++ container of wrapped + classes to a Python list it is likely that the ownership changes should be + made to each element of the list. + +The handwritten code must explicitly return a ``PyObject *``. If there was an +error then a Python exception must be raised and ``NULL`` returned. + +The following example converts a ``QList<QWidget *>`` instance to a Python +list of ``QWidget`` instances:: + + %ConvertFromTypeCode + PyObject *l; + + // Create the Python list of the correct length. + if ((l = PyList_New(sipCpp -> size())) == NULL) + return NULL; + + // Go through each element in the C++ instance and convert it to a + // wrapped QWidget. + for (int i = 0; i < sipCpp -> size(); ++i) + { + QWidget *w = sipCpp -> at(i); + PyObject *wobj; + + // Get the Python wrapper for the QWidget instance, creating a new + // one if necessary, and handle any ownership transfer. + if ((wobj = sipConvertFromInstance(w, sipClass_QWidget, sipTransferObj)) == NULL) + { + // There was an error so garbage collect the Python list. + Py_DECREF(l); + return NULL; + } + + // Add the wrapper to the list. + PyList_SET_ITEM(l, i, wobj); + } + + // Return the Python list. + return l; + %End + + +%ConvertToSubClassCode +---------------------- + +.. parsed-literal:: + + %ConvertToSubClassCode + *code* + %End + +When SIP needs to wrap a C++ class instance it first checks to make sure it +hasn't already done so. If it has then it just returns a new reference to the +corresponding Python object. Otherwise it creates a new Python object of the +appropriate type. In C++ a function may be defined to return an instance of a +certain class, but can often return a sub-class instead. + +This directive is used to specify handwritten code that exploits any available +real-time type information (RTTI) to see if there is a more specific Python +type that can be used when wrapping the C++ instance. The RTTI may be +provided by the compiler or by the C++ instance itself. + +The directive is included in the specification of one of the classes that the +handwritten code handles the type conversion for. It doesn't matter which +one, but a sensible choice would be the one at the root of that class +hierarchy in the module. + +Note that if a class hierarchy extends over a number of modules then this +directive should be used in each of those modules to handle the part of the +hierarchy defined in that module. SIP will ensure that the different pieces +of code are called in the right order to determine the most specific Python +type to use. + +The following variables are made available to the handwritten code: + +*type* \*sipCpp + This is a pointer to the C++ class instance. + +void \*\*sipCppRet + When the sub-class is derived from more than one super-class then it is + possible that the C++ address of the instance as the sub-class is + different to that of the super-class. If so, then this must be set to the + C++ address of the instance when cast (usually using ``static_cast``) + from the super-class to the sub-class. + +sipWrapperType \*sipClass + The handwritten code must set this to the SIP generated Python type object + that corresponds to the class instance. (The type object for class + ``Klass`` is ``sipClass_Klass``.) If the RTTI of the class instance isn't + recognised then ``sipClass`` must be set to ``NULL``. The code doesn't + have to recognise the exact class, only the most specific sub-class that + it can. + +The handwritten code must not explicitly return. + +The following example shows the sub-class conversion code for ``QEvent`` based +class hierarchy in PyQt:: + + class QEvent + { + %ConvertToSubClassCode + // QEvent sub-classes provide a unique type ID. + switch (sipCpp -> type()) + { + case QEvent::Timer: + sipClass = sipClass_QTimerEvent; + break; + + case QEvent::KeyPress: + case QEvent::KeyRelease: + sipClass = sipClass_QKeyEvent; + break; + + // Skip the remaining event types to keep the example short. + + default: + // We don't recognise the type. + sipClass = NULL; + } + %End + + // The rest of the class specification. + + }; + +The SIP API includes the `sipMapIntToClass()`_ and `sipMapStringToClass()`_ +functions that convert integer and string based RTTI to Python type objects +based on ordered lookup tables. + + +%ConvertToTypeCode +------------------ + +.. parsed-literal:: + + %ConvertToTypeCode + *code* + %End + +This directive is used to specify the handwritten code that converts a Python +object to a mapped type instance and to handle any ownership transfers. It is +used as part of the `%MappedType`_ directive and as part of a class +specification. The code is also called to determine if the Python object is of +the correct type prior to conversion. + +When used as part of a class specification it can automatically convert +additional types of Python object. For example, PyQt uses it in the +specification of the ``QString`` class to allow Python string objects and +unicode objects to be used wherever ``QString`` instances are expected. + +The following variables are made available to the handwritten code: + +int \*sipIsErr + If this is ``NULL`` then the code is being asked to check the type of the + Python object. The check must not have any side effects. Otherwise the + code is being asked to convert the Python object and a non-zero value + should be returned through this pointer if an error occurred during the + conversion. + +PyObject \*sipPy + This is the Python object to be converted. + +*type* \*\*sipCppPtr + This is a pointer through which the address of the mapped type instance (or + zero if appropriate) is returned. Its value is undefined if ``sipIsErr`` + is ``NULL``. + +PyObject \*sipTransferObj + This specifies any desired ownership changes to *sipPy*. If it is ``NULL`` + then the ownership should be left unchanged. If it is ``Py_None`` then + ownership should be transferred to Python. Otherwise ownership should be + transferred to C/C++ and *sipPy* associated with *sipTransferObj*. The + code can choose to interpret these changes in any way. + +The handwritten code must explicitly return an ``int`` the meaning of which +depends on the value of ``sipIsErr``. + +If ``sipIsErr`` is ``NULL`` then a non-zero value is returned if the Python +object has a type that can be converted to the mapped type. Otherwise zero is +returned. + +If ``sipIsErr`` is not ``NULL`` then a combination of the following flags is +returned. + + - ``SIP_TEMPORARY`` is set to indicate that the returned instance is a + temporary and should be released to avoid a memory leak. + + - ``SIP_DERIVED_CLASS`` is set to indicate that the type of the + returned instance is a derived class. See `Generated Derived + Classes`_. + +The following example converts a Python list of ``QPoint`` instances to a +``QList<QPoint>`` instance:: + + %ConvertToTypeCode + // See if we are just being asked to check the type of the Python + // object. + if (!sipIsErr) + { + // Checking whether or not None has been passed instead of a list + // has already been done. + if (!PyList_Check(sipPy)) + return 0; + + // Check the type of each element. We specify SIP_NOT_NONE to + // disallow None because it is a list of QPoint, not of a pointer + // to a QPoint, so None isn't appropriate. + for (int i = 0; i < PyList_GET_SIZE(sipPy); ++i) + if (!sipCanConvertToInstance(PyList_GET_ITEM(sipPy, i), + sipClass_QPoint, SIP_NOT_NONE)) + return 0; + + // The type is valid. + return 1; + } + + // Create the instance on the heap. + QList<QPoint> *ql = new QList<QPoint>; + + for (int i = 0; i < PyList_GET_SIZE(sipPy); ++i) + { + QPoint *qp; + int state; + + // Get the address of the element's C++ instance. Note that, in + // this case, we don't apply any ownership changes to the list + // elements, only to the list itself. + qp = reinterpret_cast<QPoint *>(sipConvertToInstance( + PyList_GET_ITEM(sipPy, i), + sipClass_QPoint, 0, + SIP_NOT_NONE, + &state, sipIsErr)); + + // Deal with any errors. + if (*sipIsErr) + { + sipReleaseInstance(qp, sipClass_QPoint, state); + + // Tidy up. + delete ql; + + // There is no temporary instance. + return 0; + } + + ql -> append(*qp); + + // A copy of the QPoint was appended to the list so we no longer + // need it. It may be a temporary instance that should be + // destroyed, or a wrapped instance that should not be destroyed. + // sipReleaseInstance() will do the right thing. + sipReleaseInstance(qp, sipClass_QPoint, state); + } + + // Return the instance. + *sipCppPtr = ql; + + // The instance should be regarded as temporary (and be destroyed as + // soon as it has been used) unless it has been transferred from + // Python. sipGetState() is a convenience function that implements + // this common transfer behaviour. + return sipGetState(sipTransferObj); + %End + +When used in a class specification the handwritten code replaces the code that +would normally be automatically generated. This means that the handwritten +code must also handle instances of the class itself and not just the additional +types that are being supported. This should be done by making calls to +`sipCanConvertToInstance()`_ to check the object type and +`sipConvertToInstance()`_ to convert the object. The ``SIP_NO_CONVERTORS`` +flag *must* be passed to both these functions to prevent recursive calls to the +handwritten code. + + +%Copying +-------- + +.. parsed-literal:: + + %Copying + *text* + %End + +This directive is used to specify some arbitrary text that will be included at +the start of all source files generated by SIP. It is normally used to +include copyright and licensing terms. + +For example:: + + %Copying + Copyright (c) 2007 Riverbank Computing Limited + %End + + +%Doc +---- + +.. parsed-literal:: + + %Doc + *text* + %End + +This directive is used to specify some arbitrary text that will be extracted +by SIP when the ``-d`` command line option is used. The directive can be +specified any number of times and SIP will concatenate all the separate pieces +of text in the order that it sees them. + +Documentation that is specified using this directive is local to the module in +which it appears. It is ignored by modules that `%Import`_ it. Use the +`%ExportedDoc`_ directive for documentation that should be included by all +modules that `%Import`_ this one. + +For example:: + + %Doc + <h1>An Example</h1> + <p> + This fragment of documentation is HTML and is local to the module in + which it is defined. + </p> + %End + + +%End +---- + +This isn't a directive in itself, but is used to terminate a number of +directives that allow a block of handwritten code or text to be specified. + + +%Exception +---------- + +.. parsed-literal:: + + %Exception *name* [(*base-exception)] + { + [*header-code*] + *raise-code* + }; + +This directive is used to define new Python exceptions, or to provide a stub +for existing Python exceptions. It allows handwritten code to be provided +that implements the translation between C++ exceptions and Python exceptions. +The arguments to ``throw ()`` specifiers must either be names of classes or the +names of Python exceptions defined by this directive. + +*name* is the name of the exception. + +*base-exception* is the optional base exception. This may be either one of +the standard Python exceptions or one defined with a previous `%Exception`_ +directive. + +*header-code* is the optional `%TypeHeaderCode`_ used to specify any external +interface to the exception being defined. + +*raise-code* is the `%RaiseCode`_ used to specify the handwritten code that +converts a reference to the C++ exception to the Python exception. + +For example:: + + %Exception std::exception(SIP_Exception) /PyName=StdException/ + { + %TypeHeaderCode + #include <exception> + %End + %RaiseCode + const char *detail = sipExceptionReference.what(); + + SIP_BLOCK_THREADS + PyErr_SetString(sipException_StdException, detail); + SIP_UNBLOCK_THREADS + %End + }; + +In this example we map the standard C++ exception to a new Python exception. +The new exception is called ``StdException`` and is derived from the standard +Python exception ``Exception``. + + +%ExportedDoc +------------ + +.. parsed-literal:: + + %ExportedDoc + *text* + %End + +This directive is used to specify some arbitrary text that will be extracted +by SIP when the ``-d`` command line option is used. The directive can be +specified any number of times and SIP will concatenate all the separate pieces +of text in the order that it sees them. + +Documentation that is specified using this directive will also be included by +modules that `%Import`_ it. + +For example:: + + %ExportedDoc + ========== + An Example + ========== + + This fragment of documentation is reStructuredText and will appear in the + module in which it is defined and all modules that %Import it. + %End + + +%ExportedHeaderCode +------------------- + +.. parsed-literal:: + + %ExportedHeaderCode + *code* + %End + +This directive is used to specify handwritten code, typically the declarations +of types, that is placed in a header file that is included by all generated +code for all modules. It should not include function declarations because +Python modules should not explicitly call functions in another Python module. + +See also `%ModuleCode`_ and `%ModuleHeaderCode`_. + + +%Feature +-------- + +.. parsed-literal:: + + %Feature *name* + +This directive is used to declare a feature. Features (along with +`%Platforms`_ and `%Timeline`_) are used by the `%If`_ directive to control +whether or not parts of a specification are processed or ignored. + +Features are mutually independent of each other - any combination of features +may be enabled or disable. By default all features are enabled. The SIP +``-x`` command line option is used to disable a feature. + +If a feature is enabled then SIP will automatically generate a corresponding C +preprocessor symbol for use by handwritten code. The symbol is the name of +the feature prefixed by ``SIP_FEATURE_``. + +For example:: + + %Feature FOO_SUPPORT + + %If (FOO_SUPPORT) + void foo(); + %End + + +%GCClearCode +------------ + +.. parsed-literal:: + + %GCClearCode + *code* + %End + +Python has a cyclic garbage collector which can identify and release unneeded +objects even when their reference counts are not zero. If a wrapped C +structure or C++ class keeps its own reference to a Python object then, if the +garbage collector is to do its job, it needs to provide some handwritten code +to traverse and potentially clear those embedded references. + +See the section *Supporting cyclic garbage collection* in `Embedding and +Extending the Python Interpreter <http://www.python.org/dev/doc/devel/ext/>`__ +for the details. + +This directive is used to specify the code that clears any embedded references. +(See `%GCTraverseCode`_ for specifying the code that traverses any embedded +references.) + +The following variables are made available to the handwritten code: + +*type* \*sipCpp + This is a pointer to the structure or class instance. Its *type* is a + pointer to the structure or class. + +int sipRes + The handwritten code should set this to the result to be returned. + +The following simplified example is taken from PyQt. The ``QCustomEvent`` +class allows arbitary data to be attached to the event. In PyQt this data is +always a Python object and so should be handled by the garbage collector:: + + %GCClearCode + PyObject *obj; + + // Get the object. + obj = reinterpret_cast<PyObject *>(sipCpp -> data()); + + // Clear the pointer. + sipCpp -> setData(0); + + // Clear the reference. + Py_XDECREF(obj); + + // Report no error. + sipRes = 0; + %End + + +%GCTraverseCode +--------------- + +.. parsed-literal:: + + %GCTraverseCode + *code* + %End + +This directive is used to specify the code that traverses any embedded +references for Python's cyclic garbage collector. (See `%GCClearCode`_ for a +full explanation.) + +The following variables are made available to the handwritten code: + +*type* \*sipCpp + This is a pointer to the structure or class instance. Its *type* is a + pointer to the structure or class. + +visitproc sipVisit + This is the visit function provided by the garbage collector. + +void \*sipArg + This is the argument to the visit function provided by the garbage + collector. + +int sipRes + The handwritten code should set this to the result to be returned. + +The following simplified example is taken from PyQt's ``QCustomEvent`` class:: + + %GCTraverseCode + PyObject *obj; + + // Get the object. + obj = reinterpret_cast<PyObject *>(sipCpp -> data()); + + // Call the visit function if there was an object. + if (obj) + sipRes = sipVisit(obj, sipArg); + else + sipRes = 0; + %End + + +%GetCode +-------- + +.. parsed-literal:: + + %GetCode + *code* + %End + +This directive is used after the declaration of a C++ class variable or C +structure member to specify handwritten code to convert it to a Python object. +It is usually used to handle types that SIP cannot deal with automatically. + +The following variables are made available to the handwritten code: + +*type* \*sipCpp + This is a pointer to the structure or class instance. Its *type* is a + pointer to the structure or class. It is not made available if the + variable being wrapped is a static class variable. + +PyObject \*sipPy + The handwritten code must set this to the Python representation of the + class variable or structure member. If there is an error then the code + must raise an exception and set this to ``NULL``. + +For example:: + + struct Entity + { + /* + * In this contrived example the C library we are wrapping actually + * defines this as char buffer[100] which SIP cannot handle + * automatically. + */ + char *buffer; + %GetCode + sipPy = PyString_FromStringAndSize(sipCpp -> buffer, 100); + %End + %SetCode + char *ptr; + int length; + + if (PyString_AsStringAndSize(sipPy, &ptr, &length) == -1) + sipErr = 1; + else if (length != 100) + { + /* + * Raise an exception because the length isn't exactly right. + */ + + PyErr_SetString(PyExc_ValueError, "an Entity.buffer must be exactly 100 bytes"); + sipErr = 1; + } + else + memcpy(sipCpp -> buffer, ptr, 100); + %End + } + + +%If +--- + +.. parsed-literal:: + + %If (*expression*) + *specification* + %End + +where + +.. parsed-literal:: + + *expression* ::= [*ored-qualifiers* | *range*] + + *ored-qualifiers* ::= [*qualifier* | *qualifier* ``||`` *ored-qualifiers*] + + *qualifier* ::= [``!``] [*feature* | *platform*] + + *range* ::= [*version*] ``-`` [*version*] + +This directive is used in conjunction with features (see `%Feature`_), +platforms (see `%Platforms`_) and versions (see `%Timeline`_) to control +whether or not parts of a specification are processed or not. + +A *range* of versions means all versions starting with the lower bound up to +but excluding the upper bound. If the lower bound is omitted then it is +interpreted as being before the earliest version. If the upper bound is +omitted then it is interpreted as being after the latest version. + +For example:: + + %Feature SUPPORT_FOO + %Platforms {WIN32_PLATFORM POSIX_PLATFORM MACOS_PLATFORM} + %Timeline {V1_0 V1_1 V2_0 V3_0} + + %If (!SUPPORT_FOO) + // Process this if the SUPPORT_FOO feature is disabled. + %End + + %If (POSIX_PLATFORM || MACOS_PLATFORM) + // Process this if either the POSIX_PLATFORM or MACOS_PLATFORM + // platforms are enabled. + %End + + %If (V1_0 - V2_0) + // Process this if either V1_0 or V1_1 is enabled. + %End + + %If (V2_0 - ) + // Process this if either V2_0 or V3_0 is enabled. + %End + + %If ( - ) + // Always process this. + %End + +Note that this directive is not implemented as a preprocessor. Only the +following parts of a specification are affected by it: + + - ``class`` + - `%ConvertFromTypeCode`_ + - `%ConvertToSubClassCode`_ + - `%ConvertToTypeCode`_ + - ``enum`` + - `%ExportedHeaderCode`_ + - functions + - `%GCClearCode`_ + - `%GCTraverseCode`_ + - `%If`_ + - `%MappedType`_ + - `%MethodCode`_ + - `%ModuleCode`_ + - `%ModuleHeaderCode`_ + - ``namespace`` + - `%PostInitialisationCode`_ + - `%PreInitialisationCode`_ + - ``struct`` + - ``typedef`` + - `%TypeCode`_ + - `%TypeHeaderCode`_ + - `%UnitCode`_ + - variables + - `%VirtualCatcherCode`_ + +Also note that the only way to specify the logical and of qualifiers is to use +nested `%If`_ directives. + + +%Import +------- + +.. parsed-literal:: + + %Import *filename* + +This directive is used to import the specification of another module. This is +needed if the current module makes use of any types defined in the imported +module, e.g. as an argument to a function, or to sub-class. + +If *filename* cannot be opened then SIP prepends *filename* with the name of +the directory containing the current specification file (i.e. the one +containing the `%Import`_ directive) and tries again. If this also fails then +SIP prepends *filename* with each of the directories, in turn, specified by +the ``-I`` command line option. + +For example:: + + %Import qt/qtmod.sip + + +%Include +-------- + +.. parsed-literal:: + + %Include *filename* + +This directive is used to include contents of another file as part of the +specification of the current module. It is the equivalent of the C +preprocessor's ``#include`` directive and is used to structure a large module +specification into manageable pieces. + +`%Include`_ follows the same search process as `%Import`_ when trying to open +*filename*. + +For example:: + + %Include qwidget.sip + + +%License +-------- + +.. parsed-literal:: + + %License /*license-annotations*/ + +This directive is used to specify the contents of an optional license +dictionary. The license dictionary is called ``__license__`` and is stored in +the module dictionary. The elements of the dictionary are specified using the +Licensee_, Signature_, Timestamp_ and Type_ annotations. Only the Type_ +annotation is compulsory. + +Note that this directive isn't an attempt to impose any licensing restrictions +on a module. It is simply a method for easily embedding licensing information +in a module so that it is accessible to Python scripts. + +For example:: + + %License /Type="GPL"/ + + +%MappedType +----------- + +.. parsed-literal:: + + template<*type-list*> + %MappedType *type* + { + [*header-code*] + [*convert-to-code*] + [*convert-from-code*] + }; + + %MappedType *type* + { + [*header-code*] + [*convert-to-code*] + [*convert-from-code*] + }; + +This directive is used to define an automatic mapping between a C or C++ type +and a Python type. It can be used as part of a template, or to map a specific +type. + +When used as part of a template *type* cannot itself refer to a template. Any +occurrences of any of the type names (but not any ``*`` or ``&``) in +*type-list* will be replaced by the actual type names used when the template is +instantiated. Template mapped types are instantiated automatically as required +(unlike template classes which are only instantiated using ``typedef``). + +Any explicit mapped type will be used in preference to any template that maps +the same type, ie. a template will not be automatically instantiated if there +is an explicit mapped type. + +*header-code* is the `%TypeHeaderCode`_ used to specify the library interface +to the type being mapped. + +*convert-to-code* is the `%ConvertToTypeCode`_ used to specify the handwritten +code that converts a Python object to an instance of the mapped type. + +*convert-from-code* is the `%ConvertFromTypeCode`_ used to specify the +handwritten code that converts an instance of the mapped type to a Python +object. + +For example:: + + template<Type *> + %MappedType QList + { + %TypeHeaderCode + // Include the library interface to the type being mapped. + #include <qlist.h> + %End + + %ConvertToTypeCode + // See if we are just being asked to check the type of the Python + // object. + if (sipIsErr == NULL) + { + // Check it is a list. + if (!PyList_Check(sipPy)) + return 0; + + // Now check each element of the list is of the type we expect. + // The template is for a pointer type so we don't disallow None. + for (int i = 0; i < PyList_GET_SIZE(sipPy); ++i) + if (!sipCanConvertToInstance(PyList_GET_ITEM(sipPy, i), + sipClass_Type, 0)) + return 0; + + return 1; + } + + // Create the instance on the heap. + QList<Type *> *ql = new QList<Type *>; + + for (int i = 0; i < PyList_GET_SIZE(sipPy); ++i) + { + // Use the SIP API to convert the Python object to the + // corresponding C++ instance. Note that we apply any ownership + // transfer to the list itself, not the individual elements. + Type *t = reinterpret_cast<Type *>(sipConvertToInstance( + PyList_GET_ITEM(sipPy, i), + sipClass_Type, 0, 0, 0, + sipIsErr)); + + if (*sipIsErr) + { + // Tidy up. + delete ql; + + // There is nothing on the heap. + return 0; + } + + // Add the pointer to the C++ instance. + ql -> append(t); + } + + // Return the instance on the heap. + *sipCppPtr = ql; + + // Apply the normal transfer. + return sipGetState(sipTransferObj); + %End + + %ConvertFromTypeCode + PyObject *l; + + // Create the Python list of the correct length. + if ((l = PyList_New(sipCpp -> size())) == NULL) + return NULL; + + // Go through each element in the C++ instance and convert it to the + // corresponding Python object. + for (int i = 0; i < sipCpp -> size(); ++i) + { + Type *t = sipCpp -> at(i); + PyObject *tobj; + + if ((tobj = sipConvertFromInstance(t, sipClass_Type, sipTransferObj)) == NULL) + { + // There was an error so garbage collect the Python list. + Py_DECREF(l); + return NULL; + } + + PyList_SET_ITEM(l, i, tobj); + } + + // Return the Python list. + return l; + %End + } + +Using this we can use, for example, ``QList<QObject *>`` throughout the +module's specification files (and in any module that imports this one). The +generated code will automatically map this to and from a Python list of QObject +instances when appropriate. + + +%MethodCode +----------- + +.. parsed-literal:: + + %MethodCode + *code* + %End + +This directive is used as part of the specification of a global function, class +method, operator, constructor or destructor to specify handwritten code that +replaces the normally generated call to the function being wrapped. It is +usually used to handle argument types and results that SIP cannot deal with +automatically. + +The specified code is embedded in-line after the function's arguments have +been successfully converted from Python objects to their C or C++ equivalents. +The specified code must not include any ``return`` statements. + +In the context of a destructor the specified code is embedded in-line in the +Python type's deallocation function. Unlike other contexts it supplements +rather than replaces the normally generated code, so it must not include code +to return the C structure or C++ class instance to the heap. The code is only +called if ownership of the structure or class is with Python. + +The specified code must also handle the Python Global Interpreter Lock (GIL). +If compatibility with SIP v3.x is required then the GIL must be released +immediately before the C++ call and reacquired immediately afterwards as shown +in this example fragment:: + + Py_BEGIN_ALLOW_THREADS + sipCpp -> foo(); + Py_END_ALLOW_THREADS + +If compatibility with SIP v3.x is not required then this is optional but +should be done if the C++ function might block the current thread or take a +significant amount of time to execute. (See `The Python Global Interpreter +Lock`_ and the ReleaseGIL_ and HoldGIL_ annotations.) + +The following variables are made available to the handwritten code: + +*type* a0 + There is a variable for each argument of the Python signature (excluding + any ``self`` argument) named ``a0``, ``a1``, etc. The *type* of the + variable is the same as the type defined in the specification with the + following exceptions: + + - if the argument is only used to return a value (e.g. it is an ``int *`` + without an In_ annotation) then the type has one less level of + indirection (e.g. it will be an ``int``) + - if the argument is a structure or class (or a reference or a pointer to a + structure or class) then *type* will always be a pointer to the structure + or class. + + Note that handwritten code for destructors never has any arguments. + +PyObject \*a0Wrapper + This variable is made available only if the corresponding argument wraps a + C structure or C++ class instance and the GetWrapper_ annotation is + specified. The variable is a pointer to the Python object that wraps the + argument. + +*type* \*sipCpp + If the directive is used in the context of a class constructor then this + must be set by the handwritten code to the constructed instance. In any + other context then this is a pointer to the C structure or C++ class + instance. Its *type* is a pointer to the structure or class. + +int sipIsErr + The handwritten code should set this to a non-zero value, and raise an + appropriate Python exception, if an error is detected. + + ``sipIsErr`` is not provided for destructors. + +*type* sipRes + The handwritten code should set this to the result to be returned. The + *type* of the variable is the same as the type defined in the Python + signature in the specification with the following exception: + + - if the argument is a structure or class (or a reference or a pointer to a + structure or class) then *type* will always be a pointer to the structure + or class. + + ``sipRes`` is not provided for inplace operators (e.g. ``+=`` or + ``__imul__``) as their results are handled automatically, nor for class + constructors. + +PyObject \*sipSelf + If the directive is used in the context of a class constructor or method + then this is the Python object that wraps the the structure or class + instance, i.e. ``self``. + +bool sipSelfWasArg + This is only made available for non-abstract, virtual methods. It is set + if ``self`` was explicitly passed as the first argument of the method + rather than being bound to the method. In other words, the call was:: + + Klass.foo(self, ...) + + rather than:: + + self.foo(...) + +The following is a complete example:: + + class Klass + { + public: + virtual int foo(SIP_PYTUPLE); + %MethodCode + // The C++ API takes a 2 element array of integers but passing a + // two element tuple is more Pythonic. + + int iarr[2]; + + if (PyArg_ParseTuple(a0, "ii", &iarr[0], &iarr[1])) + { + Py_BEGIN_ALLOW_THREADS + sipRes = sipSelfWasArg ? sipCpp -> Klass::foo(iarr) + : sipCpp -> foo(iarr); + Py_END_ALLOW_THREADS + } + else + { + // PyArg_ParseTuple() will have raised the exception. + sipIsErr = 1; + } + %End + }; + +As the example is a virtual method [#]_, note the use of ``sipSelfWasArg`` to +determine exactly which implementation of ``foo()`` to call. + +If a method is in the ``protected`` section of a C++ class then the call +should instead be:: + + sipRes = sipCpp -> sipProtectVirt_foo(sipSelfWasArg, iarr); + +If a method is in the ``protected`` section of a C++ class but is not virtual +then the call should instead be:: + + sipRes = sipCpp -> sipProtect_foo(iarr); + +.. [#] See `%VirtualCatcherCode`_ for a description of how SIP generated code + handles the reimplementation of C++ virtual methods in Python. + + +%Module +------- + +.. parsed-literal:: + + %Module *name* [*version*] + +This directive is used to identify that the library being wrapped is a C++ +library and to define the name of the module and it's optional version number. + +The name may contain periods to specify that the module is part of a Python +package. + +The optional version number is useful if you (or others) might create other +modules that build on this module, i.e. if another module might `%Import`_ +this module. Under the covers, a module exports an API that is used by modules +that `%Import`_ it and the API is given a version number. A module built on +that module knows the version number of the API that it is expecting. If, +when the modules are imported at run-time, the version numbers do not match +then a Python exception is raised. The dependent module must then be re-built +using the correct specification files for the base module. + +The version number should be incremented whenever a module is changed. Some +changes don't affect the exported API, but it is good practice to change the +version number anyway. + +For example:: + + %Module qt 5 + + +%ModuleCode +----------- + +.. parsed-literal:: + + %ModuleCode + *code* + %End + +This directive is used to specify handwritten code, typically the +implementations of utility functions, that can be called by other handwritten +code in the module. + +For example:: + + %ModuleCode + // Print an object on stderr for debugging purposes. + void dump_object(PyObject *o) + { + PyObject_Print(o, stderr, 0); + fprintf(stderr, "\n"); + } + %End + +See also `%ExportedHeaderCode`_ and `%ModuleHeaderCode`_. + + +%ModuleHeaderCode +----------------- + +.. parsed-literal:: + + %ModuleHeaderCode + *code* + %End + +This directive is used to specify handwritten code, typically the declarations +of utility functions, that is placed in a header file that is included by all +generated code for the same module. + +For example:: + + %ModuleHeaderCode + void dump_object(PyObject *o); + %End + +See also `%ExportedHeaderCode`_ and `%ModuleCode`_. + + +%OptionalInclude +---------------- + +.. parsed-literal:: + + %OptionalInclude *filename* + +This directive is identical to the `%Include`_ directive except that SIP +silently continues processing if *filename* could not be opened. + +For example:: + + %OptionalInclude license.sip + + +%Platforms +---------- + +.. parsed-literal:: + + %Platforms {*name* *name* ...} + +This directive is used to declare a set of platforms. Platforms (along with +`%Feature`_ and `%Timeline`_) are used by the `%If`_ directive to control +whether or not parts of a specification are processed or ignored. + +Platforms are mutually exclusive - only one platform can be enabled at a time. +By default all platforms are disabled. The SIP ``-t`` command line option is +used to enable a platform. + +For example:: + + %Platforms {WIN32_PLATFORM POSIX_PLATFORM MACOS_PLATFORM} + + %If (WIN32_PLATFORM) + void undocumented(); + %End + + %If (POSIX_PLATFORM) + void documented(); + %End + + +%PostInitialisationCode +----------------------- + +.. parsed-literal:: + + %PostInitialisationCode + *code* + %End + +This directive is used to specify handwritten code that is embedded in-line +at the very end of the generated module initialisation code. + +The following variables are made available to the handwritten code: + +PyObject \*sipModule + This is the module object returned by ``Py_InitModule()``. + +PyObject \*sipModuleDict + This is the module's dictionary object returned by ``Py_ModuleGetDict()``. + +For example:: + + %PostInitialisationCode + // The code will be executed when the module is first imported and + // after all other initialisation has been completed. + %End + + +%PreInitialisationCode +---------------------- + +.. parsed-literal:: + + %PreInitialisationCode + *code* + %End + +This directive is used to specify handwritten code that is embedded in-line +at the very start of the generated module initialisation code. + +For example:: + + %PreInitialisationCode + // The code will be executed when the module is first imported and + // before other initialisation has been completed. + %End + + +%RaiseCode +---------- + +.. parsed-literal:: + + %RaiseCode + *code* + %End + +This directive is used as part of the definition of an exception using the +`%Exception`_ directive to specify handwritten code that raises a Python +exception when a C++ exception has been caught. The code is embedded in-line +as the body of a C++ ``catch ()`` clause. + +The specified code must handle the Python Global Interpreter Lock (GIL) if +necessary. The GIL must be acquired before any calls to the Python API and +released after the last call as shown in this example fragment:: + + SIP_BLOCK_THREADS + PyErr_SetNone(PyErr_Exception); + SIP_UNBLOCK_THREADS + +Finally, the specified code must not include any ``return`` statements. + +The following variable is made available to the handwritten code: + +*type* &sipExceptionRef + This is a reference to the caught C++ exception. The *type* of the + reference is the same as the type defined in the ``throw ()`` specifier. + +See the `%Exception`_ directive for an example. + + +%SetCode +-------- + +.. parsed-literal:: + + %SetCode + *code* + %End + +This directive is used after the declaration of a C++ class variable or C +structure member to specify handwritten code to convert it from a Python +object. It is usually used to handle types that SIP cannot deal with +automatically. + +The following variables are made available to the handwritten code: + +*type* \*sipCpp + This is a pointer to the structure or class instance. Its *type* is a + pointer to the structure or class. It is not made available if the + variable being wrapped is a static class variable. + +int sipErr + If the conversion failed then the handwritten code should raise a Python + exception and set this to a non-zero value. Its initial value will be + automatically set to zero. + +PyObject \*sipPy + This is the Python object that the handwritten code should convert. + +See the `%GetCode`_ directive for an example. + + +%SIPOptions +----------- + +This directive sets one or more options that controls different aspects of +SIP's behaviour. In this version all the available options are provided +specifically to support PyQt and so are not documented. + + +%Timeline +--------- + +.. parsed-literal:: + + %Timeline {*name* *name* ...} + +This directive is used to declare a set of versions released over a period of +time. Versions (along with `%Feature`_ and `%Platforms`_) are used by the +`%If`_ directive to control whether or not parts of a specification are +processed or ignored. + +Versions are mutually exclusive - only one version can be enabled at a time. +By default all versions are disabled. The SIP ``-t`` command line option is +used to enable a version. + +For example:: + + %Timeline {V1_0 V1_1 V2_0 V3_0} + + %If (V1_0 - V2_0) + void foo(); + %End + + %If (V2_0 -) + void foo(int = 0); + %End + +`%Timeline`_ can be used any number of times in a module to allow multiple +libraries to be wrapped in the same module. + + +%TypeCode +--------- + +.. parsed-literal:: + + %TypeCode + *code* + %End + +This directive is used as part of the specification of a C structure or a C++ +class to specify handwritten code, typically the implementations of utility +functions, that can be called by other handwritten code in the structure or +class. + +For example:: + + class Klass + { + %TypeCode + // Print an instance on stderr for debugging purposes. + static void dump_klass(const Klass *k) + { + fprintf(stderr,"Klass %s at %p\n", k -> name(), k); + } + %End + + // The rest of the class specification. + + }; + +Because the scope of the code is normally within the generated file that +implements the type, any utility functions would normally be declared +``static``. However a naming convention should still be adopted to prevent +clashes of function names within a module in case the SIP ``-j`` command line +option is used. + + +%TypeHeaderCode +--------------- + +.. parsed-literal:: + + %TypeHeaderCode + *code* + %End + +This directive is used to specify handwritten code that defines the interface +to a C or C++ type being wrapped, either a structure, a class, or a template. +It is used within a class definition or a `%MappedType`_ directive. + +Normally *code* will be a pre-processor ``#include`` statement. + +For example:: + + // Wrap the Klass class. + class Klass + { + %TypeHeaderCode + #include <klass.h> + %End + + // The rest of the class specification. + }; + + +%UnitCode +--------- + +.. parsed-literal:: + + %UnitCode + *code* + %End + +This directive is used to specify handwritten code that it included at the very +start of a generated compilation unit (ie. C or C++ source file). It is +typically used to ``#include`` a C++ precompiled header file. + + +%VirtualCatcherCode +------------------- + +.. parsed-literal:: + + %VirtualCatcherCode + *code* + %End + +For most classes there are corresponding `generated derived classes`_ that +contain reimplementations of the class's virtual methods. These methods (which +SIP calls catchers) determine if there is a corresponding Python +reimplementation and call it if so. If there is no Python reimplementation +then the method in the original class is called instead. + +This directive is used to specify handwritten code that replaces the normally +generated call to the Python reimplementation and the handling of any returned +results. It is usually used to handle argument types and results that SIP +cannot deal with automatically. + +This directive can also be used in the context of a class destructor to +specify handwritten code that is embedded in-line in the internal derived +class's destructor. + +In the context of a method the Python Global Interpreter Lock (GIL) is +automatically acquired before the specified code is executed and automatically +released afterwards. + +In the context of a destructor the specified code must handle the GIL. The +GIL must be acquired before any calls to the Python API and released after the +last call as shown in this example fragment:: + + SIP_BLOCK_THREADS + Py_DECREF(obj); + SIP_UNBLOCK_THREADS + +The following variables are made available to the handwritten code in the +context of a method: + +*type* a0 + There is a variable for each argument of the C++ signature named ``a0``, + ``a1``, etc. The *type* of the variable is the same as the type defined in + the specification. + +int sipIsErr + The handwritten code should set this to a non-zero value, and raise an + appropriate Python exception, if an error is detected. + +PyObject \*sipMethod + This object is the Python reimplementation of the virtual C++ method. It + is normally passed to `sipCallMethod()`_. + +*type* sipRes + The handwritten code should set this to the result to be returned. The + *type* of the variable is the same as the type defined in the C++ signature + in the specification. + +No variables are made available in the context of a destructor. + +For example:: + + class Klass + { + public: + virtual int foo(SIP_PYTUPLE) [int (int *)]; + %MethodCode + // The C++ API takes a 2 element array of integers but passing a + // two element tuple is more Pythonic. + + int iarr[2]; + + if (PyArg_ParseTuple(a0, "ii", &iarr[0], &iarr[1])) + { + Py_BEGIN_ALLOW_THREADS + sipRes = sipCpp -> Klass::foo(iarr); + Py_END_ALLOW_THREADS + } + else + { + // PyArg_ParseTuple() will have raised the exception. + sipIsErr = 1; + } + %End + %VirtualCatcherCode + // Convert the 2 element array of integers to the two element + // tuple. + + PyObject *result; + + result = sipCallMethod(&sipIsErr, sipMethod, "ii", a0[0], a0[1]); + + if (result != NULL) + { + // Convert the result to the C++ type. + sipParseResult(&sipIsErr, sipMethod, result, "i", &sipRes); + + Py_DECREF(result); + } + %End + }; + + +SIP Annotations +=============== + +In this section we describe each of the annotations that can be used in +specification files. + +Annotations can either be argument annotations, class annotations, enum +annotations, exception annotations, function annotations, license annotations, +or variable annotations depending on the context in which they can be used. + +Annotations are placed between forward slashes (``/``). Multiple annotations +are comma separated within the slashes. + +Annotations have a type and, possibly, a value. The type determines the +format of the value. The name of an annotation and its value are separated by +``=``. + +Annotations can have one of the following types: + +boolean + This type of annotation has no value and is implicitly true. + +name + The value is a name that is compatible with a C/C++ identifier. In some + cases the value is optional. + +string + The value is a double quoted string. + +The following example shows argument and function annotations:: + + void exec(QWidget * /Transfer/) /ReleaseGIL, PyName=call_exec/; + +Note that the current version of SIP does not complain about unknown +annotations, or annotations used out of their correct context. + + +Argument Annotations +-------------------- + +AllowNone +********* + +This boolean annotation specifies that the value of the corresponding argument +(which should be either SIP_PYCALLABLE_, SIP_PYDICT_, SIP_PYLIST_, +SIP_PYSLICE_, SIP_PYTUPLE_ or SIP_PYTYPE_) may be ``None``. + + +Array +***** + +This boolean annotation specifies that the corresponding argument (which +should be either ``char *`` or ``unsigned char *``) refers to an array +rather than a ``'\0'`` terminated string. There must be a corresponding +argument with the ArraySize_ annotation specified. The annotation may only be +specified once in a list of arguments. + + +ArraySize +********* + +This boolean annotation specifies that the corresponding argument (which +should be either ``short``, ``unsigned short``, ``int``, ``unsigned``, +``long`` or ``unsigned long``) refers to the size of an array. There must be +a corresponding argument with the Array_ annotation specified. The annotation +may only be specified once in a list of arguments. + + +Constrained +*********** + +Python will automatically convert between certain compatible types. For +example, if a floating pointer number is expected and an integer supplied, +then the integer will be converted appropriately. This can cause problems +when wrapping C or C++ functions with similar signatures. For example:: + + // The wrapper for this function will also accept an integer argument + // which Python will automatically convert to a floating point number. + void foo(double); + + // The wrapper for this function will never get used. + void foo(int); + +This boolean annotation specifies that the corresponding argument (which +should be either ``bool``, ``int``, ``float``, ``double`` or a wrapped class) +must match the type without any automatic conversions. In the context of a +wrapped class the invocation of any `%ConvertToTypeCode`_ is suppressed. + +The following example gets around the above problem:: + + // The wrapper for this function will only accept floating point numbers. + void foo(double /Constrained/); + + // The wrapper for this function will be used for anything that Python can + // convert to an integer, except for floating point numbers. + void foo(int); + + +GetWrapper +********** + +This boolean annotation is only ever used in conjunction with handwritten code +specified with the `%MethodCode`_ directive. It causes an extra variable to +be generated for the corresponding argument (which should be a wrapped C +structure or C++ class instance) which is a pointer to the Python object that +wraps the argument. + +See the `%MethodCode`_ directive for more detail. + + +In +** + +This boolean annotation is used to specify that the corresponding argument +(which should be a pointer type) is used to pass a value to the function. + +For pointers to wrapped C structures or C++ class instances, ``char *`` and +``unsigned char *`` then this annotation is assumed unless the Out_ annotation +is specified. + +For pointers to other types then this annotation must be explicitly specified +if required. The argument will be dereferenced to obtain the actual value. + +Both In_ and Out_ may be specified for the same argument. + + +Out +*** + +This boolean annotation is used to specify that the corresponding argument +(which should be a pointer type) is used by the function to return a value as +an element of a tuple. + +For pointers to wrapped C structures or C++ class instances, ``char *`` and +``unsigned char *`` then this annotation must be explicitly specified if +required. + +For pointers to other types then this annotation is assumed unless the In_ +annotation is specified. + +Both In_ and Out_ may be specified for the same argument. + + +Transfer +******** + +This boolean annotation is used to specify that ownership of the corresponding +argument (which should be a wrapped C structure or C++ class instance) is +transferred from Python to C++. In addition, if the argument is of a class +method, then it is associated with the class instance with regard to the +cyclic garbage collector. + +See `Ownership of Objects`_ for more detail. + + +TransferBack +************ + +This boolean annotation is used to specify that ownership of the corresponding +argument (which should be a wrapped C structure or C++ class instance) is +transferred back to Python from C++. In addition, any association of the +argument with regard to the cyclic garbage collector with another instance is +removed. + +Note that this can also be used as a function annotation. + +See `Ownership of Objects`_ for more detail. + + +TransferThis +************ + +This boolean annotation is only used in C++ constructors or methods. In the +context of a constructor or factory method it specifies that ownership of the +instance being created is transferred from Python to C++ if the corresponding +argument (which should be a wrapped C structure or C++ class instance) is not +``None``. In addition, the newly created instance is associated with the +argument with regard to the cyclic garbage collector. + +In the context of a non-factory method it specifies that ownership of ``this`` +is transferred from Python to C++ if the corresponding argument is not +``None``. If it is ``None`` then ownership is transferred to Python. + +The annotation may be used more that once, in which case ownership is +transferred to last instance that is not ``None``. + +See `Ownership of Objects`_ for more detail. + + +Class Annotations +----------------- + +Abstract +******** + +This boolean annotation is used to specify that the class has additional pure +virtual methods that have not been specified and so it cannot be instantiated +or sub-classed from Python. + + +DelayDtor +********* + +This boolean annotation is used to specify that the class's destructor should +not be called until the Python interpreter exits. It would normally only be +applied to singleton classes. + +When the Python interpreter exits the order in which any wrapped instances are +garbage collected is unpredictable. However, the underlying C or C++ instances +may need to be destroyed in a certain order. If this annotation is specified +then when the wrapped instance is garbage collected the C or C++ instance is +not destroyed but instead added to a list of delayed instances. When the +interpreter exits then the function ``sipDelayedDtors`` is called with the +list of delayed instances. ``sipDelayedDtors`` can then choose to call (or +ignore) the destructors in any desired order. + +The ``sipDelayedDtors`` function must be specified using the `%ModuleCode`_ +directive. It's signature is as follows:: + + static void sipDelayedDtors(const sipDelayedDtor *dd_list); + +``dd_list`` is the linked list of delayed instances. The following fields are +defined. + +const char \*dd_name + This is the name of the class excluding any package or module name. + +void \*dd_ptr + This is the address of the C or C++ instance to be destroyed. It's exact + type depends on the value of ``dd_isderived``. + +int dd_isderived + This is non-zero if the type of ``dd_ptr`` is actually the generated + derived class. This allows the correct destructor to be called. See + `Generated Derived Classes`_. + +sipDelayedDtor \*dd_next + This is the address of the next entry in the list or zero if this is the + last one. + +Note that the above applies only to C and C++ instances that are owned by +Python. + + +External +******** + +This boolean annotation is used to specify that the class is defined in another +module. Declarations of external classes are private to the module in which +they appear. + + +NoDefaultCtors +************** + +This boolean annotation is used to suppress the automatic generation of default +constructors for the class. + + +PyName +****** + +This name annotation specifies an alternative name for the class being wrapped +which is used when it is referred to from Python. It is required when a class +name is the same as a Python keyword. It may also be used to avoid name +clashes with other objects (e.g. enums, exceptions, functions) that have the +same name in the same C++ scope. + + +Enum Annotations +---------------- + +PyName +****** + +This name annotation specifies an alternative name for the enum or enum member +being wrapped which is used when it is referred to from Python. It is required +when an enum or enum member name is the same as a Python keyword. It may also +be used to avoid name clashes with other objects (e.g. classes, exceptions, +functions) that have the same name in the same C++ scope. + + +Exception Annotations +--------------------- + +PyName +****** + +This name annotation specifies an alternative name for the exception being +defined which is used when it is referred to from Python. It is required when +an exception name is the same as a Python keyword. It may also be used to +avoid name clashes with other objects (e.g. classes, enums, functions) that +have the same name. + + +Function Annotations +-------------------- + +AutoGen +******* + +This optional name annotation is used with class methods to specify that the +method be automatically included in all sub-classes. The value is the name of +a feature (specified using the `%Feature`_ directive) which must be enabled +for the method to be generated. + + +Default +******* + +This boolean annotation is only used with C++ constructors. Sometimes SIP +needs to create a class instance. By default it uses a constructor with no +compulsory arguments if one is specified. (SIP will automatically generate a +constructor with no arguments if no constructors are specified.) This +annotation is used to explicitly specify which constructor to use. Zero is +passed as the value of any arguments to the constructor. + + +Factory +******* + +This boolean annotation specifies that the value returned by the function +(which should be a wrapped C structure or C++ class instance) is a newly +created instance and is owned by Python. + +See `Ownership of Objects`_ for more detail. + + +HoldGIL +******* + +This boolean annotation specifies that the Python Global Interpreter Lock (GIL) +is not released before the call to the underlying C or C++ function. See +`The Python Global Interpreter Lock`_ and the ReleaseGIL_ annotation. + + +NewThread +********* + +This boolean annotation specifies that the function will create a new thread. + + +NoDerived +********* + +This boolean annotation is only used with C++ constructors. In many cases SIP +generates a derived class for each class being wrapped (see `Generated Derived +Classes`_). This derived class contains constructors with the same C++ +signatures as the class being wrapped. Sometimes you may want to define a +Python constructor that has no corresponding C++ constructor. This annotation +is used to suppress the generation of the constructor in the derived class. + + +Numeric +******* + +This boolean annotation specifies that the operator should be interpreted as a +numeric operator rather than a sequence operator. Python uses the ``+`` +operator for adding numbers and concatanating sequences, and the ``*`` operator +for multiplying numbers and repeating sequences. SIP tries to work out which +is meant by looking at other operators that have been defined for the type. +If it finds either ``-``, ``-=``, ``/``, ``/=``, ``%`` or ``%=`` defined then +it assumes that ``+``, ``+=``, ``*`` and ``*=`` should be numeric operators. +Otherwise, if it finds either ``[]``, ``__getitem__()``, ``__setitem__()`` or +``__delitem__()`` defined then it assumes that they should be sequence +operators. This annotation is used to force SIP to treat the operator as +numeric. + + +PostHook +******** + +This name annotation is used to specify the name of a Python builtin that is +called immediately after the call to the underlying C or C++ function or any +handwritten code. The builtin is not called if an error occurred. It is +primarily used to integrate with debuggers. + + +PreHook +******* + +This name annotation is used to specify the name of a Python builtin that is +called immediately after the function's arguments have been successfully +parsed and before the call to the underlying C or C++ function or any +handwritten code. It is primarily used to integrate with debuggers. + + +PyName +****** + +This name annotation specifies an alternative name for the function being +wrapped which is used when it is referred to from Python. It is required when +a function or method name is the same as a Python keyword. It may also be used +to avoid name clashes with other objects (e.g. classes, enums, exceptions) that +have the same name in the same C++ scope. + + +ReleaseGIL +********** + +This boolean annotation specifies that the Python Global Interpreter Lock (GIL) +is released before the call to the underlying C or C++ function and reacquired +afterwards. It should be used for functions that might block or take a +significant amount of time to execute. See `The Python Global Interpreter +Lock`_ and the HoldGIL_ annotation. + + +TransferBack +************ + +This boolean annotation specifies that ownership of the value returned by the +function (which should be a wrapped C structure or C++ class instance) is +transferred back to Python from C++. Normally returned values (unless they are +new references to already wrapped values) are owned by C++. In addition, any +association of the returned value with regard to the cyclic garbage collector +with another instance is removed. + +Note that this can also be used as an argument annotation. + +See `Ownership of Objects`_ for more detail. + + +License Annotations +------------------- + +Licensee +******** + +This optional string annotation specifies the license's licensee. No +restrictions are placed on the contents of the string. + +See the `%License`_ directive. + + +Signature +********* + +This optional string annotation specifies the license's signature. No +restrictions are placed on the contents of the string. + +See the `%License`_ directive. + + +Timestamp +********* + +This optional string annotation specifies the license's timestamp. No +restrictions are placed on the contents of the string. + +See the `%License`_ directive. + + +Type +**** + +This string annotation specifies the license's type. No restrictions are +placed on the contents of the string. + +See the `%License`_ directive. + + +Variable Annotations +-------------------- + +PyName +****** + +This name annotation specifies an alternative name for the variable being +wrapped which is used when it is referred to from Python. It is required when +a variable name is the same as a Python keyword. It may also be used to avoid +name clashes with other objects (e.g. classes, functions) that have the same +name in the same C++ scope. + + +SIP API for Handwritten Code +============================ + +In this section we describe the API that can be used by handwritten code in +specification files. + + +SIP_API_MAJOR_NR +---------------- + +This is a C preprocessor symbol that defines the major number of the SIP API. +Its value is a number. There is no direct relationship between this and the +SIP version number. + + +SIP_API_MINOR_NR +---------------- + +This is a C preprocessor symbol that defines the minor number of the SIP API. +Its value is a number. There is no direct relationship between this and the +SIP version number. + + +SIP_BLOCK_THREADS +----------------- + +This is a C preprocessor macro that will make sure the Python Global +Interpreter Lock (GIL) is acquired. Python API calls must only be made when +the GIL has been acquired. There must be a corresponding +`SIP_UNBLOCK_THREADS`_ at the same lexical scope. + + +SIP_SSIZE_T +----------- + +This is a C preprocessor macro that is defined as ``Py_ssize_t`` for Python +v2.5 and later, and as ``int`` for earlier versions of Python. It makes it +easier to write PEP 353 compliant handwritten code. + + +SIP_UNBLOCK_THREADS +------------------- + +This is a C preprocessor macro that will restore the Python Global Interpreter +Lock (GIL) to the state it was prior to the corresponding `SIP_BLOCK_THREADS`_. + + +SIP_VERSION +----------- + +This is a C preprocessor symbol that defines the SIP version number +represented as a 3 part hexadecimal number (e.g. v4.0.0 is represented as +``0x040000``). + + +SIP_VERSION_STR +--------------- + +This is a C preprocessor symbol that defines the SIP version number +represented as a string. For development snapshots it will start with +``snapshot-``. + + +sipBadCatcherResult() +--------------------- + +void sipBadCatcherResult(PyObject \*method) + This raises a Python exception when the result of a Python reimplementation + of a C++ method doesn't have the expected type. It is normally called by + handwritten code specified with the `%VirtualCatcherCode`_ directive. + *method* is the Python method and would normally be the supplied + ``sipMethod``. + + +sipBadLengthForSlice() +---------------------- + +void sipBadLengthForSlice(SIP_SSIZE_T seqlen, SIP_SSIZE_T slicelen) + This raises a Python exception when the length of a slice object is + inappropriate for a sequence-like object. It is normally called by + handwritten code specified for ``__setitem__()`` methods. *seqlen* is the + length of the sequence. *slicelen* is the length of the slice. With + versions of Python prior to v2.5 the arguments have type ``int``. + + +sipBuildResult() +---------------- + +PyObject \*sipBuildResult(int \*iserr, const char \*format, ...) + This creates a Python object based on a format string and associated + values in a similar way to the Python ``Py_BuildValue()`` function. If + there was an error then ``NULL`` is returned and a Python exception is + raised. If *iserr* is not ``NULL`` then the location it points to is set + to a non-zero value. *format* is the string of format characters. + + If *format* begins and ends with parentheses then a tuple of objects is + created. If *format* contains more than one format character then + parentheses must be specified. + + In the following description the first letter is the format character, the + entry in parentheses is the Python object type that the format character + will create, and the entry in brackets are the types of the C/C++ values + to be passed. + + ``a`` (string) [char \*, int] + Convert a C/C++ character array and its length to a Python string. If + the array is ``NULL`` then the length is ignored and the result is + ``Py_None``. + + ``b`` (boolean) [int] + Convert a C/C++ ``int`` to a Python boolean. + + ``c`` (string) [char] + Convert a C/C++ ``char`` to a Python string. + + ``d`` (float) [double] + Convert a C/C++ ``double`` to a Python floating point number. + + ``e`` (integer) [enum] + Convert an anonymous C/C++ ``enum`` to a Python integer. + + ``f`` (float) [float] + Convert a C/C++ ``float`` to a Python floating point number. + + ``h`` (integer) [short] + Convert a C/C++ ``short`` to a Python integer. + + ``i`` (integer) [int] + Convert a C/C++ ``int`` to a Python integer. + + ``l`` (long) [long] + Convert a C/C++ ``long`` to a Python integer. + + ``m`` (long) [unsigned long] + Convert a C/C++ ``unsigned long`` to a Python long. + + ``n`` (long) [long long] + Convert a C/C++ ``long long`` to a Python long. + + ``o`` (long) [unsigned long long] + Convert a C/C++ ``unsigned long long`` to a Python long. + + ``s`` (string) [char \*] + Convert a C/C++ ``'\0'`` terminated string to a Python string. If the + string pointer is ``NULL`` then the result is ``Py_None``. + + ``t`` (long) [unsigned short] + Convert a C/C++ ``unsigned short`` to a Python long. + + ``u`` (long) [unsigned int] + Convert a C/C++ ``unsigned int`` to a Python long. + + ``w`` (unicode) [wchar_t] + Convert a C/C++ wide character to a Python unicode object. + + ``x`` (unicode) [wchar_t \*] + Convert a C/C++ ``L'\0'`` terminated wide character string to a Python + unicode object. If the string pointer is ``NULL`` then the result is + ``Py_None``. + + ``A`` (unicode) [wchar_t \*, int] + Convert a C/C++ wide character array and its length to a Python unicode + object. If the array is ``NULL`` then the length is ignored and the + result is ``Py_None``. + + ``B`` (wrapped instance) [*type* \*, sipWrapperType \*, PyObject \*] + Convert a new C structure or a new C++ class instance to a Python class + instance object. Ownership of the structure or instance is determined + by the ``PyObject *`` argument. If it is ``NULL`` and the instance has + already been wrapped then the ownership is unchanged. If it is + ``NULL`` or ``Py_None`` then ownership will be with Python. Otherwise + ownership will be with C/C++ and the instance associated with the + ``PyObject *`` argument. The Python class is influenced by any + applicable `%ConvertToSubClassCode`_ code. + + ``C`` (wrapped instance) [*type* \*, sipWrapperType \*, PyObject \*] + Convert a C structure or a C++ class instance to a Python class + instance object. If the structure or class instance has already been + wrapped then the result is a new reference to the existing class + instance object. Ownership of the structure or instance is determined + by the ``PyObject *`` argument. If it is ``NULL`` and the instance has + already been wrapped then the ownership is unchanged. If it is + ``NULL`` and the instance is newly wrapped then ownership will be with + C/C++. If it is ``Py_None`` then ownership is transferred to Python + via a call to `sipTransferBack()`_. Otherwise ownership is transferred + to C/C++ and the instance associated with the ``PyObject *`` argument + via a call to `sipTransferTo()`_. The Python class is influenced by + any applicable `%ConvertToSubClassCode`_ code. + + ``D`` (object) [*type* \*, const sipMappedType \*, PyObject \*] + Convert a C structure or a C++ class instance wrapped as a mapped type + to a Python object. Ownership of the structure or instance is + determined by the ``PyObject *`` argument. If it is ``NULL`` then the + ownership is unchanged. If it is ``Py_None`` then ownership is + transferred to Python via a call to `sipTransferBack()`_. Otherwise + ownership is transferred to C/C++ and the instance associated with the + ``PyObject *`` argument via a call to `sipTransferTo()`_. + + ``E`` (wrapped enum) [enum, PyTypeObject \*] + Convert a named C/C++ ``enum`` to an instance of the corresponding + Python named enum type. + + ``M`` (wrapped instance) [*type* \*, sipWrapperType \*] + Convert a C structure or a C++ class instance to a Python class + instance object. If the structure or class instance has already been + wrapped then the result is a new reference to the existing class + instance object. If the instance has already been wrapped then the + ownership is unchanged. If the instance is newly wrapped then + ownership will be with C/C++. The Python class is influenced by any + applicable `%ConvertToSubClassCode`_ code. This is deprecated from + SIP v4.4. + + ``N`` (wrapped instance) [*type* \*, sipWrapperType \*] + Convert a C structure or a C++ class instance to a Python class + instance object. This should not be used if the structure or class + instance might already have been wrapped. Ownership of the structure + or instance will be with Python. The Python class is influenced by + any applicable `%ConvertToSubClassCode`_ code. This is deprecated + from SIP v4.4. + + ``O`` (wrapped instance) [*type* \*, sipWrapperType \*] + Convert a C structure or a C++ class instance to a Python class + instance object. If the structure or class instance has already been + wrapped then the result is a new reference to the existing class + instance object. Ownership of the structure or instance will be with + C/C++. This is deprecated from SIP v4.4. + + ``P`` (wrapped instance) [*type* \*, sipWrapperType \*] + Convert a C structure or a C++ class instance to a Python class + instance object. This should not be used if the structure or class + instance might already have been wrapped. Ownership of the structure + or instance will be with Python. This is deprecated from SIP v4.4. + + ``R`` (object) [PyObject \*] + The result is value passed without any conversions. The reference + count is unaffected, i.e. a reference is taken. + + ``S`` (object) [PyObject \*] + The result is value passed without any conversions. The reference + count is incremented. + + ``T`` (object) [void \*, PyObject \*(\*)(void \*cppptr)] + Convert a C structure or a C++ class instance to a Python object using + a convertor function. See `Generated Type Convertors`_. This is + deprecated from SIP v4.4. + + ``V`` (sip.voidptr) [void \*] + Convert a C/C++ ``void *`` Python ``sip.voidptr`` object. + + +sipCallMethod() +--------------- + +PyObject \*sipCallMethod(int \*iserr, PyObject \*method, const char \*format, ...) + This calls a Python method passing a tuple of arguments based on a format + string and associated values in a similar way to the Python + ``PyObject_CallObject()`` function. If there was an error then ``NULL`` is + returned and a Python exception is raised. If *iserr* is not ``NULL`` + then the location it points to is set to a non-zero value. *method* is the + Python bound method to call. *format* is the string of format characters + (see `sipBuildResult()`_). + + This is normally called by handwritten code specified with the + `%VirtualCatcherCode`_ directive with *method* being the supplied + ``sipMethod``. + + +sipCanConvertToInstance() +------------------------- + +int sipCanConvertToInstance(PyObject \*obj, sipWrapperType \*type, int flags) + This returns a non-zero value if a Python object can be converted to an + instance of a C structure or C++ class. *obj* is the Python object. + *type* is the generated type corresponding to the C/C++ type being checked. + *flags* is any combination of the following values used to fine tune the + check. + + - ``SIP_NOT_NONE`` causes the check to fail if *obj* is ``None``. + + - ``SIP_NO_CONVERTORS`` suppresses the use of of any + `%ConvertToTypeCode`_ for *type*. + + +sipCanConvertToMappedType() +--------------------------- + +int sipCanConvertToMappedType(PyObject \*obj, const sipMappedType \*mt, int flags) + This returns a non-zero value if a Python object can be converted to an + instance of a C structure or C++ class which has been implemented as a + mapped type. *obj* is the Python object. *mt* is an opaque structure + returned by `sipFindMappedType()`_. *flags* is any combination of the + following values used to fine tune the check. + + - ``SIP_NOT_NONE`` causes the check to fail if *obj* is ``None``. + + +sipClassName() +-------------- + +PyObject \*sipClassName(PyObject \*obj) + This returns the class name of a wrapped instance as a Python string. It + comes with a reference. + + +sipConnectRx() +-------------- + +PyObject \*sipConnectRx(PyObject \*sender, const char \*signal, PyObject \*receiver, const char \*slot, int type) + This connects a signal to a signal or slot and returns ``Py_True`` if the + signal was connected or ``Py_False`` if not. If there was some other + error then a Python exception is raised and ``NULL`` is returned. *sender* + is the wrapped ``QObject`` derived instance that emits the signal. + *signal* is the typed name of the signal. *receiver* is the wrapped + ``QObject`` derived instance or Python callable that the signal is + connected to. *slot* is the typed name of the slot, or ``NULL`` if + *receiver* is a Python callable. *type* is the type of connection and is + cast from Qt::ConnectionType. It is normally only used by PyQt to + implement ``QObject.connect()``. + + +sipConvertFromInstance() +------------------------ + +PyObject \*sipConvertFromInstance(void \*cpp, sipWrapperType \*type, PyObject \*transferObj) + Convert a C structure or a C++ class instance to a Python class instance + object. *cpp* is the C/C++ instance. If the instance has already been + wrapped then the result is a new reference to the existing instance object. + *type* is the generated type corresponding to the C/C++ type. + *transferObj* controls the ownership of the returned value. If the + structure or class instance has already been wrapped then the result is a + new reference to the existing class instance object. If it is ``NULL`` and + the instance has already been wrapped then the ownership is unchanged. If + it is ``NULL`` and the instance is newly wrapped then ownership will be + with C/C++. If it is ``Py_None`` then ownership is transferred to Python + via a call to `sipTransferBack()`_. Otherwise ownership is transferred to + C/C++ and the instance associated with *transferObj* via a call to + `sipTransferTo()`_. The Python class is influenced by any applicable + `%ConvertToSubClassCode`_ code. + + +sipConvertFromMappedType() +-------------------------- + +PyObject \*sipConvertFromMappedType(void \*cpp, const sipMappedType \*mt, PyObject \*transferObj) + Convert a C structure or a C++ class instance wrapped as a mapped type to a + Python object. *cpp* is the C/C++ instance. *mt* is the opaque structure + returned by `sipFindMappedType()`_. *transferObj* controls any ownership + changes to *obj*. If it is ``NULL`` then the ownership is unchanged. If + it is ``Py_None`` then ownership is transferred to Python via a call to + `sipTransferBack()`_. Otherwise ownership is transferred to C/C++ and the + instance associated with the ``PyObject *`` argument via a call to + `sipTransferTo()`_. + + +sipConvertFromNamedEnum() +------------------------- + +PyObject \*sipConvertFromNamedEnum(int eval, PyTypeObject \*type) + Convert a named C/C++ ``enum`` to an instance of the corresponding Python + named enum type. *eval* is the enumerated value to convert. *type* is the + generated Python type object (see `Generated Named Enum Type Objects`_). + + +sipConvertFromNewInstance() +--------------------------- + +PyObject \*sipConvertFromNewInstance(void \*cpp, sipWrapperType \*type, PyObject \*transferObj) + Convert a new C structure or a new C++ class instance to a Python class + instance object. *cpp* is the C/C++ instance. *type* is the generated + type corresponding to the C/C++ type. *transferObj* controls the ownership + of the returned value. If it is ``NULL`` or ``Py_None`` then ownership + will be with Python. Otherwise ownership will be with C/C++ and the + instance associated with *transferObj*. The Python class is influenced by + any applicable `%ConvertToSubClassCode`_ code. + + +sipConvertFromSequenceIndex() +----------------------------- + +SIP_SSIZE_T sipConvertFromSequenceIndex(SIP_SSIZE_T idx, SIP_SSIZE_T len) + This converts a Python sequence index (i.e. where a negative value refers + to the offset from the end of the sequence) to a C/C++ array index. If the + index was out of range then a negative value is returned and a Python + exception raised. With versions of Python prior to v2.5 the result and the + arguments have type ``int``. + + +sipConvertFromSliceObject() +--------------------------- + +int sipConvertFromSliceObject(PyObject \*slice, SIP_SSIZE_T length, SIP_SSIZE_T \*start, SIP_SSIZE_T \*stop, SIP_SSIZE_T \*step, SIP_SSIZE_T \*slicelength) + This is a thin wrapper around the Python ``PySlice_GetIndicesEx()`` + function provided to make it easier to write handwritten code that is + compatible with SIP v3.x and versions of Python earlier that v2.3. + + +sipConvertToCpp() +----------------- + +void \*sipConvertToCpp(PyObject \*obj, sipWrapperType \*type, int \*iserr) + This function is deprecated from SIP v4.4. It is equivalent to:: + + sipConvertToInstance(obj, type, NULL, SIP_NO_CONVERTORS, NULL, iserr); + + +sipConvertToInstance() +---------------------- + +void \*sipConvertToInstance(PyObject \*obj, sipWrapperType \*type, PyObject \*transferObj, int flags, int \*state, int \*iserr) + This converts a Python object to an instance of a C structure or C++ class + assuming that a previous call to `sipCanConvertToInstance()`_ has been + successful. *obj* is the Python object. *type* is the generated type + corresponding to the C/C++ type returned. It may be any class in the + object's class hierarchy. *transferObj* controls any ownership changes to + *obj*. If it is ``NULL`` then the ownership is unchanged. If it is + ``Py_None`` then ownership is transferred to Python via a call to + `sipTransferBack()`_. Otherwise ownership is transferred to C/C++ and + *obj* associated with *transferObj* via a call to `sipTransferTo()`_. + *flags* is any combination of the following values used to fine tune the + check. + + - ``SIP_NOT_NONE`` causes the check to fail if *obj* is ``None``. + + - ``SIP_NO_CONVERTORS`` suppresses the use of of any + `%ConvertToTypeCode`_ for *type*. + + If *state* is not ``NULL`` then the location it points to is set to + describe the state of the returned C/C++ instance and is the value returned + by any `%ConvertToTypeCode`_. The calling code must then release the value + at some point to prevent a memory leak by calling `sipReleaseInstance()`_. + If there is an error then the location *iserr* points to is set to a + non-zero value. If it was initially a non-zero value then the conversion + isn't attempted in the first place. (This allows several calls to be made + that share the same error flag so that it only needs to be tested once + rather than after each call.) + + +sipConvertToMappedType() +------------------------ + +void \*sipConvertToMappedType(PyObject \*obj, const sipMappedType \*mt, PyObject \*transferObj, int flags, int \*state, int \*iserr) + This converts a Python object to an instance of a C structure or C++ + class that is implemented as a mapped type assuming that a previous call to + `sipCanConvertToMappedType()`_ has been successful. *obj* is the Python + object. *mt* is the opaque structure returned by `sipFindMappedType()`_. + *transferObj* controls any ownership changes to *obj*. If it is ``NULL`` + then the ownership is unchanged. If it is ``Py_None`` then ownership is + transferred to Python via a call to `sipTransferBack()`_. Otherwise + ownership is transferred to C/C++ and *obj* associated with *transferObj* + via a call to `sipTransferTo()`_. *flags* is any combination of the + following values used to fine tune the check. + + - ``SIP_NOT_NONE`` causes the check to fail if *obj* is ``None``. + + If *state* is not ``NULL`` then the location it points to is set to + describe the state of the returned C/C++ instance and is the value returned + by any `%ConvertToTypeCode`_. The calling code must then release the value + at some point to prevent a memory leak by calling + `sipReleaseMappedType()`_. If there is an error then the location *iserr* + points to is set to a non-zero value. If it was initially a non-zero value + then the conversion isn't attempted in the first place. (This allows + several calls to be made that share the same error flag so that it only + needs to be tested once rather than after each call.) + + +sipDisconnectRx() +----------------- + +PyObject \*sipDisconnectRx(PyObject \*sender, const char \*signal, PyObject \*receiver, const char \*slot) + This disconnects a signal from a signal or slot and returns ``Py_True`` if + the signal was disconnected or ``Py_False`` if not. If there was some + other error then a Python exception is raised and ``NULL`` is returned. + *sender* is the wrapped ``QObject`` derived instance that emits the signal. + *signal* is the typed name of the signal. *receiver* is the wrapped + ``QObject`` derived instance or Python callable that the signal is + connected to. *slot* is the typed name of the slot, or ``NULL`` if + *receiver* is a Python callable. It is normally only used by PyQt to + implement ``QObject.disconnect()``. + + +sipEmitSignal() +--------------- + +int sipEmitSignal(PyObject \*txobj, const char \*signal, PyObject \*args) + This emits a signal and returns zero if there was no error. If there was + an error then a Python exception is raised and a negative value is + returned. *txobj* is the wrapped ``QObject`` derived instance that emits + the signal. *signal* is the typed name of the signal. *args* is a Python + tuple of the signal arguments. It is normally only used by PyQt to + implement ``QObject.emit()``. + + +sipExportSymbol() +----------------- + +int sipExportSymbol(const char \*name, void \*sym) + Python does not allow extension modules to directly access symbols in + another extension module. This exports a symbol, referenced by a name, + that can subsequently be imported, using `sipImportSymbol()`_, by another + module. *name* is the name of the symbol and *sym* is its value. Zero is + returned if there was no error. A negative value is returned if *name* is + already associated with a symbol or there was some other error. + + +sipFindClass() +-------------- + +sipWrapperType \*sipFindClass(const char \*type) + This returns a pointer to the generated type corresponding to a C/C++ type. + *type* is the C/C++ declaration of the type. ``NULL`` is returned if the + C/C++ type doesn't exist. The value of the pointer will not change and + may be saved in a static cache. + + +sipFindMappedType() +------------------- + +const sipMappedType \*sipFindMappedType(const char \*type) + This returns a pointer to an opaque structure describing a mapped type. + *type* is the C/C++ declaration of the type. ``NULL`` is returned if the + mapped type doesn't exist. The value of the pointer will not change and + may be saved in a static cache. + + +sipFindNamedEnum() +------------------ + +PyTypeObject \*sipFindNamedEnum(const char \*type) + This returns a pointer to the generated type corresponding to a named C/C++ + enum. *type* is the C/C++ declaration of the enum. ``NULL`` is returned + if the named C/C++ enum doesn't exist. The value of the pointer will not + change and may be saved in a static cache. + + +sipForceConvertToInstance() +--------------------------- + +void \*sipForceConvertToInstance(PyObject \*obj, sipWrapperType \*type, PyObject \*transferObj, int flags, int \*state, int \*iserr) + This converts a Python object to an instance of a C structure or C++ class + by calling `sipCanConvertToInstance()`_ and, if it is successfull, calling + `sipConvertToInstance()`_. See `sipConvertToInstance()`_ for a full + description of the arguments. + + +sipForceConvertToMappedType() +----------------------------- + +void \*sipForceConvertToMappedType(PyObject \*obj, const sipMappedType \*mt, PyObject \*transferObj, int flags, int \*state, int \*iserr) + This converts a Python object to an instance of a C structure or C++ class + which has been implemented as a mapped type by calling + `sipCanConvertToMappedType()`_ and, if it is successfull, calling + `sipConvertToMappedType()`_. See `sipConvertToMappedType()`_ for a full + description of the arguments. + + +sipFree() +--------- + +void sipFree(void \*mem) + This returns an area of memory allocated by `sipMalloc()`_ to the heap. + *mem* is a pointer to the area of memory. + + +sipGetSender() +-------------- + +const void \*sipGetSender() + This returns a pointer to the last ``QObject`` instance that emitted a Qt + signal. It is normally only used by PyQt to implement + ``QObject.sender()``. + + +sipGetWrapper() +--------------- + +PyObject \*sipGetWrapper(void \*cppptr, sipWrapperType \*type) + This returns a borrowed reference to the wrapped instance object for a C + structure or C++ class instance. If the structure or class instance + hasn't been wrapped then ``NULL`` is returned (and no Python exception is + raised). *cppptr* is the pointer to the structure or class instance. + *type* is the generated type corresponding to the C/C++ type. + + +sipImportSymbol() +----------------- + +void \*sipImportSymbol(const char \*name) + Python does not allow extension modules to directly access symbols in + another extension module. This imports a symbol, referenced by a name, + that has previously been exported, using `sipExportSymbol()`_, by another + module. *name* is the name of the symbol. The value of the symbol is + returned if there was no error. ``NULL`` is returned if there is no such + symbol. + + +sipIntTypeClassMap +------------------ + +This C structure is used with `sipMapIntToClass()`_ to define a mapping +between integer based RTTI and `generated type objects`_. The structure +elements are as follows. + +int typeInt + The integer RTTI. + +sipWrapperType \*\*pyType. + A pointer to the corresponding Python type object. + + +sipIsSubClassInstance() +----------------------- + +int sipIsSubClassInstance(PyObject \*obj, sipWrapperType \*type) + This function is deprecated from SIP v4.4. It is equivalent to:: + + sipCanConvertToInstance(obj, type, SIP_NOT_NONE | SIP_NO_CONVERTORS); + + +sipLong_AsUnsignedLong() +------------------------ + +unsigned long sipLong_AsUnsignedLong(PyObject \*obj) + This function is a thin wrapper around PyLong_AsUnsignedLong() that works + around a bug in Python v2.3.x and earlier when converting integer objects. + + +sipMalloc() +----------- + +void \*sipMalloc(size_t nbytes) + This allocates an area of memory of size *nytes* on the heap using the + Python ``PyMem_Malloc()`` function. If there was an error then ``NULL`` is + returned and a Python exception raised. See `sipFree()`_. + + +sipMapIntToClass() +------------------ + +sipWrapperType \*sipMapIntToClass(int type, const sipIntTypeClassMap \*map, int maplen) + This is used in `%ConvertToSubClassCode`_ code as a convenient way of + converting integer based RTTI to the corresponding Python type object. + *type* is the RTTI. *map* is the table of known RTTI and the corresponding + type objects (see sipIntTypeClassMap_). The entries in the table must be + sorted in ascending order of RTTI. *maplen* is the number of entries in + the table. The corresponding Python type object is returned, or ``NULL`` + if *type* wasn't in *map*. + + +sipMapStringToClass() +--------------------- + +sipWrapperType \*sipMapStringToClass(char \*type, const sipStringTypeClassMap \*map, int maplen) + This is used in `%ConvertToSubClassCode`_ code as a convenient way of + converting ``'\0'`` terminated string based RTTI to the corresponding + Python type object. *type* is the RTTI. *map* is the table of known RTTI + and the corresponding type objects (see sipStringTypeClassMap_). The + entries in the table must be sorted in ascending order of RTTI. *maplen* + is the number of entries in the table. The corresponding Python type + object is returned, or ``NULL`` if *type* wasn't in *map*. + + +sipParseResult() +---------------- + +int sipParseResult(int \*iserr, PyObject \*method, PyObject \*result, const char \*format, ...) + This converts a Python object (usually returned by a method) to C/C++ based + on a format string and associated values in a similar way to the Python + ``PyArg_ParseTuple()`` function. If there was an error then a negative + value is returned and a Python exception is raised. If *iserr* is not + ``NULL`` then the location it points to is set to a non-zero value. + *method* is the Python bound method that returned the *result* object. + *format* is the string of format characters. + + This is normally called by handwritten code specified with the + `%VirtualCatcherCode`_ directive with *method* being the supplied + ``sipMethod`` and ``result`` being the value returned by + `sipCallMethod()`_. + + If *format* begins and ends with parentheses then *result* must be a Python + tuple and the rest of *format* is applied to the tuple contents. + + In the following description the first letter is the format character, the + entry in parentheses is the Python object type that the format character + will convert, and the entry in brackets are the types of the C/C++ values + to be passed. + + ``a`` (string) [char \*\*, int \*] + Convert a Python string to a C/C++ character array and its length. If + the Python object is ``Py_None`` then the array and length are ``NULL`` + and zero respectively. + + ``b`` (integer) [bool \*] + Convert a Python integer to a C/C++ ``bool``. + + ``c`` (string) [char \*] + Convert a Python string of length 1 to a C/C++ ``char``. + + ``d`` (float) [double \*] + Convert a Python floating point number to a C/C++ ``double``. + + ``e`` (integer) [enum \*] + Convert a Python integer to an anonymous C/C++ ``enum``. + + ``f`` (float) [float \*] + Convert a Python floating point number to a C/C++ ``float``. + + ``h`` (integer) [short \*] + Convert a Python integer to a C/C++ ``short``. + + ``i`` (integer) [int \*] + Convert a Python integer to a C/C++ ``int``. + + ``l`` (long) [long \*] + Convert a Python long to a C/C++ ``long``. + + ``m`` (long) [unsigned long \*] + Convert a Python long to a C/C++ ``unsigned long``. + + ``n`` (long) [long long \*] + Convert a Python long to a C/C++ ``long long``. + + ``o`` (long) [unsigned long long \*] + Convert a Python long to a C/C++ ``unsigned long long``. + + ``s`` (string) [char \*\*] + Convert a Python string to a C/C++ ``'\0'`` terminated string. If the + Python object is ``Py_None`` then the string is ``NULL``. + + ``t`` (long) [unsigned short \*] + Convert a Python long to a C/C++ ``unsigned short``. + + ``u`` (long) [unsigned int \*] + Convert a Python long to a C/C++ ``unsigned int``. + + ``w`` (unicode) [wchar_t \*] + Convert a Python unicode object of length 1 to a C/C++ wide character. + + ``x`` (unicode) [wchar_t \*\*] + Convert a Python unicode object to a C/C++ ``L'\0'`` terminated wide + character string. If the Python object is ``Py_None`` then the string + is ``NULL``. + + ``A`` (unicode) [wchar_t \*\*, int \*] + Convert a Python unicode object to a C/C++ wide character array and its + length. If the Python object is ``Py_None`` then the array and length + are ``NULL`` and zero respectively. + + ``Cf`` (wrapped class) [sipWrapperType \*, int \*, void \*\*] + Convert a Python object to a C structure or a C++ class instance and + return its state as described in `sipConvertToInstance()`_. ``f`` is a + combination of the following flags encoded as an ASCII character by + adding ``0`` to the combined value: + + 0x01 disallows the conversion of ``Py_None`` to ``NULL`` + + 0x02 implements the `Factory`_ annotation + + 0x04 suppresses the return of the state of the returned C/C++ + instance. Note that the ``int *`` used to return the state is + not passed if this flag is specified. + + ``Df`` (mapped type) [const sipMappedType \*, int \*, void \*\*] + Convert a Python object to a C structure or a C++ class instance + implemented as a mapped type and return its state as described in + `sipConvertToMappedType()`_. ``f`` is a combination of the following + flags encoded as an ASCII character by adding ``0`` to the combined + value: + + 0x01 disallows the conversion of ``Py_None`` to ``NULL`` + + 0x02 implements the `Factory`_ annotation + + 0x04 suppresses the return of the state of the returned C/C++ + instance. Note that the ``int *`` used to return the state is + not passed if this flag is specified. + + ``E`` (wrapped enum) [PyTypeObject \*, enum \*] + Convert a Python named enum type to the corresponding C/C++ ``enum``. + + ``L`` (object) [*type* \*(\*)(PyObject \*obj, int \*iserr), void \*\*] + Convert a Python object to a C structure or a C++ class instance using + a convertor function. See `Generated Type Convertors`_. This is + deprecated from SIP v4.4. + + ``M`` (object) [*type* \*(\*)(PyObject \*obj, int \*iserr), void \*\*] + Convert a Python object to a C structure or a C++ class instance using + a convertor function. If the structure or class instance pointer is + ``NULL`` then return an error. See `Generated Type Convertors`_. This + is deprecated from SIP v4.4. + + ``N`` (object) [PyTypeObject \*, PyObject \*\*] + A Python object is checked to see if it is a certain type and then + returned without any conversions. The reference count is incremented. + The Python object may be ``Py_None``. + + ``O`` (object) [PyObject \*\*] + A Python object is returned without any conversions. The reference + count is incremented. + + ``T`` (object) [PyTypeObject \*, PyObject \*\*] + A Python object is checked to see if it is a certain type and then + returned without any conversions. The reference count is incremented. + The Python object may not be ``Py_None``. + + ``V`` (sip.voidptr) [void \*] + Convert a Python ``sip.voidptr`` object to a C/C++ ``void *``. + + ``Z`` (object) [] + Check that a Python object is ``Py_None``. No value is returned. + + +sipReleaseInstance() +-------------------- + +void sipReleaseInstance(void \*cpp, sipWrapperType \*type, int state) + This destroys a wrapped C/C++ instance if it was a temporary instance. It + is called after a call to either `sipConvertToInstance()`_ or + `sipForceConvertToInstance()`_. *cpp* is the wrapped C/C++ instance. + *type* is the generated type corresponding to *cpp*. *state* describes the + state of the instance. + + +sipReleaseMappedType() +---------------------- + +void sipReleaseMappedType(void \*cpp, const sipMappedType \*mt, int state) + This destroys a wrapped C/C++ mapped type if it was a temporary instance. + It is called after a call to either `sipConvertToMappedType()`_ or + `sipForceConvertToMappedType()`_. *cpp* is the wrapped C/C++ instance. + *mt* is the opaque structure returned by `sipFindMappedType()`_. *state* + describes the state of the instance. + + +sipStringTypeClassMap +--------------------- + +This C structure is used with `sipMapStringToClass()`_ to define a mapping +between ``'\0'`` terminated string based RTTI and `generated type objects`_. +The structure elements are as follows. + +char \*typeString + The ``'\0'`` terminated string RTTI. + +sipWrapperType \*\*pyType. + A pointer to the corresponding Python type object. + + +sipTransfer() +------------- + +void sipTransfer(PyObject \*obj, int tocpp) + This function is deprecated from SIP v4.3. If *tocpp* is non-zero then the + equivalent call is:: + + sipTransferTo(obj, obj); + + If *tocpp* is zero then the equivalent call is:: + + sipTransferBack(obj); + + +sipTransferBack() +----------------- + +void sipTransferBack(PyObject \*obj) + This transfers ownership of a Python wrapped instance to Python (see + `Ownership of Objects`_). *obj* is the wrapped instance. In addition, + any association of the instance with regard to the cyclic garbage + collector with another instance is removed. + + +sipTransferTo() +--------------- + +void sipTransferTo(PyObject \*obj, PyObject \*owner) + This transfers ownership of a Python wrapped instance to C++ (see + `Ownership of Objects`_). *obj* is the wrapped instance. *owner* is an + optional wrapped instance that *obj* becomes associated with with regard + to the cyclic garbage collector. If *owner* is ``NULL`` then no such + association is made. If *owner* is the same value as *obj* then any + reference cycles involving *obj* can never be detected or broken by the + cyclic garbage collector. Responsibility for calling the C++ instance's + destructor is always transfered to C++. + + +sipWrapper +---------- + +This is a C structure that represents a Python wrapped instance. It is an +extension of the Python ``PyObject`` structure and so may be safely cast to +``PyObject``. It includes a member called ``user`` which is of type +``PyObject *``. This can be used for any purpose by handwritten code and will +automatically be garbage collected at the appropriate time. + + +sipWrapper_Check() +------------------ + +int sipWrapper_Check(PyObject \*obj) + This returns a non-zero value if a Python object is a wrapped instance. + *obj* is the Python object. + + +sipWrapperType +-------------- + +This is a C structure that represents a SIP generated type object. It is an +extension of the Python ``PyTypeObject`` structure (which is itself an +extension of the Python ``PyObject`` structure) and so may be safely cast to +``PyTypeObject`` (and ``PyObject``). + + +Generated Type Convertors +------------------------- + +These functions are deprecated from SIP v4.4. + +SIP generates functions for all types being wrapped (including mapped types +defined with the `%MappedType`_ directive) that convert a Python object to the +C structure or C++ class instance. The name of this convertor is the name of +the structure or class prefixed by ``sipForceConvertTo_``. + +void \*sipForceConvertTo_*class*(PyObject \*obj, int \*iserr) + *obj* is the Python object to convert. If *obj* is ``NULL`` or the + location pointed to by *iserr* is non-zero then the conversion is not + attempted and ``NULL`` is returned. If there was an error then the + location pointed to by *iserr* is set to a non-zero value, a Python + exception is raised, and ``NULL`` is returned. + +SIP also generates functions for mapped types that convert a C structure or +C++ class instance to a Python object. The name of this convertor is the name +of the structure or class prefixed by ``sipConvertFrom_``. + +PyObject \*sipConvertFrom_*class*(void \*cppptr) + *cppptr* is a pointer to the C structure or C++ class instance to convert. + If there was an error then ``NULL`` is returned and a Python exception + raised. + +The convertor functions of all imported types are available to handwritten +code. + + +Generated Type Objects +---------------------- + +SIP generates a type object for each C structure or C++ class being wrapped. +These are sipWrapperType_ structures and are used extensively by the SIP API. + +These objects are named with the structure or class name prefixed by +``sipClass_``. For example, the type object for class ``Klass`` is +``sipClass_Klass``. + +The type objects of all imported classes are available to handwritten code. + + +Generated Named Enum Type Objects +--------------------------------- + +SIP generates a type object for each named enum being wrapped. These are +PyTypeObject structures. (Anonymous enums are wrapped as Python integers.) + +These objects are named with the fully qualified enum name (i.e. including any +enclosing scope) prefixed by ``sipEnum_``. For example, the type object for +enum ``Enum`` defined in class ``Klass`` is ``sipEnum_Klass_Enum``. + +The type objects of all imported named enums are available to handwritten code. + + +Generated Derived Classes +------------------------- + +For most C++ classes being wrapped SIP generates a derived class with the same +name prefixed by ``sip``. For example, the derived class for class ``Klass`` +is ``sipKlass``. + +If a C++ class doesn't have any virtual or protected methods in it or any of +it's super-class hierarchy, or does not emit any Qt signals, then a derived +class is not generated. + +Most of the time handwritten code should ignore the derived classes. The only +exception is that handwritten constructor code specified using the +`%MethodCode`_ directive should call the derived class's constructor (which +has the same C++ signature) rather then the wrapped class's constructor. + + +Generated Exception Objects +--------------------------- + +SIP generates a Python object for each exception defined with the `%Exception_` +directive. + +These objects are named with the fully qualified exception name (i.e. including +any enclosing scope) prefixed by ``sipException_``. For example, the type +object for enum ``Except`` defined in class ``Klass`` is +``sipException_Klass_Except``. + +The objects of all imported exceptions are available to handwritten code. + + +Using the SIP Module in Applications +==================================== + +The main purpose of the SIP module is to provide functionality common to all +SIP generated bindings. It is loaded automatically and most of the time you +will completely ignore it. However, it does expose some functionality that can +be used by applications. + +cast(obj, type) + This does the Python equivalent of casting a C++ instance to one of its + sub or super-class types. *obj* is the Python object and *type* is the + type. A new Python object is returned that wraps the same C++ instance as + *obj*, but has the type *type*. + +delete(obj) + For C++ instances this calls the C++ destructor. For C structures it + returns the structure's memory to the heap. *obj* is the Python object. + +isdeleted(obj) + This returns True if the C++ instance or C structure has been destroyed or + returned to the heap. *obj* is the Python object. + +setdeleted(obj) + This marks the C++ instance or C structure as having been destroyed or + returned to the heap so that future references to it raise an exception + rather than cause a program crash. Normally SIP handles such things + automatically, but there are circumstances where this isn't possible. + *obj* is the Python object. + +settracemask(mask) + If the bindings have been created with SIP's ``-r`` command line option + then the generated code will produce debugging statements that trace the + execution of the code. (It is particularly useful when trying to + understand the operation of a C++ library's virtual function calls.) + + Debugging statements are generated at the following points: + + - in a C++ virtual function (*mask* is ``0x0001``) + - in a C++ constructor (*mask* is ``0x0002``) + - in a C++ destructor (*mask* is ``0x0004``) + - in a Python type's __init__ method (*mask* is ``0x0008``) + - in a Python type's __del__ method (*mask* is ``0x0010``) + - in a Python type's ordinary method (*mask* is ``0x0020``). + + By default the trace mask is zero and all debugging statements are + disabled. + +SIP_VERSION + This is a Python integer object that represents the SIP version number as + a 3 part hexadecimal number (e.g. v4.0.0 is represented as ``0x040000``). + It was first implemented in SIP v4.2. + +SIP_VERSION_STR + This is a Python string object that defines the SIP version number as + represented as a string. For development snapshots it will start with + ``snapshot-``. It was first implemented in SIP v4.3. + +transfer(obj, direction) + This function is deprecated from SIP v4.3. If *direction* is non-zero then + the equivalent call is:: + + sip.transferto(obj, None) + + If *direction* is zero then the equivalent call is:: + + sip.transferback(obj) + +transferback(obj) + This function is a wrapper around `sipTransferBack()`_. + +transferto(obj, owner) + This function is a wrapper around `sipTransferTo()`_. + +unwrapinstance(obj) + Return the address, as a number, of the wrapped C/C++ structure or class + instance *obj*. + +voidptr + This is the type object for the type SIP uses to represent a C/C++ + ``void *``. The type constructor takes a single argument that must either + be another ``voidptr``, ``None``, a Python CObject, or an integer. The + type has the following methods: + + __int__() + This returns the pointer as an integer. + + __hex__() + This returns the pointer as a hexadecimal string. + + ascobject() + This returns the pointer as a Python CObject. + + asstring(nbytes) + This returns a copy of the first *nbytes* of memory at the pointer as a + Python string. + +wrapinstance(addr, type) + A C/C++ structure or class instance is wrapped and the Python object + created is returned. If the instance has already been wrapped then a new + reference to the existing object is returned. *addr* is the address of + the instance represented as a number. *type* is the type of the object + (e.g. ``qt.QWidget``). + +wrapper + This is the type object of the base type of all instances wrapped by SIP. + +wrappertype + This is the type object of the metatype of the ``wrapper`` type. + + +The SIP Build System +==================== + +The purpose of the build system is to make it easy for you to write +configuration scripts in Python for your own bindings. The build system takes +care of the details of particular combinations of platform and compiler. It +supports over 50 different platform/compiler combinations. + +The build system is implemented as a pure Python module called ``sipconfig`` +that contains a number of classes and functions. Using this module you can +write bespoke configuration scripts (e.g. PyQt's ``configure.py``) or use it +with other Python based build systems (e.g. +`Distutils <http://www.python.org/sigs/distutils-sig/distutils.html>`_ and +`SCons <http://www.scons.org>`_). + +An important feature of SIP is the ability to generate bindings that are built +on top of existing bindings. For example, both +`PyKDE <http://www.riverbankcomputing.co.uk/pykde/>`_ and +`PyQwt <http://pyqwt.sourceforge.net/>`_ are built on top of PyQt but all three +packages are maintained by different developers. To make this easier PyQt +includes its own configuration module, ``pyqtconfig``, that contains additional +classes intended to be used by the configuration scripts of bindings built on +top of PyQt. The SIP build system includes facilities that do a lot of the +work of creating these additional configuration modules. + + +``sipconfig`` Functions +----------------------- + +create_config_module(module, template, content, macros=None) + This creates a configuration module (e.g. ``pyqtconfig``) from a template + file and a string. + + ``module`` is the name of the configuration module file to create. + + ``template`` is the name of the template file. + + ``content`` is a string which replaces every occurence of the pattern + ``@SIP_CONFIGURATION@`` in the template file. The content string is + usually created from a Python dictionary using + ``sipconfig.create_content()``. ``content`` may also be a dictionary, in + which case ``sipconfig.create_content()`` is automatically called to + convert it to a string. + + ``macros`` is an optional dictionary of platform specific build macros. It + is only used if ``sipconfig.create_content()`` is called automatically to + convert a ``content`` dictionary to a string. + +create_content(dict, macros=None) + This converts a Python dictionary to a string that can be parsed by the + Python interpreter and converted back to an equivalent dictionary. It is + typically used to generate the content string for + ``sipconfig.create_config_module()``. + + ``dict`` is the Python dictionary to convert. + + ``macros`` is the optional dictionary of platform specific build macros. + + Returns the dictionary as a string. + +create_wrapper(script, wrapper, gui=0) + This creates a platform dependent executable wrapper around a Python + script. + + ``script`` is the full pathname of the script. + + ``wrapper`` is the pathname of the wrapper to create. + + ``gui`` is non-zero if a GUI enabled version of the interpreter should be + used on platforms that require it. + + Returns the platform specific name of the wrapper. + +error(msg) + This displays an error message on ``stderr`` and calls ``sys.exit()`` with + a value of 1. + + ``msg`` is the text of the message and should not include any newline + characters. + +format(msg, leftmargin=0, rightmargin=78) + This formats a message by inserting newline characters at appropriate + places. + + ``msg`` is the text of the message and should not include any newline + characters. + + ``leftmargin`` is the optional position of the left margin. + + ``rightmargin`` is the optional position of the right margin. + +inform(msg) + This displays an information message on ``stdout``. + + ``msg`` is the text of the message and should not include any newline + characters. + +parse_build_macros(filename, names, overrides=None, properties=None) + This parses a qmake compatible file of build system macros and converts it + to a dictionary. A macro is a name/value pair. The dictionary is returned + or None if any of the overrides was invalid. + + ``filename`` is the name of the file to parse. + + ``names`` is a list of the macro names to extract from the file. + + ``overrides`` is an optional list of macro names and values that modify + those found in the file. They are of the form *name=value* (in which case + the value replaces the value found in the file) or *name+=value* (in which + case the value is appended to the value found in the file). + + ``properties`` is an optional dictionary of property name and values that + are used to resolve any expressions of the form ``$[name]`` in the file. + +read_version(filename, description, numdefine=None, strdefine=None) + This extracts version information for a package from a file, usually a C or + C++ header file. The version information must each be specified as a + ``#define`` of a numeric (hexadecimal or decimal) value and/or a string + value. + + ``filename`` is the name of the file to read. + + ``description`` is a descriptive name of the package used in error + messages. + + ``numdefine`` is the optional name of the ``#define`` of the version as a + number. If it is ``None`` then the numeric version is ignored. + + ``strdefine`` is the optional name of the ``#define`` of the version as a + string. If it is ``None`` then the string version is ignored. + + Returns a tuple of the numeric and string versions. ``sipconfig.error()`` + is called if either were required but could not be found. + +version_to_sip_tag(version, tags, description) + This converts a version number to a SIP version tag. SIP uses the + `%Timeline`_ directive to define the chronology of the different versions + of the C/C++ library being wrapped. Typically it is not necessary to + define a version tag for every version of the library, but only for those + versions that affect the library's API as SIP sees it. + + ``version`` is the numeric version number of the C/C++ library being + wrapped. If it is negative then the latest version is assumed. (This is + typically useful if a snapshot is indicated by a negative version number.) + + ``tags`` is the dictionary of SIP version tags keyed by the corresponding + C/C++ library version number. The tag used is the one with the smallest + key (i.e. earliest version) that is greater than ``version``. + + ``description`` is a descriptive name of the C/C++ library used in error + messages. + + Returns the SIP version tag. ``sipconfig.error()`` is called if the C/C++ + library version number did not correspond to a SIP version tag. + +version_to_string(v) + This converts a 3 part version number encoded as a hexadecimal value to a + string. + + ``v`` is the version number. + + Returns a string. + + +``sipconfig`` Classes +--------------------- + +Configuration + This class encapsulates configuration values that can be accessed as + instance objects. A sub-class may provide a dictionary of additional + configuration values in its constructor the elements of which will have + precedence over the super-class's values. + + The following configuration values are provided: + + default_bin_dir + The name of the directory where executables should be installed by + default. + + default_mod_dir + The name of the directory where SIP generated modules should be + installed by default. + + default_sip_dir + The name of the base directory where the ``.sip`` files for SIP + generated modules should be installed by default. A sub-directory + with the same name as the module should be created and its ``.sip`` + files should be installed in the sub-directory. The ``.sip`` + files only need to be installed if you might want to build other + bindings based on them. + + platform + The name of the platform/compiler for which the build system has + been configured for. + + py_conf_inc_dir + The name of the directory containing the ``pyconfig.h`` header + file. + + py_inc_dir + The name of the directory containing the ``Python.h`` header file. + + py_lib_dir + The name of the directory containing the Python interpreter + library. + + py_version + The Python version as a 3 part hexadecimal number (e.g. v2.3.3 is + represented as ``0x020303``). + + sip_bin + The full pathname of the SIP executable. + + sip_config_args + The command line passed to ``configure.py`` when SIP was + configured. + + sip_inc_dir + The name of the directory containing the ``sip.h`` header file. + + sip_mod_dir + The name of the directory containing the SIP module. + + sip_version + The SIP version as a 3 part hexadecimal number (e.g. v4.0.0 is + represented as ``0x040000``). + + sip_version_str + The SIP version as a string. For development snapshots it will + start with ``snapshot-``. + + universal + The name of the MacOS/X SDK used when creating universal binaries. + + __init__(self, sub_cfg=None) + Initialise the instance. + + ``sub_cfg`` is an optional list of sub-class configurations. It should + only be used by the ``__init__()`` method of a sub-class to append its + own dictionary of configuration values before passing the list to its + super-class. + + build_macros(self) + Return the dictionary of platform specific build macros. + + set_build_macros(self, macros) + Set the dictionary of platform specific build macros to be use when + generating Makefiles. Normally there is no need to change the default + macros. + +Makefile + This class encapsulates a Makefile. It is intended to be sub-classed to + generate Makefiles for particular purposes. It handles all platform and + compiler specific flags, but allows them to be adjusted to suit the + requirements of a particular module or program. These are defined using a + number of macros which can be accessed as instance objects. + + The following instance objects are provided to help in fine tuning the + generated Makefile: + + chkdir + A string that will check for the existence of a directory. + + config + A reference to the ``configuration`` argument that was passed to + the constructor. + + console + A reference to the ``console`` argument that was passed to the + constructor. + + copy + A string that will copy a file. + + extra_cflags + A list of additional flags passed to the C compiler. + + extra_cxxflags + A list of additional flags passed to the C++ compiler. + + extra_defines + A list of additional macro names passed to the C/C++ preprocessor. + + extra_include_dirs + A list of additional include directories passed to the C/C++ + preprocessor. + + extra_lflags + A list of additional flags passed to the linker. + + extra_lib_dirs + A list of additional library directories passed to the linker. + + extra_libs + A list of additional libraries passed to the linker. The names of + the libraries must be in platform neutral form (i.e. without any + platform specific prefixes, version numbers or extensions). + + generator + A string that defines the platform specific style of Makefile. The + only supported values are ``UNIX`` and something else that is not + ``UNIX``. + + mkdir + A string that will create a directory. + + rm + A string that will remove a file. + + __init__(self, configuration, console=0, qt=0, opengl=0, python=0, threaded=0, warnings=None, debug=0, dir=None, makefile="Makefile", installs=None, universal='') + Initialise the instance. + + ``configuration`` is the current configuration and is an instance of + the ``Configuration`` class or a sub-class. + + ``console`` is set if the target is a console (rather than GUI) target. + This only affects Windows and is ignored on other platforms. + + ``qt`` is set if the target uses Qt. For Qt v4 a list of Qt libraries + may be specified and a simple non-zero value implies QtCore and QtGui. + + ``opengl`` is set if the target uses OpenGL. + + ``python`` is set if the target uses Python.h. + + ``threaded`` is set if the target requires thread support. It is set + automatically if the target uses Qt and Qt has thread support enabled. + + ``warnings`` is set if compiler warning messages should be enabled. + The default of ``None`` means that warnings are enabled for SIP v4.x + and disabled for SIP v3.x. + + ``debug`` is set if debugging symbols should be generated. + + ``dir`` is the name of the directory where build files are read from + and Makefiles are written to. The default of ``None`` means the + current directory is used. + + ``makefile`` is the name of the generated Makefile. + + ``installs`` is a list of extra install targets. Each element is a two + part list, the first of which is the source and the second is the + destination. If the source is another list then it is a list of source + files and the destination is a directory. + + ``universal`` is the name of the SDK if universal binaries are to be + created under MacOS/X. + + clean_build_file_objects(self, mfile, build) + This generates the Makefile commands that will remove any files + generated during the build of the default target. + + ``mfile`` is the Python file object of the Makefile. + + ``build`` is the dictionary created from parsing the build file. + + finalise(self) + This is called just before the Makefile is generated to ensure that it + is fully configured. It must be reimplemented by a sub-class. + + generate(self) + This generates the Makefile. + + generate_macros_and_rules(self, mfile) + This is the default implementation of the Makefile macros and rules + generation. + + ``mfile`` is the Python file object of the Makefile. + + generate_target_clean(self, mfile) + This is the default implementation of the Makefile clean target + generation. + + ``mfile`` is the Python file object of the Makefile. + + generate_target_default(self, mfile) + This is the default implementation of the Makefile default target + generation. + + ``mfile`` is the Python file object of the Makefile. + + generate_target_install(self, mfile) + This is the default implementation of the Makefile install target + generation. + + ``mfile`` is the Python file object of the Makefile. + + install_file(self, mfile, src, dst, strip=0) + This generates the Makefile commands to install one or more files to a + directory. + + ``mfile`` is the Python file object of the Makefile. + + ``src`` is the name of a single file to install or a list of a number + of files to install. + + ``dst`` is the name of the destination directory. + + ``strip`` is set if the files should be stripped of unneeded symbols + after having been installed. + + optional_list(self, name) + This returns an optional Makefile macro as a list. + + ``name`` is the name of the macro. + + Returns the macro as a list. + + optional_string(self, name, default="") + This returns an optional Makefile macro as a string. + + ``name`` is the name of the macro. + + ``default`` is the optional default value of the macro. + + Returns the macro as a string. + + parse_build_file(self, filename) + This parses a build file (created with the ``-b`` SIP command line + option) and converts it to a dictionary. It can also validate an + existing dictionary created through other means. + + ``filename`` is the name of the build file, or is a dictionary to be + validated. A valid dictionary will contain the name of the target to + build (excluding any platform specific extension) keyed by ``target``; + the names of all source files keyed by ``sources``; and, optionally, + the names of all header files keyed by ``headers``. + + Returns a dictionary corresponding to the parsed build file. + + platform_lib(self, clib, framework=0) + This converts a library name to a platform specific form. + + ``clib`` is the name of the library in cannonical form. + + ``framework`` is set if the library is implemented as a MacOS + framework. + + Return the platform specific name. + + ready(self) + This is called to ensure that the Makefile is fully configured. It is + normally called automatically when needed. + + required_string(self, name) + This returns a required Makefile macro as a string. + + ``name`` is the name of the macro. + + Returns the macro as a string. An exception is raised if the macro + does not exist or has an empty value. + +ModuleMakefile(Makefile) + This class encapsulates a Makefile to build a generic Python extension + module. + + __init__(self, configuration, build_file, install_dir=None, static=0, console=0, opengl=0, threaded=0, warnings=None, debug=0, dir=None, makefile="Makefile", installs=None, strip=1, export_all=0, universal='') + Initialise the instance. + + ``configuration`` - see ``sipconfig.Makefile.__init__()``. + + ``build_file`` is the name of the build file. Build files are + generated using the ``-b`` SIP command line option. + + ``install_dir`` is the name of the directory where the module will be + optionally installed. + + ``static`` is set if the module should be built as a static library + (see `Builtin Modules and Custom Interpreters`_). + + ``console`` - see ``sipconfig.Makefile.__init__()``. + + ``qt`` - see ``sipconfig.Makefile.__init__()``. + + ``opengl`` - see ``sipconfig.Makefile.__init__()``. + + ``threaded`` - see ``sipconfig.Makefile.__init__()``. + + ``warnings`` - see ``sipconfig.Makefile.__init__()``. + + ``debug`` - see ``sipconfig.Makefile.__init__()``. + + ``dir`` - see ``sipconfig.Makefile.__init__()``. + + ``makefile`` - see ``sipconfig.Makefile.__init__()``. + + ``installs`` - see ``sipconfig.Makefile.__init__()``. + + ``strip`` is set if the module should be stripped of unneeded symbols + after installation. It is ignored if either ``debug`` or ``static`` is + set, or if the platform doesn't support it. + + ``export_all`` is set if all of the module's symbols should be exported + rather than just the module's initialisation function. Exporting all + symbols increases the size of the module and slows down module load + times but may avoid problems with modules that use C++ exceptions. All + symbols are exported if either ``debug`` or ``static`` is set, or if + the platform doesn't support it. + + finalise(self) + This is a reimplementation of ``sipconfig.Makefile.finalise()``. + + generate_macros_and_rules(self, mfile) + This is a reimplementation of + ``sipconfig.Makefile.generate_macros_and_rules()``. + + generate_target_clean(self, mfile) + This is a reimplementation of + ``sipconfig.Makefile.generate_target_clean()``. + + generate_target_default(self, mfile) + This is a reimplementation of + ``sipconfig.Makefile.generate_target_default()``. + + generate_target_install(self, mfile) + This is a reimplementation of + ``sipconfig.Makefile.generate_target_install()``. + + module_as_lib(self, mname) + This returns the name of a SIP v3.x module for when it is used as a + library to be linked against. An exception will be raised if it is + used with SIP v4.x modules. + + ``mname`` is the name of the module. + + Returns the corresponding library name. + +ParentMakefile(Makefile) + This class encapsulates a Makefile that sits above a number of other + Makefiles in sub-directories. + + __init__(self, configuration, subdirs, dir=None, makefile="Makefile", installs=None) + Initialise the instance. + + ``configuration`` - see ``sipconfig.Makefile.__init__()``. + + ``subdirs`` is the sequence of sub-directories. + + ``dir`` - see ``sipconfig.Makefile.__init__()``. + + ``makefile`` - see ``sipconfig.Makefile.__init__()``. + + ``installs`` - see ``sipconfig.Makefile.__init__()``. + + generate_macros_and_rules(self, mfile) + This is a reimplementation of + ``sipconfig.Makefile.generate_macros_and_rules()``. + + generate_target_clean(self, mfile) + This is a reimplementation of + ``sipconfig.Makefile.generate_target_clean()``. + + generate_target_default(self, mfile) + This is a reimplementation of + ``sipconfig.Makefile.generate_target_default()``. + + generate_target_install(self, mfile) + This is a reimplementation of + ``sipconfig.Makefile.generate_target_install()``. + +ProgramMakefile(Makefile) + This class encapsulates a Makefile to build an executable program. + + __init__(self, configuration, build_file=None, install_dir=None, console=0, qt=0, opengl=0, python=0, threaded=0, warnings=None, debug=0, dir=None, makefile="Makefile", installs=None, universal='') + Initialise the instance. + + ``configuration`` - see ``sipconfig.Makefile.__init__()``. + + ``build_file`` is the name of the optional build file. Build files are + generated using the ``-b`` SIP command line option. + + ``install_dir`` is the name of the directory where the executable + program will be optionally installed. + + ``console`` - see ``sipconfig.Makefile.__init__()``. + + ``qt`` - see ``sipconfig.Makefile.__init__()``. + + ``opengl`` - see ``sipconfig.Makefile.__init__()``. + + ``python`` - see ``sipconfig.Makefile.__init__()``. + + ``threaded`` - see ``sipconfig.Makefile.__init__()``. + + ``warnings`` - see ``sipconfig.Makefile.__init__()``. + + ``debug`` - see ``sipconfig.Makefile.__init__()``. + + ``dir`` - see ``sipconfig.Makefile.__init__()``. + + ``makefile`` - see ``sipconfig.Makefile.__init__()``. + + ``installs`` - see ``sipconfig.Makefile.__init__()``. + + build_command(self, source) + This creates a single command line that will create an executable + program from a single source file. + + ``source`` is the name of the source file. + + Returns a tuple of the name of the executable that will be created and + the command line. + + finalise(self) + This is a reimplementation of ``sipconfig.Makefile.finalise()``. + + generate_macros_and_rules(self, mfile) + This is a reimplementation of + ``sipconfig.Makefile.generate_macros_and_rules()``. + + generate_target_clean(self, mfile) + This is a reimplementation of + ``sipconfig.Makefile.generate_target_clean()``. + + generate_target_default(self, mfile) + This is a reimplementation of + ``sipconfig.Makefile.generate_target_default()``. + + generate_target_install(self, mfile) + This is a reimplementation of + ``sipconfig.Makefile.generate_target_install()``. + +PythonModuleMakefile(Makefile) + This class encapsulates a Makefile that installs a pure Python module. + + __init__(self, configuration, dstdir, srcdir=None, dir=None, makefile="Makefile", installs=None) + Initialise the instance. + + ``configuration`` - see ``sipconfig.Makefile.__init__()``. + + ``dstdir`` is the name of the directory in which the module's Python + code will be installed. + + ``srcdir`` is the name of the directory (relative to ``dir``) + containing the module's Python code. It defaults to the same + directory. + + ``dir`` - see ``sipconfig.Makefile.__init__()``. + + ``makefile`` - see ``sipconfig.Makefile.__init__()``. + + ``installs`` - see ``sipconfig.Makefile.__init__()``. + + generate_macros_and_rules(self, mfile) + This is a reimplementation of + ``sipconfig.Makefile.generate_macros_and_rules()``. + + generate_target_install(self, mfile) + This is a reimplementation of + ``sipconfig.Makefile.generate_target_install()``. + +SIPModuleMakefile(ModuleMakefile) + This class encapsulates a Makefile to build a SIP generated Python + extension module. + + finalise(self) + This is a reimplementation of ``sipconfig.Makefile.finalise()``. + + +Building Your Extension with distutils +====================================== + +To build the example in `A Simple C++ Example`_ using distutils, it is +sufficient to create a standard ``setup.py``, listing ``word.sip`` among the +files to build, and hook-up SIP into distutils:: + + from distutils.core import setup, Extension + import sipdistutils + + setup( + name = 'word', + versione = '1.0', + ext_modules=[ + Extension("word", ["word.sip", "word.cpp"]), + ], + + cmdclass = {'build_ext': sipdistutils.build_ext} + ) + +As we can see, the above is a normal distutils setup script, with just a +special line which is needed so that SIP can see and process ``word.sip``. +Then, running ``setup.py build`` will build our extension module. + + +Builtin Modules and Custom Interpreters +======================================= + +Sometimes you want to create a custom Python interpreter with some modules +built in to the interpreter itself rather than being dynamically loaded. To +do this the module must be created as a static library and linked with a +custom stub and the normal Python library. + +To build the SIP module as a static library you must pass the ``-k`` command +line option to ``configure.py``. You should then build and install SIP as +normal. (Note that, because the module is now a static library, you will not +be able to import it.) + +To build a module you have created for your own library you must modify your +own configuration script to pass a non-zero value as the ``static`` argument +of the ``__init__()`` method of the ``ModuleMakefile`` class (or any derived +class you have created). Normally you would make this configurable using a +command line option in the same way that SIP's ``configure.py`` handles it. + +The next stage is to create a custom stub and a Makefile. The SIP distribution +contains a directory called ``custom`` which contains example stubs and a +Python script that will create a correct Makefile. Note that, if your copy of +SIP was part of a standard Linux distribution, the ``custom`` directory may +not be installed on your system. + +The ``custom`` directory contains the following files. They are provided as +examples - each needs to be modified according to your particular +requirements. + + - ``mkcustom.py`` is a Python script that will create a Makefile which is + then used to build the custom interpreter. Comments in the file describe + how it should be modified. + + - ``custom.c`` is a stub for a custom interpreter on Linux/UNIX. It + should also be used for a custom console interpreter on Windows (i.e. + like ``python.exe``). Comments in the file describe how it should be + modified. + + - ``customw.c`` is a stub for a custom GUI interpreter on Windows (i.e. + like ``pythonw.exe``). Comments in the file describe how it should be + modified. + +Note that this technique does not restrict how the interpreter can be used. +For example, it still allows users to write their own applications that can +import your builtin modules. If you want to prevent users from doing that, +perhaps to protect a proprietary API, then take a look at the +`VendorID <http://www.riverbankcomputing.co.uk/vendorid/>`__ package. |