Initial import of SIP4 for Qt3
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,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>.
|
||||
|
||||
-------------------------------------------------------------------------
|
||||
@ -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 — 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> »</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">"None"</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">"ASCII"</span></tt>,
|
||||
<tt class="docutils literal"><span class="pre">"Latin-1"</span></tt>, <tt class="docutils literal"><span class="pre">"UTF-8"</span></tt> or <tt class="docutils literal"><span class="pre">"None"</span></tt>. An encoding of <tt class="docutils literal"><span class="pre">"None"</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">"None"</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">"None"</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’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’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> – 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’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’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’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’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’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’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’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’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’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’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> »</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="footer">
|
||||
© 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"
|
||||