Initial import of SIP4 for Qt3

pull/1/head
Timothy Pearson 14 years ago
commit 6c4cc3653e

@ -0,0 +1,48 @@
RIVERBANK COMPUTING LIMITED LICENSE AGREEMENT FOR SIP
1. This LICENSE AGREEMENT is between Riverbank Computing Limited ("Riverbank"),
and the Individual or Organization ("Licensee") accessing and otherwise using
SIP software in source or binary form and its associated documentation. SIP
comprises a software tool for generating Python bindings for software C and C++
libraries, and a Python extension module used at runtime by those generated
bindings.
2. Subject to the terms and conditions of this License Agreement, Riverbank
hereby grants Licensee a nonexclusive, royalty-free, world-wide license to
reproduce, analyze, test, perform and/or display publicly, prepare derivative
works, distribute, and otherwise use SIP alone or in any derivative version,
provided, however, that Riverbank's License Agreement and Riverbank's notice of
copyright, e.g., "Copyright (c) 2010 Riverbank Computing Limited; All Rights
Reserved" are retained in SIP alone or in any derivative version prepared by
Licensee.
3. In the event Licensee prepares a derivative work that is based on or
incorporates SIP or any part thereof, and wants to make the derivative work
available to others as provided herein, then Licensee hereby agrees to include
in any such work a brief summary of the changes made to SIP.
4. Licensee may not use SIP to generate Python bindings for any C or C++
library for which bindings are already provided by Riverbank.
5. Riverbank is making SIP available to Licensee on an "AS IS" basis.
RIVERBANK MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY WAY
OF EXAMPLE, BUT NOT LIMITATION, RIVERBANK MAKES NO AND DISCLAIMS ANY
REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR
PURPOSE OR THAT THE USE OF SIP WILL NOT INFRINGE ANY THIRD PARTY RIGHTS.
6. RIVERBANK SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF SIP FOR ANY
INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF MODIFYING,
DISTRIBUTING, OR OTHERWISE USING SIP, OR ANY DERIVATIVE THEREOF, EVEN IF
ADVISED OF THE POSSIBILITY THEREOF.
7. This License Agreement will automatically terminate upon a material breach
of its terms and conditions.
8. Nothing in this License Agreement shall be deemed to create any relationship
of agency, partnership, or joint venture between Riverbank and Licensee. This
License Agreement does not grant permission to use Riverbank trademarks or
trade name in a trademark sense to endorse or promote products or services of
Licensee, or any third party.
9. By copying, installing or otherwise using SIP, Licensee agrees to be bound
by the terms and conditions of this License Agreement.

@ -0,0 +1,344 @@
-------------------------------------------------------------------------
GNU GENERAL PUBLIC LICENSE
Version 2, June 1991
Copyright (C) 1989, 1991 Free Software Foundation, Inc.
51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
Preamble
The licenses for most software are designed to take away your
freedom to share and change it. By contrast, the GNU General Public
License is intended to guarantee your freedom to share and change free
software--to make sure the software is free for all its users. This
General Public License applies to most of the Free Software
Foundation's software and to any other program whose authors commit to
using it. (Some other Free Software Foundation software is covered by
the GNU Library General Public License instead.) You can apply it to
your programs, too.
When we speak of free software, we are referring to freedom, not
price. Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
this service if you wish), that you receive source code or can get it
if you want it, that you can change the software or use pieces of it
in new free programs; and that you know you can do these things.
To protect your rights, we need to make restrictions that forbid
anyone to deny you these rights or to ask you to surrender the rights.
These restrictions translate to certain responsibilities for you if you
distribute copies of the software, or if you modify it.
For example, if you distribute copies of such a program, whether
gratis or for a fee, you must give the recipients all the rights that
you have. You must make sure that they, too, receive or can get the
source code. And you must show them these terms so they know their
rights.
We protect your rights with two steps: (1) copyright the software, and
(2) offer you this license which gives you legal permission to copy,
distribute and/or modify the software.
Also, for each author's protection and ours, we want to make certain
that everyone understands that there is no warranty for this free
software. If the software is modified by someone else and passed on, we
want its recipients to know that what they have is not the original, so
that any problems introduced by others will not reflect on the original
authors' reputations.
Finally, any free program is threatened constantly by software
patents. We wish to avoid the danger that redistributors of a free
program will individually obtain patent licenses, in effect making the
program proprietary. To prevent this, we have made it clear that any
patent must be licensed for everyone's free use or not licensed at all.
The precise terms and conditions for copying, distribution and
modification follow.
GNU GENERAL PUBLIC LICENSE
TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
0. This License applies to any program or other work which contains
a notice placed by the copyright holder saying it may be distributed
under the terms of this General Public License. The "Program", below,
refers to any such program or work, and a "work based on the Program"
means either the Program or any derivative work under copyright law:
that is to say, a work containing the Program or a portion of it,
either verbatim or with modifications and/or translated into another
language. (Hereinafter, translation is included without limitation in
the term "modification".) Each licensee is addressed as "you".
Activities other than copying, distribution and modification are not
covered by this License; they are outside its scope. The act of
running the Program is not restricted, and the output from the Program
is covered only if its contents constitute a work based on the
Program (independent of having been made by running the Program).
Whether that is true depends on what the Program does.
1. You may copy and distribute verbatim copies of the Program's
source code as you receive it, in any medium, provided that you
conspicuously and appropriately publish on each copy an appropriate
copyright notice and disclaimer of warranty; keep intact all the
notices that refer to this License and to the absence of any warranty;
and give any other recipients of the Program a copy of this License
along with the Program.
You may charge a fee for the physical act of transferring a copy, and
you may at your option offer warranty protection in exchange for a fee.
2. You may modify your copy or copies of the Program or any portion
of it, thus forming a work based on the Program, and copy and
distribute such modifications or work under the terms of Section 1
above, provided that you also meet all of these conditions:
a) You must cause the modified files to carry prominent notices
stating that you changed the files and the date of any change.
b) You must cause any work that you distribute or publish, that in
whole or in part contains or is derived from the Program or any
part thereof, to be licensed as a whole at no charge to all third
parties under the terms of this License.
c) If the modified program normally reads commands interactively
when run, you must cause it, when started running for such
interactive use in the most ordinary way, to print or display an
announcement including an appropriate copyright notice and a
notice that there is no warranty (or else, saying that you provide
a warranty) and that users may redistribute the program under
these conditions, and telling the user how to view a copy of this
License. (Exception: if the Program itself is interactive but
does not normally print such an announcement, your work based on
the Program is not required to print an announcement.)
These requirements apply to the modified work as a whole. If
identifiable sections of that work are not derived from the Program,
and can be reasonably considered independent and separate works in
themselves, then this License, and its terms, do not apply to those
sections when you distribute them as separate works. But when you
distribute the same sections as part of a whole which is a work based
on the Program, the distribution of the whole must be on the terms of
this License, whose permissions for other licensees extend to the
entire whole, and thus to each and every part regardless of who wrote it.
Thus, it is not the intent of this section to claim rights or contest
your rights to work written entirely by you; rather, the intent is to
exercise the right to control the distribution of derivative or
collective works based on the Program.
In addition, mere aggregation of another work not based on the Program
with the Program (or with a work based on the Program) on a volume of
a storage or distribution medium does not bring the other work under
the scope of this License.
3. You may copy and distribute the Program (or a work based on it,
under Section 2) in object code or executable form under the terms of
Sections 1 and 2 above provided that you also do one of the following:
a) Accompany it with the complete corresponding machine-readable
source code, which must be distributed under the terms of Sections
1 and 2 above on a medium customarily used for software interchange; or,
b) Accompany it with a written offer, valid for at least three
years, to give any third party, for a charge no more than your
cost of physically performing source distribution, a complete
machine-readable copy of the corresponding source code, to be
distributed under the terms of Sections 1 and 2 above on a medium
customarily used for software interchange; or,
c) Accompany it with the information you received as to the offer
to distribute corresponding source code. (This alternative is
allowed only for noncommercial distribution and only if you
received the program in object code or executable form with such
an offer, in accord with Subsection b above.)
The source code for a work means the preferred form of the work for
making modifications to it. For an executable work, complete source
code means all the source code for all modules it contains, plus any
associated interface definition files, plus the scripts used to
control compilation and installation of the executable. However, as a
special exception, the source code distributed need not include
anything that is normally distributed (in either source or binary
form) with the major components (compiler, kernel, and so on) of the
operating system on which the executable runs, unless that component
itself accompanies the executable.
If distribution of executable or object code is made by offering
access to copy from a designated place, then offering equivalent
access to copy the source code from the same place counts as
distribution of the source code, even though third parties are not
compelled to copy the source along with the object code.
4. You may not copy, modify, sublicense, or distribute the Program
except as expressly provided under this License. Any attempt
otherwise to copy, modify, sublicense or distribute the Program is
void, and will automatically terminate your rights under this License.
However, parties who have received copies, or rights, from you under
this License will not have their licenses terminated so long as such
parties remain in full compliance.
5. You are not required to accept this License, since you have not
signed it. However, nothing else grants you permission to modify or
distribute the Program or its derivative works. These actions are
prohibited by law if you do not accept this License. Therefore, by
modifying or distributing the Program (or any work based on the
Program), you indicate your acceptance of this License to do so, and
all its terms and conditions for copying, distributing or modifying
the Program or works based on it.
6. Each time you redistribute the Program (or any work based on the
Program), the recipient automatically receives a license from the
original licensor to copy, distribute or modify the Program subject to
these terms and conditions. You may not impose any further
restrictions on the recipients' exercise of the rights granted herein.
You are not responsible for enforcing compliance by third parties to
this License.
7. If, as a consequence of a court judgment or allegation of patent
infringement or for any other reason (not limited to patent issues),
conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License. If you cannot
distribute so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you
may not distribute the Program at all. For example, if a patent
license would not permit royalty-free redistribution of the Program by
all those who receive copies directly or indirectly through you, then
the only way you could satisfy both it and this License would be to
refrain entirely from distribution of the Program.
If any portion of this section is held invalid or unenforceable under
any particular circumstance, the balance of the section is intended to
apply and the section as a whole is intended to apply in other
circumstances.
It is not the purpose of this section to induce you to infringe any
patents or other property right claims or to contest validity of any
such claims; this section has the sole purpose of protecting the
integrity of the free software distribution system, which is
implemented by public license practices. Many people have made
generous contributions to the wide range of software distributed
through that system in reliance on consistent application of that
system; it is up to the author/donor to decide if he or she is willing
to distribute software through any other system and a licensee cannot
impose that choice.
This section is intended to make thoroughly clear what is believed to
be a consequence of the rest of this License.
8. If the distribution and/or use of the Program is restricted in
certain countries either by patents or by copyrighted interfaces, the
original copyright holder who places the Program under this License
may add an explicit geographical distribution limitation excluding
those countries, so that distribution is permitted only in or among
countries not thus excluded. In such case, this License incorporates
the limitation as if written in the body of this License.
9. The Free Software Foundation may publish revised and/or new versions
of the General Public License from time to time. Such new versions will
be similar in spirit to the present version, but may differ in detail to
address new problems or concerns.
Each version is given a distinguishing version number. If the Program
specifies a version number of this License which applies to it and "any
later version", you have the option of following the terms and conditions
either of that version or of any later version published by the Free
Software Foundation. If the Program does not specify a version number of
this License, you may choose any version ever published by the Free Software
Foundation.
10. If you wish to incorporate parts of the Program into other free
programs whose distribution conditions are different, write to the author
to ask for permission. For software which is copyrighted by the Free
Software Foundation, write to the Free Software Foundation; we sometimes
make exceptions for this. Our decision will be guided by the two goals
of preserving the free status of all derivatives of our free software and
of promoting the sharing and reuse of software generally.
NO WARRANTY
11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
REPAIR OR CORRECTION.
12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.
END OF TERMS AND CONDITIONS
How to Apply These Terms to Your New Programs
If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these terms.
To do so, attach the following notices to the program. It is safest
to attach them to the start of each source file to most effectively
convey the exclusion of warranty; and each file should have at least
the "copyright" line and a pointer to where the full notice is found.
<one line to give the program's name and a brief idea of what it does.>
Copyright (C) <year> <name of author>
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
Also add information on how to contact you by electronic and paper mail.
If the program is interactive, make it output a short notice like this
when it starts in an interactive mode:
Gnomovision version 69, Copyright (C) year name of author
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type `show c' for details.
The hypothetical commands `show w' and `show c' should show the appropriate
parts of the General Public License. Of course, the commands you use may
be called something other than `show w' and `show c'; they could even be
mouse-clicks or menu items--whatever suits your program.
You should also get your employer (if you work as a programmer) or your
school, if any, to sign a "copyright disclaimer" for the program, if
necessary. Here is a sample; alter the names:
Yoyodyne, Inc., hereby disclaims all copyright interest in the program
`Gnomovision' (which makes passes at compilers) written by James Hacker.
<signature of Ty Coon>, 1 April 1989
Ty Coon, President of Vice
This General Public License does not permit incorporating your program into
proprietary programs. If your program is a subroutine library, you may
consider it more useful to permit linking proprietary applications with the
library. If this is what you want to do, use the GNU Library General
Public License instead of this License.
-------------------------------------------------------------------------

@ -0,0 +1,678 @@
-------------------------------------------------------------------------
GNU GENERAL PUBLIC LICENSE
Version 3, 29 June 2007
Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
Preamble
The GNU General Public License is a free, copyleft license for
software and other kinds of works.
The licenses for most software and other practical works are designed
to take away your freedom to share and change the works. By contrast,
the GNU General Public License is intended to guarantee your freedom to
share and change all versions of a program--to make sure it remains free
software for all its users. We, the Free Software Foundation, use the
GNU General Public License for most of our software; it applies also to
any other work released this way by its authors. You can apply it to
your programs, too.
When we speak of free software, we are referring to freedom, not
price. Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
them if you wish), that you receive source code or can get it if you
want it, that you can change the software or use pieces of it in new
free programs, and that you know you can do these things.
To protect your rights, we need to prevent others from denying you
these rights or asking you to surrender the rights. Therefore, you have
certain responsibilities if you distribute copies of the software, or if
you modify it: responsibilities to respect the freedom of others.
For example, if you distribute copies of such a program, whether
gratis or for a fee, you must pass on to the recipients the same
freedoms that you received. You must make sure that they, too, receive
or can get the source code. And you must show them these terms so they
know their rights.
Developers that use the GNU GPL protect your rights with two steps:
(1) assert copyright on the software, and (2) offer you this License
giving you legal permission to copy, distribute and/or modify it.
For the developers' and authors' protection, the GPL clearly explains
that there is no warranty for this free software. For both users' and
authors' sake, the GPL requires that modified versions be marked as
changed, so that their problems will not be attributed erroneously to
authors of previous versions.
Some devices are designed to deny users access to install or run
modified versions of the software inside them, although the manufacturer
can do so. This is fundamentally incompatible with the aim of
protecting users' freedom to change the software. The systematic
pattern of such abuse occurs in the area of products for individuals to
use, which is precisely where it is most unacceptable. Therefore, we
have designed this version of the GPL to prohibit the practice for those
products. If such problems arise substantially in other domains, we
stand ready to extend this provision to those domains in future versions
of the GPL, as needed to protect the freedom of users.
Finally, every program is threatened constantly by software patents.
States should not allow patents to restrict development and use of
software on general-purpose computers, but in those that do, we wish to
avoid the special danger that patents applied to a free program could
make it effectively proprietary. To prevent this, the GPL assures that
patents cannot be used to render the program non-free.
The precise terms and conditions for copying, distribution and
modification follow.
TERMS AND CONDITIONS
0. Definitions.
"This License" refers to version 3 of the GNU General Public License.
"Copyright" also means copyright-like laws that apply to other kinds of
works, such as semiconductor masks.
"The Program" refers to any copyrightable work licensed under this
License. Each licensee is addressed as "you". "Licensees" and
"recipients" may be individuals or organizations.
To "modify" a work means to copy from or adapt all or part of the work
in a fashion requiring copyright permission, other than the making of an
exact copy. The resulting work is called a "modified version" of the
earlier work or a work "based on" the earlier work.
A "covered work" means either the unmodified Program or a work based
on the Program.
To "propagate" a work means to do anything with it that, without
permission, would make you directly or secondarily liable for
infringement under applicable copyright law, except executing it on a
computer or modifying a private copy. Propagation includes copying,
distribution (with or without modification), making available to the
public, and in some countries other activities as well.
To "convey" a work means any kind of propagation that enables other
parties to make or receive copies. Mere interaction with a user through
a computer network, with no transfer of a copy, is not conveying.
An interactive user interface displays "Appropriate Legal Notices"
to the extent that it includes a convenient and prominently visible
feature that (1) displays an appropriate copyright notice, and (2)
tells the user that there is no warranty for the work (except to the
extent that warranties are provided), that licensees may convey the
work under this License, and how to view a copy of this License. If
the interface presents a list of user commands or options, such as a
menu, a prominent item in the list meets this criterion.
1. Source Code.
The "source code" for a work means the preferred form of the work
for making modifications to it. "Object code" means any non-source
form of a work.
A "Standard Interface" means an interface that either is an official
standard defined by a recognized standards body, or, in the case of
interfaces specified for a particular programming language, one that
is widely used among developers working in that language.
The "System Libraries" of an executable work include anything, other
than the work as a whole, that (a) is included in the normal form of
packaging a Major Component, but which is not part of that Major
Component, and (b) serves only to enable use of the work with that
Major Component, or to implement a Standard Interface for which an
implementation is available to the public in source code form. A
"Major Component", in this context, means a major essential component
(kernel, window system, and so on) of the specific operating system
(if any) on which the executable work runs, or a compiler used to
produce the work, or an object code interpreter used to run it.
The "Corresponding Source" for a work in object code form means all
the source code needed to generate, install, and (for an executable
work) run the object code and to modify the work, including scripts to
control those activities. However, it does not include the work's
System Libraries, or general-purpose tools or generally available free
programs which are used unmodified in performing those activities but
which are not part of the work. For example, Corresponding Source
includes interface definition files associated with source files for
the work, and the source code for shared libraries and dynamically
linked subprograms that the work is specifically designed to require,
such as by intimate data communication or control flow between those
subprograms and other parts of the work.
The Corresponding Source need not include anything that users
can regenerate automatically from other parts of the Corresponding
Source.
The Corresponding Source for a work in source code form is that
same work.
2. Basic Permissions.
All rights granted under this License are granted for the term of
copyright on the Program, and are irrevocable provided the stated
conditions are met. This License explicitly affirms your unlimited
permission to run the unmodified Program. The output from running a
covered work is covered by this License only if the output, given its
content, constitutes a covered work. This License acknowledges your
rights of fair use or other equivalent, as provided by copyright law.
You may make, run and propagate covered works that you do not
convey, without conditions so long as your license otherwise remains
in force. You may convey covered works to others for the sole purpose
of having them make modifications exclusively for you, or provide you
with facilities for running those works, provided that you comply with
the terms of this License in conveying all material for which you do
not control copyright. Those thus making or running the covered works
for you must do so exclusively on your behalf, under your direction
and control, on terms that prohibit them from making any copies of
your copyrighted material outside their relationship with you.
Conveying under any other circumstances is permitted solely under
the conditions stated below. Sublicensing is not allowed; section 10
makes it unnecessary.
3. Protecting Users' Legal Rights From Anti-Circumvention Law.
No covered work shall be deemed part of an effective technological
measure under any applicable law fulfilling obligations under article
11 of the WIPO copyright treaty adopted on 20 December 1996, or
similar laws prohibiting or restricting circumvention of such
measures.
When you convey a covered work, you waive any legal power to forbid
circumvention of technological measures to the extent such circumvention
is effected by exercising rights under this License with respect to
the covered work, and you disclaim any intention to limit operation or
modification of the work as a means of enforcing, against the work's
users, your or third parties' legal rights to forbid circumvention of
technological measures.
4. Conveying Verbatim Copies.
You may convey verbatim copies of the Program's source code as you
receive it, in any medium, provided that you conspicuously and
appropriately publish on each copy an appropriate copyright notice;
keep intact all notices stating that this License and any
non-permissive terms added in accord with section 7 apply to the code;
keep intact all notices of the absence of any warranty; and give all
recipients a copy of this License along with the Program.
You may charge any price or no price for each copy that you convey,
and you may offer support or warranty protection for a fee.
5. Conveying Modified Source Versions.
You may convey a work based on the Program, or the modifications to
produce it from the Program, in the form of source code under the
terms of section 4, provided that you also meet all of these conditions:
a) The work must carry prominent notices stating that you modified
it, and giving a relevant date.
b) The work must carry prominent notices stating that it is
released under this License and any conditions added under section
7. This requirement modifies the requirement in section 4 to
"keep intact all notices".
c) You must license the entire work, as a whole, under this
License to anyone who comes into possession of a copy. This
License will therefore apply, along with any applicable section 7
additional terms, to the whole of the work, and all its parts,
regardless of how they are packaged. This License gives no
permission to license the work in any other way, but it does not
invalidate such permission if you have separately received it.
d) If the work has interactive user interfaces, each must display
Appropriate Legal Notices; however, if the Program has interactive
interfaces that do not display Appropriate Legal Notices, your
work need not make them do so.
A compilation of a covered work with other separate and independent
works, which are not by their nature extensions of the covered work,
and which are not combined with it such as to form a larger program,
in or on a volume of a storage or distribution medium, is called an
"aggregate" if the compilation and its resulting copyright are not
used to limit the access or legal rights of the compilation's users
beyond what the individual works permit. Inclusion of a covered work
in an aggregate does not cause this License to apply to the other
parts of the aggregate.
6. Conveying Non-Source Forms.
You may convey a covered work in object code form under the terms
of sections 4 and 5, provided that you also convey the
machine-readable Corresponding Source under the terms of this License,
in one of these ways:
a) Convey the object code in, or embodied in, a physical product
(including a physical distribution medium), accompanied by the
Corresponding Source fixed on a durable physical medium
customarily used for software interchange.
b) Convey the object code in, or embodied in, a physical product
(including a physical distribution medium), accompanied by a
written offer, valid for at least three years and valid for as
long as you offer spare parts or customer support for that product
model, to give anyone who possesses the object code either (1) a
copy of the Corresponding Source for all the software in the
product that is covered by this License, on a durable physical
medium customarily used for software interchange, for a price no
more than your reasonable cost of physically performing this
conveying of source, or (2) access to copy the
Corresponding Source from a network server at no charge.
c) Convey individual copies of the object code with a copy of the
written offer to provide the Corresponding Source. This
alternative is allowed only occasionally and noncommercially, and
only if you received the object code with such an offer, in accord
with subsection 6b.
d) Convey the object code by offering access from a designated
place (gratis or for a charge), and offer equivalent access to the
Corresponding Source in the same way through the same place at no
further charge. You need not require recipients to copy the
Corresponding Source along with the object code. If the place to
copy the object code is a network server, the Corresponding Source
may be on a different server (operated by you or a third party)
that supports equivalent copying facilities, provided you maintain
clear directions next to the object code saying where to find the
Corresponding Source. Regardless of what server hosts the
Corresponding Source, you remain obligated to ensure that it is
available for as long as needed to satisfy these requirements.
e) Convey the object code using peer-to-peer transmission, provided
you inform other peers where the object code and Corresponding
Source of the work are being offered to the general public at no
charge under subsection 6d.
A separable portion of the object code, whose source code is excluded
from the Corresponding Source as a System Library, need not be
included in conveying the object code work.
A "User Product" is either (1) a "consumer product", which means any
tangible personal property which is normally used for personal, family,
or household purposes, or (2) anything designed or sold for incorporation
into a dwelling. In determining whether a product is a consumer product,
doubtful cases shall be resolved in favor of coverage. For a particular
product received by a particular user, "normally used" refers to a
typical or common use of that class of product, regardless of the status
of the particular user or of the way in which the particular user
actually uses, or expects or is expected to use, the product. A product
is a consumer product regardless of whether the product has substantial
commercial, industrial or non-consumer uses, unless such uses represent
the only significant mode of use of the product.
"Installation Information" for a User Product means any methods,
procedures, authorization keys, or other information required to install
and execute modified versions of a covered work in that User Product from
a modified version of its Corresponding Source. The information must
suffice to ensure that the continued functioning of the modified object
code is in no case prevented or interfered with solely because
modification has been made.
If you convey an object code work under this section in, or with, or
specifically for use in, a User Product, and the conveying occurs as
part of a transaction in which the right of possession and use of the
User Product is transferred to the recipient in perpetuity or for a
fixed term (regardless of how the transaction is characterized), the
Corresponding Source conveyed under this section must be accompanied
by the Installation Information. But this requirement does not apply
if neither you nor any third party retains the ability to install
modified object code on the User Product (for example, the work has
been installed in ROM).
The requirement to provide Installation Information does not include a
requirement to continue to provide support service, warranty, or updates
for a work that has been modified or installed by the recipient, or for
the User Product in which it has been modified or installed. Access to a
network may be denied when the modification itself materially and
adversely affects the operation of the network or violates the rules and
protocols for communication across the network.
Corresponding Source conveyed, and Installation Information provided,
in accord with this section must be in a format that is publicly
documented (and with an implementation available to the public in
source code form), and must require no special password or key for
unpacking, reading or copying.
7. Additional Terms.
"Additional permissions" are terms that supplement the terms of this
License by making exceptions from one or more of its conditions.
Additional permissions that are applicable to the entire Program shall
be treated as though they were included in this License, to the extent
that they are valid under applicable law. If additional permissions
apply only to part of the Program, that part may be used separately
under those permissions, but the entire Program remains governed by
this License without regard to the additional permissions.
When you convey a copy of a covered work, you may at your option
remove any additional permissions from that copy, or from any part of
it. (Additional permissions may be written to require their own
removal in certain cases when you modify the work.) You may place
additional permissions on material, added by you to a covered work,
for which you have or can give appropriate copyright permission.
Notwithstanding any other provision of this License, for material you
add to a covered work, you may (if authorized by the copyright holders of
that material) supplement the terms of this License with terms:
a) Disclaiming warranty or limiting liability differently from the
terms of sections 15 and 16 of this License; or
b) Requiring preservation of specified reasonable legal notices or
author attributions in that material or in the Appropriate Legal
Notices displayed by works containing it; or
c) Prohibiting misrepresentation of the origin of that material, or
requiring that modified versions of such material be marked in
reasonable ways as different from the original version; or
d) Limiting the use for publicity purposes of names of licensors or
authors of the material; or
e) Declining to grant rights under trademark law for use of some
trade names, trademarks, or service marks; or
f) Requiring indemnification of licensors and authors of that
material by anyone who conveys the material (or modified versions of
it) with contractual assumptions of liability to the recipient, for
any liability that these contractual assumptions directly impose on
those licensors and authors.
All other non-permissive additional terms are considered "further
restrictions" within the meaning of section 10. If the Program as you
received it, or any part of it, contains a notice stating that it is
governed by this License along with a term that is a further
restriction, you may remove that term. If a license document contains
a further restriction but permits relicensing or conveying under this
License, you may add to a covered work material governed by the terms
of that license document, provided that the further restriction does
not survive such relicensing or conveying.
If you add terms to a covered work in accord with this section, you
must place, in the relevant source files, a statement of the
additional terms that apply to those files, or a notice indicating
where to find the applicable terms.
Additional terms, permissive or non-permissive, may be stated in the
form of a separately written license, or stated as exceptions;
the above requirements apply either way.
8. Termination.
You may not propagate or modify a covered work except as expressly
provided under this License. Any attempt otherwise to propagate or
modify it is void, and will automatically terminate your rights under
this License (including any patent licenses granted under the third
paragraph of section 11).
However, if you cease all violation of this License, then your
license from a particular copyright holder is reinstated (a)
provisionally, unless and until the copyright holder explicitly and
finally terminates your license, and (b) permanently, if the copyright
holder fails to notify you of the violation by some reasonable means
prior to 60 days after the cessation.
Moreover, your license from a particular copyright holder is
reinstated permanently if the copyright holder notifies you of the
violation by some reasonable means, this is the first time you have
received notice of violation of this License (for any work) from that
copyright holder, and you cure the violation prior to 30 days after
your receipt of the notice.
Termination of your rights under this section does not terminate the
licenses of parties who have received copies or rights from you under
this License. If your rights have been terminated and not permanently
reinstated, you do not qualify to receive new licenses for the same
material under section 10.
9. Acceptance Not Required for Having Copies.
You are not required to accept this License in order to receive or
run a copy of the Program. Ancillary propagation of a covered work
occurring solely as a consequence of using peer-to-peer transmission
to receive a copy likewise does not require acceptance. However,
nothing other than this License grants you permission to propagate or
modify any covered work. These actions infringe copyright if you do
not accept this License. Therefore, by modifying or propagating a
covered work, you indicate your acceptance of this License to do so.
10. Automatic Licensing of Downstream Recipients.
Each time you convey a covered work, the recipient automatically
receives a license from the original licensors, to run, modify and
propagate that work, subject to this License. You are not responsible
for enforcing compliance by third parties with this License.
An "entity transaction" is a transaction transferring control of an
organization, or substantially all assets of one, or subdividing an
organization, or merging organizations. If propagation of a covered
work results from an entity transaction, each party to that
transaction who receives a copy of the work also receives whatever
licenses to the work the party's predecessor in interest had or could
give under the previous paragraph, plus a right to possession of the
Corresponding Source of the work from the predecessor in interest, if
the predecessor has it or can get it with reasonable efforts.
You may not impose any further restrictions on the exercise of the
rights granted or affirmed under this License. For example, you may
not impose a license fee, royalty, or other charge for exercise of
rights granted under this License, and you may not initiate litigation
(including a cross-claim or counterclaim in a lawsuit) alleging that
any patent claim is infringed by making, using, selling, offering for
sale, or importing the Program or any portion of it.
11. Patents.
A "contributor" is a copyright holder who authorizes use under this
License of the Program or a work on which the Program is based. The
work thus licensed is called the contributor's "contributor version".
A contributor's "essential patent claims" are all patent claims
owned or controlled by the contributor, whether already acquired or
hereafter acquired, that would be infringed by some manner, permitted
by this License, of making, using, or selling its contributor version,
but do not include claims that would be infringed only as a
consequence of further modification of the contributor version. For
purposes of this definition, "control" includes the right to grant
patent sublicenses in a manner consistent with the requirements of
this License.
Each contributor grants you a non-exclusive, worldwide, royalty-free
patent license under the contributor's essential patent claims, to
make, use, sell, offer for sale, import and otherwise run, modify and
propagate the contents of its contributor version.
In the following three paragraphs, a "patent license" is any express
agreement or commitment, however denominated, not to enforce a patent
(such as an express permission to practice a patent or covenant not to
sue for patent infringement). To "grant" such a patent license to a
party means to make such an agreement or commitment not to enforce a
patent against the party.
If you convey a covered work, knowingly relying on a patent license,
and the Corresponding Source of the work is not available for anyone
to copy, free of charge and under the terms of this License, through a
publicly available network server or other readily accessible means,
then you must either (1) cause the Corresponding Source to be so
available, or (2) arrange to deprive yourself of the benefit of the
patent license for this particular work, or (3) arrange, in a manner
consistent with the requirements of this License, to extend the patent
license to downstream recipients. "Knowingly relying" means you have
actual knowledge that, but for the patent license, your conveying the
covered work in a country, or your recipient's use of the covered work
in a country, would infringe one or more identifiable patents in that
country that you have reason to believe are valid.
If, pursuant to or in connection with a single transaction or
arrangement, you convey, or propagate by procuring conveyance of, a
covered work, and grant a patent license to some of the parties
receiving the covered work authorizing them to use, propagate, modify
or convey a specific copy of the covered work, then the patent license
you grant is automatically extended to all recipients of the covered
work and works based on it.
A patent license is "discriminatory" if it does not include within
the scope of its coverage, prohibits the exercise of, or is
conditioned on the non-exercise of one or more of the rights that are
specifically granted under this License. You may not convey a covered
work if you are a party to an arrangement with a third party that is
in the business of distributing software, under which you make payment
to the third party based on the extent of your activity of conveying
the work, and under which the third party grants, to any of the
parties who would receive the covered work from you, a discriminatory
patent license (a) in connection with copies of the covered work
conveyed by you (or copies made from those copies), or (b) primarily
for and in connection with specific products or compilations that
contain the covered work, unless you entered into that arrangement,
or that patent license was granted, prior to 28 March 2007.
Nothing in this License shall be construed as excluding or limiting
any implied license or other defenses to infringement that may
otherwise be available to you under applicable patent law.
12. No Surrender of Others' Freedom.
If conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License. If you cannot convey a
covered work so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you may
not convey it at all. For example, if you agree to terms that obligate you
to collect a royalty for further conveying from those to whom you convey
the Program, the only way you could satisfy both those terms and this
License would be to refrain entirely from conveying the Program.
13. Use with the GNU Affero General Public License.
Notwithstanding any other provision of this License, you have
permission to link or combine any covered work with a work licensed
under version 3 of the GNU Affero General Public License into a single
combined work, and to convey the resulting work. The terms of this
License will continue to apply to the part which is the covered work,
but the special requirements of the GNU Affero General Public License,
section 13, concerning interaction through a network will apply to the
combination as such.
14. Revised Versions of this License.
The Free Software Foundation may publish revised and/or new versions of
the GNU General Public License from time to time. Such new versions will
be similar in spirit to the present version, but may differ in detail to
address new problems or concerns.
Each version is given a distinguishing version number. If the
Program specifies that a certain numbered version of the GNU General
Public License "or any later version" applies to it, you have the
option of following the terms and conditions either of that numbered
version or of any later version published by the Free Software
Foundation. If the Program does not specify a version number of the
GNU General Public License, you may choose any version ever published
by the Free Software Foundation.
If the Program specifies that a proxy can decide which future
versions of the GNU General Public License can be used, that proxy's
public statement of acceptance of a version permanently authorizes you
to choose that version for the Program.
Later license versions may give you additional or different
permissions. However, no additional obligations are imposed on any
author or copyright holder as a result of your choosing to follow a
later version.
15. Disclaimer of Warranty.
THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
16. Limitation of Liability.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
SUCH DAMAGES.
17. Interpretation of Sections 15 and 16.
If the disclaimer of warranty and limitation of liability provided
above cannot be given local legal effect according to their terms,
reviewing courts shall apply local law that most closely approximates
an absolute waiver of all civil liability in connection with the
Program, unless a warranty or assumption of liability accompanies a
copy of the Program in return for a fee.
END OF TERMS AND CONDITIONS
How to Apply These Terms to Your New Programs
If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these terms.
To do so, attach the following notices to the program. It is safest
to attach them to the start of each source file to most effectively
state the exclusion of warranty; and each file should have at least
the "copyright" line and a pointer to where the full notice is found.
<one line to give the program's name and a brief idea of what it does.>
Copyright (C) <year> <name of author>
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
Also add information on how to contact you by electronic and paper mail.
If the program does terminal interaction, make it output a short
notice like this when it starts in an interactive mode:
<program> Copyright (C) <year> <name of author>
This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type `show c' for details.
The hypothetical commands `show w' and `show c' should show the appropriate
parts of the General Public License. Of course, your program's commands
might be different; for a GUI interface, you would use an "about box".
You should also get your employer (if you work as a programmer) or school,
if any, to sign a "copyright disclaimer" for the program, if necessary.
For more information on this, and how to apply and follow the GNU GPL, see
<http://www.gnu.org/licenses/>.
The GNU General Public License does not permit incorporating your program
into proprietary programs. If your program is a subroutine library, you
may consider it more useful to permit linking proprietary applications with
the library. If this is what you want to do, use the GNU Lesser General
Public License instead of this License. But first, please read
<http://www.gnu.org/philosophy/why-not-lgpl.html>.
-------------------------------------------------------------------------

363
NEWS

@ -0,0 +1,363 @@
v4.10.5 16th July 2010
- A bug fix release for Python v3 and Python v2.7.
v4.10.4 15th July 2010
- Use capsules when being built for Python v2.7 to work around an apparent
bug in the support for PyCObject.
v4.10.3 12th July 2010
- Added support for Q_SLOT, Q_SLOTS, Q_SIGNAL and Q_SIGNALS.
- Added the /__len__/ function annotation.
v4.10.2 16th April 2010
- A bug fix release.
v4.10.1 17th March 2010
- Added the /NoCopy/ function and argument annotations.
v4.10 14th January 2010
- Added the sip.voidptr.ascapsule() method.
- Added the -P command line option to build modules with "protected"
redefined to "public" if supported by the platform. This can result in
significantly smaller modules.
- Added the -o command line option to automatically generate docstrings.
- Added the -k command line option and /KeywordArgs/ and /NoKeywordArgs/
function annotations to support keyword arguments.
- Added the /Default/ exception annotation.
- Added the /DocType/ argument, function, mapped type and variable
annotation.
- Added the /DocValue/ argument annotation.
- Added the %Docstring directive to specify explicit docstrings for classes,
functions and methods.
- Added sipError to %MethodCode to allow user errors to be distinguished from
interpreter errors.
- Added sipBadCallableArg() to the C API.
- Added support for configuring and building outside of the source tree.
v4.9.3 23rd November 2009
- A bug fix release.
v4.9.2 20th November 2009
- A bug fix release.
v4.9.1 23rd October 2009
- A bug fix release.
v4.9 26th September 2009
- Added support for __iter__ and __next__. (__next__ is used for Python v2
as well as v3.)
- Added the %API directive.
- Added the /API/ annotation.
- Added sipIsAPIEnabled() to the C API.
- Added sip.getapi() and sip.setapi() to the Python API.
- Added sip.ispyowned() to the Python API.
- Mapped types can now act as a namespace for enums and static methods.
- The /Array/ annotation can now be applied to classes and mapped types.
- The /NoArgParser/ annotation can now be applied to methods as well as
functions.
- Added the --arch flag to configure.py to specify which MacOS/X
architectures are built.
- SIP is now also licensed under the GPL v2 and v3.
v4.8.2 27th July 2009
- Added the /AllowNone/ class annotation.
v4.8.1 16th June 2009
- Added support for defining a private assignment operator to suppress the
possible generation of an assignment helper.
v4.8 5th June 2009
- Added support for Python v3.
- Added the %BIGetBufferCode and %BIReleaseBufferCode to support the buffer
interface of Python v3.
- Added the %DefaultMetatype directive and the /Metatype/ class annotation to
allow the meta-type of a wrapped type to be changed.
- Added the %DefaultSupertype directive and the /Supertype/ class annotation
to allow the super-type of a wrapped type to be changed.
- Added the sip.simplewrapper type to be used as a super-type for wrapped
types that don't take part in parent/child relationships.
- Added the %InitialisationCode directive.
- Added the /KeepReference/ argument annotation.
- Added the /Encoding/ argument, function, typedef and variable annotation.
- super() now works as expected with wrapped types.
- Added support for __floordiv__, __ifloordiv__, __truediv__, __itruediv__
and __index__.
- __bool__ is a synonym for __nonzero__.
- Sphinx is now used for the documentation.
- Many additions and deprecations in the API to eliminate the differences
between classes and mapped types. (See the documentation for the details.)
v4.7.9 17th November 2008
- A bug fix release.
v4.7.8 8th November 2008
- Added the /Deprecated/ class and function annotation (based on a patch from
Lorenzo Berni).
- Templates now support instance variables and enums.
- A Python int object can now be used whenever an enum is expected without
needing to explicitly cast it using the enum's constructor. The
/Constrained/ argument annotation can be used to suppress this behaviour.
- typedef type names are now used in string representations of types (e.g. in
the names of mapped types) to reflect what the programmer sees rather than
what the compiler sees. The /NoTypeName/ typedef annotation can be used to
suppress this behaviour.
v4.7.7 8th August 2008
- C++ structs are now properly handled as a class with a default public
section.
- sip.dump() now includes the object's first child wrapper.
v4.7.6 20th May 2008
- Added the -s flag to configure.py to specify the SDK directory to use when
building universal binaries on MacOS/X.
- Added support for MSVC 2008 to the build system.
- Added support for v10.x of the Intel compiler and removed support for
earlier versions.
- MSVC 2008 is the default platform when using Python v2.6.
v4.7.5 13th May 2008
- The sip.voidptr type has an optional size associated with it and supports
const void *. If a size is associated then it also supports Python's
buffer protocol.
- Added sipConvertToVoidPtr() to the SIP API.
- Added sipConvertFromConstVoidPtr(), sipConvertFromConstVoidPtrAndSize(),
sipConvertFromVoidPtr() and sipConvertFromVoidPtrAndSize() to the SIP API.
- Added the /ResultSize/ argument annotation to specify the size of a block
of memory returned as a void * or const void *.
- Added the /NoArgParser/ function annotation to give %MethodCode complete
responsibility for argument parsing.
- Added the /NoRelease/ mapped type annotation to specify that the
sipReleaseMappedType() function is not supported.
- The /ArraySize/ annotation now supports arrays with more than 2^31
elements.
- %GetCode and %SetCode for class attributes now have access to the
referencing type object.
- Any object that supports the Python buffer protocol can now be passed as a
char or char * argument.
v4.7.4 12th February 2008
- The build system handles the directory structure used by Leopard's Python
installation.
- Added support for /Transfer/ as a constructor annotation.
v4.7.3 6th December 2007
- Added support for automatically generating missing complementary
comparision operators. Note that this introduces a potential compatibility
problem - see the documentation for details.
v4.7.2 5th December 2007
- Added the /SingleShot/ argument annotation.
- Added the /TransferThis/ function annotation.
v4.7.1 28th September 2007
- A bug fix release.
v4.7 30th July 2007
- Added %PickleCode to allow handwritten code to pickle a wrapped C++
instance or C structure.
- Added %CompositeModule to create modules that are composites of ordinary
modules.
- Added %ConsolidatedModule (and the -p command line option) to create
modules that contain all the wrapper code on behalf of ordinary modules.
- Added the dump() function to the sip module.
- Added sipTransferBreak() to the SIP API.
- Added support for /Transfer/ as a function annotation.
v4.6 10th April 2007
- Added support for wchar_t.
- The -g command line option releases the GIL whenever a call is made to the
wrapped library.
- Added the /HoldGIL/ annotation to explicitly retain the GIL when calling a
particular function in the wrapped library.
- Added sipFindClass() and sipFindNamedEnum() to the public API.
- /TransferThis/ may be specified more than once.
- Added support for __truediv__ and __itruediv__.
- The SIP code generator and module may be built as universal binaries under
MacOS/X using the -n command line option to configure.py.
v4.5.2 9th December 2006
- A bug fix release.
v4.5.1 9th December 2006
- Added the SIP_SSIZE_T type to help write PEP 353 compliant handwritten
code.
v4.5 4th November 2006
- Added support for Python v2.5.
- Added sip_config_args to sipconfig.py.
- sip.voidptr now implements __hex__().
- Added sip.delete() to call a C++ instance's destructor, or return a C
structure to the heap.
- Added sip.isdeleted() to check if a C++ instance or C structure has been
destroyed or returned to the heap.
- Added sip.setdeleted() to mark that a C++ instance or C structure has been
destroyed or returned to the heap.
- Added support for pure virtual destructors.
- Added the __dtor__() method to allow Python code to be called from a C++
destructor.
- Added the /NoDefaultCtors/ class annotation.
- The generated API files are now more complete and use Python types rather
than C/C++ types.
- Added support for embedding manifests for MSVC 2005.
v4.4.5 10th June 2006
- A bug fix release.
v4.4.4 8th June 2006
- Added %ExportedHeaderCode and %UnitCode.
- Added sipExportSymbol() and sipImportSymbol() to the public API.
v4.4.3 27th April 2006
- A bug fix release.
v4.4.2 23rd April 2006
- A bug fix release.
v4.4.1 3rd April 2006
- A bug fix release.
v4.4 24th March 2006
- The major number of the internal API has changed so it will be necessary
to regenerate all modules.
- This release introduces small incompatibilities that may affect handwritten
code. See the documentation for the details.
- Module names specified with %Module and %CModule can now include periods to
denote a Python package structure.
- Namespaces can be split across multiple Python modules.
- Class templates are now supported and instantiated using "typedef".
- Mapped type templates are now supported and instantiated automatically.
- Global operators are now supported.
- Operator casts in classes are now supported.
- C/C++ signed char type is now treated as a separate type to char.
- C/C++ long and unsigned long types are now wrapped as Python long objects
rather than Python integer objects.
- C/C++ long long and unsigned long long types are now supported.
- unsigned short and unsigned int are now implemented as long objects instead
of integer objects.
- Classes can now be declared using the /External/ annotation and be defined
in another, unspecified, module.
- /TransferThis/ can now be used in non-factory methods to change the
ownership to a different C++ instance or to change it to Python.
- /Constrained/ can now be used with booleans.
- Added support for Python's buffer interface, %BIGetCharBufferCode,
%BIGetReadBufferCode, %BIGetSegCountCode and %BIGetWriteBufferCode.
- The "user" member has been added to the sipWrapper structure and can be
used for any purpose by handwritten code.
- Function argument names are now parsed, but otherwise ignored.
- The "explicit" keyword is now parsed, but otherwise ignored.
- Added the /DelayDtor/ class annotation which given more control over the
order in which instances are deleted when an application terminates.
- Added support for the SIP_PYTYPE pseudo-type that represents a Python
type object.
- Added support for ellipsis (ie. "...") in function arguments. Any
remaining arguments will be gathered as a Python tuple.
- Add support for the /NoDerived/ annotation for Python class constructors
that have no C/C++ equivalent.
- The sipSelfWasArg boolean is now available to the %MethodCode of
non-abstract, virtual methods to indicate whether the class implementation
of the method rather than the virtual implementation should be called.
%MethodCode for non-abstract, virtual, protected methods must now call the
sipProtectVirt wrapper (rather than sipProtect).
- sipCanConvertToInstance(), sipConvertToInstance(),
sipForceConvertToInstance(), sipReleaseInstance(),
sipConvertFromInstance(), sipConvertFromNewInstance(),
sipCanConvertToMappedType(), sipConvertToMappedType(),
sipForceConvertToMappedType(), sipReleaseMappedType(),
sipConvertFromMappedType() and sipFindMappedType() have been added to the
SIP API.
- sipLong_AsUnsignedLong() has been added, primarily as a workaround for a
bug in Python v2.3.x and earlier.
- Added the 't', 'u', 'C' and 'D' format characters to sipParseResult().
- Added the 't', 'u', 'B', 'C' and 'D' format characters to sipBuildResult().
- Responsibility for interpreting and implementing the /Transfer/ and
/TransferBack/ annotations has been pushed down to %ConvertToTypeCode and
%ConvertFromTypeCode. The generated type convertors sipForceConvertTo_*()
and sipConvertFrom_*() have been deprecated.
- Added the %SIPNoEmitters directive for PyQt4.
- Added support for the __hash__ Python special method.
- The __getitem__ Python special method no longer requires %MethodCode.
- All of the calls to Qt have been moved out of the sip module and into PyQt.
The generated sipconfig.py file no longer contains any Qt specific
information. These changes mean that SIP can support PyQt v3 and v4 at the
same time.
- Static methods can now be defined as Qt slots.
- Removed SIP_BUILD from sip.h.
- The -c, -l, -q and -x flags to configure.py have been removed.
- Added the PythonModuleMakefile class to the build system for installing
pure Python modules.
- Added the create_wrapper() function to the build system for creating
platform dependent executable wrappers for Python scripts.
- Added Configuration.platform to the build system.
v4.3.2 14th November 2005
- The sipdistutils.py script has contributed by Giovanni Bajo that enables
SIP extension modules to be built with distutils.
v4.3.1 10th September 2005
- A bug fix release.
v4.3 30th August 2005
- The major number of the internal API has changed so it will be necessary
to regenerate all modules.
- C structures can now have constructors and a destructor defined so that
they can be made to behave more Pythonically.
- %TypeHeaderCode can now be used in namespaces.
- Added sip.SIP_VERSION_STR.
- Added support for Python's cyclic garbage collector, %GCTraverseCode and
%GCClearCode.
- Deprecated sipTransfer() and sip.transfer().
- Added sipTransferTo, sipTransferBack(), sip.transferto() and
sip.transferback().
- Added support for sipCppRet in %ConvertSubClassCode.
- Added support for %GetCode and %SetCode for instance variables and
structure members.
- Added support for %Exception and %RaiseCode.
- Added support for __pos__ and __abs__.
- sip.voidptr instances can now be created from Python.
- The ascobject() method has been added to sip.voidptr.
- Added the -c flag to configure.py to explicitly specify the location of
the qconfig.h file.
v4.2.1 6th March 2005
- Restored the pre-4.2 behaviour of Python exceptions raised in virtual
re-implementations.
- %Timeline can now be used more than once in a module.
v4.2 19th February 2005
- The /PyName/ annotation can now be applied to classes, namespaces,
enums, enum members and variables.
- Added the %PreInitialisationCode directive and is subject to version
control. %PostInitialisationCode is now subject to version control.
- Named enums now have distinct types and so can be differentiated from
integers in function signatures.
- The handling of Qt signals has changed so that "foreign" signals (ie.
those raised by ActiveX controls) can be handled.
- The voidptr, wrapper and wrappertype types are now exposed in the sip
module.
- Virtual and abstract operators are now supported.
- The __call__ slot no longer requires %MethodCode.
- Any Python exceptions raised in virtual re-implementations are now
detected when they occur.
- sip.cast() can now cast downwards as well as upwards.
- Added sip.SIP_VERSION.
- The -k flag to configure.py can now be used to build modules as builtins
to custom interpreters.
- The build system now strips modules and only exports the module
initialisation function by default (when supported by the platform).
v4.1.1 24th September 2004
- A bug fix release.
v4.1 20th September 2004
- Added the cast() method to the sip module.
- Added limited support for protected classes.
- Added the /Abstract/ class annotation.
- Added support for typedefs that define pointers to functions.
- The SIP_PYCALLABLE type now supports the /AllowNone/ annotation.
- Added support for MSVC.NET to the build system.
v4.0.1 6th July 2004
- A bug fix release.
v4.0 23rd June 2004
- The release of SIP v4.

@ -0,0 +1,33 @@
SIP - C/C++ Bindings Generator for Python v2 and v3
===================================================
The SIP documentation (including installation instructions) can be found in the
``doc`` directory.
Building from the Mercurial Repository
--------------------------------------
If you are using a copy of SIP cloned from the Mercurial repository, or are
using a Mercurial archive, then you have to prepare it first before you follow
the normal installation instructions.
The preparation is done using the ``build.py`` script which can be found in the
same directory as this ``README`` file. If it isn't there then you probably
have a packaged release and should just follow the normal installation
instructions.
The ``build.py`` script requires that ``flex`` and ``bison``, and the Mercurial
Python bindings are installed. If you want to create the HTML documentation
then Sphinx must also be installed.
To prepare run the following::
python build.py prepare
Note that ``build.py`` is a Python v2 script.
Now you can follow the normal installation instructions.
The ``build.py`` script has other useful commands, use the ``--help`` option to
see the details.

@ -0,0 +1,471 @@
# This script handles the SIP configuration and generates the Makefiles.
#
# Copyright (c) 2010 Riverbank Computing Limited <info@riverbankcomputing.com>
#
# This file is part of SIP.
#
# This copy of SIP is licensed for use under the terms of the SIP License
# Agreement. See the file LICENSE for more details.
#
# This copy of SIP may also used under the terms of the GNU General Public
# License v2 or v3 as published by the Free Software Foundation which can be
# found in the files LICENSE-GPL2 and LICENSE-GPL3 included in this package.
#
# SIP is supplied WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
import sys
import os
import glob
import optparse
from distutils import sysconfig
import siputils
# Initialise the globals.
sip_version = 0x040a05
sip_version_str = "4.10.5"
py_version = sys.hexversion >> 8
plat_py_site_dir = None
plat_py_inc_dir = None
plat_py_conf_inc_dir = None
plat_py_lib_dir = None
plat_sip_dir = None
plat_bin_dir = None
platform_specs = []
src_dir = os.path.dirname(os.path.abspath(__file__))
# Constants.
DEFAULT_MACOSX_ARCH = 'i386 ppc'
MACOSX_SDK_DIR = '/Developer/SDKs'
# Command line options.
default_platform = None
default_sipbindir = None
default_sipmoddir = None
default_sipincdir = None
default_sipsipdir = None
# The names of build macros extracted from the platform specific configuration
# files.
build_macro_names = [
"DEFINES", "CONFIG",
"CC",
"CFLAGS",
"CFLAGS_RELEASE", "CFLAGS_DEBUG",
"CFLAGS_CONSOLE", "CFLAGS_SHLIB", "CFLAGS_THREAD",
"CFLAGS_MT", "CFLAGS_MT_DBG", "CFLAGS_MT_DLL", "CFLAGS_MT_DLLDBG",
"CFLAGS_EXCEPTIONS_ON", "CFLAGS_EXCEPTIONS_OFF",
"CFLAGS_RTTI_ON", "CFLAGS_RTTI_OFF",
"CFLAGS_STL_ON", "CFLAGS_STL_OFF",
"CFLAGS_WARN_ON", "CFLAGS_WARN_OFF",
"CHK_DIR_EXISTS", "COPY",
"CXX",
"CXXFLAGS",
"CXXFLAGS_RELEASE", "CXXFLAGS_DEBUG",
"CXXFLAGS_CONSOLE", "CXXFLAGS_SHLIB", "CXXFLAGS_THREAD",
"CXXFLAGS_MT", "CXXFLAGS_MT_DBG", "CXXFLAGS_MT_DLL", "CXXFLAGS_MT_DLLDBG",
"CXXFLAGS_EXCEPTIONS_ON", "CXXFLAGS_EXCEPTIONS_OFF",
"CXXFLAGS_RTTI_ON", "CXXFLAGS_RTTI_OFF",
"CXXFLAGS_STL_ON", "CXXFLAGS_STL_OFF",
"CXXFLAGS_WARN_ON", "CXXFLAGS_WARN_OFF",
"DEL_FILE",
"EXTENSION_SHLIB", "EXTENSION_PLUGIN",
"INCDIR", "INCDIR_X11", "INCDIR_OPENGL",
"LIBS_CORE", "LIBS_GUI", "LIBS_NETWORK", "LIBS_OPENGL", "LIBS_WEBKIT",
"LINK", "LINK_SHLIB", "AIX_SHLIB", "LINK_SHLIB_CMD",
"LFLAGS", "LFLAGS_CONSOLE", "LFLAGS_CONSOLE_DLL", "LFLAGS_DEBUG",
"LFLAGS_DLL",
"LFLAGS_PLUGIN", "LFLAGS_RELEASE", "LFLAGS_SHLIB", "LFLAGS_SONAME",
"LFLAGS_THREAD", "LFLAGS_WINDOWS", "LFLAGS_WINDOWS_DLL", "LFLAGS_OPENGL",
"LIBDIR", "LIBDIR_X11", "LIBDIR_OPENGL",
"LIBS", "LIBS_CONSOLE", "LIBS_RT",
"LIBS_RTMT", "LIBS_THREAD", "LIBS_WINDOWS", "LIBS_X11",
"MAKEFILE_GENERATOR",
"MKDIR",
"RPATH",
"AR", "RANLIB", "LIB", "STRIP"
]
def show_platforms():
"""Display the different platform/compilers.
"""
sys.stdout.write("""
The following platform/compiler configurations are supported:
""")
platform_specs.sort()
sys.stdout.write(siputils.format(", ".join(platform_specs), leftmargin=2))
sys.stdout.write("\n\n")
def show_macros():
"""Display the different build macros.
"""
sys.stdout.write("""
The following options may be used to adjust the compiler configuration:
""")
build_macro_names.sort()
sys.stdout.write(siputils.format(", ".join(build_macro_names), leftmargin=2))
sys.stdout.write("\n\n")
def set_defaults():
"""Set up the defaults for values that can be set on the command line.
"""
global default_platform, default_sipbindir, default_sipmoddir
global default_sipincdir, default_sipsipdir
# Set the platform specific default specification.
platdefaults = {
"aix": "aix-xlc",
"bsd": "bsdi-g++",
"cygwin": "cygwin-g++",
"darwin": "macx-g++",
"dgux": "dgux-g++",
"freebsd": "freebsd-g++",
"gnu": "hurd-g++",
"hp-ux": "hpux-acc",
"irix": "irix-cc",
"linux": "linux-g++",
"lynxos": "lynxos-g++",
"netbsd": "netbsd-g++",
"openbsd": "openbsd-g++",
"openunix": "unixware-cc",
"osf1": "tru64-cxx",
"qnx": "qnx-g++",
"reliantunix": "reliant-cds",
"sco_sv": "sco-cc",
"sinix": "reliant-cds",
"sunos5": "solaris-cc",
"ultrix": "ultrix-g++",
"unix_sv": "unixware-g++",
"unixware": "unixware-cc"
}
default_platform = "none"
if sys.platform == "win32":
if py_version >= 0x020600:
default_platform = "win32-msvc2008"
elif py_version >= 0x020400:
default_platform = "win32-msvc.net"
else:
default_platform = "win32-msvc"
else:
for pd in list(platdefaults.keys()):
if sys.platform[:len(pd)] == pd:
default_platform = platdefaults[pd]
break
default_sipbindir = plat_bin_dir
default_sipmoddir = plat_py_site_dir
default_sipincdir = plat_py_inc_dir
default_sipsipdir = plat_sip_dir
def inform_user():
"""Tell the user the option values that are going to be used.
"""
siputils.inform("The SIP code generator will be installed in %s." % opts.sipbindir)
siputils.inform("The SIP module will be installed in %s." % opts.sipmoddir)
siputils.inform("The SIP header file will be installed in %s." % opts.sipincdir)
siputils.inform("The default directory to install .sip files in is %s." % opts.sipsipdir)
siputils.inform("The platform/compiler configuration is %s." % opts.platform)
if opts.arch:
siputils.inform("MacOS/X binaries will be created for %s." % (", ".join(opts.arch.split())))
if opts.universal:
siputils.inform("MacOS/X universal binaries will be created using %s." % opts.universal)
def set_platform_directories():
"""Initialise the global variables relating to platform specific
directories.
"""
global plat_py_site_dir, plat_py_inc_dir, plat_py_conf_inc_dir
global plat_bin_dir, plat_py_lib_dir, plat_sip_dir
# We trust distutils for some stuff.
plat_py_site_dir = sysconfig.get_python_lib(plat_specific=1)
plat_py_inc_dir = sysconfig.get_python_inc()
plat_py_conf_inc_dir = os.path.dirname(sysconfig.get_config_h_filename())
if sys.platform == "win32":
plat_py_lib_dir = sys.prefix + "\\libs"
plat_bin_dir = sys.exec_prefix
plat_sip_dir = sys.prefix + "\\sip"
else:
lib_dir = sysconfig.get_python_lib(plat_specific=1, standard_lib=1)
plat_py_lib_dir = lib_dir + "/config"
plat_bin_dir = sys.exec_prefix + "/bin"
plat_sip_dir = sys.prefix + "/share/sip"
def create_config(module, template, macros):
"""Create the SIP configuration module so that it can be imported by build
scripts.
module is the module file name.
template is the template file name.
macros is the dictionary of build macros.
"""
siputils.inform("Creating %s..." % module)
content = {
"sip_config_args": sys.argv[1:],
"sip_version": sip_version,
"sip_version_str": sip_version_str,
"platform": opts.platform,
"sip_bin": os.path.join(opts.sipbindir, "sip"),
"sip_inc_dir": opts.sipincdir,
"sip_mod_dir": opts.sipmoddir,
"default_bin_dir": plat_bin_dir,
"default_mod_dir": plat_py_site_dir,
"default_sip_dir": opts.sipsipdir,
"py_version": py_version,
"py_inc_dir": plat_py_inc_dir,
"py_conf_inc_dir": plat_py_conf_inc_dir,
"py_lib_dir": plat_py_lib_dir,
"universal": opts.universal,
"arch": opts.arch
}
siputils.create_config_module(module, template, content, macros)
def create_makefiles(macros):
"""Create the Makefiles.
macros is the dictionary of platform specific build macros.
"""
# Bootstrap. Make sure we get the right one.
sys.path.insert(0, os.path.curdir)
import sipconfig
cfg = sipconfig.Configuration()
cfg.set_build_macros(macros)
sipconfig.inform("Creating top level Makefile...")
sipconfig.ParentMakefile(
configuration=cfg,
subdirs=["sipgen", "siplib"],
installs=(["sipconfig.py", os.path.join(src_dir, "sipdistutils.py")],
cfg.sip_mod_dir)
).generate()
sipconfig.inform("Creating sip code generator Makefile...")
sipconfig.ProgramMakefile(
configuration=cfg,
build_file=os.path.join(src_dir, "sipgen", "sipgen.sbf"),
dir="sipgen",
install_dir=os.path.dirname(cfg.sip_bin),
console=1,
warnings=0,
universal=opts.universal,
arch=opts.arch
).generate()
sipconfig.inform("Creating sip module Makefile...")
makefile = sipconfig.ModuleMakefile(
configuration=cfg,
build_file=os.path.join(src_dir, "siplib", "siplib.sbf"),
dir="siplib",
install_dir=cfg.sip_mod_dir,
installs=([os.path.join(src_dir, "siplib", "sip.h")], cfg.sip_inc_dir),
console=1,
warnings=0,
static=opts.static,
debug=opts.debug,
universal=opts.universal,
arch=opts.arch
)
makefile.generate()
def create_optparser():
"""Create the parser for the command line.
"""
def store_abspath(option, opt_str, value, parser):
setattr(parser.values, option.dest, os.path.abspath(value))
p = optparse.OptionParser(usage="python %prog [opts] [macro=value] "
"[macro+=value]", version=sip_version_str)
# Note: we don't use %default to be compatible with Python 2.3.
p.add_option("-k", "--static", action="store_true", default=False,
dest="static", help="build the SIP module as a static library")
p.add_option("-p", "--platform", action="store",
default=default_platform, type="string", metavar="PLATFORM",
dest="platform", help="the platform/compiler configuration "
"[default: %s]" % default_platform)
p.add_option("-u", "--debug", action="store_true", default=False,
help="build with debugging symbols")
if sys.platform == 'darwin':
# Get the latest SDK to use as the default.
sdks = glob.glob(MACOSX_SDK_DIR + '/MacOSX*.sdk')
if len(sdks) > 0:
sdks.sort()
_, default_sdk = os.path.split(sdks[-1])
else:
default_sdk = 'MacOSX10.4u.sdk'
g = optparse.OptionGroup(p, title="MacOS X Configuration")
g.add_option("--arch", action="append", default=[], dest="arch",
choices=["i386", "x86_64", "ppc"],
help="build for architecture ARCH")
g.add_option("-n", "--universal", action="store_true", default=False,
dest="universal",
help="build the SIP code generator and module as universal "
"binaries")
g.add_option("-s", "--sdk", action="store", default=default_sdk,
type="string", metavar="SDK", dest="sdk",
help="the name of the SDK used when building universal "
"binaries [default: %s]" % default_sdk)
p.add_option_group(g)
# Querying.
g = optparse.OptionGroup(p, title="Query")
g.add_option("--show-platforms", action="store_true", default=False,
dest="show_platforms", help="show the list of supported "
"platform/compiler configurations")
g.add_option("--show-build-macros", action="store_true", default=False,
dest="show_build_macros", help="show the list of supported build "
"macros")
p.add_option_group(g)
# Installation.
g = optparse.OptionGroup(p, title="Installation")
g.add_option("-b", "--bindir", action="callback",
default=default_sipbindir, type="string", metavar="DIR",
dest="sipbindir", callback=store_abspath, help="where the SIP "
"code generator will be installed [default: %s]" %
default_sipbindir)
g.add_option("-d", "--destdir", action="callback",
default=default_sipmoddir, type="string", metavar="DIR",
dest="sipmoddir", callback=store_abspath, help="where the SIP "
"module will be installed [default: %s]" % default_sipmoddir)
g.add_option("-e", "--incdir", action="callback",
default=default_sipincdir, type="string", metavar="DIR",
dest="sipincdir", callback=store_abspath, help="where the SIP "
"header file will be installed [default: %s]" % default_sipincdir)
g.add_option("-v", "--sipdir", action="callback",
default=default_sipsipdir, type="string", metavar="DIR",
dest="sipsipdir", callback=store_abspath, help="where .sip files "
"are normally installed [default: %s]" % default_sipsipdir)
p.add_option_group(g)
return p
def main(argv):
"""Create the configuration module module.
argv is the list of command line arguments.
"""
siputils.inform("This is SIP %s for Python %s on %s." % (sip_version_str, sys.version.split()[0], sys.platform))
if py_version < 0x020300:
siputils.error("This version of SIP requires Python v2.3 or later.")
# Basic initialisation.
set_platform_directories()
# Build up the list of valid specs.
for s in os.listdir(os.path.join(src_dir, "specs")):
platform_specs.append(s)
# Parse the command line.
global opts
set_defaults()
p = create_optparser()
opts, args = p.parse_args()
# Make sure MacOS specific options get initialised.
if sys.platform != 'darwin':
opts.universal = ''
opts.arch = []
opts.sdk = ''
# Handle the query options.
if opts.show_platforms or opts.show_build_macros:
if opts.show_platforms:
show_platforms()
if opts.show_build_macros:
show_macros()
sys.exit()
# Convert the list 'arch' option to a string. Multiple architectures
# imply a universal binary.
if len(opts.arch) > 1:
opts.universal = True
opts.arch = ' '.join(opts.arch)
# Convert the boolean 'universal' option to a string.
if opts.universal:
if '/' in opts.sdk:
opts.universal = os.path.abspath(opts.sdk)
else:
opts.universal = MACOSX_SDK_DIR + '/' + opts.sdk
if not os.path.isdir(opts.universal):
siputils.error("Unable to find the SDK directory %s. Use the --sdk flag to specify the name of the SDK or its full path." % opts.universal)
if opts.arch == '':
opts.arch = DEFAULT_MACOSX_ARCH
else:
opts.universal = ''
# Get the platform specific macros for building.
macros = siputils.parse_build_macros(
os.path.join(src_dir, "specs", opts.platform), build_macro_names,
args)
if macros is None:
p.print_help()
sys.exit(2)
# Tell the user what's been found.
inform_user()
# Install the configuration module.
create_config("sipconfig.py", os.path.join(src_dir, "siputils.py"),
macros)
# Create the Makefiles.
create_makefiles(macros)
###############################################################################
# The script starts here.
###############################################################################
if __name__ == "__main__":
try:
main(sys.argv)
except SystemExit:
raise
except:
sys.stderr.write(
"""An internal error occured. Please report all the output from the program,
including the following traceback, to support@riverbankcomputing.com.
""")
raise

@ -0,0 +1,60 @@
/*
* This file is the basis of a custom Python interpreter. Use it for Linux,
* UNIX and Windows (console). You will also need to edit mkcustom.py.
*/
#include <Python.h>
int main(int argc, char **argv)
{
/*
* Declare the module initialisation function for each module you want
* to be a builtin in the custom interpreter. The name of the function
* will be the name of the module with "init" prepended. The modules
* must be built as static libraries (using the -k flag to configure.py
* for SIP and PyQt).
*/
/* The sip module will be builtin. */
extern void initsip(void);
/*
* Uncomment these (and in the structure below) to include the PyQt
* modules as builtins.
*/
/* extern void initqt(void);*/
/* extern void initqtaxcontainer(void);*/
/* extern void initqtcanvas(void);*/
/* extern void initqtext(void);*/
/* extern void initqtgl(void);*/
/* extern void initqtnetwork(void);*/
/* extern void initqtsql(void);*/
/* extern void initqttable(void);*/
/* extern void initqtui(void);*/
/* extern void initqtxml(void);*/
/*
* This structure specifies the names and initialisation functions of
* the builtin modules.
*/
struct _inittab builtin_modules[] = {
{"sip", initsip},
/* {"qt", initqt},*/
/* {"qtaxcontainer", initqtaxcontainer},*/
/* {"qtcanvas", initqtcanvas},*/
/* {"qtext", initqtext},*/
/* {"qtgl", initqtgl},*/
/* {"qtnetwork", initqtnetwork},*/
/* {"qtsql", initqtsql},*/
/* {"qttable", initqttable},*/
/* {"qtui", initqtui},*/
/* {"qtxml", initqtxml},*/
{NULL, NULL}
};
PyImport_ExtendInittab(builtin_modules);
return Py_Main(argc, argv);
}

@ -0,0 +1,64 @@
/*
* This file is the basis of a custom Python interpreter. Use it for Windows
* (non-console). You will also need to edit mkcustom.py.
*/
#define WIN32_LEAN_AND_MEAN
#include <windows.h>
#include <Python.h>
int WINAPI WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance,
LPSTR lpCmdLine, int nCmdShow)
{
/*
* Declare the module initialisation function for each module you want
* to be a builtin in the custom interpreter. The name of the function
* will be the name of the module with "init" prepended. The modules
* must be built as static libraries (using the -k flag to configure.py
* for SIP and PyQt).
*/
/* The sip module will be builtin. */
extern void initsip(void);
/*
* Uncomment these (and in the structure below) to include the PyQt
* modules as builtins.
*/
/* extern void initqt(void);*/
/* extern void initqtaxcontainer(void);*/
/* extern void initqtcanvas(void);*/
/* extern void initqtext(void);*/
/* extern void initqtgl(void);*/
/* extern void initqtnetwork(void);*/
/* extern void initqtsql(void);*/
/* extern void initqttable(void);*/
/* extern void initqtui(void);*/
/* extern void initqtxml(void);*/
/*
* This structure specifies the names and initialisation functions of
* the builtin modules.
*/
struct _inittab builtin_modules[] = {
{"sip", initsip},
/* {"qt", initqt},*/
/* {"qtaxcontainer", initqtaxcontainer},*/
/* {"qtcanvas", initqtcanvas},*/
/* {"qtext", initqtext},*/
/* {"qtgl", initqtgl},*/
/* {"qtnetwork", initqtnetwork},*/
/* {"qtsql", initqtsql},*/
/* {"qttable", initqttable},*/
/* {"qtui", initqtui},*/
/* {"qtxml", initqtxml},*/
{NULL, NULL}
};
PyImport_ExtendInittab(builtin_modules);
return Py_Main(__argc, __argv);
}

@ -0,0 +1,87 @@
"""This Python script uses the SIP build system to create a Makefile for
building a custom Python interpreter. The script doesn't take any command line
flags - just edit it to suit your needs. You will also need to edit custom.c
or customw.c.
"""
import sys
import sipconfig
# Get the SIP configuration.
cfg = sipconfig.Configuration()
# This is the name of the interpreter executable (excluding any platform
# specific extension.
InterpreterName = "custom"
# Set this to True to create a non-console interpreter on Windows (ie. a custom
# version of pythonw). Make sure you make changes to customw.c rather than
# custom.c. It is ignored on other platforms.
WindowsInterpreter = False
# Set this to the list of the name of modules to be builtin to the custom
# interpreter. The modules must also be added to custom.c and/or customw.c.
Modules = ["sip"]
#Modules = ["sip", "qt", "qtaxcontainer", "qtcanvas", "qtext", "qtgl",
# "qtnetwork", "qtsql", "qttable", "qtui", "qtxml"]
# Set this to the name of the directory containing the static modules.
ModuleDirectory = cfg.default_mod_dir
# Set this to the list of additional libraries to link with the custom
# interpreter.
ExtraLibraries = []
#ExtraLibraries = ["qassistantclient"]
# Set this to the list of additional directory names to search for any
# additional libraries.
ExtraLibraryDirectories = []
# Set this to the name of the directory containing the Python library.
PythonLibraryDirectory = cfg.py_lib_dir
# Make platform specific modifications.
if sys.platform == "linux2":
ExtraLibraries.append("util")
# Create a dictionary describing the target and source files to be passed to
# the SIP build system.
build = {}
if sys.platform == "win32" and WindowsInterpreter:
build["target"] = InterpreterName + "w"
build["sources"] = "customw.c"
console = False
else:
build["target"] = InterpreterName
build["sources"] = "custom.c"
console = True
# Assume Qt support is required if Qt support was enabled in the sip module.
qt = (cfg.qt_version > 0)
# Create the Makefile instance.
mf = sipconfig.ProgramMakefile(cfg, build, python=True, console=console, qt=qt)
# Modify the Makefile according to the values set above.
mf.extra_lib_dirs.extend(ExtraLibraryDirectories)
mf.extra_lib_dirs.append(ModuleDirectory)
mf.extra_lib_dirs.append(PythonLibraryDirectory)
mf.extra_libs.extend(Modules)
if sys.platform == "win32":
pylib = "python%u%u"
else:
pylib = "python%u.%u"
mf.extra_libs.append(pylib % ((cfg.py_version >> 16), ((cfg.py_version >> 8) & 0xff)))
mf.extra_libs.extend(ExtraLibraries)
# Generate the Makefile itself.
mf.generate()

@ -0,0 +1,805 @@
Annotations
===========
In this section we describe each of the annotations that can be used in
specification files.
Annotations can either be :ref:`argument annotations <ref-arg-annos>`,
:ref:`class annotations <ref-class-annos>`, :ref:`mapped type annotations
<ref-mapped-type-annos>`, :ref:`enum annotations <ref-enum-annos>`,
:ref:`exception annotations <ref-exception-annos>`, :ref:`function annotations
<ref-function-annos>`, :ref:`license annotations <ref-license-annos>`,
:ref:`typedef annotations <ref-typedef-annos>` or :ref:`variable annotations
<ref-variable-annos>` 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.
*dotted name*
The value is a name that is compatible with an identifier preceded by a
Python scope.
*string*
The value is a double quoted string.
*API range*
The value is the name of an API (defined using the :directive:`%API`
directive) separated by a range of version numbers with a colon.
The range of version numbers is a pair of numbers separated by a hyphen
specifying the lower and upper bounds of the range. A version number is
within the range if it is greater or equal to the lower bound and less
than the upper bound. Each bound can be omitted meaning that the range is
unbounded in that direction.
For example::
# This is part of the PyQt4 API up to but excluding v2.
void hex() /API=PyQt4:-2/
# This is part of the PyQt4 API starting from v2.
void hex() /PyName=hex_, API=PyQt4:2-/
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.
.. _ref-arg-annos:
Argument Annotations
--------------------
.. argument-annotation:: AllowNone
This boolean annotation specifies that the value of the corresponding
argument (which should be either :stype:`SIP_PYCALLABLE`,
:stype:`SIP_PYDICT`, :stype:`SIP_PYLIST`, :stype:`SIP_PYSLICE`,
:stype:`SIP_PYTUPLE` or :stype:`SIP_PYTYPE`) may be ``None``.
.. argument-annotation:: Array
This boolean annotation specifies that the corresponding argument refers
to an array.
The argument should be either a pointer to a wrapped type, a ``char *`` or
a ``unsigned char *``. If the argument is a character array then the
annotation also implies the :aanno:`Encoding` annotation with an encoding
of ``"None"``.
There must be a corresponding argument with the :aanno:`ArraySize`
annotation specified. The annotation may only be specified once in a list
of arguments.
.. argument-annotation:: 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 :aanno:`Array` annotation specified.
The annotation may only be specified once in a list of arguments.
.. argument-annotation:: 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``, ``enum`` or a
wrapped class) must match the type without any automatic conversions. In
the context of a wrapped class the invocation of any
:directive:`%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);
.. argument-annotation:: DocType
.. versionadded:: 4.10
This string annotation specifies the type of the argument as it will appear
in any generated docstrings. It is usually used with arguments of type
:stype:`SIP_PYOBJECT` to provide a more specific type.
.. argument-annotation:: DocValue
.. versionadded:: 4.10
This string annotation specifies the default value of the argument as it
will appear in any generated docstrings.
.. argument-annotation:: Encoding
This string annotation specifies that the corresponding argument (which
should be either ``char``, ``const char``, ``char *`` or ``const char *``)
refers to an encoded character or ``'\0'`` terminated encoded string with
the specified encoding. The encoding can be either ``"ASCII"``,
``"Latin-1"``, ``"UTF-8"`` or ``"None"``. An encoding of ``"None"`` means
that the corresponding argument refers to an unencoded character or string.
The default encoding is specified by the :directive:`%DefaultEncoding`
directive. If the directive is not specified then ``None`` is used.
Python v3 will use the ``bytes`` type to represent the argument if the
encoding is ``"None"`` and the ``str`` type otherwise.
Python v2 will use the ``str`` type to represent the argument if the
encoding is ``"None"`` and the ``unicode`` type otherwise.
.. argument-annotation:: GetWrapper
This boolean annotation is only ever used in conjunction with handwritten
code specified with the :directive:`%MethodCode` directive. It causes an
extra variable to be generated for the corresponding argument which is a
pointer to the Python object that wraps the argument.
See the :directive:`%MethodCode` directive for more detail.
.. argument-annotation:: 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 :aanno:`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 :aanno:`In` and :aanno:`Out` may be specified for the same argument.
.. argument-annotation:: KeepReference
This boolean annotation is used to specify that a reference to the
corresponding argument should be kept to ensure that the object is not
garbage collected. If the method is called again with a new argument then
the reference to the previous argument is discarded. Note that ownership
of the argument is not changed.
.. argument-annotation:: NoCopy
.. versionadded:: 4.10.1
This boolean annotation is used with arguments of virtual methods that are
a ``const`` reference to a class. Normally, if the class defines a copy
constructor then a copy of the returned reference is automatically created
and wrapped before being passed to a Python reimplementation of the method.
The copy will be owned by Python. This means that the reimplementation may
take a reference to the argument without having to make an explicit copy.
If the annotation is specified then the copy is not made and the original
reference is wrapped instead and will be owned by C++.
.. argument-annotation:: 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
:aanno:`In` annotation is specified.
Both :aanno:`In` and :aanno:`Out` may be specified for the same argument.
.. argument-annotation:: ResultSize
This boolean annotation is used with functions or methods that return a
``void *`` or ``const void *``. It identifies an argument that defines the
size of the block of memory whose address is being returned. This allows
the ``sip.voidptr`` object that wraps the address to support the Python
buffer protocol and allows the memory to be read and updated when wrapped
by the Python ``buffer()`` builtin.
.. argument-annotation:: SingleShot
This boolean annotation is used only with arguments of type
:stype:`SIP_RXOBJ_CON` to specify that the signal connected to the slot
will only ever be emitted once. This prevents a certain class of memory
leaks.
.. argument-annotation:: 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 :ref:`ref-object-ownership` for more detail.
.. argument-annotation:: 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.
See :ref:`ref-object-ownership` for more detail.
.. argument-annotation:: 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 :ref:`ref-object-ownership` for more detail.
.. _ref-class-annos:
Class Annotations
-----------------
.. class-annotation:: 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.
.. class-annotation:: AllowNone
.. versionadded:: 4.8.2
Normally when a Python object is converted to a C/C++ instance ``None``
is handled automatically before the class's
:directive:`%ConvertToTypeCode` is called. This boolean annotation
specifies that the handling of ``None`` will be left to the
:directive:`%ConvertToTypeCode`. The annotation is ignored if the class
does not have any :directive:`%ConvertToTypeCode`.
.. class-annotation:: API
.. versionadded:: 4.9
This API range annotation is used to specify an API and corresponding
range of version numbers that the class is enabled for.
If a class or mapped type has different implementations enabled for
different ranges of version numbers then those ranges must not overlap.
See :ref:`ref-incompat-apis` for more detail.
.. class-annotation:: 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
:cfunc:`sipDelayedDtors()` is called with the list of delayed instances.
:cfunc:`sipDelayedDtors()` can then choose to call (or ignore) the
destructors in any desired order.
The :cfunc:`sipDelayedDtors()` function must be specified using the
:directive:`%ModuleCode` directive.
.. cfunction:: void sipDelayedDtors(const sipDelayedDtor *dd_list)
:param dd_list:
the linked list of delayed instances.
.. ctype:: sipDelayedDtor
This structure describes a particular delayed destructor.
.. cmember:: const char *dd_name
This is the name of the class excluding any package or module name.
.. cmember:: 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 :cmember:`dd_isderived`.
.. cmember:: int dd_isderived
This is non-zero if the type of :cmember:`dd_ptr` is actually the
generated derived class. This allows the correct destructor to be
called. See :ref:`ref-derived-classes`.
.. cmember:: 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.
.. class-annotation:: Deprecated
This boolean annotation is used to specify that the class is deprecated.
It is the equivalent of annotating all the class's constructors, function
and methods as being deprecated.
.. class-annotation:: 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.
.. class-annotation:: Metatype
This dotted name annotation specifies the name of the Python type object
(i.e. the value of the ``tp_name`` field) used as the meta-type used when
creating the type object for this C structure or C++ type.
See the section :ref:`ref-types-metatypes` for more details.
.. class-annotation:: NoDefaultCtors
This boolean annotation is used to suppress the automatic generation of
default constructors for the class.
.. class-annotation:: 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.
.. class-annotation:: Supertype
This dotted name annotation specifies the name of the Python type object
(i.e. the value of the ``tp_name`` field) used as the super-type used when
creating the type object for this C structure or C++ type.
See the section :ref:`ref-types-metatypes` for more details.
.. _ref-mapped-type-annos:
Mapped Type Annotations
-----------------------
.. mapped-type-annotation:: AllowNone
Normally when a Python object is converted to a C/C++ instance ``None``
is handled automatically before the mapped type's
:directive:`%ConvertToTypeCode` is called. This boolean annotation
specifies that the handling of ``None`` will be left to the
:directive:`%ConvertToTypeCode`.
.. mapped-type-annotation:: API
.. versionadded:: 4.9
This API range annotation is used to specify an API and corresponding
range of version numbers that the mapped type is enabled for.
If a class or mapped type has different implementations enabled for
different ranges of version numbers then those ranges must not overlap.
See :ref:`ref-incompat-apis` for more detail.
.. mapped-type-annotation:: DocType
.. versionadded:: 4.10
This string annotation specifies the name of the type as it will appear in
any generated docstrings.
.. mapped-type-annotation:: NoRelease
This boolean annotation is used to specify that the mapped type does not
support the :cfunc:`sipReleaseType()` function. Any
:directive:`%ConvertToTypeCode` should not create temporary instances of
the mapped type, i.e. it should not return :cmacro:`SIP_TEMPORARY`.
.. _ref-enum-annos:
Enum Annotations
----------------
.. enum-annotation:: 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.
.. _ref-exception-annos:
Exception Annotations
---------------------
.. exception-annotation:: Default
This boolean annotation specifies that the exception being defined will be
used as the default exception to be caught if a function or constructor
does not have a ``throw`` clause.
.. exception-annotation:: 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.
.. _ref-function-annos:
Function Annotations
--------------------
.. function-annotation:: API
.. versionadded:: 4.9
This API range annotation is used to specify an API and corresponding
range of version numbers that the function is enabled for.
See :ref:`ref-incompat-apis` for more detail.
.. function-annotation:: 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 :directive:`%Feature` directive)
which must be enabled for the method to be generated.
.. function-annotation:: 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.
.. function-annotation:: Deprecated
This boolean annotation is used to specify that the constructor or function
is deprecated. A deprecation warning is issued whenever the constructor or
function is called.
.. function-annotation:: DocType
.. versionadded:: 4.10
This string annotation specifies the name of the type of the returned value
as it will appear in any generated docstrings. It is usually used with
values of type :stype:`SIP_PYOBJECT` to provide a more specific type.
.. function-annotation:: 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 :ref:`ref-object-ownership` for more detail.
.. function-annotation:: 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 :ref:`ref-gil` and the :fanno:`ReleaseGIL` annotation.
.. function-annotation:: KeywordArgs
.. versionadded:: 4.10
This boolean annotation specifies that the argument parser generated for
this function will support passing the parameters using Python's keyword
argument syntax. Keyword arguments cannot be used for functions that have
unnamed arguments or use an ellipsis to designate that the function has a
variable number of arguments.
.. function-annotation:: __len__
.. versionadded:: 4.10.3
This boolean annotation specifies that a ``__len__()`` method should be
automatically generated that will use the method being annotated to compute
the value that the ``__len__()`` method will return.
.. function-annotation:: NewThread
This boolean annotation specifies that the function will create a new
thread.
.. function-annotation:: NoArgParser
This boolean annotation is used with methods and global functions to
specify that the supplied :directive:`%MethodCode` will handle the parsing
of the arguments.
.. function-annotation:: NoCopy
.. versionadded:: 4.10.1
This boolean annotation is used with methods and global functions that
return a ``const`` reference to a class. Normally, if the class defines a
copy constructor then a copy of the returned reference is automatically
created and wrapped. The copy will be owned by Python.
If the annotation is specified then the copy is not made and the original
reference is wrapped instead and will be owned by C++.
.. function-annotation:: NoDerived
This boolean annotation is only used with C++ constructors. In many cases
SIP generates a derived class for each class being wrapped (see
:ref:`ref-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.
.. function-annotation:: NoKeywordArgs
.. versionadded:: 4.10
This boolean annotation specifies that the argument parser generated for
this function will not support passing the parameters using Python's
keyword argument syntax. In other words, the argument parser will only
support only normal positional arguments. This annotation is useful when
the default setting of allowing keyword arguments has been changed via the
command line, but you would still like certain functions to only support
positional arguments.
.. function-annotation:: 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 ``[]``,
:meth:`__getitem__`, :meth:`__setitem__` or :meth:`__delitem__` defined
then it assumes that they should be sequence operators. This annotation is
used to force SIP to treat the operator as numeric.
.. function-annotation:: 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.
.. function-annotation:: 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.
.. function-annotation:: 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.
.. function-annotation:: 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 :ref:`ref-gil` and the
:fanno:`HoldGIL` annotation.
.. function-annotation:: Transfer
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 to C++. It is only used in the context of a class
constructor or a method.
In the case of methods returned values (unless they are new references to
already wrapped values) are normally owned by C++ anyway. However, in
addition, an association between the returned value and the instance
containing the method is created with regard to the cyclic garbage
collector.
See :ref:`ref-object-ownership` for more detail.
.. function-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.
See :ref:`ref-object-ownership` for more detail.
.. function-annotation:: TransferThis
This boolean annotation specifies that ownership of ``this`` is transferred
from Python to C++.
See :ref:`ref-object-ownership` for more detail.
.. _ref-license-annos:
License Annotations
-------------------
.. license-annotation:: Licensee
This optional string annotation specifies the license's licensee. No
restrictions are placed on the contents of the string.
See the :directive:`%License` directive.
.. license-annotation:: Signature
This optional string annotation specifies the license's signature. No
restrictions are placed on the contents of the string.
See the :directive:`%License` directive.
.. license-annotation:: Timestamp
This optional string annotation specifies the license's timestamp. No
restrictions are placed on the contents of the string.
See the :directive:`%License` directive.
.. license-annotation:: Type
This string annotation specifies the license's type. No restrictions are
placed on the contents of the string.
See the :directive:`%License` directive.
.. _ref-typedef-annos:
Typedef Annotations
-------------------
.. typedef-annotation:: NoTypeName
This boolean annotation specifies that the definition of the type rather
than the name of the type being defined should be used in the generated
code.
Normally a typedef would be defined as follows::
typedef bool MyBool;
This would result in ``MyBool`` being used in the generated code.
Specifying the annotation means that ``bool`` will be used in the generated
code instead.
.. _ref-variable-annos:
Variable Annotations
--------------------
.. variable-annotation:: DocType
.. versionadded:: 4.10
This string annotation specifies the name of the type of the variable as it
will appear in any generated docstrings. It is usually used with variables
of type :stype:`SIP_PYOBJECT` to provide a more specific type.
.. variable-annotation:: 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.

@ -0,0 +1,843 @@
.. _ref-build-system:
The Build System
================
.. module:: sipconfig
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 :mod:`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.com/software/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.
.. function:: create_config_module(module, template, content[, macros=None])
This creates a configuration module (e.g. ``pyqtconfig``) from a template
file and a string.
:param module:
the name of the configuration module file to create.
:param template:
the name of the template file.
:param content:
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
:func:`sipconfig.create_content()`. *content* may also be a
dictionary, in which case :func:`sipconfig.create_content()` is
automatically called to convert it to a string.
:param macros:
an optional dictionary of platform specific build macros. It is only
used if :func:`sipconfig.create_content()` is called automatically to
convert a *content* dictionary to a string.
.. function:: create_content(dict[, macros=None]) -> string
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
:func:`sipconfig.create_config_module()`.
:param dict:
the Python dictionary to convert.
:param macros:
the optional dictionary of platform specific build macros.
:return:
the string representation of the dictionary.
.. function:: create_wrapper(script, wrapper[, gui=0[, use_arch='']]) -> string
This creates a platform dependent executable wrapper around a Python
script.
:param script:
the full pathname of the script.
:param wrapper:
the full pathname of the wrapper to create, excluding any platform
specific extension.
:param gui:
is non-zero if a GUI enabled version of the interpreter should be used
on platforms that require it.
:param use_arch:
is the MacOS/X architecture to invoke python with.
:return:
the platform specific name of the wrapper.
.. function:: error(msg)
This displays an error message on ``stderr`` and calls ``sys.exit(1)``.
:param msg:
the text of the message and should not include any newline characters.
.. function:: format(msg[, leftmargin=0[, rightmargin=78]]) -> string
This formats a message by inserting newline characters at appropriate
places.
:param msg:
the text of the message and should not include any newline characters.
:param leftmargin:
the optional position of the left margin.
:param rightmargin:
the optional position of the right margin.
:return:
the formatted message.
.. function:: inform(msg)
This displays an information message on ``stdout``.
:param msg:
the text of the message and should not include any newline characters.
.. function:: parse_build_macros(filename, names[, overrides=None[, properties=None]]) -> dict
This parses a ``qmake`` compatible file of build system macros and converts
it to a dictionary. A macro is a name/value pair. Individual macros may
be augmented or replaced.
:param filename:
the name of the file to parse.
:param names:
the list of the macro names to extract from the file.
:param overrides:
the 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).
:param properties:
the optional dictionary of property name and values that are used to
resolve any expressions of the form ``$[name]`` in the file.
:return:
the dictionary of parsed macros or ``None`` if any of the overrides
were invalid.
.. function:: read_version(filename, description[, numdefine=None[, strdefine=None]]) -> integer, string
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.
:param filename:
the name of the file to read.
:param description:
a descriptive name of the package used in error messages.
:param numdefine:
the optional name of the ``#define`` of the version as a number. If it
is ``None`` then the numeric version is ignored.
:param strdefine:
the optional name of the ``#define`` of the version as a string. If it
is ``None`` then the string version is ignored.
:return:
a tuple of the numeric and string versions. :func:`sipconfig.error()`
is called if either were required but could not be found.
.. function:: version_to_sip_tag(version, tags, description) -> string
This converts a version number to a SIP version tag. SIP uses the
:directive:`%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.
:param version:
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.)
:param tags:
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*.
:param description:
a descriptive name of the C/C++ library used in error messages.
:return:
the SIP version tag. :func:`sipconfig.error()` is called if the C/C++
library version number did not correspond to a SIP version tag.
.. function:: version_to_string(v) -> string
This converts a 3 part version number encoded as a hexadecimal value to a
string.
:param v:
the version number.
:return:
a string.
.. class:: 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:
.. attribute:: default_bin_dir
The name of the directory where executables should be installed by
default.
.. attribute:: default_mod_dir
The name of the directory where SIP generated modules should be
installed by default.
.. attribute:: 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.
.. attribute:: platform
The name of the platform/compiler for which the build system has been
configured for.
.. attribute:: py_conf_inc_dir
The name of the directory containing the ``pyconfig.h`` header file.
.. attribute:: py_inc_dir
The name of the directory containing the ``Python.h`` header file.
.. attribute:: py_lib_dir
The name of the directory containing the Python interpreter library.
.. attribute:: py_version
The Python version as a 3 part hexadecimal number (e.g. v2.3.3 is
represented as ``0x020303``).
.. attribute:: sip_bin
The full pathname of the SIP executable.
.. attribute:: sip_config_args
The command line passed to ``configure.py`` when SIP was configured.
.. attribute:: sip_inc_dir
The name of the directory containing the ``sip.h`` header file.
.. attribute:: sip_mod_dir
The name of the directory containing the SIP module.
.. attribute:: sip_version
The SIP version as a 3 part hexadecimal number (e.g. v4.0.0 is
represented as ``0x040000``).
.. attribute:: sip_version_str
The SIP version as a string. For development snapshots it will start
with ``snapshot-``.
.. attribute:: universal
The name of the MacOS/X SDK used when creating universal binaries.
.. attribute:: arch
The space separated MacOS/X architectures to build.
.. method:: __init__([sub_cfg=None])
:param sub_cfg:
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.
.. method:: build_macros() -> dict
Get the dictionary of platform specific build macros.
:return:
the macros dictionary.
.. method:: set_build_macros(macros)
Set the dictionary of platform specific build macros to be used when
generating Makefiles. Normally there is no need to change the default
macros.
:param macros:
the macros dictionary.
.. class:: 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 attributes.
The following instance attributes are provided to help in fine tuning the
generated Makefile:
.. attribute:: chkdir
A string that will check for the existence of a directory.
.. attribute:: config
A reference to the *configuration* argument that was passed to
:meth:`Makefile.__init__`.
.. attribute:: console
A reference to the *console* argument that was passed to the
:meth:`Makefile.__init__`.
.. attribute:: copy
A string that will copy a file.
.. attribute:: extra_cflags
A list of additional flags passed to the C compiler.
.. attribute:: extra_cxxflags
A list of additional flags passed to the C++ compiler.
.. attribute:: extra_defines
A list of additional macro names passed to the C/C++ preprocessor.
.. attribute:: extra_include_dirs
A list of additional include directories passed to the C/C++
preprocessor.
.. attribute:: extra_lflags
A list of additional flags passed to the linker.
.. attribute:: extra_lib_dirs
A list of additional library directories passed to the linker.
.. attribute:: 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).
.. attribute:: generator
A string that defines the platform specific style of Makefile. The
only supported values are ``UNIX``, ``MSVC``, ``MSVC.NET``, ``MINGW``
and ``BMAKE``.
.. attribute:: mkdir
A string that will create a directory.
.. attribute:: rm
A string that will remove a file.
.. method:: __init__(configuration[, console=0[, qt=0[, opengl=0[, python=0[, threaded=0[, warnings=None[, debug=0[, dir=None[, makefile="Makefile"[, installs=None[, universal=None[, arch=None]]]]]]]]]]]])
:param configuration:
the current configuration and is an instance of the
:class:`Configuration` class or a sub-class.
:param console:
is set if the target is a console (rather than GUI) target. This
only affects Windows and is ignored on other platforms.
:param 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.
:param opengl:
is set if the target uses OpenGL.
:param python:
is set if the target uses Python.h.
:param threaded:
is set if the target requires thread support. It is set
automatically if the target uses Qt and Qt has thread support
enabled.
:param 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.
:param debug:
is set if debugging symbols should be generated.
:param dir:
the name of the directory where build files are read from (if they
are not absolute file names) and Makefiles are written to. The
default of ``None`` means the current directory is used.
:param makefile:
the name of the generated Makefile.
:param installs:
the 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.
:param universal:
the name of the SDK if universal binaries are to be created under
MacOS/X. If it is ``None`` then the value is taken from the
configuration.
:param arch:
the space separated MacOS/X architectures to build. If it is
``None`` then the value is taken from the configuration.
.. method:: clean_build_file_objects(mfile, build)
This generates the Makefile commands that will remove any files
generated during the build of the default target.
:param mfile:
the Python file object of the Makefile.
:param build:
the dictionary created from parsing the build file.
.. method:: finalise()
This is called just before the Makefile is generated to ensure that it
is fully configured. It must be reimplemented by a sub-class.
.. method:: generate()
This generates the Makefile.
.. method:: generate_macros_and_rules(mfile)
This is the default implementation of the Makefile macros and rules
generation.
:param mfile:
the Python file object of the Makefile.
.. method:: generate_target_clean(mfile)
This is the default implementation of the Makefile clean target
generation.
:param mfile:
the Python file object of the Makefile.
.. method:: generate_target_default(mfile)
This is the default implementation of the Makefile default target
generation.
:param mfile:
the Python file object of the Makefile.
.. method:: generate_target_install(mfile)
This is the default implementation of the Makefile install target
generation.
:param mfile:
the Python file object of the Makefile.
.. method:: install_file(mfile, src, dst[, strip=0])
This generates the Makefile commands to install one or more files to a
directory.
:param mfile:
the Python file object of the Makefile.
:param src:
the name of a single file to install or a list of a number of files
to install.
:param dst:
the name of the destination directory.
:param strip:
is set if the files should be stripped of unneeded symbols after
having been installed.
.. method:: optional_list(name) -> list
This returns an optional Makefile macro as a list.
:param name:
the name of the macro.
:return:
the macro as a list.
.. method:: optional_string(name[, default=""])
This returns an optional Makefile macro as a string.
:param name:
the name of the macro.
:param default:
the optional default value of the macro.
:return:
the macro as a string.
.. method:: parse_build_file(filename) -> dict
This parses a build file (created with the :option:`-b <sip -b>` SIP
command line option) and converts it to a dictionary. It can also
validate an existing dictionary created through other means.
:param 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``.
:return:
a dictionary corresponding to the parsed build file.
.. method:: platform_lib(clib[, framework=0]) -> string
This converts a library name to a platform specific form.
:param clib:
the name of the library in cannonical form.
:param framework:
is set if the library is implemented as a MacOS framework.
:return:
the platform specific name.
.. method:: ready()
This is called to ensure that the Makefile is fully configured. It is
normally called automatically when needed.
.. method:: required_string(name) -> string
This returns a required Makefile macro as a string.
:param name:
the name of the macro.
:return:
the macro as a string. An exception is raised if the macro does
not exist or has an empty value.
.. class:: ModuleMakefile
This class is derived from :class:`sipconfig.Makefile`.
This class encapsulates a Makefile to build a generic Python extension
module.
.. method:: __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=None[, arch=None]]]]]]]]]]]]]])
:param configuration:
see :meth:`sipconfig.Makefile.__init__`.
:param build_file:
the name of the build file. Build files are generated using the
:option:`-b <sip -b>` SIP command line option.
:param install_dir:
the name of the directory where the module will be optionally
installed.
:param static:
is set if the module should be built as a static library (see
:ref:`ref-builtin`).
:param console:
see :meth:`sipconfig.Makefile.__init__`.
:param qt:
see :meth:`sipconfig.Makefile.__init__`.
:param opengl:
see :meth:`sipconfig.Makefile.__init__`.
:param threaded:
see :meth:`sipconfig.Makefile.__init__`.
:param warnings:
see :meth:`sipconfig.Makefile.__init__`.
:param debug:
see :meth:`sipconfig.Makefile.__init__`.
:param dir:
see :meth:`sipconfig.Makefile.__init__`.
:param makefile:
see :meth:`sipconfig.Makefile.__init__`.
:param installs:
see :meth:`sipconfig.Makefile.__init__`.
:param 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.
:param 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.
:param universal:
see :meth:`sipconfig.Makefile.__init__`.
:param arch:
see :meth:`sipconfig.Makefile.__init__`.
.. method:: finalise()
This is a reimplementation of :meth:`sipconfig.Makefile.finalise`.
.. method:: generate_macros_and_rules(mfile)
This is a reimplementation of
:meth:`sipconfig.Makefile.generate_macros_and_rules`.
.. method:: generate_target_clean(mfile)
This is a reimplementation of
:meth:`sipconfig.Makefile.generate_target_clean`.
.. method:: generate_target_default(mfile)
This is a reimplementation of
:meth:`sipconfig.Makefile.generate_target_default`.
.. method:: generate_target_install(mfile)
This is a reimplementation of
:meth:`sipconfig.Makefile.generate_target_install`.
.. method:: module_as_lib(mname) -> string
This gets 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.
:param mname:
the name of the module.
:return:
the corresponding library name.
.. class:: ParentMakefile
This class is derived from :class:`sipconfig.Makefile`.
This class encapsulates a Makefile that sits above a number of other
Makefiles in sub-directories.
.. method:: __init__(self, configuration, subdirs[, dir=None[, makefile[="Makefile"[, installs=None]]]])
:param configuration:
see :meth:`sipconfig.Makefile.__init__`.
:param subdirs:
the sequence of sub-directories.
:param dir:
see :meth:`sipconfig.Makefile.__init__`.
:param makefile:
see :meth:`sipconfig.Makefile.__init__`.
:param installs:
see :meth:`sipconfig.Makefile.__init__`.
.. method:: generate_macros_and_rules(mfile)
This is a reimplementation of
:meth:`sipconfig.Makefile.generate_macros_and_rules`.
.. method:: generate_target_clean(mfile)
This is a reimplementation of
:meth:`sipconfig.Makefile.generate_target_clean`.
.. method:: generate_target_default(mfile)
This is a reimplementation of
:meth:`sipconfig.Makefile.generate_target_default`.
.. method:: generate_target_install(mfile)
This is a reimplementation of
:meth:`sipconfig.Makefile.generate_target_install`.
.. class:: ProgramMakefile
This class is derived from :class:`sipconfig.Makefile`.
This class encapsulates a Makefile to build an executable program.
.. method:: __init__(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=None[, arch=None]]]]]]]]]]]]]])
:param configuration:
see :meth:`sipconfig.Makefile.__init__`.
:param build_file:
the name of the optional build file. Build files are generated
using the :option:`-b <sip -b>` SIP command line option.
:param install_dir:
the name of the directory where the executable program will be
optionally installed.
:param console:
see :meth:`sipconfig.Makefile.__init__`.
:param qt:
see :meth:`sipconfig.Makefile.__init__`.
:param opengl:
see :meth:`sipconfig.Makefile.__init__`.
:param python:
see :meth:`sipconfig.Makefile.__init__`.
:param threaded:
see :meth:`sipconfig.Makefile.__init__`.
:param warnings:
see :meth:`sipconfig.Makefile.__init__`.
:param debug:
see :meth:`sipconfig.Makefile.__init__`.
:param dir:
see :meth:`sipconfig.Makefile.__init__`.
:param makefile:
see :meth:`sipconfig.Makefile.__init__`.
:param installs:
see :meth:`sipconfig.Makefile.__init__`.
:param universal:
see :meth:`sipconfig.Makefile.__init__`.
:param arch:
see :meth:`sipconfig.Makefile.__init__`.
.. method:: build_command(source) -> string, string
This creates a single command line that will create an executable
program from a single source file.
:param source:
the name of the source file.
:return:
a tuple of the name of the executable that will be created and the
command line.
.. method:: finalise()
This is a reimplementation of :meth:`sipconfig.Makefile.finalise`.
.. method:: generate_macros_and_rules(mfile)
This is a reimplementation of
:meth:`sipconfig.Makefile.generate_macros_and_rules`.
.. method:: generate_target_clean(mfile)
This is a reimplementation of
:meth:`sipconfig.Makefile.generate_target_clean`.
.. method:: generate_target_default(mfile)
This is a reimplementation of
:meth:`sipconfig.Makefile.generate_target_default`.
.. method:: generate_target_install(mfile)
This is a reimplementation of
:meth:`sipconfig.Makefile.generate_target_install`.
.. class:: PythonModuleMakefile
This class is derived from :class:`sipconfig.Makefile`.
This class encapsulates a Makefile that installs a pure Python module.
.. method:: __init__(self, configuration, dstdir[, srcdir=None[, dir=None[, makefile="Makefile"[, installs=None]]]])
:param configuration:
see :meth:`sipconfig.Makefile.__init__`.
:param dstdir:
the name of the directory in which the module's Python code will be
installed.
:param srcdir:
the name of the directory (relative to *dir*) containing the
module's Python code. It defaults to the same directory.
:param dir:
see :meth:`sipconfig.Makefile.__init__`.
:param makefile:
see :meth:`sipconfig.Makefile.__init__`.
:param installs:
see :meth:`sipconfig.Makefile.__init__`.
.. method:: generate_macros_and_rules(mfile)
This is a reimplementation of
:meth:`sipconfig.Makefile.generate_macros_and_rules`.
.. method:: generate_target_install(mfile)
This is a reimplementation of
:meth:`sipconfig.Makefile.generate_target_install`.
.. class:: SIPModuleMakefile
This class is derived from :class:`sipconfig.ModuleMakefile`.
This class encapsulates a Makefile to build a SIP generated Python
extension module.
.. method:: __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=None[, arch=None[, prot_is_public=0]]]]]]]]]]]]]]])
:param configuration:
see :meth:`sipconfig.Makefile.__init__`.
:param build_file:
see :meth:`sipconfig.ModuleMakefile.__init__`.
:param install_dir:
see :meth:`sipconfig.ModuleMakefile.__init__`.
:param static:
see :meth:`sipconfig.ModuleMakefile.__init__`.
:param console:
see :meth:`sipconfig.Makefile.__init__`.
:param qt:
see :meth:`sipconfig.Makefile.__init__`.
:param opengl:
see :meth:`sipconfig.Makefile.__init__`.
:param threaded:
see :meth:`sipconfig.Makefile.__init__`.
:param warnings:
see :meth:`sipconfig.Makefile.__init__`.
:param debug:
see :meth:`sipconfig.Makefile.__init__`.
:param dir:
see :meth:`sipconfig.Makefile.__init__`.
:param makefile:
see :meth:`sipconfig.Makefile.__init__`.
:param installs:
see :meth:`sipconfig.Makefile.__init__`.
:param strip:
see :meth:`sipconfig.ModuleMakefile.__init__`.
:param export_all:
see :meth:`sipconfig.ModuleMakefile.__init__`.
:param universal:
see :meth:`sipconfig.Makefile.__init__`.
:param arch:
see :meth:`sipconfig.Makefile.__init__`.
:param prot_is_public:
is set if ``protected`` should be redefined as ``public`` when
compiling the generated module.
.. method:: finalise()
This is a reimplementation of :meth:`sipconfig.Makefile.finalise`.

@ -0,0 +1,50 @@
.. _ref-builtin:
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 :class:`sipconfig.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.com/software/vendorid/>`__ package.

File diff suppressed because it is too large Load Diff

@ -0,0 +1,137 @@
.. _ref-command-line:
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:
.. program:: sip
.. cmdoption:: -h
Display a help message.
.. cmdoption:: -V
Display the SIP version number.
.. cmdoption:: -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.
.. cmdoption:: -b <FILE>
The name of the build file to generate. This file contains the information
about the module needed by the :ref:`SIP build system <ref-build-system>`
to generate a platform and compiler specific Makefile for the module. By
default the file is not generated.
.. cmdoption:: -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.
.. cmdoption:: -d <FILE>
The name of the documentation file to generate. Documentation is included
in specification files using the :directive:`%Doc` and
:directive:`%ExportedDoc` directives. By default the file is not
generated.
.. cmdoption:: -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.
.. cmdoption:: -g
The Python GIL is released before making any calls to the C/C++ library
being wrapped and reacquired afterwards. See :ref:`ref-gil` and the
:fanno:`ReleaseGIL` and :fanno:`HoldGIL` annotations.
.. cmdoption:: -I <DIR>
The directory is added to the list of directories searched when looking for
a specification file given in an :directive:`%Include` or
:directive:`%Import` directive. This option may be given any number of
times.
.. cmdoption:: -j <NUMBER>
The generated code is split into the given number of files. This makes 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.
.. cmdoption:: -k
.. versionadded:: 4.10
All functions and methods will, by default, support passing parameters
using the Python keyword argument syntax.
.. cmdoption:: -o
.. versionadded:: 4.10
Docstrings will be automatically generated that describe the signature of
all functions, methods and constructors.
.. cmdoption:: -p <MODULE>
The name of the :directive:`%ConsolidatedModule` which will contain the
wrapper code for this component module.
.. cmdoption:: -P
.. versionadded:: 4.10
By default SIP generates code to provide access to protected C++ functions
from Python. On some platforms (notably Linux, but not Windows) this code
can be avoided if the ``protected`` keyword is redefined as ``public``
during compilation. This can result in a significant reduction in the size
of a generated Python module. This option disables the generation of the
extra code.
.. cmdoption:: -r
Debugging statements that trace the execution of the bindings are
automatically generated. By default the statements are not generated.
.. cmdoption:: -s <SUFFIX>
The suffix to use for generated C or C++ source files. By default ``.c``
is used for C and ``.cpp`` for C++.
.. cmdoption:: -t <TAG>
The SIP version tag (declared using a :directive:`%Timeline` directive) or
the SIP platform tag (declared using the :directive:`%Platforms` directive)
to generate code for. This option may be given any number of times so long
as the tags do not conflict.
.. cmdoption:: -w
The display of warning messages is enabled. By default warning messages
are disabled.
.. cmdoption:: -x <FEATURE>
The feature (declared using the :directive:`%Feature` directive) is
disabled.
.. cmdoption:: -z <FILE>
The name of a file containing more command line options.

File diff suppressed because it is too large Load Diff

@ -0,0 +1,41 @@
.. _ref-distutils:
Building Your Extension with distutils
======================================
To build the example in :ref:`ref-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.
If you want to use any of sip's command-line options described in
:ref:`ref-command-line`, there is a new option available for the
``build_ext`` command in distutils: ``--sip-opts``. So you can either invoke
distutils as follows::
$ python setup.py build_ext --sip-opts="-e -g" build
or you can leverage distutils' config file support by creating a ``setup.cfg``
file in the supported system or local paths (eg: in the same directory of
``setup.py``) with these contents::
[build_ext]
sip-opts = -e -g
and then run ``setup.py build`` as usual.

@ -0,0 +1,62 @@
Using the C API when Embedding
==============================
The :ref:`C API <ref-c-api>` is intended to be called from handwritten code in
SIP generated modules. However it is also often necessary to call it from C or
C++ applications that embed the Python interpreter and need to pass C or C++
instances between the application and the interpreter.
The API is exported by the SIP module as a ``sipAPIDef`` data structure
containing a set of function pointers. The data structure is defined in the
SIP header file ``sip.h``. The data structure is wrapped as a Python
``PyCObject`` object and is referenced by the name ``_C_API`` in the SIP
module dictionary.
Each member of the data structure is a pointer to one of the functions of the
SIP API. The name of the member can be derived from the function name by
replacing the ``sip`` prefix with ``api`` and converting each word in the
name to lower case and preceding it with an underscore. For example:
``sipExportSymbol`` becomes ``api_export_symbol``
``sipWrapperCheck`` becomes ``api_wrapper_check``
Note that the type objects that SIP generates for a wrapped module (see
:ref:`ref-type-structures`, :ref:`ref-enum-type-objects` and
:ref:`ref-exception-objects`) cannot be refered to directly and must be
obtained using the :cfunc:`sipFindType()` function. Of course, the
corresponding modules must already have been imported into the interpreter.
The following code fragment shows how to get a pointer to the ``sipAPIDef``
data structure::
#include <sip.h>
const sipAPIDef *get_sip_api()
{
PyObject *sip_module;
PyObject *sip_module_dict;
PyObject *c_api;
/* Import the SIP module. */
sip_module = PyImport_ImportModule("sip");
if (sip_module == NULL)
return NULL;
/* Get the module's dictionary. */
sip_module_dict = PyModule_GetDict(sip_module);
/* Get the "_C_API" attribute. */
c_api = PyDict_GetItemString(sip_module_dict, "_C_API");
if (c_api == NULL)
return NULL;
/* Sanity check that it is the right type. */
if (!PyCObject_Check(c_api))
return NULL;
/* Get the actual pointer from the object. */
return (const sipAPIDef *)PyCObject_AsVoidPtr(c_api);
}

@ -0,0 +1,198 @@
Potential Incompatibilities with Earlier Versions
=================================================
This section describes incompatibilities introduced by particular versions of
SIP. Normally these are the removal of previously deprecated features.
SIP v4.10.1
-----------
Newly Deprecated Features
*************************
The following parts of the :ref:`C API <ref-c-api>` are now deprecated (but
still supported).
- The ``D`` format character of :cfunc:`sipParseResult()`.
SIP v4.8
--------
__truediv__
***********
Prior to this version the :meth:`__div__` special method implicitly defined the
:meth:`__truediv__` special method. From this version the :meth:`__truediv__`
special method must be explicitly defined.
sipWrapper user Member
**********************
Prior to this version the :ctype:`sipWrapper` structure had a member called
:ctype:`user` which is available for handwritten code to use. From this
version :ctype:`user` is a member of the :ctype:`sipSimpleWrapper` structure.
:ctype:`sipWrapper` pointers can be safely cast to :ctype:`sipSimpleWrapper`
pointers, so if your code does something like::
((sipWrapper *)obj)->user = an_object_reference;
then you just need to change it to::
((sipSimpleWrapper *)obj)->user = an_object_reference;
Removal of Previously Deprecated Features
*****************************************
The following parts of the :ref:`C API <ref-c-api>` have been removed.
- The ``a``, ``A``, ``M``, ``N``, ``O``, ``P`` and ``T`` format characters
from :cfunc:`sipBuildResult()` and :cfunc:`sipCallMethod()`.
- The ``a``, ``A``, ``L`` and ``M`` format characters from
:cfunc:`sipParseResult()`.
- :cfunc:`sipConvertToCpp()`
- :cfunc:`sipIsSubClassInstance()`
- :cfunc:`sipTransfer()`
- The :func:`transfer` function of the :mod:`sip` module.
- The old-style generated type convertors.
In addition the :option:`-a` command line option to :file:`configure.py` has
been removed.
Removal of PyQt-specific Features
*********************************
The following PyQt-specific support functions have been removed.
- :cfunc:`sipConnectRx()`
- :cfunc:`sipDisconnectRx()`
- :cfunc:`sipEmitSlot()`
- :cfunc:`sipGetSender()`
Newly Deprecated Features
*************************
The following parts of the :ref:`C API <ref-c-api>` are now deprecated (but
still supported).
- The :ref:`ref-type-objects`.
- The :ref:`ref-enum-type-objects`.
- :cfunc:`sipConvertFromInstance()`
- :cfunc:`sipConvertFromMappedType()`
- :cfunc:`sipConvertFromNamedEnum()`
- :cfunc:`sipConvertFromNewInstance()`
- :cfunc:`sipCanConvertToInstance()`
- :cfunc:`sipCanConvertToMappedType()`
- :cfunc:`sipConvertToInstance()`
- :cfunc:`sipConvertToMappedType()`
- :cfunc:`sipForceConvertToInstance()`
- :cfunc:`sipForceConvertToMappedType()`
- :cfunc:`sipClassName()`
- :cfunc:`sipFindClass()`
- :cfunc:`sipFindNamedEnum()`
- :cfunc:`sipFindMappedType()`
- :cfunc:`sipGetWrapper()`
- :cfunc:`sipReleaseInstance()`
- :cfunc:`sipReleaseMappedType()`
- :cfunc:`sipWrapper_Check()`
- The ``B``, ``C`` and ``E`` format characters of :cfunc:`sipBuildResult()` and
:cfunc:`sipCallMethod()`.
- The ``s``, ``C`` and ``E`` format characters of :cfunc:`sipParseResult()`.
SIP v4.7.8
----------
Automatic int to Enum Conversions
*********************************
This version allows a Python ``int`` object to be passed whenever an enum is
expected. This can mean that two signatures that were different with prior
versions are now the same as far as Python is concerned.
The :aanno:`Constrained` argument annotation can now be applied to an enum
argument to revert to the earlier behaviour.
SIP v4.7.3
----------
Complementary Comparison Operators
**********************************
Prior to this version SIP did not automatically generate missing complementary
comparison operators. Typically this was worked around by adding them
explicitly to the .sip files, even though they weren't implemented in C++ and
relied on the C++ compiler calling the complementary operator that was
implemented.
A necessary change to the code generator meant that this not longer worked and
so SIP was changed to automatically generate any missing complementary
operators. If you have added such operators explicitly then you should remove
them or make them dependent on the particular version of SIP.
SIP v4.4
--------
%ConvertFromTypeCode and %ConvertToTypeCode
*******************************************
Handwritten :directive:`%ConvertFromTypeCode` and
:directive:`%ConvertToTypeCode` now have the responsibility for implementing
the :aanno:`Transfer` and :aanno:`TransferBack` annotations.
SIP_BUILD
*********
The :cmacro:`SIP_BUILD` C preprocessor symbol has been removed.
Newly Deprecated Features
*************************
The following parts of the :ref:`C API <ref-c-api>` are now deprecated (but
still supported).
- The old-style generated type convertors.
- :cfunc:`sipConvertToCpp()`
- :cfunc:`sipIsSubClassInstance()`

@ -0,0 +1,20 @@
SIP Reference Guide
===================
.. toctree::
:maxdepth: 2
introduction
incompatibilities
installation
using
command_line
specification_files
directives
annotations
c_api
embedding
python_api
build_system
distutils
builtin

@ -0,0 +1,169 @@
Installation
============
Downloading
-----------
You can get the latest release of the SIP source code from
http://www.riverbankcomputing.com/software/sip/download.
SIP is also included with all of the major Linux distributions. However, it
may be a version or two out of date.
Configuring
-----------
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:\python26\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:
.. program:: configure.py
.. cmdoption:: --version
Display the SIP version number.
.. cmdoption:: -h, --help
Display a help message.
.. cmdoption:: --arch <ARCH>
Binaries for the MacOS/X architecture ``<ARCH>`` will be built. This
option should be given once for each architecture to be built. Specifying
more than one architecture will cause a universal binary to be created.
.. cmdoption:: -b <DIR>, --bindir <DIR>
The SIP code generator will be installed in the directory ``<DIR>``.
.. cmdoption:: -d <DIR>, --destdir <DIR>
The SIP module will be installed in the directory ``<DIR>``.
.. cmdoption:: -e <DIR>, --incdir <DIR>
The SIP header file will be installed in the directory ``<DIR>``.
.. cmdoption:: -k, --static
The SIP module will be built as a static library. This is useful when
building the SIP module as a Python builtin (see :ref:`ref-builtin`).
.. cmdoption:: -n, --universal
The SIP code generator and module will be built as universal binaries
under MacOS/X. If the :option:`--arch <configure.py --arch>` option has
not been specified then the universal binary will include the ``i386`` and
``ppc`` architectures.
.. cmdoption:: -p <PLATFORM>, --platform <PLATFORM>
Explicitly specify the platform/compiler to be used by the build system,
otherwise a platform specific default will be used. The
:option:`--show-platforms <configure.py --show-platforms>` option will
display all the supported platform/compilers.
.. cmdoption:: -s <SDK>, --sdk <SDK>
If the :option:`--universal <configure.py -n>` option was given then this
specifies the name of the SDK directory. If a path is not given then it is
assumed to be a sub-directory of ``/Developer/SDKs``.
.. cmdoption:: -u, --debug
The SIP module will be built with debugging symbols.
.. cmdoption:: -v <DIR>, --sipdir <DIR>
By default ``.sip`` files will be installed in the directory ``<DIR>``.
.. cmdoption:: --show-platforms
The list of all supported platform/compilers will be displayed.
.. cmdoption:: --show-build-macros
The list of all available build macros will be displayed.
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 :option:`--show-build-macros <configure.py
--show-build-macros>` 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 :ref:`ref-build-system`.
Configuring for MinGW
*********************
SIP, and the modules it generates, can be built with MinGW, the Windows port of
GCC. You must use the :option:`--platform <configure.py -p>` command line
option to specify the correct platform. For example::
c:\python26\python configure.py --platform win32-g++
Configuring for the Borland C++ Compiler
****************************************
SIP, and the modules it generates, can be built with the free Borland C++
compiler. You must use the :option:`--platform <configure.py -p>` command line
option to specify the correct platform. For example::
c:\python26\python configure.py --platform 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 python26.lib python26_bcpp.lib
Building
--------
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.

@ -0,0 +1,169 @@
Introduction
============
This is the reference guide for SIP 4.10.5. 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.com/software/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, including
Python v3.
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.com/software/sip. Here
you will always find the latest stable version and the latest version of this
documentation.
SIP can also be downloaded from the
`Mercurial <http://mercurial.selenic.com/>`__ repository at
http://www.riverbankcomputing.com/hg/sip.
License
-------
SIP is licensed under similar terms as Python itself. SIP is also licensed
under the GPL (both v2 and v3). It is your choice as to which license you
use. If you choose the GPL then any bindings you create must be distributed
under the terms of the GPL.
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
- support for Python's keyword argument syntax
- support for both explicitly specified and automatically generated docstrings
- 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 :meth:`__dtor__` 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 automatic generation of complementary rich comparison slots
- support for deprecation warnings
- 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
- the ability to change the type and meta-type of the Python object used to
wrap a C/C++ data type
- 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 consolidated modules where the generated wrapper code for a
number of related modules may be included in a single, possibly private,
module
- 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 (:program:`sip`). This processes :file:`.sip`
specification files and generates C or C++ bindings. It is covered in detail
in :ref:`ref-using`.
- The SIP header file (:file:`sip.h`). This contains definitions and data
structures needed by the generated C and C++ code.
- The SIP module (:file:`sip.so` or :file:`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
:ref:`ref-python-api`.
- The SIP build system (:file:`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 :ref:`ref-build-system`.
- The SIP distutils extension (:file:`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
:ref:`ref-distutils`.
Qt Support
----------
SIP has specific support for the creation of bindings based on Nokia'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.

@ -0,0 +1,282 @@
.. _ref-python-api:
Python API for Applications
===========================
.. module:: sip
The main purpose of the :mod:`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.
.. function:: cast(obj, type) -> object
This does the Python equivalent of casting a C++ instance to one of its
sub or super-class types.
:param obj:
the Python object.
:param type:
the type.
:return:
a new Python object is that wraps the same C++ instance as *obj*, but
has the type *type*.
.. function:: delete(obj)
For C++ instances this calls the C++ destructor. For C structures it
returns the structure's memory to the heap.
:param obj:
the Python object.
.. function:: dump(obj)
This displays various bits of useful information about the internal state
of the Python object that wraps a C++ instance or C structure.
:param obj:
the Python object.
.. function:: getapi(name) -> version
.. versionadded:: 4.9
This returns the version number that has been set for an API. The version
number is either set explicitly by a call to :func:`sip.setapi` or
implicitly by importing the module that defines it.
:param name:
the name of the API.
:return:
The version number that has been set for the API. An exception will
be raised if the API is unknown.
.. function:: isdeleted(obj) -> bool
This checks if the C++ instance or C structure has been deleted and
returned to the heap.
:param obj:
the Python object.
:return:
``True`` if the C/C++ instance has been deleted.
.. function:: ispyowned(obj) -> bool
This checks if the C++ instance or C structure is owned by Python.
:param obj:
the Python object.
:return:
``True`` if the C/C++ instance is owned by Python.
.. function:: setapi(name, version)
.. versionadded:: 4.9
This sets the version number of an API. An exception is raised if a
different version number has already been set, either explicitly by a
previous call, or implicitly by importing the module that defines it.
:param name:
the name of the API.
:param version:
The version number to set for the API. Version numbers must be
greater than or equal to 1.
.. function:: setdeleted(obj)
This marks the C++ instance or C structure as having been deleted and
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 may be circumstances where this isn't possible.
:param obj:
the Python object.
.. function:: settracemask(mask)
If the bindings have been created with SIP's :option:`-r <sip -r>` command
line option then the generated code will include 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.)
:param mask:
the mask that determines which debugging statements are enabled.
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.
.. data:: 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.
.. data:: 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.
.. function:: transferback(obj)
This function is a wrapper around :cfunc:`sipTransferBack()`.
.. function:: transferto(obj, owner)
This function is a wrapper around :cfunc:`sipTransferTo()`.
.. function:: unwrapinstance(obj) -> integer
This returns the address, as an integer, of a wrapped C/C++ structure or
class instance.
:param obj:
the Python object.
:return:
an integer that is the address of the C/C++ instance.
.. class:: voidptr
This is the type object for the type SIP uses to represent a C/C++
``void *``. It may have a size associated with the address in which case
the Python buffer protocol is supported. This means that the memory can
be treated as a mutable array of bytes when wrapped with the ``buffer()``
builtin. The type has the following methods.
.. method:: __init__(address[, size=-1[, writeable=True]])
:param address:
the address, either another :class:`sip.voidptr`, ``None``, a
Python Capsule, a Python CObject, or an integer.
:param size:
the optional associated size of the block of memory and is negative
if the size is not known.
:param writeable:
set if the memory is writeable. If it is not specified, and
*address* is a :class:`sip.voidptr` instance then its value will be
used.
.. method:: __int__() -> integer
This returns the address as an integer.
:return:
the integer address.
.. method:: __hex__() -> string
This returns the address as a hexadecimal string.
:return:
the hexadecimal string address.
.. method:: ascapsule() -> capsule
.. versionadded:: 4.10
This returns the address as an unnamed Python Capsule. This requires
Python v3.1 or later or Python v2.7 or later.
:return:
the Capsule.
.. method:: ascobject() -> cObject
This returns the address as a Python CObject. This is deprecated with
Python v3.1 or later.
:return:
the CObject.
.. method:: asstring([size=-1]) -> string/bytes
This returns a copy of the block of memory as a Python v2 string object
or a Python v3 bytes object.
:param size:
the number of bytes to copy. If it is negative then the size
associated with the address is used. If there is no associated
size then an exception is raised.
:return:
the string or bytes object.
.. method:: getsize() -> integer
This returns the size associated with the address.
:return:
the associated size which will be negative if there is none.
.. method:: setsize(size)
This sets the size associated with the address.
:param size:
the size to associate. If it is negative then no size is
associated.
.. method:: getwriteable() -> bool
This returns the writeable state of the memory.
:return:
``True`` if the memory is writeable.
.. method:: setwriteable(writeable)
This sets the writeable state of the memory.
:param writeable:
the writeable state to set.
.. function:: wrapinstance(addr, type) -> object
This wraps a C structure or C++ class instance in a Python object. If the
instance has already been wrapped then a new reference to the existing
object is returned.
:param addr:
the address of the instance as a number.
:param type:
the Python type of the instance.
:return:
the Python object that wraps the instance.
.. class:: wrapper
This is the type object of the base type of all instances wrapped by SIP.
.. class:: wrappertype
This is the type object of the metatype of the :class:`sip.wrapper` type.

@ -0,0 +1,499 @@
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 :directive:`%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
:ref:`ref-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* ::= [
:directive:`%API` |
:directive:`%CModule` |
:directive:`%CompositeModule` |
:directive:`%ConsolidatedModule` |
:directive:`%Copying` |
:directive:`%DefaultEncoding` |
:directive:`%DefaultMetatype` |
:directive:`%DefaultSupertype` |
:directive:`%Doc` |
:directive:`%ExportedDoc` |
:directive:`%ExportedHeaderCode` |
:directive:`%Feature` |
:directive:`%Import` |
:directive:`%Include` |
:directive:`%InitialisationCode` |
:directive:`%License` |
:directive:`%MappedType` |
:directive:`%Module` |
:directive:`%ModuleCode` |
:directive:`%ModuleHeaderCode` |
:directive:`%OptionalInclude` |
:directive:`%Platforms` |
:directive:`%PreInitialisationCode` |
:directive:`%PostInitialisationCode` |
:directive:`%Timeline` |
:directive:`%UnitCode` |
*mapped-type-template*]
*statement* :: [*class-statement* | *function* | *variable*]
*class-statement* :: [
:directive:`%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* |
:directive:`%BIGetBufferCode` |
:directive:`%BIGetReadBufferCode` |
:directive:`%BIGetWriteBufferCode` |
:directive:`%BIGetSegCountCode` |
:directive:`%BIGetCharBufferCode` |
:directive:`%BIReleaseBufferCode` |
:directive:`%ConvertToSubClassCode` |
:directive:`%ConvertToTypeCode` |
:directive:`%Docstring` |
:directive:`%GCClearCode` |
:directive:`%GCTraverseCode` |
:directive:`%PickleCode` |
:directive:`%TypeCode` |
:directive:`%TypeHeaderCode` |
*constructor* |
*destructor* |
*method* |
*static-method* |
*virtual-method* |
*special-method* |
*operator* |
*virtual-operator* |
*class-variable* |
**public:** |
**public Q_SLOTS:** |
**public slots:** |
**protected:** |
**protected Q_SLOTS:** |
**protected slots:** |
**private:** |
**private Q_SLOTS:** |
**private slots:** |
**Q_SIGNALS:** |
**signals:**]
*constructor* ::= [**explicit**] *name* **(** [*argument-list*] **)**
[*exceptions*] [*function-annotations*]
[*c++-constructor-signature*] **;** [:directive:`%Docstring`]
[:directive:`%MethodCode`]
*c++-constructor-signature* ::= **[(** [*argument-list*] **)]**
*destructor* ::= [**virtual**] **~** *name* **()** [*exceptions*] [**= 0**]
[*function-annotations*] **;** [:directive:`%MethodCode`]
[:directive:`%VirtualCatcherCode`]
*method* ::= [**Q_SIGNAL**] [**Q_SLOT**] *type* *name* **(**
[*argument-list*] **)** [**const**] [*exceptions*] [**= 0**]
[*function-annotations*] [*c++-signature*] **;**
[:directive:`%Docstring`] [:directive:`%MethodCode`]
*c++-signature* ::= **[** *type* **(** [*argument-list*] **)]**
*static-method* ::= **static** *function*
*virtual-method* ::= [**Q_SIGNAL**] [**Q_SLOT**] **virtual** *type* *name*
**(** [*argument-list*] **)** [**const**] [*exceptions*] [**= 0**]
[*function-annotations*] [*c++-signature*] **;**
[:directive:`%MethodCode`] [:directive:`%VirtualCatcherCode`]
*special-method* ::= *type* *special-method-name*
**(** [*argument-list*] **)** [*function-annotations*] **;**
[:directive:`%MethodCode`]
*special-method-name* ::= [**__abs__** | **__add__** | **__and__** |
**__bool__** | **__call__** | **__cmp__** | **__contains__** |
**__delitem__** | **__div__** | **__eq__** | **__float__** |
**__floordiv__** | **__ge__** | **__getitem__** | **__gt__** |
**__hash__** | **__iadd__** | **__iand__** | **__idiv__** |
**__ifloordiv__** | **__ilshift__** | **__imod__** | **__imul__** |
**__index__** | **__int__** | **__invert__** | **__ior__** |
**__irshift__** | **__isub__** | **__iter__** | **__itruediv__** |
**__ixor__** | **__le__** | **__len__** | **__long__** |
**__lshift__** | **__lt__** | **__mod__** | **__mul__** |
**__ne__** | **__neg__** | **__next__** | **__nonzero__** |
**__or__** | **__pos__** | **__repr__** | **__rshift__** |
**__setitem__** | **__str__** | **__sub__** | **__truediv__** |
**__xor__**]
*operator* ::= *operator-type*
**(** [*argument-list*] **)** [**const**] [*exceptions*]
[*function-annotations*] **;** [:directive:`%MethodCode`]
*virtual-operator* ::= **virtual** *operator-type*
**(** [*argument-list*] **)** [**const**] [*exceptions*] [**= 0**]
[*function-annotations*] **;** [:directive:`%MethodCode`]
[:directive:`%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* **>**
:directive:`%MappedType`
*enum* ::= **enum** [*name*] [*enum-annotations*] **{** {*enum-line*} **};**
*enum-line* ::= [:directive:`%If` | *name* [*enum-annotations*] **,**
*function* ::= *type* *name* **(** [*argument-list*] **)** [*exceptions*]
[*function-annotations*] **;** [:directive:`%Docstring`]
[:directive:`%MethodCode`]
*namespace* ::= **namespace** *name* **{** {*namespace-line*} **};**
*namespace-line* ::= [:directive:`%TypeHeaderCode` | *statement*]
*opaque-class* ::= **class** *scoped-name* **;**
*struct* ::= **struct** *name* **{** {*class-line*} **};**
*typedef* ::= **typedef** [*typed-name* | *function-pointer*]
*typedef-annotations* **;**
*variable*::= *typed-name* [*variable-annotations*] **;**
[:directive:`%AccessCode`] [:directive:`%GetCode`]
[:directive:`%SetCode`]
*exception* ::= :directive:`%Exception` *exception-name* [*exception-base*]
**{** [:directive:`%TypeHeaderCode`] :directive:`%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*] |
:stype:`SIP_ANYSLOT` [*default-value*] |
:stype:`SIP_QOBJECT` |
:stype:`SIP_RXOBJ_CON` |
:stype:`SIP_RXOBJ_DIS` |
:stype:`SIP_SIGNAL` [*default-value*] |
:stype:`SIP_SLOT` [*default-value*] |
:stype:`SIP_SLOT_CON` |
:stype:`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 :ref:`ref-arg-annos`
*class-annotations* ::= see :ref:`ref-class-annos`
*enum-annotations* ::= see :ref:`ref-enum-annos`
*function-annotations* ::= see :ref:`ref-function-annos`
*typedef-annotations* ::= see :ref:`ref-typedef-annos`
*variable-annotations* ::= see :ref:`ref-variable-annos`
*type* ::= [**const**] *base-type* {*****} [**&**]
*type-list* ::= *type* [**,** *type-list*]
*base-type* ::= [*scoped-name* | *template* | **struct** *scoped-name* |
**char** | **signed char** | **unsigned char** | **wchar_t** |
**int** | **unsigned** | **unsigned int** |
**short** | **unsigned short** |
**long** | **unsigned long** |
**long long** | **unsigned long long** |
**float** | **double** |
**bool** |
**void** |
:stype:`SIP_PYCALLABLE` |
:stype:`SIP_PYDICT` |
:stype:`SIP_PYLIST` |
:stype:`SIP_PYOBJECT` |
:stype:`SIP_PYSLICE` |
:stype:`SIP_PYTUPLE` |
:stype:`SIP_PYTYPE`]
*scoped-name* ::= *name* [**::** *scoped-name*]
*template* ::= *scoped-name* **<** *type-list* **>**
*dotted-name* ::= *name* [**.** *dotted-name*]
*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-type:: 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-type:: SIP_PYCALLABLE
This is a ``PyObject *`` that is a Python callable object.
.. sip-type:: SIP_PYDICT
This is a ``PyObject *`` that is a Python dictionary object.
.. sip-type:: SIP_PYLIST
This is a ``PyObject *`` that is a Python list object.
.. sip-type:: SIP_PYOBJECT
This is a ``PyObject *`` of any Python type.
.. sip-type:: SIP_PYSLICE
This is a ``PyObject *`` that is a Python slice object.
.. sip-type:: SIP_PYTUPLE
This is a ``PyObject *`` that is a Python tuple object.
.. sip-type:: SIP_PYTYPE
This is a ``PyObject *`` that is a Python type object.
.. sip-type:: SIP_QOBJECT
This is a ``QObject *`` that is a C++ instance of a class derived from Qt's
``QObject`` class.
.. sip-type:: 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-type:: 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-type:: 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-type:: 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-type:: 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-type:: 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.
Classic Division and True Division
----------------------------------
SIP supports the ``__div__`` and ``__truediv__`` special methods (and the
corresponding inplace versions) for both Python v2 and v3.
For Python v2 the ``__div__`` method will be used for both classic and true
division if a ``__truediv__`` method is not defined.
For Python v3 the ``__div__`` method will be used for true division if a
``__truediv__`` method is not defined.
For all versions of Python, if both methods are defined then ``__div__``
should be defined first.

@ -0,0 +1,662 @@
.. _ref-using:
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.
.. _ref-simple-c++-example:
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 :directive:`%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 :directive:`%TypeHeaderCode` directive has been added. The text
between this and the following :directive:`%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
:ref:`SIP build system <ref-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 :ref:`ref-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 :directive:`%CModule` directive has been added. This has the same
syntax as the :directive:`%Module` directive used in the previous example
but tells SIP that the library being wrapped is implemented in C rather
than C++.
- The :directive:`%TypeHeaderCode` directive has been added.
- The :fanno:`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 v4.2 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 = 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 QtGui/QtGuimod.sip
%If (Qt_4_2_0 -)
class Hello : QLabel {
%TypeHeaderCode
#include <hello.h>
%End
public:
Hello(QWidget *parent /TransferThis/ = 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 :directive:`%Import` directive has been added to specify that we are
extending the class hierarchy defined in the file ``QtGui/QtGuimod.sip``.
This file is part of PyQt. The build system will take care of finding
the file's exact location.
- The :directive:`%If` directive has been added to specify that everything
[#]_ up to the matching :directive:`%End` directive only applies to Qt
v4.2 and later. ``Qt_4_2_0`` is a *tag* defined in ``QtCoremod.sip``
[#]_ using the :directive:`%Timeline` directive. :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 :aanno:`TransferThis` annotation has been added to the constructor's
argument. 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 :ref:`ref-object-ownership`. 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 :directive:`%If` directive has been added to specify that everything
up to the matching :directive:`%End` directive does not apply to Windows.
``WS_WIN`` is another tag defined by PyQt, this time using the
:directive:`%Platforms` directive. Tags defined by the
:directive:`%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
from PyQt4 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 PyQt modules. Note that
# this normally only includes those flags (-x and -t) that relate to SIP's
# versioning system.
pyqt_sip_flags = config.pyqt_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, pyqt_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 QtGuiModuleMakefile class provided by the
# pyqtconfig module takes care of all the extra preprocessor, compiler and
# linker flags needed by the Qt library.
makefile = pyqtconfig.QtGuiModuleMakefile(
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": pyqt_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::
from PyQt4 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.QtGuiModuleMakefile):
"""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.QtGuiModuleMakefile.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 :directive:`%Include`
directive to split the SIP specification for Qt across a large number of
separate ``.sip`` files.
.. [#] Tags can also be defined by the :directive:`%Feature` directive. These
tags are not mutually exclusive, i.e. any number may be valid at a time.
.. _ref-object-ownership:
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 :cfunc:`sipTransferTo()`, :cfunc:`sipTransferBack()` and
:cfunc:`sipTransferBreak()`.
.. _ref-types-metatypes:
Types and Meta-types
--------------------
Every Python object (with the exception of the :class:`object` object itself)
has a meta-type and at least one super-type. By default an object's meta-type
is the meta-type of its first super-type.
SIP implements two super-types, :class:`sip.simplewrapper` and
:class:`sip.wrapper`, and a meta-type, :class:`sip.wrappertype`.
:class:`sip.simplewrapper` is the super-type of :class:`sip.wrapper`. The
super-type of :class:`sip.simplewrapper` is :class:`object`.
:class:`sip.wrappertype` is the meta-type of both :class:`sip.simplewrapper`
and :class:`sip.wrapper`. The super-type of :class:`sip.wrappertype` is
:class:`type`.
:class:`sip.wrapper` supports the concept of object ownership described in
:ref:`ref-object-ownership` and, by default, is the super-type of all the types
that SIP generates.
:class:`sip.simplewrapper` does not support the concept of object ownership but
SIP generated types that are sub-classed from it have Python objects that take
less memory.
SIP allows a class's meta-type and super-type to be explicitly specified using
the :canno:`Metatype` and :canno:`Supertype` class annotations.
SIP also allows the default meta-type and super-type to be changed for a module
using the :directive:`%DefaultMetatype` and :directive:`%DefaultSupertype`
directives. Unlike the default super-type, the default meta-type is inherited
by importing modules.
If you want to use your own meta-type or super-type then they must be
sub-classed from one of the SIP provided types. Your types must be registered
using :cfunc:`sipRegisterPyType()`. This is normally done in code specified
using the :directive:`%InitialisationCode` directive.
As an example, PyQt4 uses :directive:`%DefaultMetatype` to specify a new
meta-type that handles the interaction with Qt's own meta-type system. It also
uses :directive:`%DefaultSupertype` to specify that the smaller
:class:`sip.simplewrapper` super-type is normally used. Finally it uses
:canno:`Supertype` as an annotation of the ``QObject`` class to override the
default and use :class:`sip.wrapper` as the super-type so that the parent/child
relationships of ``QObject`` instances are properly maintained.
.. _ref-lazy-type-attributes:
Lazy Type Attributes
--------------------
Instead of populating a wrapped type's dictionary with its attributes (or
descriptors for those attributes) SIP only creates objects for those attributes
when they are actually needed. This is done to reduce the memory footprint and
start up time when used to wrap large libraries with hundreds of classes and
tens of thousands of attributes.
SIP allows you to extend the handling of lazy attributes to your own attribute
types by allowing you to register an attribute getter handler (using
:cfunc:`sipRegisterAttributeGetter()`). This will be called just before a
type's dictionary is accessed for the first time.
Support for Python's Buffer Interface
-------------------------------------
SIP supports Python's buffer interface in that whenever C/C++ requires a
``char`` or ``char *`` type then any Python type that supports the buffer
interface (including ordinary Python strings) can be used.
If a buffer is made up of a number of segments then all but the first will be
ignored.
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 :cfunc:`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 :cfunc:`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.
.. _ref-gil:
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 :fanno:`ReleaseGIL` annotation can be used to
override this behaviour when required.
If SIP is given the :option:`-g <sip -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 :fanno:`HoldGIL` annotation can be used to
override this behaviour when required.
.. _ref-incompat-apis:
Managing Incompatible APIs
--------------------------
.. versionadded:: 4.9
Sometimes it is necessary to change the way something is wrapped in a way that
introduces an incompatibility. For example a new feature of Python may
suggest that something may be wrapped in a different way to exploit that
feature.
SIP's :directive:`%Feature` directive could be used to provide two different
implementations. However this would mean that the choice between the two
implementations would have to be made when building the generated module
potentially causing all sorts of deployment problems. It may also require
applications to work out which implementation was available and to change
their behaviour accordingly.
Instead SIP provides limited support for providing multiple implementations
(of classes, mapped types and functions) that can be selected by an
application at run-time. It is then up to the application developer how they
want to manage the migration from the old API to the new, incompatible API.
This support is implemented in three parts.
Firstly the :directive:`%API` directive is used to define the name of an API
and its default version number. The default version number is the one used if
an application doesn't explicitly set the version number to use.
Secondly the :canno:`API class <API>`, :manno:`mapped type <API>` or
:fanno:`function <API>` annotation is applied accordingly to specify the API
and range of version numbers that a particular class, mapped type or function
implementation should be enabled for.
Finally the application calls :func:`sip.setapi` to specify the version number
of the API that should be enabled. This call must be made before any module
that has multiple implementations is imported for the first time.
Note this mechanism is not intended as a way or providing equally valid
alternative APIs. For example::
%API MyAPI 1
class Foo
{
public:
void bar();
};
class Baz : Foo
{
public:
void bar() /API=MyAPI:2-/;
};
If the following Python code is executed then an exception will be raised::
b = Baz()
b.bar()
This is because when version 1 of the *MyAPI* API (the default) is enabled
there is no *Baz.bar()* implementation and *Foo.bar()* will not be called
instead as might be expected.

@ -0,0 +1,417 @@
/**
* Sphinx stylesheet -- basic theme
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*/
/* -- main layout ----------------------------------------------------------- */
div.clearer {
clear: both;
}
/* -- relbar ---------------------------------------------------------------- */
div.related {
width: 100%;
font-size: 90%;
}
div.related h3 {
display: none;
}
div.related ul {
margin: 0;
padding: 0 0 0 10px;
list-style: none;
}
div.related li {
display: inline;
}
div.related li.right {
float: right;
margin-right: 5px;
}
/* -- sidebar --------------------------------------------------------------- */
div.sphinxsidebarwrapper {
padding: 10px 5px 0 10px;
}
div.sphinxsidebar {
float: left;
width: 230px;
margin-left: -100%;
font-size: 90%;
}
div.sphinxsidebar ul {
list-style: none;
}
div.sphinxsidebar ul ul,
div.sphinxsidebar ul.want-points {
margin-left: 20px;
list-style: square;
}
div.sphinxsidebar ul ul {
margin-top: 0;
margin-bottom: 0;
}
div.sphinxsidebar form {
margin-top: 10px;
}
div.sphinxsidebar input {
border: 1px solid #98dbcc;
font-family: sans-serif;
font-size: 1em;
}
img {
border: 0;
}
/* -- search page ----------------------------------------------------------- */
ul.search {
margin: 10px 0 0 20px;
padding: 0;
}
ul.search li {
padding: 5px 0 5px 20px;
background-image: url(file.png);
background-repeat: no-repeat;
background-position: 0 7px;
}
ul.search li a {
font-weight: bold;
}
ul.search li div.context {
color: #888;
margin: 2px 0 0 30px;
text-align: left;
}
ul.keywordmatches li.goodmatch a {
font-weight: bold;
}
/* -- index page ------------------------------------------------------------ */
table.contentstable {
width: 90%;
}
table.contentstable p.biglink {
line-height: 150%;
}
a.biglink {
font-size: 1.3em;
}
span.linkdescr {
font-style: italic;
padding-top: 5px;
font-size: 90%;
}
/* -- general index --------------------------------------------------------- */
table.indextable td {
text-align: left;
vertical-align: top;
}
table.indextable dl, table.indextable dd {
margin-top: 0;
margin-bottom: 0;
}
table.indextable tr.pcap {
height: 10px;
}
table.indextable tr.cap {
margin-top: 10px;
background-color: #f2f2f2;
}
img.toggler {
margin-right: 3px;
margin-top: 3px;
cursor: pointer;
}
/* -- general body styles --------------------------------------------------- */
a.headerlink {
visibility: hidden;
}
h1:hover > a.headerlink,
h2:hover > a.headerlink,
h3:hover > a.headerlink,
h4:hover > a.headerlink,
h5:hover > a.headerlink,
h6:hover > a.headerlink,
dt:hover > a.headerlink {
visibility: visible;
}
div.body p.caption {
text-align: inherit;
}
div.body td {
text-align: left;
}
.field-list ul {
padding-left: 1em;
}
.first {
margin-top: 0 !important;
}
p.rubric {
margin-top: 30px;
font-weight: bold;
}
/* -- sidebars -------------------------------------------------------------- */
div.sidebar {
margin: 0 0 0.5em 1em;
border: 1px solid #ddb;
padding: 7px 7px 0 7px;
background-color: #ffe;
width: 40%;
float: right;
}
p.sidebar-title {
font-weight: bold;
}
/* -- topics ---------------------------------------------------------------- */
div.topic {
border: 1px solid #ccc;
padding: 7px 7px 0 7px;
margin: 10px 0 10px 0;
}
p.topic-title {
font-size: 1.1em;
font-weight: bold;
margin-top: 10px;
}
/* -- admonitions ----------------------------------------------------------- */
div.admonition {
margin-top: 10px;
margin-bottom: 10px;
padding: 7px;
}
div.admonition dt {
font-weight: bold;
}
div.admonition dl {
margin-bottom: 0;
}
p.admonition-title {
margin: 0px 10px 5px 0px;
font-weight: bold;
}
div.body p.centered {
text-align: center;
margin-top: 25px;
}
/* -- tables ---------------------------------------------------------------- */
table.docutils {
border: 0;
border-collapse: collapse;
}
table.docutils td, table.docutils th {
padding: 1px 8px 1px 0;
border-top: 0;
border-left: 0;
border-right: 0;
border-bottom: 1px solid #aaa;
}
table.field-list td, table.field-list th {
border: 0 !important;
}
table.footnote td, table.footnote th {
border: 0 !important;
}
th {
text-align: left;
padding-right: 5px;
}
/* -- other body styles ----------------------------------------------------- */
dl {
margin-bottom: 15px;
}
dd p {
margin-top: 0px;
}
dd ul, dd table {
margin-bottom: 10px;
}
dd {
margin-top: 3px;
margin-bottom: 10px;
margin-left: 30px;
}
dt:target, .highlight {
background-color: #fbe54e;
}
dl.glossary dt {
font-weight: bold;
font-size: 1.1em;
}
.field-list ul {
margin: 0;
padding-left: 1em;
}
.field-list p {
margin: 0;
}
.refcount {
color: #060;
}
.optional {
font-size: 1.3em;
}
.versionmodified {
font-style: italic;
}
.system-message {
background-color: #fda;
padding: 5px;
border: 3px solid red;
}
.footnote:target {
background-color: #ffa
}
.line-block {
display: block;
margin-top: 1em;
margin-bottom: 1em;
}
.line-block .line-block {
margin-top: 0;
margin-bottom: 0;
margin-left: 1.5em;
}
/* -- code displays --------------------------------------------------------- */
pre {
overflow: auto;
}
td.linenos pre {
padding: 5px 0px;
border: 0;
background-color: transparent;
color: #aaa;
}
table.highlighttable {
margin-left: 0.5em;
}
table.highlighttable td {
padding: 0 0.5em 0 0.5em;
}
tt.descname {
background-color: transparent;
font-weight: bold;
font-size: 1.2em;
}
tt.descclassname {
background-color: transparent;
}
tt.xref, a tt {
background-color: transparent;
font-weight: bold;
}
h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
background-color: transparent;
}
/* -- math display ---------------------------------------------------------- */
img.math {
vertical-align: middle;
}
div.body div.math p {
text-align: center;
}
span.eqno {
float: right;
}
/* -- printout stylesheet --------------------------------------------------- */
@media print {
div.document,
div.documentwrapper,
div.bodywrapper {
margin: 0 !important;
width: 100%;
}
div.sphinxsidebar,
div.related,
div.footer,
#top-link {
display: none;
}
}

@ -0,0 +1,218 @@
/**
* Sphinx stylesheet -- default theme
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*/
@import url("basic.css");
/* -- page layout ----------------------------------------------------------- */
body {
font-family: sans-serif;
font-size: 100%;
background-color: #11303d;
color: #000;
margin: 0;
padding: 0;
}
div.document {
background-color: #1c4e63;
}
div.documentwrapper {
float: left;
width: 100%;
}
div.bodywrapper {
margin: 0 0 0 230px;
}
div.body {
background-color: #ffffff;
color: #000000;
padding: 0 20px 30px 20px;
}
div.footer {
color: #ffffff;
width: 100%;
padding: 9px 0 9px 0;
text-align: center;
font-size: 75%;
}
div.footer a {
color: #ffffff;
text-decoration: underline;
}
div.related {
background-color: #133f52;
line-height: 30px;
color: #ffffff;
}
div.related a {
color: #ffffff;
}
div.sphinxsidebar {
}
div.sphinxsidebar h3 {
font-family: 'Trebuchet MS', sans-serif;
color: #ffffff;
font-size: 1.4em;
font-weight: normal;
margin: 0;
padding: 0;
}
div.sphinxsidebar h3 a {
color: #ffffff;
}
div.sphinxsidebar h4 {
font-family: 'Trebuchet MS', sans-serif;
color: #ffffff;
font-size: 1.3em;
font-weight: normal;
margin: 5px 0 0 0;
padding: 0;
}
div.sphinxsidebar p {
color: #ffffff;
}
div.sphinxsidebar p.topless {
margin: 5px 10px 10px 10px;
}
div.sphinxsidebar ul {
margin: 10px;
padding: 0;
color: #ffffff;
}
div.sphinxsidebar a {
color: #98dbcc;
}
div.sphinxsidebar input {
border: 1px solid #98dbcc;
font-family: sans-serif;
font-size: 1em;
}
/* -- body styles ----------------------------------------------------------- */
a {
color: #355f7c;
text-decoration: none;
}
a:hover {
text-decoration: underline;
}
div.body p, div.body dd, div.body li {
text-align: justify;
line-height: 130%;
}
div.body h1,
div.body h2,
div.body h3,
div.body h4,
div.body h5,
div.body h6 {
font-family: 'Trebuchet MS', sans-serif;
background-color: #f2f2f2;
font-weight: normal;
color: #20435c;
border-bottom: 1px solid #ccc;
margin: 20px -20px 10px -20px;
padding: 3px 0 3px 10px;
}
div.body h1 { margin-top: 0; font-size: 200%; }
div.body h2 { font-size: 160%; }
div.body h3 { font-size: 140%; }
div.body h4 { font-size: 120%; }
div.body h5 { font-size: 110%; }
div.body h6 { font-size: 100%; }
a.headerlink {
color: #c60f0f;
font-size: 0.8em;
padding: 0 4px 0 4px;
text-decoration: none;
}
a.headerlink:hover {
background-color: #c60f0f;
color: white;
}
div.body p, div.body dd, div.body li {
text-align: justify;
line-height: 130%;
}
div.admonition p.admonition-title + p {
display: inline;
}
div.note {
background-color: #eee;
border: 1px solid #ccc;
}
div.seealso {
background-color: #ffc;
border: 1px solid #ff6;
}
div.topic {
background-color: #eee;
}
div.warning {
background-color: #ffe4e4;
border: 1px solid #f66;
}
p.admonition-title {
display: inline;
}
p.admonition-title:after {
content: ":";
}
pre {
padding: 5px;
background-color: #eeffcc;
color: #333333;
line-height: 120%;
border: 1px solid #ac9;
border-left: none;
border-right: none;
}
tt {
background-color: #ecf0f3;
padding: 0 1px 0 1px;
font-size: 0.95em;
}
.warning tt {
background: #efc2c2;
}
.note tt {
background: #d6d6d6;
}

@ -0,0 +1,232 @@
/// XXX: make it cross browser
/**
* make the code below compatible with browsers without
* an installed firebug like debugger
*/
if (!window.console || !console.firebug) {
var names = ["log", "debug", "info", "warn", "error", "assert", "dir", "dirxml",
"group", "groupEnd", "time", "timeEnd", "count", "trace", "profile", "profileEnd"];
window.console = {};
for (var i = 0; i < names.length; ++i)
window.console[names[i]] = function() {}
}
/**
* small helper function to urldecode strings
*/
jQuery.urldecode = function(x) {
return decodeURIComponent(x).replace(/\+/g, ' ');
}
/**
* small helper function to urlencode strings
*/
jQuery.urlencode = encodeURIComponent;
/**
* This function returns the parsed url parameters of the
* current request. Multiple values per key are supported,
* it will always return arrays of strings for the value parts.
*/
jQuery.getQueryParameters = function(s) {
if (typeof s == 'undefined')
s = document.location.search;
var parts = s.substr(s.indexOf('?') + 1).split('&');
var result = {};
for (var i = 0; i < parts.length; i++) {
var tmp = parts[i].split('=', 2);
var key = jQuery.urldecode(tmp[0]);
var value = jQuery.urldecode(tmp[1]);
if (key in result)
result[key].push(value);
else
result[key] = [value];
}
return result;
}
/**
* small function to check if an array contains
* a given item.
*/
jQuery.contains = function(arr, item) {
for (var i = 0; i < arr.length; i++) {
if (arr[i] == item)
return true;
}
return false;
}
/**
* highlight a given string on a jquery object by wrapping it in
* span elements with the given class name.
*/
jQuery.fn.highlightText = function(text, className) {
function highlight(node) {
if (node.nodeType == 3) {
var val = node.nodeValue;
var pos = val.toLowerCase().indexOf(text);
if (pos >= 0 && !jQuery.className.has(node.parentNode, className)) {
var span = document.createElement("span");
span.className = className;
span.appendChild(document.createTextNode(val.substr(pos, text.length)));
node.parentNode.insertBefore(span, node.parentNode.insertBefore(
document.createTextNode(val.substr(pos + text.length)),
node.nextSibling));
node.nodeValue = val.substr(0, pos);
}
}
else if (!jQuery(node).is("button, select, textarea")) {
jQuery.each(node.childNodes, function() {
highlight(this)
});
}
}
return this.each(function() {
highlight(this);
});
}
/**
* Small JavaScript module for the documentation.
*/
var Documentation = {
init : function() {
this.fixFirefoxAnchorBug();
this.highlightSearchWords();
this.initModIndex();
},
/**
* i18n support
*/
TRANSLATIONS : {},
PLURAL_EXPR : function(n) { return n == 1 ? 0 : 1; },
LOCALE : 'unknown',
// gettext and ngettext don't access this so that the functions
// can savely bound to a different name (_ = Documentation.gettext)
gettext : function(string) {
var translated = Documentation.TRANSLATIONS[string];
if (typeof translated == 'undefined')
return string;
return (typeof translated == 'string') ? translated : translated[0];
},
ngettext : function(singular, plural, n) {
var translated = Documentation.TRANSLATIONS[singular];
if (typeof translated == 'undefined')
return (n == 1) ? singular : plural;
return translated[Documentation.PLURALEXPR(n)];
},
addTranslations : function(catalog) {
for (var key in catalog.messages)
this.TRANSLATIONS[key] = catalog.messages[key];
this.PLURAL_EXPR = new Function('n', 'return +(' + catalog.plural_expr + ')');
this.LOCALE = catalog.locale;
},
/**
* add context elements like header anchor links
*/
addContextElements : function() {
$('div[id] > :header:first').each(function() {
$('<a class="headerlink">\u00B6</a>').
attr('href', '#' + this.id).
attr('title', _('Permalink to this headline')).
appendTo(this);
});
$('dt[id]').each(function() {
$('<a class="headerlink">\u00B6</a>').
attr('href', '#' + this.id).
attr('title', _('Permalink to this definition')).
appendTo(this);
});
},
/**
* workaround a firefox stupidity
*/
fixFirefoxAnchorBug : function() {
if (document.location.hash && $.browser.mozilla)
window.setTimeout(function() {
document.location.href += '';
}, 10);
},
/**
* highlight the search words provided in the url in the text
*/
highlightSearchWords : function() {
var params = $.getQueryParameters();
var terms = (params.highlight) ? params.highlight[0].split(/\s+/) : [];
if (terms.length) {
var body = $('div.body');
window.setTimeout(function() {
$.each(terms, function() {
body.highlightText(this.toLowerCase(), 'highlight');
});
}, 10);
$('<li class="highlight-link"><a href="javascript:Documentation.' +
'hideSearchWords()">' + _('Hide Search Matches') + '</a></li>')
.appendTo($('.sidebar .this-page-menu'));
}
},
/**
* init the modindex toggle buttons
*/
initModIndex : function() {
var togglers = $('img.toggler').click(function() {
var src = $(this).attr('src');
var idnum = $(this).attr('id').substr(7);
console.log($('tr.cg-' + idnum).toggle());
if (src.substr(-9) == 'minus.png')
$(this).attr('src', src.substr(0, src.length-9) + 'plus.png');
else
$(this).attr('src', src.substr(0, src.length-8) + 'minus.png');
}).css('display', '');
if (DOCUMENTATION_OPTIONS.COLLAPSE_MODINDEX) {
togglers.click();
}
},
/**
* helper function to hide the search marks again
*/
hideSearchWords : function() {
$('.sidebar .this-page-menu li.highlight-link').fadeOut(300);
$('span.highlight').removeClass('highlight');
},
/**
* make the url absolute
*/
makeURL : function(relativeURL) {
return DOCUMENTATION_OPTIONS.URL_ROOT + '/' + relativeURL;
},
/**
* get the current relative url
*/
getCurrentURL : function() {
var path = document.location.pathname;
var parts = path.split(/\//);
$.each(DOCUMENTATION_OPTIONS.URL_ROOT.split(/\//), function() {
if (this == '..')
parts.pop();
});
var url = parts.join('/');
return path.substring(url.lastIndexOf('/') + 1, path.length - 1);
}
};
// quick alias for translations
_ = Documentation.gettext;
$(document).ready(function() {
Documentation.init();
});

Binary file not shown.

After

Width:  |  Height:  |  Size: 392 B

File diff suppressed because it is too large Load Diff

Binary file not shown.

After

Width:  |  Height:  |  Size: 199 B

Binary file not shown.

After

Width:  |  Height:  |  Size: 199 B

@ -0,0 +1,61 @@
.hll { background-color: #ffffcc }
.c { color: #408090; font-style: italic } /* Comment */
.err { border: 1px solid #FF0000 } /* Error */
.k { color: #007020; font-weight: bold } /* Keyword */
.o { color: #666666 } /* Operator */
.cm { color: #408090; font-style: italic } /* Comment.Multiline */
.cp { color: #007020 } /* Comment.Preproc */
.c1 { color: #408090; font-style: italic } /* Comment.Single */
.cs { color: #408090; background-color: #fff0f0 } /* Comment.Special */
.gd { color: #A00000 } /* Generic.Deleted */
.ge { font-style: italic } /* Generic.Emph */
.gr { color: #FF0000 } /* Generic.Error */
.gh { color: #000080; font-weight: bold } /* Generic.Heading */
.gi { color: #00A000 } /* Generic.Inserted */
.go { color: #303030 } /* Generic.Output */
.gp { color: #c65d09; font-weight: bold } /* Generic.Prompt */
.gs { font-weight: bold } /* Generic.Strong */
.gu { color: #800080; font-weight: bold } /* Generic.Subheading */
.gt { color: #0040D0 } /* Generic.Traceback */
.kc { color: #007020; font-weight: bold } /* Keyword.Constant */
.kd { color: #007020; font-weight: bold } /* Keyword.Declaration */
.kn { color: #007020; font-weight: bold } /* Keyword.Namespace */
.kp { color: #007020 } /* Keyword.Pseudo */
.kr { color: #007020; font-weight: bold } /* Keyword.Reserved */
.kt { color: #902000 } /* Keyword.Type */
.m { color: #208050 } /* Literal.Number */
.s { color: #4070a0 } /* Literal.String */
.na { color: #4070a0 } /* Name.Attribute */
.nb { color: #007020 } /* Name.Builtin */
.nc { color: #0e84b5; font-weight: bold } /* Name.Class */
.no { color: #60add5 } /* Name.Constant */
.nd { color: #555555; font-weight: bold } /* Name.Decorator */
.ni { color: #d55537; font-weight: bold } /* Name.Entity */
.ne { color: #007020 } /* Name.Exception */
.nf { color: #06287e } /* Name.Function */
.nl { color: #002070; font-weight: bold } /* Name.Label */
.nn { color: #0e84b5; font-weight: bold } /* Name.Namespace */
.nt { color: #062873; font-weight: bold } /* Name.Tag */
.nv { color: #bb60d5 } /* Name.Variable */
.ow { color: #007020; font-weight: bold } /* Operator.Word */
.w { color: #bbbbbb } /* Text.Whitespace */
.mf { color: #208050 } /* Literal.Number.Float */
.mh { color: #208050 } /* Literal.Number.Hex */
.mi { color: #208050 } /* Literal.Number.Integer */
.mo { color: #208050 } /* Literal.Number.Oct */
.sb { color: #4070a0 } /* Literal.String.Backtick */
.sc { color: #4070a0 } /* Literal.String.Char */
.sd { color: #4070a0; font-style: italic } /* Literal.String.Doc */
.s2 { color: #4070a0 } /* Literal.String.Double */
.se { color: #4070a0; font-weight: bold } /* Literal.String.Escape */
.sh { color: #4070a0 } /* Literal.String.Heredoc */
.si { color: #70a0d0; font-style: italic } /* Literal.String.Interpol */
.sx { color: #c65d09 } /* Literal.String.Other */
.sr { color: #235388 } /* Literal.String.Regex */
.s1 { color: #4070a0 } /* Literal.String.Single */
.ss { color: #517918 } /* Literal.String.Symbol */
.bp { color: #007020 } /* Name.Builtin.Pseudo */
.vc { color: #bb60d5 } /* Name.Variable.Class */
.vg { color: #bb60d5 } /* Name.Variable.Global */
.vi { color: #bb60d5 } /* Name.Variable.Instance */
.il { color: #208050 } /* Literal.Number.Integer.Long */

@ -0,0 +1,467 @@
/**
* helper function to return a node containing the
* search summary for a given text. keywords is a list
* of stemmed words, hlwords is the list of normal, unstemmed
* words. the first one is used to find the occurance, the
* latter for highlighting it.
*/
jQuery.makeSearchSummary = function(text, keywords, hlwords) {
var textLower = text.toLowerCase();
var start = 0;
$.each(keywords, function() {
var i = textLower.indexOf(this.toLowerCase());
if (i > -1)
start = i;
});
start = Math.max(start - 120, 0);
var excerpt = ((start > 0) ? '...' : '') +
$.trim(text.substr(start, 240)) +
((start + 240 - text.length) ? '...' : '');
var rv = $('<div class="context"></div>').text(excerpt);
$.each(hlwords, function() {
rv = rv.highlightText(this, 'highlight');
});
return rv;
}
/**
* Porter Stemmer
*/
var PorterStemmer = function() {
var step2list = {
ational: 'ate',
tional: 'tion',
enci: 'ence',
anci: 'ance',
izer: 'ize',
bli: 'ble',
alli: 'al',
entli: 'ent',
eli: 'e',
ousli: 'ous',
ization: 'ize',
ation: 'ate',
ator: 'ate',
alism: 'al',
iveness: 'ive',
fulness: 'ful',
ousness: 'ous',
aliti: 'al',
iviti: 'ive',
biliti: 'ble',
logi: 'log'
};
var step3list = {
icate: 'ic',
ative: '',
alize: 'al',
iciti: 'ic',
ical: 'ic',
ful: '',
ness: ''
};
var c = "[^aeiou]"; // consonant
var v = "[aeiouy]"; // vowel
var C = c + "[^aeiouy]*"; // consonant sequence
var V = v + "[aeiou]*"; // vowel sequence
var mgr0 = "^(" + C + ")?" + V + C; // [C]VC... is m>0
var meq1 = "^(" + C + ")?" + V + C + "(" + V + ")?$"; // [C]VC[V] is m=1
var mgr1 = "^(" + C + ")?" + V + C + V + C; // [C]VCVC... is m>1
var s_v = "^(" + C + ")?" + v; // vowel in stem
this.stemWord = function (w) {
var stem;
var suffix;
var firstch;
var origword = w;
if (w.length < 3)
return w;
var re;
var re2;
var re3;
var re4;
firstch = w.substr(0,1);
if (firstch == "y")
w = firstch.toUpperCase() + w.substr(1);
// Step 1a
re = /^(.+?)(ss|i)es$/;
re2 = /^(.+?)([^s])s$/;
if (re.test(w))
w = w.replace(re,"$1$2");
else if (re2.test(w))
w = w.replace(re2,"$1$2");
// Step 1b
re = /^(.+?)eed$/;
re2 = /^(.+?)(ed|ing)$/;
if (re.test(w)) {
var fp = re.exec(w);
re = new RegExp(mgr0);
if (re.test(fp[1])) {
re = /.$/;
w = w.replace(re,"");
}
}
else if (re2.test(w)) {
var fp = re2.exec(w);
stem = fp[1];
re2 = new RegExp(s_v);
if (re2.test(stem)) {
w = stem;
re2 = /(at|bl|iz)$/;
re3 = new RegExp("([^aeiouylsz])\\1$");
re4 = new RegExp("^" + C + v + "[^aeiouwxy]$");
if (re2.test(w))
w = w + "e";
else if (re3.test(w)) {
re = /.$/;
w = w.replace(re,"");
}
else if (re4.test(w))
w = w + "e";
}
}
// Step 1c
re = /^(.+?)y$/;
if (re.test(w)) {
var fp = re.exec(w);
stem = fp[1];
re = new RegExp(s_v);
if (re.test(stem))
w = stem + "i";
}
// Step 2
re = /^(.+?)(ational|tional|enci|anci|izer|bli|alli|entli|eli|ousli|ization|ation|ator|alism|iveness|fulness|ousness|aliti|iviti|biliti|logi)$/;
if (re.test(w)) {
var fp = re.exec(w);
stem = fp[1];
suffix = fp[2];
re = new RegExp(mgr0);
if (re.test(stem))
w = stem + step2list[suffix];
}
// Step 3
re = /^(.+?)(icate|ative|alize|iciti|ical|ful|ness)$/;
if (re.test(w)) {
var fp = re.exec(w);
stem = fp[1];
suffix = fp[2];
re = new RegExp(mgr0);
if (re.test(stem))
w = stem + step3list[suffix];
}
// Step 4
re = /^(.+?)(al|ance|ence|er|ic|able|ible|ant|ement|ment|ent|ou|ism|ate|iti|ous|ive|ize)$/;
re2 = /^(.+?)(s|t)(ion)$/;
if (re.test(w)) {
var fp = re.exec(w);
stem = fp[1];
re = new RegExp(mgr1);
if (re.test(stem))
w = stem;
}
else if (re2.test(w)) {
var fp = re2.exec(w);
stem = fp[1] + fp[2];
re2 = new RegExp(mgr1);
if (re2.test(stem))
w = stem;
}
// Step 5
re = /^(.+?)e$/;
if (re.test(w)) {
var fp = re.exec(w);
stem = fp[1];
re = new RegExp(mgr1);
re2 = new RegExp(meq1);
re3 = new RegExp("^" + C + v + "[^aeiouwxy]$");
if (re.test(stem) || (re2.test(stem) && !(re3.test(stem))))
w = stem;
}
re = /ll$/;
re2 = new RegExp(mgr1);
if (re.test(w) && re2.test(w)) {
re = /.$/;
w = w.replace(re,"");
}
// and turn initial Y back to y
if (firstch == "y")
w = firstch.toLowerCase() + w.substr(1);
return w;
}
}
/**
* Search Module
*/
var Search = {
_index : null,
_queued_query : null,
_pulse_status : -1,
init : function() {
var params = $.getQueryParameters();
if (params.q) {
var query = params.q[0];
$('input[name="q"]')[0].value = query;
this.performSearch(query);
}
},
/**
* Sets the index
*/
setIndex : function(index) {
var q;
this._index = index;
if ((q = this._queued_query) !== null) {
this._queued_query = null;
Search.query(q);
}
},
hasIndex : function() {
return this._index !== null;
},
deferQuery : function(query) {
this._queued_query = query;
},
stopPulse : function() {
this._pulse_status = 0;
},
startPulse : function() {
if (this._pulse_status >= 0)
return;
function pulse() {
Search._pulse_status = (Search._pulse_status + 1) % 4;
var dotString = '';
for (var i = 0; i < Search._pulse_status; i++)
dotString += '.';
Search.dots.text(dotString);
if (Search._pulse_status > -1)
window.setTimeout(pulse, 500);
};
pulse();
},
/**
* perform a search for something
*/
performSearch : function(query) {
// create the required interface elements
this.out = $('#search-results');
this.title = $('<h2>' + _('Searching') + '</h2>').appendTo(this.out);
this.dots = $('<span></span>').appendTo(this.title);
this.status = $('<p style="display: none"></p>').appendTo(this.out);
this.output = $('<ul class="search"/>').appendTo(this.out);
$('#search-progress').text(_('Preparing search...'));
this.startPulse();
// index already loaded, the browser was quick!
if (this.hasIndex())
this.query(query);
else
this.deferQuery(query);
},
query : function(query) {
// stem the searchterms and add them to the
// correct list
var stemmer = new PorterStemmer();
var searchterms = [];
var excluded = [];
var hlterms = [];
var tmp = query.split(/\s+/);
var object = (tmp.length == 1) ? tmp[0].toLowerCase() : null;
for (var i = 0; i < tmp.length; i++) {
// stem the word
var word = stemmer.stemWord(tmp[i]).toLowerCase();
// select the correct list
if (word[0] == '-') {
var toAppend = excluded;
word = word.substr(1);
}
else {
var toAppend = searchterms;
hlterms.push(tmp[i].toLowerCase());
}
// only add if not already in the list
if (!$.contains(toAppend, word))
toAppend.push(word);
};
var highlightstring = '?highlight=' + $.urlencode(hlterms.join(" "));
console.debug('SEARCH: searching for:');
console.info('required: ', searchterms);
console.info('excluded: ', excluded);
// prepare search
var filenames = this._index.filenames;
var titles = this._index.titles;
var terms = this._index.terms;
var descrefs = this._index.descrefs;
var modules = this._index.modules;
var desctypes = this._index.desctypes;
var fileMap = {};
var files = null;
var objectResults = [];
var regularResults = [];
$('#search-progress').empty();
// lookup as object
if (object != null) {
for (var module in modules) {
if (module.indexOf(object) > -1) {
fn = modules[module];
descr = _('module, in ') + titles[fn];
objectResults.push([filenames[fn], module, '#module-'+module, descr]);
}
}
for (var prefix in descrefs) {
for (var name in descrefs[prefix]) {
var fullname = (prefix ? prefix + '.' : '') + name;
if (fullname.toLowerCase().indexOf(object) > -1) {
match = descrefs[prefix][name];
descr = desctypes[match[1]] + _(', in ') + titles[match[0]];
objectResults.push([filenames[match[0]], fullname, '#'+fullname, descr]);
}
}
}
}
// sort results descending
objectResults.sort(function(a, b) {
return (a[1] > b[1]) ? -1 : ((a[1] < b[1]) ? 1 : 0);
});
// perform the search on the required terms
for (var i = 0; i < searchterms.length; i++) {
var word = searchterms[i];
// no match but word was a required one
if ((files = terms[word]) == null)
break;
if (files.length == undefined) {
files = [files];
}
// create the mapping
for (var j = 0; j < files.length; j++) {
var file = files[j];
if (file in fileMap)
fileMap[file].push(word);
else
fileMap[file] = [word];
}
}
// now check if the files don't contain excluded terms
for (var file in fileMap) {
var valid = true;
// check if all requirements are matched
if (fileMap[file].length != searchterms.length)
continue;
// ensure that none of the excluded terms is in the
// search result.
for (var i = 0; i < excluded.length; i++) {
if (terms[excluded[i]] == file ||
$.contains(terms[excluded[i]] || [], file)) {
valid = false;
break;
}
}
// if we have still a valid result we can add it
// to the result list
if (valid)
regularResults.push([filenames[file], titles[file], '', null]);
}
// delete unused variables in order to not waste
// memory until list is retrieved completely
delete filenames, titles, terms;
// now sort the regular results descending by title
regularResults.sort(function(a, b) {
var left = a[1].toLowerCase();
var right = b[1].toLowerCase();
return (left > right) ? -1 : ((left < right) ? 1 : 0);
});
// combine both
var results = regularResults.concat(objectResults);
// print the results
var resultCount = results.length;
function displayNextItem() {
// results left, load the summary and display it
if (results.length) {
var item = results.pop();
var listItem = $('<li style="display:none"></li>');
listItem.append($('<a/>').attr(
'href',
item[0] + DOCUMENTATION_OPTIONS.FILE_SUFFIX +
highlightstring + item[2]).html(item[1]));
if (item[3]) {
listItem.append($('<span> (' + item[3] + ')</span>'));
Search.output.append(listItem);
listItem.slideDown(5, function() {
displayNextItem();
});
} else if (DOCUMENTATION_OPTIONS.HAS_SOURCE) {
$.get('_sources/' + item[0] + '.txt', function(data) {
listItem.append($.makeSearchSummary(data, searchterms, hlterms));
Search.output.append(listItem);
listItem.slideDown(5, function() {
displayNextItem();
});
});
} else {
// no source available, just display title
Search.output.append(listItem);
listItem.slideDown(5, function() {
displayNextItem();
});
}
}
// search finished, update title and status message
else {
Search.stopPulse();
Search.title.text(_('Search Results'));
if (!resultCount)
Search.status.text(_('Your search did not match any documents. Please make sure that all words are spelled correctly and that you\'ve selected enough categories.'));
else
Search.status.text(_('Search finished, found %s page(s) matching the search query.').replace('%s', resultCount));
Search.status.fadeIn(500);
}
}
displayNextItem();
}
}
$(document).ready(function() {
Search.init();
});

@ -0,0 +1,901 @@
<!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">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Annotations &mdash; SIP 4.10.5 Reference Guide</title>
<link rel="stylesheet" href="_static/default.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '#',
VERSION: '4.10.5',
COLLAPSE_MODINDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="top" title="SIP 4.10.5 Reference Guide" href="index.html" />
<link rel="next" title="C API for Handwritten Code" href="c_api.html" />
<link rel="prev" title="Directives" href="directives.html" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="modindex.html" title="Global Module Index"
accesskey="M">modules</a> |</li>
<li class="right" >
<a href="c_api.html" title="C API for Handwritten Code"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="directives.html" title="Directives"
accesskey="P">previous</a> |</li>
<li><a href="index.html">SIP 4.10.5 Reference Guide</a> &raquo;</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="annotations">
<h1>Annotations<a class="headerlink" href="#annotations" title="Permalink to this headline"></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 <a class="reference internal" href="#ref-arg-annos"><em>argument annotations</em></a>,
<a class="reference internal" href="#ref-class-annos"><em>class annotations</em></a>, <a class="reference internal" href="#ref-mapped-type-annos"><em>mapped type annotations</em></a>, <a class="reference internal" href="#ref-enum-annos"><em>enum annotations</em></a>,
<a class="reference internal" href="#ref-exception-annos"><em>exception annotations</em></a>, <a class="reference internal" href="#ref-function-annos"><em>function annotations</em></a>, <a class="reference internal" href="#ref-license-annos"><em>license annotations</em></a>,
<a class="reference internal" href="#ref-typedef-annos"><em>typedef annotations</em></a> or <a class="reference internal" href="#ref-variable-annos"><em>variable annotations</em></a> 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><em>boolean</em></dt>
<dd>This type of annotation has no value and is implicitly true.</dd>
<dt><em>name</em></dt>
<dd>The value is a name that is compatible with a C/C++ identifier. In some
cases the value is optional.</dd>
<dt><em>dotted name</em></dt>
<dd>The value is a name that is compatible with an identifier preceded by a
Python scope.</dd>
<dt><em>string</em></dt>
<dd>The value is a double quoted string.</dd>
<dt><em>API range</em></dt>
<dd><p class="first">The value is the name of an API (defined using the <a class="reference external" href="directives.html#directive-%API"><tt class="xref docutils literal"><span class="pre">%API</span></tt></a>
directive) separated by a range of version numbers with a colon.</p>
<p>The range of version numbers is a pair of numbers separated by a hyphen
specifying the lower and upper bounds of the range. A version number is
within the range if it is greater or equal to the lower bound and less
than the upper bound. Each bound can be omitted meaning that the range is
unbounded in that direction.</p>
<p>For example:</p>
<div class="last highlight-python"><pre># This is part of the PyQt4 API up to but excluding v2.
void hex() /API=PyQt4:-2/
# This is part of the PyQt4 API starting from v2.
void hex() /PyName=hex_, API=PyQt4:2-/</pre>
</div>
</dd>
</dl>
<p>The following example shows argument and function annotations:</p>
<div class="highlight-python"><pre>void exec(QWidget * /Transfer/) /ReleaseGIL, PyName=call_exec/;</pre>
</div>
<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" id="argument-annotations">
<span id="ref-arg-annos"></span><h2>Argument Annotations<a class="headerlink" href="#argument-annotations" title="Permalink to this headline"></a></h2>
<dl class="argument-annotation">
<dt id="aanno-AllowNone">
<tt class="descname">AllowNone</tt><a class="headerlink" href="#aanno-AllowNone" title="Permalink to this definition"></a></dt>
<dd>This boolean annotation specifies that the value of the corresponding
argument (which should be either <a class="reference external" href="specification_files.html#stype-SIP_PYCALLABLE"><tt class="xref docutils literal"><span class="pre">SIP_PYCALLABLE</span></tt></a>,
<a class="reference external" href="specification_files.html#stype-SIP_PYDICT"><tt class="xref docutils literal"><span class="pre">SIP_PYDICT</span></tt></a>, <a class="reference external" href="specification_files.html#stype-SIP_PYLIST"><tt class="xref docutils literal"><span class="pre">SIP_PYLIST</span></tt></a>, <a class="reference external" href="specification_files.html#stype-SIP_PYSLICE"><tt class="xref docutils literal"><span class="pre">SIP_PYSLICE</span></tt></a>,
<a class="reference external" href="specification_files.html#stype-SIP_PYTUPLE"><tt class="xref docutils literal"><span class="pre">SIP_PYTUPLE</span></tt></a> or <a class="reference external" href="specification_files.html#stype-SIP_PYTYPE"><tt class="xref docutils literal"><span class="pre">SIP_PYTYPE</span></tt></a>) may be <tt class="xref docutils literal"><span class="pre">None</span></tt>.</dd></dl>
<dl class="argument-annotation">
<dt id="aanno-Array">
<tt class="descname">Array</tt><a class="headerlink" href="#aanno-Array" title="Permalink to this definition"></a></dt>
<dd><p>This boolean annotation specifies that the corresponding argument refers
to an array.</p>
<p>The argument should be either a pointer to a wrapped type, a <tt class="docutils literal"><span class="pre">char</span> <span class="pre">*</span></tt> or
a <tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">char</span> <span class="pre">*</span></tt>. If the argument is a character array then the
annotation also implies the <a class="reference internal" href="#aanno-Encoding"><tt class="xref docutils literal"><span class="pre">Encoding</span></tt></a> annotation with an encoding
of <tt class="docutils literal"><span class="pre">&quot;None&quot;</span></tt>.</p>
<p>There must be a corresponding argument with the <a class="reference internal" href="#aanno-ArraySize"><tt class="xref docutils literal"><span class="pre">ArraySize</span></tt></a>
annotation specified. The annotation may only be specified once in a list
of arguments.</p>
</dd></dl>
<dl class="argument-annotation">
<dt id="aanno-ArraySize">
<tt class="descname">ArraySize</tt><a class="headerlink" href="#aanno-ArraySize" title="Permalink to this definition"></a></dt>
<dd>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 internal" href="#aanno-Array"><tt class="xref docutils literal"><span class="pre">Array</span></tt></a> annotation specified.
The annotation may only be specified once in a list of arguments.</dd></dl>
<dl class="argument-annotation">
<dt id="aanno-Constrained">
<tt class="descname">Constrained</tt><a class="headerlink" href="#aanno-Constrained" title="Permalink to this definition"></a></dt>
<dd><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>
<div class="highlight-python"><pre>// 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>
</div>
<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>, <tt class="docutils literal"><span class="pre">enum</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 external" href="directives.html#directive-%ConvertToTypeCode"><tt class="xref docutils literal"><span class="pre">%ConvertToTypeCode</span></tt></a> is suppressed.</p>
<p>The following example gets around the above problem:</p>
<div class="highlight-python"><pre>// 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>
</dd></dl>
<dl class="argument-annotation">
<dt id="aanno-DocType">
<tt class="descname">DocType</tt><a class="headerlink" href="#aanno-DocType" title="Permalink to this definition"></a></dt>
<dd><p>
<span class="versionmodified">New in version 4.10.</span></p>
<p>This string annotation specifies the type of the argument as it will appear
in any generated docstrings. It is usually used with arguments of type
<a class="reference external" href="specification_files.html#stype-SIP_PYOBJECT"><tt class="xref docutils literal"><span class="pre">SIP_PYOBJECT</span></tt></a> to provide a more specific type.</p>
</dd></dl>
<dl class="argument-annotation">
<dt id="aanno-DocValue">
<tt class="descname">DocValue</tt><a class="headerlink" href="#aanno-DocValue" title="Permalink to this definition"></a></dt>
<dd><p>
<span class="versionmodified">New in version 4.10.</span></p>
<p>This string annotation specifies the default value of the argument as it
will appear in any generated docstrings.</p>
</dd></dl>
<dl class="argument-annotation">
<dt id="aanno-Encoding">
<tt class="descname">Encoding</tt><a class="headerlink" href="#aanno-Encoding" title="Permalink to this definition"></a></dt>
<dd><p>This string annotation specifies that the corresponding argument (which
should be either <tt class="docutils literal"><span class="pre">char</span></tt>, <tt class="docutils literal"><span class="pre">const</span> <span class="pre">char</span></tt>, <tt class="docutils literal"><span class="pre">char</span> <span class="pre">*</span></tt> or <tt class="docutils literal"><span class="pre">const</span> <span class="pre">char</span> <span class="pre">*</span></tt>)
refers to an encoded character or <tt class="docutils literal"><span class="pre">'\0'</span></tt> terminated encoded string with
the specified encoding. The encoding can be either <tt class="docutils literal"><span class="pre">&quot;ASCII&quot;</span></tt>,
<tt class="docutils literal"><span class="pre">&quot;Latin-1&quot;</span></tt>, <tt class="docutils literal"><span class="pre">&quot;UTF-8&quot;</span></tt> or <tt class="docutils literal"><span class="pre">&quot;None&quot;</span></tt>. An encoding of <tt class="docutils literal"><span class="pre">&quot;None&quot;</span></tt> means
that the corresponding argument refers to an unencoded character or string.</p>
<p>The default encoding is specified by the <a class="reference external" href="directives.html#directive-%DefaultEncoding"><tt class="xref docutils literal"><span class="pre">%DefaultEncoding</span></tt></a>
directive. If the directive is not specified then <tt class="xref docutils literal"><span class="pre">None</span></tt> is used.</p>
<p>Python v3 will use the <tt class="docutils literal"><span class="pre">bytes</span></tt> type to represent the argument if the
encoding is <tt class="docutils literal"><span class="pre">&quot;None&quot;</span></tt> and the <tt class="docutils literal"><span class="pre">str</span></tt> type otherwise.</p>
<p>Python v2 will use the <tt class="docutils literal"><span class="pre">str</span></tt> type to represent the argument if the
encoding is <tt class="docutils literal"><span class="pre">&quot;None&quot;</span></tt> and the <tt class="docutils literal"><span class="pre">unicode</span></tt> type otherwise.</p>
</dd></dl>
<dl class="argument-annotation">
<dt id="aanno-GetWrapper">
<tt class="descname">GetWrapper</tt><a class="headerlink" href="#aanno-GetWrapper" title="Permalink to this definition"></a></dt>
<dd><p>This boolean annotation is only ever used in conjunction with handwritten
code specified with the <a class="reference external" href="directives.html#directive-%MethodCode"><tt class="xref docutils literal"><span class="pre">%MethodCode</span></tt></a> directive. It causes an
extra variable to be generated for the corresponding argument which is a
pointer to the Python object that wraps the argument.</p>
<p>See the <a class="reference external" href="directives.html#directive-%MethodCode"><tt class="xref docutils literal"><span class="pre">%MethodCode</span></tt></a> directive for more detail.</p>
</dd></dl>
<dl class="argument-annotation">
<dt id="aanno-In">
<tt class="descname">In</tt><a class="headerlink" href="#aanno-In" title="Permalink to this definition"></a></dt>
<dd><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 internal" href="#aanno-Out"><tt class="xref docutils literal"><span class="pre">Out</span></tt></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 internal" href="#aanno-In"><tt class="xref docutils literal"><span class="pre">In</span></tt></a> and <a class="reference internal" href="#aanno-Out"><tt class="xref docutils literal"><span class="pre">Out</span></tt></a> may be specified for the same argument.</p>
</dd></dl>
<dl class="argument-annotation">
<dt id="aanno-KeepReference">
<tt class="descname">KeepReference</tt><a class="headerlink" href="#aanno-KeepReference" title="Permalink to this definition"></a></dt>
<dd>This boolean annotation is used to specify that a reference to the
corresponding argument should be kept to ensure that the object is not
garbage collected. If the method is called again with a new argument then
the reference to the previous argument is discarded. Note that ownership
of the argument is not changed.</dd></dl>
<dl class="argument-annotation">
<dt id="aanno-NoCopy">
<tt class="descname">NoCopy</tt><a class="headerlink" href="#aanno-NoCopy" title="Permalink to this definition"></a></dt>
<dd><p>
<span class="versionmodified">New in version 4.10.1.</span></p>
<p>This boolean annotation is used with arguments of virtual methods that are
a <tt class="docutils literal"><span class="pre">const</span></tt> reference to a class. Normally, if the class defines a copy
constructor then a copy of the returned reference is automatically created
and wrapped before being passed to a Python reimplementation of the method.
The copy will be owned by Python. This means that the reimplementation may
take a reference to the argument without having to make an explicit copy.</p>
<p>If the annotation is specified then the copy is not made and the original
reference is wrapped instead and will be owned by C++.</p>
</dd></dl>
<dl class="argument-annotation">
<dt id="aanno-Out">
<tt class="descname">Out</tt><a class="headerlink" href="#aanno-Out" title="Permalink to this definition"></a></dt>
<dd><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 internal" href="#aanno-In"><tt class="xref docutils literal"><span class="pre">In</span></tt></a> annotation is specified.</p>
<p>Both <a class="reference internal" href="#aanno-In"><tt class="xref docutils literal"><span class="pre">In</span></tt></a> and <a class="reference internal" href="#aanno-Out"><tt class="xref docutils literal"><span class="pre">Out</span></tt></a> may be specified for the same argument.</p>
</dd></dl>
<dl class="argument-annotation">
<dt id="aanno-ResultSize">
<tt class="descname">ResultSize</tt><a class="headerlink" href="#aanno-ResultSize" title="Permalink to this definition"></a></dt>
<dd>This boolean annotation is used with functions or methods that return a
<tt class="docutils literal"><span class="pre">void</span> <span class="pre">*</span></tt> or <tt class="docutils literal"><span class="pre">const</span> <span class="pre">void</span> <span class="pre">*</span></tt>. It identifies an argument that defines the
size of the block of memory whose address is being returned. This allows
the <tt class="docutils literal"><span class="pre">sip.voidptr</span></tt> object that wraps the address to support the Python
buffer protocol and allows the memory to be read and updated when wrapped
by the Python <tt class="docutils literal"><span class="pre">buffer()</span></tt> builtin.</dd></dl>
<dl class="argument-annotation">
<dt id="aanno-SingleShot">
<tt class="descname">SingleShot</tt><a class="headerlink" href="#aanno-SingleShot" title="Permalink to this definition"></a></dt>
<dd>This boolean annotation is used only with arguments of type
<a class="reference external" href="specification_files.html#stype-SIP_RXOBJ_CON"><tt class="xref docutils literal"><span class="pre">SIP_RXOBJ_CON</span></tt></a> to specify that the signal connected to the slot
will only ever be emitted once. This prevents a certain class of memory
leaks.</dd></dl>
<dl class="argument-annotation">
<dt id="aanno-Transfer">
<tt class="descname">Transfer</tt><a class="headerlink" href="#aanno-Transfer" title="Permalink to this definition"></a></dt>
<dd><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 external" href="using.html#ref-object-ownership"><em>Ownership of Objects</em></a> for more detail.</p>
</dd></dl>
<dl class="argument-annotation">
<dt id="aanno-TransferBack">
<tt class="descname">TransferBack</tt><a class="headerlink" href="#aanno-TransferBack" title="Permalink to this definition"></a></dt>
<dd><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>See <a class="reference external" href="using.html#ref-object-ownership"><em>Ownership of Objects</em></a> for more detail.</p>
</dd></dl>
<dl class="argument-annotation">
<dt id="aanno-TransferThis">
<tt class="descname">TransferThis</tt><a class="headerlink" href="#aanno-TransferThis" title="Permalink to this definition"></a></dt>
<dd><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="xref 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="xref docutils literal"><span class="pre">None</span></tt>. If it is <tt class="xref 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="xref docutils literal"><span class="pre">None</span></tt>.</p>
<p>See <a class="reference external" href="using.html#ref-object-ownership"><em>Ownership of Objects</em></a> for more detail.</p>
</dd></dl>
</div>
<div class="section" id="class-annotations">
<span id="ref-class-annos"></span><h2>Class Annotations<a class="headerlink" href="#class-annotations" title="Permalink to this headline"></a></h2>
<dl class="class-annotation">
<dt id="canno-Abstract">
<tt class="descname">Abstract</tt><a class="headerlink" href="#canno-Abstract" title="Permalink to this definition"></a></dt>
<dd>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.</dd></dl>
<dl class="class-annotation">
<dt id="canno-AllowNone">
<tt class="descname">AllowNone</tt><a class="headerlink" href="#canno-AllowNone" title="Permalink to this definition"></a></dt>
<dd><p>
<span class="versionmodified">New in version 4.8.2.</span></p>
<p>Normally when a Python object is converted to a C/C++ instance <tt class="xref docutils literal"><span class="pre">None</span></tt>
is handled automatically before the class&#8217;s
<a class="reference external" href="directives.html#directive-%ConvertToTypeCode"><tt class="xref docutils literal"><span class="pre">%ConvertToTypeCode</span></tt></a> is called. This boolean annotation
specifies that the handling of <tt class="xref docutils literal"><span class="pre">None</span></tt> will be left to the
<a class="reference external" href="directives.html#directive-%ConvertToTypeCode"><tt class="xref docutils literal"><span class="pre">%ConvertToTypeCode</span></tt></a>. The annotation is ignored if the class
does not have any <a class="reference external" href="directives.html#directive-%ConvertToTypeCode"><tt class="xref docutils literal"><span class="pre">%ConvertToTypeCode</span></tt></a>.</p>
</dd></dl>
<dl class="class-annotation">
<dt id="canno-API">
<tt class="descname">API</tt><a class="headerlink" href="#canno-API" title="Permalink to this definition"></a></dt>
<dd><p>
<span class="versionmodified">New in version 4.9.</span></p>
<p>This API range annotation is used to specify an API and corresponding
range of version numbers that the class is enabled for.</p>
<p>If a class or mapped type has different implementations enabled for
different ranges of version numbers then those ranges must not overlap.</p>
<p>See <a class="reference external" href="using.html#ref-incompat-apis"><em>Managing Incompatible APIs</em></a> for more detail.</p>
</dd></dl>
<dl class="class-annotation">
<dt id="canno-DelayDtor">
<tt class="descname">DelayDtor</tt><a class="headerlink" href="#canno-DelayDtor" title="Permalink to this definition"></a></dt>
<dd><p>This boolean annotation is used to specify that the class&#8217;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
<a title="sipDelayedDtors" class="reference internal" href="#sipDelayedDtors"><tt class="xref docutils literal"><span class="pre">sipDelayedDtors()</span></tt></a> is called with the list of delayed instances.
<a title="sipDelayedDtors" class="reference internal" href="#sipDelayedDtors"><tt class="xref docutils literal"><span class="pre">sipDelayedDtors()</span></tt></a> can then choose to call (or ignore) the
destructors in any desired order.</p>
<p>The <a title="sipDelayedDtors" class="reference internal" href="#sipDelayedDtors"><tt class="xref docutils literal"><span class="pre">sipDelayedDtors()</span></tt></a> function must be specified using the
<a class="reference external" href="directives.html#directive-%ModuleCode"><tt class="xref docutils literal"><span class="pre">%ModuleCode</span></tt></a> directive.</p>
</dd></dl>
<dl class="cfunction">
<dt id="sipDelayedDtors">
void <tt class="descname">sipDelayedDtors</tt><big>(</big>const <a title="sipDelayedDtor" class="reference internal" href="#sipDelayedDtor">sipDelayedDtor</a><em> *dd_list</em><big>)</big><a class="headerlink" href="#sipDelayedDtors" title="Permalink to this definition"></a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>dd_list</em> &#8211; the linked list of delayed instances.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="ctype">
<dt id="sipDelayedDtor">
<tt class="descname">sipDelayedDtor</tt><a class="headerlink" href="#sipDelayedDtor" title="Permalink to this definition"></a></dt>
<dd><p>This structure describes a particular delayed destructor.</p>
<dl class="cmember">
<dt id="dd_name">
const char *<tt class="descname">dd_name</tt><a class="headerlink" href="#dd_name" title="Permalink to this definition"></a></dt>
<dd>This is the name of the class excluding any package or module name.</dd></dl>
<dl class="cmember">
<dt id="dd_ptr">
void *<tt class="descname">dd_ptr</tt><a class="headerlink" href="#dd_ptr" title="Permalink to this definition"></a></dt>
<dd>This is the address of the C or C++ instance to be destroyed. It&#8217;s
exact type depends on the value of <a title="dd_isderived" class="reference internal" href="#dd_isderived"><tt class="xref docutils literal"><span class="pre">dd_isderived</span></tt></a>.</dd></dl>
<dl class="cmember">
<dt id="dd_isderived">
int <tt class="descname">dd_isderived</tt><a class="headerlink" href="#dd_isderived" title="Permalink to this definition"></a></dt>
<dd>This is non-zero if the type of <a title="dd_ptr" class="reference internal" href="#dd_ptr"><tt class="xref docutils literal"><span class="pre">dd_ptr</span></tt></a> is actually the
generated derived class. This allows the correct destructor to be
called. See <a class="reference external" href="c_api.html#ref-derived-classes"><em>Generated Derived Classes</em></a>.</dd></dl>
<dl class="cmember">
<dt id="dd_next">
<a title="sipDelayedDtor" class="reference internal" href="#sipDelayedDtor">sipDelayedDtor</a> *<tt class="descname">dd_next</tt><a class="headerlink" href="#dd_next" title="Permalink to this definition"></a></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>
</dd></dl>
<dl class="class-annotation">
<dt id="canno-Deprecated">
<tt class="descname">Deprecated</tt><a class="headerlink" href="#canno-Deprecated" title="Permalink to this definition"></a></dt>
<dd>This boolean annotation is used to specify that the class is deprecated.
It is the equivalent of annotating all the class&#8217;s constructors, function
and methods as being deprecated.</dd></dl>
<dl class="class-annotation">
<dt id="canno-External">
<tt class="descname">External</tt><a class="headerlink" href="#canno-External" title="Permalink to this definition"></a></dt>
<dd>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.</dd></dl>
<dl class="class-annotation">
<dt id="canno-Metatype">
<tt class="descname">Metatype</tt><a class="headerlink" href="#canno-Metatype" title="Permalink to this definition"></a></dt>
<dd><p>This dotted name annotation specifies the name of the Python type object
(i.e. the value of the <tt class="docutils literal"><span class="pre">tp_name</span></tt> field) used as the meta-type used when
creating the type object for this C structure or C++ type.</p>
<p>See the section <a class="reference external" href="using.html#ref-types-metatypes"><em>Types and Meta-types</em></a> for more details.</p>
</dd></dl>
<dl class="class-annotation">
<dt id="canno-NoDefaultCtors">
<tt class="descname">NoDefaultCtors</tt><a class="headerlink" href="#canno-NoDefaultCtors" title="Permalink to this definition"></a></dt>
<dd>This boolean annotation is used to suppress the automatic generation of
default constructors for the class.</dd></dl>
<dl class="class-annotation">
<dt id="canno-PyName">
<tt class="descname">PyName</tt><a class="headerlink" href="#canno-PyName" title="Permalink to this definition"></a></dt>
<dd>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.</dd></dl>
<dl class="class-annotation">
<dt id="canno-Supertype">
<tt class="descname">Supertype</tt><a class="headerlink" href="#canno-Supertype" title="Permalink to this definition"></a></dt>
<dd><p>This dotted name annotation specifies the name of the Python type object
(i.e. the value of the <tt class="docutils literal"><span class="pre">tp_name</span></tt> field) used as the super-type used when
creating the type object for this C structure or C++ type.</p>
<p>See the section <a class="reference external" href="using.html#ref-types-metatypes"><em>Types and Meta-types</em></a> for more details.</p>
</dd></dl>
</div>
<div class="section" id="mapped-type-annotations">
<span id="ref-mapped-type-annos"></span><h2>Mapped Type Annotations<a class="headerlink" href="#mapped-type-annotations" title="Permalink to this headline"></a></h2>
<dl class="mapped-type-annotation">
<dt id="manno-AllowNone">
<tt class="descname">AllowNone</tt><a class="headerlink" href="#manno-AllowNone" title="Permalink to this definition"></a></dt>
<dd>Normally when a Python object is converted to a C/C++ instance <tt class="xref docutils literal"><span class="pre">None</span></tt>
is handled automatically before the mapped type&#8217;s
<a class="reference external" href="directives.html#directive-%ConvertToTypeCode"><tt class="xref docutils literal"><span class="pre">%ConvertToTypeCode</span></tt></a> is called. This boolean annotation
specifies that the handling of <tt class="xref docutils literal"><span class="pre">None</span></tt> will be left to the
<a class="reference external" href="directives.html#directive-%ConvertToTypeCode"><tt class="xref docutils literal"><span class="pre">%ConvertToTypeCode</span></tt></a>.</dd></dl>
<dl class="mapped-type-annotation">
<dt id="manno-API">
<tt class="descname">API</tt><a class="headerlink" href="#manno-API" title="Permalink to this definition"></a></dt>
<dd><p>
<span class="versionmodified">New in version 4.9.</span></p>
<p>This API range annotation is used to specify an API and corresponding
range of version numbers that the mapped type is enabled for.</p>
<p>If a class or mapped type has different implementations enabled for
different ranges of version numbers then those ranges must not overlap.</p>
<p>See <a class="reference external" href="using.html#ref-incompat-apis"><em>Managing Incompatible APIs</em></a> for more detail.</p>
</dd></dl>
<dl class="mapped-type-annotation">
<dt id="manno-DocType">
<tt class="descname">DocType</tt><a class="headerlink" href="#manno-DocType" title="Permalink to this definition"></a></dt>
<dd><p>
<span class="versionmodified">New in version 4.10.</span></p>
<p>This string annotation specifies the name of the type as it will appear in
any generated docstrings.</p>
</dd></dl>
<dl class="mapped-type-annotation">
<dt id="manno-NoRelease">
<tt class="descname">NoRelease</tt><a class="headerlink" href="#manno-NoRelease" title="Permalink to this definition"></a></dt>
<dd>This boolean annotation is used to specify that the mapped type does not
support the <a title="sipReleaseType" class="reference external" href="c_api.html#sipReleaseType"><tt class="xref docutils literal"><span class="pre">sipReleaseType()</span></tt></a> function. Any
<a class="reference external" href="directives.html#directive-%ConvertToTypeCode"><tt class="xref docutils literal"><span class="pre">%ConvertToTypeCode</span></tt></a> should not create temporary instances of
the mapped type, i.e. it should not return <tt class="xref docutils literal"><span class="pre">SIP_TEMPORARY</span></tt>.</dd></dl>
</div>
<div class="section" id="enum-annotations">
<span id="ref-enum-annos"></span><h2>Enum Annotations<a class="headerlink" href="#enum-annotations" title="Permalink to this headline"></a></h2>
<dl class="enum-annotation">
<dt id="eanno-PyName">
<tt class="descname">PyName</tt><a class="headerlink" href="#eanno-PyName" title="Permalink to this definition"></a></dt>
<dd>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.</dd></dl>
</div>
<div class="section" id="exception-annotations">
<span id="ref-exception-annos"></span><h2>Exception Annotations<a class="headerlink" href="#exception-annotations" title="Permalink to this headline"></a></h2>
<dl class="exception-annotation">
<dt id="xanno-Default">
<tt class="descname">Default</tt><a class="headerlink" href="#xanno-Default" title="Permalink to this definition"></a></dt>
<dd>This boolean annotation specifies that the exception being defined will be
used as the default exception to be caught if a function or constructor
does not have a <tt class="docutils literal"><span class="pre">throw</span></tt> clause.</dd></dl>
<dl class="exception-annotation">
<dt id="xanno-PyName">
<tt class="descname">PyName</tt><a class="headerlink" href="#xanno-PyName" title="Permalink to this definition"></a></dt>
<dd>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.</dd></dl>
</div>
<div class="section" id="function-annotations">
<span id="ref-function-annos"></span><h2>Function Annotations<a class="headerlink" href="#function-annotations" title="Permalink to this headline"></a></h2>
<dl class="function-annotation">
<dt id="fanno-API">
<tt class="descname">API</tt><a class="headerlink" href="#fanno-API" title="Permalink to this definition"></a></dt>
<dd><p>
<span class="versionmodified">New in version 4.9.</span></p>
<p>This API range annotation is used to specify an API and corresponding
range of version numbers that the function is enabled for.</p>
<p>See <a class="reference external" href="using.html#ref-incompat-apis"><em>Managing Incompatible APIs</em></a> for more detail.</p>
</dd></dl>
<dl class="function-annotation">
<dt id="fanno-AutoGen">
<tt class="descname">AutoGen</tt><a class="headerlink" href="#fanno-AutoGen" title="Permalink to this definition"></a></dt>
<dd>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 external" href="directives.html#directive-%Feature"><tt class="xref docutils literal"><span class="pre">%Feature</span></tt></a> directive)
which must be enabled for the method to be generated.</dd></dl>
<dl class="function-annotation">
<dt id="fanno-Default">
<tt class="descname">Default</tt><a class="headerlink" href="#fanno-Default" title="Permalink to this definition"></a></dt>
<dd>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.</dd></dl>
<dl class="function-annotation">
<dt id="fanno-Deprecated">
<tt class="descname">Deprecated</tt><a class="headerlink" href="#fanno-Deprecated" title="Permalink to this definition"></a></dt>
<dd>This boolean annotation is used to specify that the constructor or function
is deprecated. A deprecation warning is issued whenever the constructor or
function is called.</dd></dl>
<dl class="function-annotation">
<dt id="fanno-DocType">
<tt class="descname">DocType</tt><a class="headerlink" href="#fanno-DocType" title="Permalink to this definition"></a></dt>
<dd><p>
<span class="versionmodified">New in version 4.10.</span></p>
<p>This string annotation specifies the name of the type of the returned value
as it will appear in any generated docstrings. It is usually used with
values of type <a class="reference external" href="specification_files.html#stype-SIP_PYOBJECT"><tt class="xref docutils literal"><span class="pre">SIP_PYOBJECT</span></tt></a> to provide a more specific type.</p>
</dd></dl>
<dl class="function-annotation">
<dt id="fanno-Factory">
<tt class="descname">Factory</tt><a class="headerlink" href="#fanno-Factory" title="Permalink to this definition"></a></dt>
<dd><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 external" href="using.html#ref-object-ownership"><em>Ownership of Objects</em></a> for more detail.</p>
</dd></dl>
<dl class="function-annotation">
<dt id="fanno-HoldGIL">
<tt class="descname">HoldGIL</tt><a class="headerlink" href="#fanno-HoldGIL" title="Permalink to this definition"></a></dt>
<dd>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 external" href="using.html#ref-gil"><em>The Python Global Interpreter Lock</em></a> and the <a class="reference internal" href="#fanno-ReleaseGIL"><tt class="xref docutils literal"><span class="pre">ReleaseGIL</span></tt></a> annotation.</dd></dl>
<dl class="function-annotation">
<dt id="fanno-KeywordArgs">
<tt class="descname">KeywordArgs</tt><a class="headerlink" href="#fanno-KeywordArgs" title="Permalink to this definition"></a></dt>
<dd><p>
<span class="versionmodified">New in version 4.10.</span></p>
<p>This boolean annotation specifies that the argument parser generated for
this function will support passing the parameters using Python&#8217;s keyword
argument syntax. Keyword arguments cannot be used for functions that have
unnamed arguments or use an ellipsis to designate that the function has a
variable number of arguments.</p>
</dd></dl>
<dl class="function-annotation">
<dt id="fanno-__len__">
<tt class="descname">__len__</tt><a class="headerlink" href="#fanno-__len__" title="Permalink to this definition"></a></dt>
<dd><p>
<span class="versionmodified">New in version 4.10.3.</span></p>
<p>This boolean annotation specifies that a <tt class="docutils literal"><span class="pre">__len__()</span></tt> method should be
automatically generated that will use the method being annotated to compute
the value that the <tt class="docutils literal"><span class="pre">__len__()</span></tt> method will return.</p>
</dd></dl>
<dl class="function-annotation">
<dt id="fanno-NewThread">
<tt class="descname">NewThread</tt><a class="headerlink" href="#fanno-NewThread" title="Permalink to this definition"></a></dt>
<dd>This boolean annotation specifies that the function will create a new
thread.</dd></dl>
<dl class="function-annotation">
<dt id="fanno-NoArgParser">
<tt class="descname">NoArgParser</tt><a class="headerlink" href="#fanno-NoArgParser" title="Permalink to this definition"></a></dt>
<dd>This boolean annotation is used with methods and global functions to
specify that the supplied <a class="reference external" href="directives.html#directive-%MethodCode"><tt class="xref docutils literal"><span class="pre">%MethodCode</span></tt></a> will handle the parsing
of the arguments.</dd></dl>
<dl class="function-annotation">
<dt id="fanno-NoCopy">
<tt class="descname">NoCopy</tt><a class="headerlink" href="#fanno-NoCopy" title="Permalink to this definition"></a></dt>
<dd><p>
<span class="versionmodified">New in version 4.10.1.</span></p>
<p>This boolean annotation is used with methods and global functions that
return a <tt class="docutils literal"><span class="pre">const</span></tt> reference to a class. Normally, if the class defines a
copy constructor then a copy of the returned reference is automatically
created and wrapped. The copy will be owned by Python.</p>
<p>If the annotation is specified then the copy is not made and the original
reference is wrapped instead and will be owned by C++.</p>
</dd></dl>
<dl class="function-annotation">
<dt id="fanno-NoDerived">
<tt class="descname">NoDerived</tt><a class="headerlink" href="#fanno-NoDerived" title="Permalink to this definition"></a></dt>
<dd>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 external" href="c_api.html#ref-derived-classes"><em>Generated Derived Classes</em></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.</dd></dl>
<dl class="function-annotation">
<dt id="fanno-NoKeywordArgs">
<tt class="descname">NoKeywordArgs</tt><a class="headerlink" href="#fanno-NoKeywordArgs" title="Permalink to this definition"></a></dt>
<dd><p>
<span class="versionmodified">New in version 4.10.</span></p>
<p>This boolean annotation specifies that the argument parser generated for
this function will not support passing the parameters using Python&#8217;s
keyword argument syntax. In other words, the argument parser will only
support only normal positional arguments. This annotation is useful when
the default setting of allowing keyword arguments has been changed via the
command line, but you would still like certain functions to only support
positional arguments.</p>
</dd></dl>
<dl class="function-annotation">
<dt id="fanno-Numeric">
<tt class="descname">Numeric</tt><a class="headerlink" href="#fanno-Numeric" title="Permalink to this definition"></a></dt>
<dd>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="xref docutils literal"><span class="pre">__getitem__()</span></tt>, <tt class="xref docutils literal"><span class="pre">__setitem__()</span></tt> or <tt class="xref 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.</dd></dl>
<dl class="function-annotation">
<dt id="fanno-PostHook">
<tt class="descname">PostHook</tt><a class="headerlink" href="#fanno-PostHook" title="Permalink to this definition"></a></dt>
<dd>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.</dd></dl>
<dl class="function-annotation">
<dt id="fanno-PreHook">
<tt class="descname">PreHook</tt><a class="headerlink" href="#fanno-PreHook" title="Permalink to this definition"></a></dt>
<dd>This name annotation is used to specify the name of a Python builtin that
is called immediately after the function&#8217;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.</dd></dl>
<dl class="function-annotation">
<dt id="fanno-PyName">
<tt class="descname">PyName</tt><a class="headerlink" href="#fanno-PyName" title="Permalink to this definition"></a></dt>
<dd>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.</dd></dl>
<dl class="function-annotation">
<dt id="fanno-ReleaseGIL">
<tt class="descname">ReleaseGIL</tt><a class="headerlink" href="#fanno-ReleaseGIL" title="Permalink to this definition"></a></dt>
<dd>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 external" href="using.html#ref-gil"><em>The Python Global Interpreter Lock</em></a> and the
<a class="reference internal" href="#fanno-HoldGIL"><tt class="xref docutils literal"><span class="pre">HoldGIL</span></tt></a> annotation.</dd></dl>
<dl class="function-annotation">
<dt id="fanno-Transfer">
<tt class="descname">Transfer</tt><a class="headerlink" href="#fanno-Transfer" title="Permalink to this definition"></a></dt>
<dd><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 to C++. It is only used in the context of a class
constructor or a method.</p>
<p>In the case of methods returned values (unless they are new references to
already wrapped values) are normally owned by C++ anyway. However, in
addition, an association between the returned value and the instance
containing the method is created with regard to the cyclic garbage
collector.</p>
<p>See <a class="reference external" href="using.html#ref-object-ownership"><em>Ownership of Objects</em></a> for more detail.</p>
</dd></dl>
<dl class="function-annotation">
<dt id="fanno-TransferBack">
<tt class="descname">TransferBack</tt><a class="headerlink" href="#fanno-TransferBack" title="Permalink to this definition"></a></dt>
<dd><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>See <a class="reference external" href="using.html#ref-object-ownership"><em>Ownership of Objects</em></a> for more detail.</p>
</dd></dl>
<dl class="function-annotation">
<dt id="fanno-TransferThis">
<tt class="descname">TransferThis</tt><a class="headerlink" href="#fanno-TransferThis" title="Permalink to this definition"></a></dt>
<dd><p>This boolean annotation specifies that ownership of <tt class="docutils literal"><span class="pre">this</span></tt> is transferred
from Python to C++.</p>
<p>See <a class="reference external" href="using.html#ref-object-ownership"><em>Ownership of Objects</em></a> for more detail.</p>
</dd></dl>
</div>
<div class="section" id="license-annotations">
<span id="ref-license-annos"></span><h2>License Annotations<a class="headerlink" href="#license-annotations" title="Permalink to this headline"></a></h2>
<dl class="license-annotation">
<dt id="lanno-Licensee">
<tt class="descname">Licensee</tt><a class="headerlink" href="#lanno-Licensee" title="Permalink to this definition"></a></dt>
<dd><p>This optional string annotation specifies the license&#8217;s licensee. No
restrictions are placed on the contents of the string.</p>
<p>See the <a class="reference external" href="directives.html#directive-%License"><tt class="xref docutils literal"><span class="pre">%License</span></tt></a> directive.</p>
</dd></dl>
<dl class="license-annotation">
<dt id="lanno-Signature">
<tt class="descname">Signature</tt><a class="headerlink" href="#lanno-Signature" title="Permalink to this definition"></a></dt>
<dd><p>This optional string annotation specifies the license&#8217;s signature. No
restrictions are placed on the contents of the string.</p>
<p>See the <a class="reference external" href="directives.html#directive-%License"><tt class="xref docutils literal"><span class="pre">%License</span></tt></a> directive.</p>
</dd></dl>
<dl class="license-annotation">
<dt id="lanno-Timestamp">
<tt class="descname">Timestamp</tt><a class="headerlink" href="#lanno-Timestamp" title="Permalink to this definition"></a></dt>
<dd><p>This optional string annotation specifies the license&#8217;s timestamp. No
restrictions are placed on the contents of the string.</p>
<p>See the <a class="reference external" href="directives.html#directive-%License"><tt class="xref docutils literal"><span class="pre">%License</span></tt></a> directive.</p>
</dd></dl>
<dl class="license-annotation">
<dt id="lanno-Type">
<tt class="descname">Type</tt><a class="headerlink" href="#lanno-Type" title="Permalink to this definition"></a></dt>
<dd><p>This string annotation specifies the license&#8217;s type. No restrictions are
placed on the contents of the string.</p>
<p>See the <a class="reference external" href="directives.html#directive-%License"><tt class="xref docutils literal"><span class="pre">%License</span></tt></a> directive.</p>
</dd></dl>
</div>
<div class="section" id="typedef-annotations">
<span id="ref-typedef-annos"></span><h2>Typedef Annotations<a class="headerlink" href="#typedef-annotations" title="Permalink to this headline"></a></h2>
<dl class="typedef-annotation">
<dt id="tanno-NoTypeName">
<tt class="descname">NoTypeName</tt><a class="headerlink" href="#tanno-NoTypeName" title="Permalink to this definition"></a></dt>
<dd><p>This boolean annotation specifies that the definition of the type rather
than the name of the type being defined should be used in the generated
code.</p>
<p>Normally a typedef would be defined as follows:</p>
<div class="highlight-python"><pre>typedef bool MyBool;</pre>
</div>
<p>This would result in <tt class="docutils literal"><span class="pre">MyBool</span></tt> being used in the generated code.</p>
<p>Specifying the annotation means that <tt class="docutils literal"><span class="pre">bool</span></tt> will be used in the generated
code instead.</p>
</dd></dl>
</div>
<div class="section" id="variable-annotations">
<span id="ref-variable-annos"></span><h2>Variable Annotations<a class="headerlink" href="#variable-annotations" title="Permalink to this headline"></a></h2>
<dl class="variable-annotation">
<dt id="vanno-DocType">
<tt class="descname">DocType</tt><a class="headerlink" href="#vanno-DocType" title="Permalink to this definition"></a></dt>
<dd><p>
<span class="versionmodified">New in version 4.10.</span></p>
<p>This string annotation specifies the name of the type of the variable as it
will appear in any generated docstrings. It is usually used with variables
of type <a class="reference external" href="specification_files.html#stype-SIP_PYOBJECT"><tt class="xref docutils literal"><span class="pre">SIP_PYOBJECT</span></tt></a> to provide a more specific type.</p>
</dd></dl>
<dl class="variable-annotation">
<dt id="vanno-PyName">
<tt class="descname">PyName</tt><a class="headerlink" href="#vanno-PyName" title="Permalink to this definition"></a></dt>
<dd>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.</dd></dl>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference external" href="#">Annotations</a><ul>
<li><a class="reference external" href="#argument-annotations">Argument Annotations</a></li>
<li><a class="reference external" href="#class-annotations">Class Annotations</a></li>
<li><a class="reference external" href="#mapped-type-annotations">Mapped Type Annotations</a></li>
<li><a class="reference external" href="#enum-annotations">Enum Annotations</a></li>
<li><a class="reference external" href="#exception-annotations">Exception Annotations</a></li>
<li><a class="reference external" href="#function-annotations">Function Annotations</a></li>
<li><a class="reference external" href="#license-annotations">License Annotations</a></li>
<li><a class="reference external" href="#typedef-annotations">Typedef Annotations</a></li>
<li><a class="reference external" href="#variable-annotations">Variable Annotations</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="directives.html"
title="previous chapter">Directives</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="c_api.html"
title="next chapter">C API for Handwritten Code</a></p>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" size="18" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="modindex.html" title="Global Module Index"
>modules</a> |</li>
<li class="right" >
<a href="c_api.html" title="C API for Handwritten Code"
>next</a> |</li>
<li class="right" >
<a href="directives.html" title="Directives"
>previous</a> |</li>
<li><a href="index.html">SIP 4.10.5 Reference Guide</a> &raquo;</li>
</ul>
</div>
<div class="footer">
&copy; Copyright 2010 Riverbank Computing Limited.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.4.
</div>
</body>
</html>

File diff suppressed because it is too large Load Diff

@ -0,0 +1,138 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"