PSEP Index
+ +| PSEP: | 0 |
|---|---|
| Title: | Index of PySide Enhancement Proposals (PSEPs) |
| Last-Modified: | 02-Nov-2011 |
| Author: | Matti Airas <matti.p.airas at nokia.com>, |
| Status: | Active |
| Type: | Informational |
| Created: | 24-Sep-2009 |
+
Introduction
++ The PSEP contains the index of all PySide Enhancement Proposals, + known as PSEPs. PSEP numbers are assigned by the PSEP Editor, and + once assigned are never changed. The Git history[1] of the PSEP + texts represent their historical record. + + ++
Index by Category
++ num title owner + --- ----- ----- + + Meta-PSEPs (PSEPs about PSEPs or Processes) + + P 1 PSEP Purpose and Guidelines Airas + P 5 Guidelines for implementing backwards-incompatible ... Airas + P 12 Sample reStructuredText PSEP Template Airas + + Other Informational PSEPs + + + Accepted PSEPs (accepted; may not be implemented yet) + + SA 103 Support for declaring Qt meta-object properties Airas + SA 106 Shiboken helper module Lima + + Open PSEPs (under consideration) + + S 102 Use Python properties instead of getters and setters Lima + S 104 Decorator syntax for declaring Qt meta-object ... Airas + + Finished PSEPs (done, implemented in code repository) + + SF 100 New-style Signals and Slots Airas + SF 101 Adopt PyQt's API 2 for PySide Summerfield + + Deferred, Abandoned, Withdrawn, and Rejected PSEPs + + + + Numerical Index + + num title owner + --- ----- ----- + P 1 PSEP Purpose and Guidelines Airas + + P 5 Guidelines for implementing backwards-incompatible ... Airas + + P 12 Sample reStructuredText PSEP Template Airas + + SF 100 New-style Signals and Slots Airas + SF 101 Adopt PyQt's API 2 for PySide Summerfield + S 102 Use Python properties instead of getters and setters Lima + SA 103 Support for declaring Qt meta-object properties Airas + S 104 Decorator syntax for declaring Qt meta-object ... Airas + + SA 106 Shiboken helper module Lima + + ++
Key
++ S - Standards Track PSEP + I - Informational PSEP + P - Process PSEP + + A - Accepted proposal + R - Rejected proposal + W - Withdrawn proposal + D - Deferred proposal + F - Final proposal + A - Active proposal + D - Draft proposal + R - Replaced proposal + + ++
Owners
++ name email address + ---- ------------- + Airas, Matti matti.p.airas at nokia.com + Lima, Hugo Parente hugo.lima at openbossa.org + Summerfield, Mark mark at qtrac.eu + + ++
References
++ [1] View PSEP history online + http://qt.gitorious.org/pyside/pseps/trees/master + + ++
+ 
+ 
+ 
+ PSEP 0001
+ +| PSEP: | 1 | +
|---|---|
| Title: | PSEP Purpose and Guidelines | +
| Version: | 1 | +
| Last-Modified: | 15-Aug-2011 | +
| Author: | Matti Airas | +
| Status: | Active | +
| Type: | Process | +
| Content-Type: | text/x-rst | +
| Created: | 23-Sep-2009 | +
+
Contents
+-
+
- What is a PSEP? +
- PSEP Types +
- PSEP Work Flow +
- What belongs in a successful PSEP? +
- PSEP Formats and Templates +
- PSEP Header Preamble +
- Auxiliary Files +
- Reporting PSEP Bugs, or Submitting PSEP Updates +
- Transferring PSEP Ownership +
- PSEP Editor Responsibilities & Workflow +
- References and Footnotes +
- Copyright +
What is a PSEP?
+PSEP stands for PySide Enhancement Proposal. A PSEP is a design +document providing information to the PySide community, or describing +a new feature for PySide or its processes or environment. The PSEP +should provide a concise technical specification of the feature and a +rationale for the feature.
+We intend PSEPs to be the primary mechanisms for proposing new +features, for collecting community input on an issue, and for +documenting the design decisions that have gone into PySide. The PSEP +author is responsible for building consensus within the community and +documenting dissenting opinions.
+Because the PSEPs are maintained as text files in a versioned +repository, their revision history is the historical record of the +feature proposal [1].
+The whole PSEP process has been copied verbatim from Python's PEP +(Python Enhancement Proposal) process, and this document has been +adapted to PSEP by Matti Airas from PEP 1 by Barry Warsaw, Jeremy +Hylton, and David Goodger.
+PSEP Types
+There are three kinds of PSEP:
+-
+
- A Standards Track PSEP describes a new feature or implementation +for PySide. +
- An Informational PSEP describes a PySide design issue, or +provides general guidelines or information to the PySide community, +but does not propose a new feature. Informational PSEPs do not +necessarily represent a PySide community consensus or +recommendation, so users and implementors are free to ignore +Informational PSEPs or follow their advice. +
- A Process PSEP describes a process surrounding PySide, or +proposes a change to (or an event in) a process. Process PSEPs are +like Standards Track PSEPs but apply to areas other than the PySide +itself. They may propose an implementation, but not to +PySide's codebase; they often require community consensus; unlike +Informational PSEPs, they are more than recommendations, and users +are typically not free to ignore them. Examples include +procedures, guidelines, changes to the decision-making process, and +changes to the tools or environment used in Python development. +Any meta-PSEP is also considered a Process PSEP. +
PSEP Work Flow
+The PSEP editors assign PSEP numbers and change their status. The +current PSEP editor is Matti Airas. Please send +all PSEP-related email to <pyside@lists.openbossa.org> (no cross-posting please). +Also see PSEP Editor Responsibilities & Workflow below.
+The PSEP process begins with a new idea for PySide. It is highly +recommended that a single PSEP contain a single key proposal or new +idea. The more focussed the PSEP, the more successful it tends to +be. The PSEP editor reserves the right to reject PSEP proposals if they +appear too unfocussed or too broad. If in doubt, split your PSEP into +several well-focussed ones.
+Each PSEP must have a champion -- someone who writes the PSEP using the +style and format described below, shepherds the discussions in the +appropriate forums, and attempts to build community consensus around the +idea. The PSEP champion (a.k.a. Author) should first attempt to +ascertain whether the idea is PSEP-able. Posting to the +pyside@lists.openbossa.org mailing list is recommended. Enhancements not +resulting in API changes usually don't need a PSEP and can be injected +into the PySide development work flow with a patch submission to the +PySide issue tracker [4].
+The PSEP champion then emails the PSEP editor <pyside@lists.openbossa.org> with a +proposed title and a rough, but fleshed out, draft of the PSEP. This +draft must be written in PSEP style as described below.
+If the PSEP editor approves, he will assign the PSEP a number, label it +as Standards Track, Informational, or Process, give it status "Draft", +and create and check-in the initial draft of the PSEP. The PSEP editor +will not unreasonably deny a PSEP. Reasons for denying PSEP status +include duplication of effort, being technically unsound, not providing +proper motivation or addressing backwards compatibility, or not in +keeping with the PySide philosophy. The TBC (Temporary Benevolent +Committee, consisting of the core dev team and Matti Airas) can be consulted +during the approval phase, and is the final arbiter of the draft's +PSEP-ability.
+If a pre-PSEP is rejected, the author may elect to take the pre-PSEP to +the pyside@lists.openbossa.org mailing list to help flesh it out, gain feedback +and consensus from the community at large, and improve the PSEP for +re-submission.
+The author of the PSEP is then responsible for posting the PSEP to the +community forums, and marshaling community support for it. As updates +are necessary, the PSEP author can check in new versions if they have +SVN commit permissions, or can email new PSEP versions to the PSEP +editor for committing.
+Standards Track PSEPs consist of two parts, a design document and a +reference implementation. The PSEP should be reviewed and accepted +before a reference implementation is begun, unless a reference +implementation will aid people in studying the PSEP. Standards Track +PSEPs must include an implementation -- in the form of code, a patch, +or a URL to same -- before it can be considered Final.
+PSEP authors are responsible for collecting community feedback on a PSEP +before submitting it for review. A PSEP that has not been discussed on +pyside@lists.openbossa.org will not be +accepted. However, wherever possible, long open-ended discussions on +public mailing lists should be avoided. Strategies to keep the +discussions efficient include: setting up a separate SIG mailing list +for the topic, having the PSEP author accept private comments in the +early design phases, setting up a wiki page, etc. PSEP authors should +use their discretion here.
+Once the authors have completed a PSEP, they must inform the PSEP editor +that it is ready for review. PSEPs are reviewed by the TBC, who may +accept or reject a PSEP or send it back to the author(s) for revision. +For a PSEP that is pre-determined to be acceptable (e.g., it is an +obvious win as-is and/or its implementation has already been checked in) +the TBC may also initiate a PSEP review, first notifying the PSEP +author(s) and giving them a chance to make revisions.
+For a PSEP to be accepted it must meet certain minimum criteria. It +must be a clear and complete description of the proposed enhancement. +The enhancement must represent a net improvement. The proposed +implementation, if applicable, must be solid and must not complicate the +interpreter unduly. Finally, a proposed enhancement must properly +balance the "pythonicity" and "Qt-likeness" in order to be accepted by +the TBC. (However, "pythonic" and "Qt-likeness" are imprecise terms; +they may be defined as whatever is acceptable to the TBC. This logic is +intentionally circular.)
+Once a PSEP has been accepted, the reference implementation must be +completed. When the reference implementation is complete and accepted +by the TBC, the status will be changed to "Final".
+A PSEP can also be assigned status "Deferred". The PSEP author or +editor can assign the PSEP this status when no progress is being made +on the PSEP. Once a PSEP is deferred, the PSEP editor can re-assign it +to draft status.
+A PSEP can also be "Rejected". Perhaps after all is said and done it +was not a good idea. It is still important to have a record of this +fact.
+PSEPs can also be replaced by a different PSEP, rendering the original +obsolete. This is intended for Informational PSEPs, where version 2 of +an API can replace version 1.
+The possible paths of the status of PSEPs are as follows:
+
+Some Informational and Process PSEPs may also have a status of "Active" +if they are never meant to be completed. E.g. PSEP 1 (this PSEP).
+What belongs in a successful PSEP?
+Each PSEP should have the following parts:
+-
+
Preamble -- RFC 822 style headers containing meta-data about the +PSEP, including the PSEP number, a short descriptive title (limited +to a maximum of 44 characters), the names, and optionally the +contact info for each author, etc.
+
+Abstract -- a short (~200 word) description of the technical issue +being addressed.
+
+Copyright/public domain -- Each PSEP must either be explicitly +labelled as placed in the public domain (see this PSEP as an +example) or licensed under the Open Publication License [5].
+
+Specification -- The technical specification should describe the +syntax and semantics of any new API feature. The +specification should be detailed enough to allow competing, +interoperable implementations for any of the current Python Qt +bindings.
+
+Motivation -- The motivation is critical for PSEPs that want to +change the PySide API. It should clearly explain why the +existing API is inadequate to address the +problem that the PSEP solves. PSEP submissions without sufficient +motivation may be rejected outright.
+
+Rationale -- The rationale fleshes out the specification by +describing what motivated the design and why particular design +decisions were made. It should describe alternate designs that +were considered and related work, e.g. how the feature is supported +in other languages.
+The rationale should provide evidence of consensus within the +community and discuss important objections or concerns raised +during discussion.
+
+Backwards Compatibility -- All PSEPs that introduce backwards +incompatibilities must include a section describing these +incompatibilities and their severity. The PSEP must explain how the +author proposes to deal with these incompatibilities. PSEP +submissions without a sufficient backwards compatibility treatise +may be rejected outright.
+
+Reference Implementation -- The reference implementation must be +completed before any PSEP is given status "Final", but it need not +be completed before the PSEP is accepted. It is better to finish +the specification and rationale first and reach consensus on it +before writing code.
+The final implementation must include test code and documentation +appropriate for either the PySide API reference or the respective +generator tool reference.
+
+
PSEP Formats and Templates
+As opposed to PEP, there is only one PSEP format available to authors: +reStructuredText [6]. ReStructuredText [6] PSEPs allow for rich markup that +is still quite easy to read, but results in much better-looking and more +functional HTML. PSEP 12 contains instructions and a template [2] for +reStructuredText PSEPs.
+There is a Python script that converts PSEPs to HTML for +viewing on the web [3]. reStructuredText PSEPs are parsed +and converted by Docutils [7] code called from the script.
+PSEP Header Preamble
+Each PSEP must begin with an RFC 822 style header preamble. The headers +must appear in the following order. Headers marked with "*" are +optional and are described below. All other headers are required.
+PSEP: <psep number> + Title: <psep title> + Last-Modified: <svn date string> + Author: <list of authors' real names and optionally, email addrs> +* Discussions-To: <email address> + Status: <Draft | Active | Accepted | Deferred | Rejected | + Withdrawn | Final | Replaced> + Type: <Standards Track | Informational | Process> +* Content-Type: <text/plain | text/x-rst> +* Requires: <psep numbers> + Created: <date created on, in dd-mmm-yyyy format> +* Python-Version: <version number> + Post-History: <dates of postings to python-list and python-dev> +* Replaces: <psep number> +* Replaced-By: <psep number> ++
The Author header lists the names, and optionally the email addresses +of all the authors/owners of the PSEP. The format of the Author header +value must be
++Random J. User <address@dom.ain>+
if the email address is included, and just
++Random J. User+
if the address is not given. New PSEPs must use the mandated format +above.
+If there are multiple authors, each should be on a separate line +following RFC 2822 continuation line conventions. Note that personal +email addresses in PSEPs will be obscured as a defense against spam +harvesters.
+While a PSEP is in private discussions (usually during the initial +Draft phase), a Discussions-To header will indicate the mailing list +or URL where the PSEP is being discussed. No Discussions-To header is +necessary if the PSEP is being discussed privately with the author, or +on the pyside@lists.openbossa.org mailing list. Note that email +addresses in the Discussions-To header will not be obscured.
+The Type header specifies the type of PSEP: Standards Track, +Informational, or Process.
+The format of a PSEP is specified with a Content-Type header. The only +acceptable values is "text/x-rst" for reStructuredText PSEPs (see PSEP +12 [2]).
+The Created header records the date that the PSEP was assigned a +number, while Post-History is used to record the dates of when new +versions of the PSEP are posted to python-list and/or python-dev. Both +headers should be in dd-mmm-yyyy format, e.g. 14-Aug-2001.
+TODO: How should we deal with different Python, Qt, and PySide versions?
+Standards Track PSEPs must have a Python-Version header which indicates +the version of Python that the feature will be released with. +Informational and Process PSEPs do not need a Python-Version header.
+PSEPs may have a Requires header, indicating the PSEP numbers that this +PSEP depends on.
+PSEPs may also have a Replaced-By header indicating that a PSEP has been +rendered obsolete by a later document; the value is the number of the +PSEP that replaces the current document. The newer PSEP must have a +Replaces header containing the number of the PSEP that it rendered +obsolete.
+Auxiliary Files
+PSEPs may include auxiliary files such as diagrams. Such files must be +named psep-XXXX-Y.ext, where "XXXX" is the PSEP number, "Y" is a +serial number (starting at 1), and "ext" is replaced by the actual +file extension (e.g. "png").
+Reporting PSEP Bugs, or Submitting PSEP Updates
+How you report a bug, or submit a PSEP update depends on several +factors, such as the maturity of the PSEP, the preferences of the PSEP +author, and the nature of your comments. For the early draft stages +of the PSEP, it's probably best to send your comments and changes +directly to the PSEP author. For more mature, or finished PSEPs you may +want to submit corrections to the PySide issue tracker [4] so that your +changes don't get lost. If the PSEP author is a PySide developer, assign the +bug/patch to him, otherwise assign it to the PSEP editor.
+When in doubt about where to send your changes, please check first +with the PSEP author and/or PSEP editor.
+PSEP authors who have write permissions to the Gitorious repository can +push the changes to the repository themselves.
+Transferring PSEP Ownership
+It occasionally becomes necessary to transfer ownership of PSEPs to a +new champion. In general, we'd like to retain the original author as +a co-author of the transferred PSEP, but that's really up to the +original author. A good reason to transfer ownership is because the +original author no longer has the time or interest in updating it or +following through with the PSEP process, or has fallen off the face of +the 'net (i.e. is unreachable or not responding to email). A bad +reason to transfer ownership is because you don't agree with the +direction of the PSEP. We try to build consensus around a PSEP, but if +that's not possible, you can always submit a competing PSEP.
+If you are interested in assuming ownership of a PSEP, send a message +asking to take over, addressed to both the original author and the PSEP +editor <pyside@lists.openbossa.org>. If the original author doesn't respond to +email in a timely manner, the PSEP editor will make a unilateral +decision (it's not like such decisions can't be reversed :).
+PSEP Editor Responsibilities & Workflow
+A PSEP editor must subscribe to the <pyside@lists.openbossa.org> list. All +PSEP-related correspondence should be sent (or CC'd) to +<pyside@lists.openbossa.org> (but please do not cross-post!).
+For each new PSEP that comes in an editor does the following:
+-
+
- Read the PSEP to check if it is ready: sound and complete. The ideas +must make technical sense, even if they don't seem likely to be +accepted. +
- The title should accurately describe the content. +
- Edit the PSEP for language (spelling, grammar, sentence structure, +etc.), markup (for reST PSEPs), code style (examples should match PSEP +8 & 7). +
If the PSEP isn't ready, the editor will send it back to the author for +revision, with specific instructions.
+Once the PSEP is ready for the repository, the PSEP editor will:
+-
+
- Assign a PSEP number (almost always just the next available number, +but sometimes it's a special/joke number, like 666 or 3141). +
- List the PSEP in PSEP 0 (in two places: the categorized list, and the +numeric list). +
- Add the PSEP to the Git repository. To clone a copy of the Git +repository, see the PySide Gitorious page. +
- Monitor python.org to make sure the PSEP gets added to the site +properly. +
- Send email back to the PSEP author with next steps (post to +pyside@lists.openbossa.org). +
Updates to existing PSEPs also come in to pyside@lists.openbossa.org. +Alternatively, Gitorious merge requests may be made directly.
+Many PSEPs are written and maintained by developers with write access to +the PySide repository. The PSEP editors monitor the repository PSEP +changes, and correct any structure, grammar, spelling, or markup +mistakes we see.
+The editors don't pass judgement on PSEPs. We merely do the +administrative & editorial part. Except for times like this, there's +relatively low volume.
+References and Footnotes
+| [1] | This historical record is available by the normal Git commands +for retrieving older revisions. For those without direct access to +the Git tree, you can browse the current and past PSEP revisions here: +http://qt.gitorious.org/pyside/pseps |
| [2] | (1, 2) PEP 12, Sample reStructuredText PSEP Template, Goodger, Warsaw +(http://www.python.org/dev/peps/pep-0012) |
| [3] | The script referred to here is pep2pyramid.py, the successor to +pep2html.py, both of which live in the same directory in the Git +tree as the PEPs themselves. Try pep2html.py --help for +details. The URL for viewing PEPs on the web is +http://www.python.org/dev/peps/. |
| [4] | (1, 2) http://bugs.openbossa.org/ |
| [5] | http://www.opencontent.org/openpub/ |
| [6] | (1, 2) http://docutils.sourceforge.net/rst.html |
| [7] | http://docutils.sourceforge.net/ |
Copyright
+This document has been placed in the public domain.
+ +
+
+
+
+ PSEP 0005
+ +| PSEP: | 5 | +
|---|---|
| Title: | Guidelines for implementing backwards-incompatible changes | +
| Version: | $Revision$ | +
| Last-Modified: | $Date$ | +
| Author: | Matti Airas <matti.p.airas at nokia.com> | +
| Status: | Active | +
| Type: | Process | +
| Content-Type: | text/x-rst | +
| Created: | 06-Oct-2009 | +
+
Contents
+ +Abstract
+There exists a strong interest for implementing new, partially +backwards-incompatible API features to PySide. However, simply modifying +the existing API would break any existing applications, so such +modifications need to be done in a controlled manner. This PSEP sets the +guidelines for implementing backwards-incompatible changes in PySide.
+Introduction
+The idea of improving the PySide API by making it more Pythonic was +presented already during the project launch. Soon thereafter, several +ideas were discussed, but at that point the design process and a clear +implementation roadmap was still undefined.
+The planned API update coincides temporally with plans to implement Python 3 +support in PySide. While these changes do not necessarily depend on each other, +Python 3 requires considerable changes in PySide and is backwards-incompatible +by itself. As the API changes have a similar scope, special emphasis will be +placed on whether or not to perform both of the non-backward compatible changes +together.
+This PSEP discusses the different proposed update strategies together +with their pros and cons and then proceeds to select one specific +strategy for the PySide API updates.
+API Update Strategies
+Changing the existing API
+The simplest method of updating the API is just to change the existing +API. This is obviously very simple for the developers, and there exists +only one API at any given time. However, any existing applications +depending on PySide would need to be constantly updated. Any amount of +such changes would in practice discourage any developers from using +PySide, and therefore, this approach would only be possible at the very +early stages of any project when there are not yet any applications +using the project.
+Coinciding the API break with Python 3 transition
+Python 3 is backwards incompatible with older Python versions both at +the syntax and the standard library API levels. Since the users would +need to adapt their code in any case, the thought of simultaneously +updating the PySide API is an enticing one. The approach is tempting +also from the API developers' perspective. Since Python 3 breaks the +extension API compatibility in any case, this strategy cleanly splits +the code to the old and the new APIs under the hood as well.
+On the other hand, one might argue that the tandem update strategy will +actually be more difficult to implement in practice. Not only will there +be changes due to the Python 3 transition, but the visible API behaviour +will be changed as well. In practice, the two changes would need to be +performed sequentially to implement the features in a controlled manner.
+The tandem update strategy would lead to a difficult upgrade path for +existing applications. The recommended development model for upgrading +from Python 2 to 3 is to utilize a specific 2to3 script to convert +the script from Python 2.6 to the 3 syntax [2]. This will not +work if the APIs are modified in an incompatible manner at the same +time. With the library APIs breaking simultaneously, the developer would +have no idea whether the problems in his application are due to the +Python or the PySide changes.
+When considering the alternatives, it is of importance that the tandem +update strategy has been discouraged by Python core developers +[1], to a great extent due to the reasons discussed +above.
+Separate imports for different API versions
+The final API upgrade strategy is to disconnect the upgrade altogether +from the Python version upgrade. In this case, the +backwards-incompatible API would be placed in its own module. For +example, the current QtCore library is imported using:
++import PySide.QtCore ++
The new API would then utilize a different import:
++import PySideFoo.QtCoreBar ++
This approach might arguably actually simplify implementing the new +features as they would be only simple steps on top of the old API. +Furthermore, Python 3 porting would only focus on the extension API +differences instead of mixing the PySide API changes in the issue. +For users, separate imports would provide for a standard upgrade path, +removing any extra barriers for upgrading to Python 3.
+The main drawback in this approach is the potentially increased +maintenance effort. Two sets of APIs on two major Python versions need +to be maintained. This may tie down the developers and decrease general +project velocity.
+Selected API update strategy
+From the update strategy alternatives discussed in the previous section, +the last one (separate imports for different API versions) will be +chosen as the PySide update strategy. Having separate imports provides +the safest upgrade path both for the internal PySide developers and for +any projects depending on PySide. Any specifics such as the new import +names will be dealt with in a separate PSEP.
+References
+| [1] | Python 3000 and You, Van Rossum +(http://www.artima.com/weblogs/viewpost.jsp?thread=227041) |
| [2] | PEP 3000, Van Rossum +(http://www.python.org/dev/peps/pep-3000/) |
Copyright
+This document has been placed in the public domain.
+ +
+
+
+
+ PSEP 0012
+ +| PSEP: | 12 | +
|---|---|
| Title: | Sample reStructuredText PSEP Template | +
| Version: | $Revision$ | +
| Last-Modified: | $Date$ | +
| Author: | Matti Airas <matti.p.airas at nokia.com> | +
| Status: | Active | +
| Type: | Process | +
| Content-Type: | text/x-rst | +
| Created: | 25-Sep-2009 | +
+
Contents
+ +Abstract
+This PSEP provides a boilerplate or sample template for creating your +own reStructuredText PSEPs. In conjunction with the content guidelines +in PSEP 1 [1], this should make it easy for you to conform your own +PSEPs to the format outlined below.
+Note: if you are reading this PSEP via the web, you should first grab +the text (reStructuredText) source of this PSEP in order to complete +the steps below. DO NOT USE THE HTML FILE AS YOUR TEMPLATE!
+To get the source this (or any) PSEP, look at the top of the HTML page +and click on the date & time on the "Last-Modified" line. It is a +link to the source text in the PySide repository.
+This PSEP has been adapted (mostly copied verbatim) from PEP 12.
+Rationale
+PSEP submissions come in a wide variety of forms, not all adhering +to the format guidelines set forth below. Use this template, in +conjunction with the format guidelines below, to ensure that your +PSEP submission won't get automatically rejected because of form.
+ReStructuredText is offered as an alternative to plaintext PSEPs, to +allow PSEP authors more functionality and expressivity, while +maintaining easy readability in the source text. The processed HTML +form makes the functionality accessible to readers: live hyperlinks, +styled text, tables, images, and automatic tables of contents, among +other advantages. For an example of a PEP marked up with +reStructuredText, see PEP 287.
+How to Use This Template
+To use this template you must first decide whether your PSEP is going +to be an Informational or Standards Track PSEP. Most PSEPs are +Standards Track because they propose a new feature for the PySide +language or standard library. When in doubt, read PSEP 1 for details +or contact the PSEP editors <pyside@lists.openbossa.org>.
+Once you've decided which type of PSEP yours is going to be, follow the +directions below.
+-
+
Make a copy of this file (.txt file, not HTML!) and perform +the following edits.
+
+Replace the "PSEP: 12" header with "PSEP: XXX" since you don't yet have +a PSEP number assignment.
+
+Change the Title header to the title of your PSEP.
+
+Leave the Version and Last-Modified headers alone; we'll take care +of those when we check your PSEP into PySide's Git repository. +These headers consist of keywords ("Revision" and "Date" enclosed in +"$"-signs) which are automatically expanded by the repository. +Please do not edit the expanded date or revision text.
+
+Change the Author header to include your name, and optionally your +email address. Be sure to follow the format carefully: your name +must appear first, and it must not be contained in parentheses. +Your email address may appear second (or it can be omitted) and if +it appears, it must appear in angle brackets. It is okay to +obfuscate your email address.
+
+If there is a mailing list for discussion of your new feature, add a +Discussions-To header right after the Author header. You should not add a +Discussions-To header if the mailing list to be used is +pyside@lists.openbossa.org, or if discussions should be sent to you directly. +Most Informational PSEPs don't have a Discussions-To header.
+
+Change the Status header to "Draft".
+
+For Standards Track PSEPs, change the Type header to "Standards +Track".
+
+For Informational PSEPs, change the Type header to "Informational".
+
+For Standards Track PSEPs, if your feature depends on the acceptance +of some other currently in-development PSEP, add a Requires header +right after the Type header. The value should be the PSEP number of +the PSEP yours depends on. Don't add this header if your dependent +feature is described in a Final PSEP.
+
+Change the Created header to today's date. Be sure to follow the +format carefully: it must be in dd-mmm-yyyy format, where the +mmm is the 3 English letter month abbreviation, i.e. one of Jan, +Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec.
+
+For Standards Track PSEPs, after the Created header, add a +Python-Version header and set the value to the next planned version +of Python, i.e. the one your new feature will hopefully make its +first appearance in. Do not use an alpha or beta release +designation here. Thus, if the last version of Python was 2.2 alpha +1 and you're hoping to get your new feature into Python 2.2, set the +header to:
++Python-Version: 2.2 +
+TODO: How to deal with different PySide/Qt/Python versions?
+
+Leave Post-History alone for now; you'll add dates to this header each time +you post your PSEP to pyside@lists.openbossa.org. If you posted your PSEP to +the lists on August 14, 2001 and September 3, 2001, the Post-History header +would look like:
++Post-History: 14-Aug-2001, 03-Sept-2001 +
+You must manually add new dates and check them in. If you don't +have check-in privileges, send your changes to the PSEP editors.
+
+Add a Replaces header if your PSEP obsoletes an earlier PSEP. The +value of this header is the number of the PSEP that your new PSEP is +replacing. Only add this header if the older PSEP is in "final" +form, i.e. is either Accepted, Final, or Rejected. You aren't +replacing an older open PSEP if you're submitting a competing idea.
+
+Now write your Abstract, Rationale, and other content for your PSEP, +replacing all this gobbledygook with your own text. Be sure to +adhere to the format guidelines below, specifically on the +prohibition of tab characters and the indentation requirements.
+
+Update your References and Copyright section. Usually you'll place +your PSEP into the public domain, in which case just leave the +Copyright section alone. Alternatively, you can use the Open +Publication License [5], but public domain is still strongly +preferred.
+
+Leave the Emacs stanza at the end of this file alone, including the +formfeed character ("^L", or \f).
+
+Send your PSEP submission to the PSEP editors at pyside@lists.openbossa.org.
+
+
ReStructuredText PSEP Formatting Requirements
+The following is a PSEP-specific summary of reStructuredText syntax. +For the sake of simplicity and brevity, much detail is omitted. For +more detail, see Resources below. Literal blocks (in which no +markup processing is done) are used for examples throughout, to +illustrate the plaintext markup.
+General
+You must adhere to the Emacs convention of adding two spaces at the +end of every sentence. You should fill your paragraphs to column 70, +but under no circumstances should your lines extend past column 79. +If your code samples spill over column 79, you should rewrite them.
+Tab characters must never appear in the document at all. A PSEP should +include the standard Emacs stanza included by example at the bottom of +this PSEP.
+Section Headings
+PSEP headings must begin in column zero and the initial letter of each +word must be capitalized as in book titles. Acronyms should be in all +capitals. Section titles must be adorned with an underline, a single +repeated punctuation character, which begins in column zero and must +extend at least as far as the right edge of the title text (4 +characters minimum). First-level section titles are underlined with +"=" (equals signs), second-level section titles with "-" (hyphens), +and third-level section titles with "'" (single quotes or +apostrophes). For example:
++First-Level Title +================= + +Second-Level Title +------------------ + +Third-Level Title +''''''''''''''''' ++
If there are more than three levels of sections in your PSEP, you may +insert overline/underline-adorned titles for the first and second +levels as follows:
++============================ +First-Level Title (optional) +============================ + +----------------------------- +Second-Level Title (optional) +----------------------------- + +Third-Level Title +================= + +Fourth-Level Title +------------------ + +Fifth-Level Title +''''''''''''''''' ++
You shouldn't have more than five levels of sections in your PSEP. If +you do, you should consider rewriting it.
+You must use two blank lines between the last line of a section's body +and the next section heading. If a subsection heading immediately +follows a section heading, a single blank line in-between is +sufficient.
+The body of each section is not normally indented, although some +constructs do use indentation, as described below. Blank lines are +used to separate constructs.
+Paragraphs
+Paragraphs are left-aligned text blocks separated by blank lines. +Paragraphs are not indented unless they are part of an indented +construct (such as a block quote or a list item).
+Inline Markup
+Portions of text within paragraphs and other text blocks may be +styled. For example:
++Text may be marked as *emphasized* (single asterisk markup, +typically shown in italics) or **strongly emphasized** (double +asterisks, typically boldface). ``Inline literals`` (using double +backquotes) are typically rendered in a monospaced typeface. No +further markup recognition is done within the double backquotes, +so they're safe for any kind of code snippets. ++
Block Quotes
+Block quotes consist of indented body elements. For example:
++This is a paragraph. + + This is a block quote. + + A block quote may contain many paragraphs. ++
Block quotes are used to quote extended passages from other sources. +Block quotes may be nested inside other body elements. Use 4 spaces +per indent level.
+Literal Blocks
+ +Literal blocks are used for code samples or preformatted ASCII art. To +indicate a literal block, preface the indented text block with +"::" (two colons). The literal block continues until the end of +the indentation. Indent the text block by 4 spaces. For example:
++This is a typical paragraph. A literal block follows. + +:: + + for a in [5,4,3,2,1]: # this is program code, shown as-is + print a + print "it's..." + # a literal block continues until the indentation ends ++
The paragraph containing only "::" will be completely removed from +the output; no empty paragraph will remain. "::" is also +recognized at the end of any paragraph. If immediately preceded by +whitespace, both colons will be removed from the output. When text +immediately precedes the "::", one colon will be removed from +the output, leaving only one colon visible (i.e., "::" will be +replaced by ":"). For example, one colon will remain visible +here:
++Paragraph:: + + Literal block ++
Lists
+Bullet list items begin with one of "-", "*", or "+" (hyphen, +asterisk, or plus sign), followed by whitespace and the list item +body. List item bodies must be left-aligned and indented relative to +the bullet; the text immediately after the bullet determines the +indentation. For example:
++This paragraph is followed by a list. + +* This is the first bullet list item. The blank line above the + first list item is required; blank lines between list items + (such as below this paragraph) are optional. + +* This is the first paragraph in the second item in the list. + + This is the second paragraph in the second item in the list. + The blank line above this paragraph is required. The left edge + of this paragraph lines up with the paragraph above, both + indented relative to the bullet. + + - This is a sublist. The bullet lines up with the left edge of + the text blocks above. A sublist is a new list so requires a + blank line above and below. + +* This is the third item of the main list. + +This paragraph is not part of the list. ++
Enumerated (numbered) list items are similar, but use an enumerator +instead of a bullet. Enumerators are numbers (1, 2, 3, ...), letters +(A, B, C, ...; uppercase or lowercase), or Roman numerals (i, ii, iii, +iv, ...; uppercase or lowercase), formatted with a period suffix +("1.", "2."), parentheses ("(1)", "(2)"), or a right-parenthesis +suffix ("1)", "2)"). For example:
++1. As with bullet list items, the left edge of paragraphs must + align. + +2. Each list item may contain multiple paragraphs, sublists, etc. + + This is the second paragraph of the second list item. + + a) Enumerated lists may be nested. + b) Blank lines may be omitted between list items. ++
Definition lists are written like this:
++what + Definition lists associate a term with a definition. + +how + The term is a one-line phrase, and the definition is one + or more paragraphs or body elements, indented relative to + the term. ++
Tables
+Simple tables are easy and compact:
++===== ===== ======= + A B A and B +===== ===== ======= +False False False +True False False +False True False +True True True +===== ===== ======= ++
There must be at least two columns in a table (to differentiate from +section titles). Column spans use underlines of hyphens ("Inputs" +spans the first two columns):
++===== ===== ====== + Inputs Output +------------ ------ + A B A or B +===== ===== ====== +False False False +True False True +False True True +True True True +===== ===== ====== ++
Text in a first-column cell starts a new row. No text in the first +column indicates a continuation line; the rest of the cells may +consist of multiple lines. For example:
++===== ========================= +col 1 col 2 +===== ========================= +1 Second column of row 1. +2 Second column of row 2. + Second line of paragraph. +3 - Second column of row 3. + + - Second item in bullet + list (row 3, column 2). +===== ========================= ++
Hyperlinks
+When referencing an external web page in the body of a PSEP, you should +include the title of the page in the text, with either an inline +hyperlink reference to the URL or a footnote reference (see +Footnotes below). Do not include the URL in the body text of the +PSEP.
+Hyperlink references use backquotes and a trailing underscore to mark +up the reference text; backquotes are optional if the reference text +is a single word. For example:
++In this paragraph, we refer to the `Python web site`_. ++
An explicit target provides the URL. Put targets in a References +section at the end of the PSEP, or immediately after the reference. +Hyperlink targets begin with two periods and a space (the "explicit +markup start"), followed by a leading underscore, the reference text, +a colon, and the URL (absolute or relative):
++.. _Python web site: http://www.python.org/ ++
The reference text and the target text must match (although the match +is case-insensitive and ignores differences in whitespace). Note that +the underscore trails the reference text but precedes the target text. +If you think of the underscore as a right-pointing arrow, it points +away from the reference and toward the target.
+The same mechanism can be used for internal references. Every unique +section title implicitly defines an internal hyperlink target. We can +make a link to the Abstract section like this:
++Here is a hyperlink reference to the `Abstract`_ section. The +backquotes are optional since the reference text is a single word; +we can also just write: Abstract_. ++
Footnotes containing the URLs from external targets will be generated +automatically at the end of the References section of the PSEP, along +with footnote references linking the reference text to the footnotes.
+Text of the form "PSEP x" or "RFC x" (where "x" is a number) will be +linked automatically to the appropriate URLs.
+Footnotes
+Footnote references consist of a left square bracket, a number, a +right square bracket, and a trailing underscore:
++This sentence ends with a footnote reference [1]_. ++
Whitespace must precede the footnote reference. Leave a space between +the footnote reference and the preceding word.
+When referring to another PSEP, include the PSEP number in the body +text, such as "PSEP 1". The title may optionally appear. Add a +footnote reference following the title. For example:
++Refer to PSEP 1 [2]_ for more information. ++
Add a footnote that includes the PSEP's title and author. It may +optionally include the explicit URL on a separate line, but only in +the References section. Footnotes begin with ".. " (the explicit +markup start), followed by the footnote marker (no underscores), +followed by the footnote body. For example:
++References +========== + +.. [2] PEP 1, "PEP Purpose and Guidelines", Warsaw, Hylton + (http://www.python.org/dev/peps/pep-0001) ++
If you decide to provide an explicit URL for a PSEP, please use this as +the URL template:
++https://pyside.github.io/docs/pseps/psep-xxxx ++
PSEP numbers in URLs must be padded with zeros from the left, so as to +be exactly 4 characters wide, however PSEP numbers in the text are +never padded.
+During the course of developing your PSEP, you may have to add, remove, +and rearrange footnote references, possibly resulting in mismatched +references, obsolete footnotes, and confusion. Auto-numbered +footnotes allow more freedom. Instead of a number, use a label of the +form "#word", where "word" is a mnemonic consisting of alphanumerics +plus internal hyphens, underscores, and periods (no whitespace or +other characters are allowed). For example:
++Refer to PSEP 1 [#PEP-1]_ for more information. + +References +========== + +.. [#PEP-1] PEP 1, "PEP Purpose and Guidelines", Warsaw, Hylton + + http://www.python.org/dev/peps/pep-0001 ++
Footnotes and footnote references will be numbered automatically, and +the numbers will always match. Once a PSEP is finalized, auto-numbered +labels should be replaced by numbers for simplicity.
+Images
+If your PSEP contains a diagram, you may include it in the processed +output using the "image" directive:
++.. image:: diagram.png ++
Any browser-friendly graphics format is possible: .png, .jpeg, .gif, +.tiff, etc.
+Since this image will not be visible to readers of the PSEP in source +text form, you should consider including a description or ASCII art +alternative, using a comment (below).
+Comments
+A comment block is an indented block of arbitrary text immediately +following an explicit markup start: two periods and whitespace. Leave +the ".." on a line by itself to ensure that the comment is not +misinterpreted as another explicit markup construct. Comments are not +visible in the processed document. For the benefit of those reading +your PSEP in source form, please consider including a descriptions of +or ASCII art alternatives to any images you include. For example:
++.. image:: dataflow.png + +.. + Data flows from the input module, through the "black box" + module, and finally into (and through) the output module. ++
The Emacs stanza at the bottom of this document is inside a comment.
+Escaping Mechanism
+reStructuredText uses backslashes ("\") to override the special +meaning given to markup characters and get the literal characters +themselves. To get a literal backslash, use an escaped backslash +("\\"). There are two contexts in which backslashes have no +special meaning: literal blocks and inline literals (see Inline +Markup above). In these contexts, no markup recognition is done, +and a single backslash represents a literal backslash, without having +to double up.
+If you find that you need to use a backslash in your text, consider +using inline literals or a literal block instead.
+Habits to Avoid
+Many programmers who are familiar with TeX often write quotation marks +like this:
++`single-quoted' or ``double-quoted'' ++
Backquotes are significant in reStructuredText, so this practice +should be avoided. For ordinary text, use ordinary 'single-quotes' or +"double-quotes". For inline literal text (see Inline Markup +above), use double-backquotes:
++``literal text: in here, anything goes!`` ++
Resources
+Many other constructs and variations are possible. For more details +about the reStructuredText markup, in increasing order of +thoroughness, please see:
+-
+
- A ReStructuredText Primer [6], a gentle introduction. +
- Quick reStructuredText [7], a users' quick reference. +
- reStructuredText Markup Specification [8], the final authority. +
The processing of reStructuredText PSEPs is done using Docutils [2]. If +you have a question or require assistance with reStructuredText or +Docutils, please post a message [3] to the Docutils-users mailing +list [4]. The Docutils project web site [2] has more information.
+References
+| [1] | PSEP 1, PSEP Purpose and Guidelines, Airas +(https://pyside.github.io/docs/pseps/psep-0001) |
| [2] | (1, 2) http://docutils.sourceforge.net/ |
| [3] | mailto:docutils-users@lists.sourceforge.net?subject=PEPs |
| [4] | http://docutils.sf.net/docs/user/mailing-lists.html#docutils-users |
| [5] | http://www.opencontent.org/openpub/ |
| [6] | http://docutils.sourceforge.net/docs/rst/quickstart.html |
| [7] | http://docutils.sourceforge.net/docs/rst/quickref.html |
| [8] | http://docutils.sourceforge.net/spec/rst/reStructuredText.html |
Copyright
+This document has been placed in the public domain.
+ +
+
+
+
+ PSEP 0100
+ + +| PSEP: | 100 | +
|---|---|
| Title: | New-style Signals and Slots | +
| Version: | 1 | +
| Last-Modified: | 15-Aug-2011 | +
| Author: | Matti Airas <matti.p.airas at nokia.com> | +
| Status: | Final | +
| Type: | Standards Track | +
| Content-Type: | text/x-rst | +
| Created: | 30-Oct-2009 | +
| Post-History: | 30-Oct-2009, 03-Nov-2009, 24-May-2010 | +
+
Contents
+ +Abstract
+This PSEP describes the support of PyQt's new-style signals and slots in +PySide. Traditionally PyQt, and by extension PySide, has required the +use of C++ function signature strings in connecting signals to slots. +This has been widely regarded as unwieldy and non-Pythonic. A new-style +signal and slot support was introduced in PyQt 4.5, in which the signals +and slots may be manipulated using native Python objects and methods. +This new syntax will be adopted to PySide with minor modifications.
+Rationale
+The PyQt's traditional syntax for signals and slots requires the use of +explicit C++ style signal signatures [1]. This has +been regarded as unwieldy and non-Pythonic feature and an opportunity +for improvement in the syntax.
+A new-style signal and slot syntax has been introduced in PyQt 4.5 +[2]. The new style provides a clean syntax to connect +signals and slots using Python objects and methods instead of C++ style +signature strings. An example of connecting and emitting signals using +the new-style syntax is given below (adapted from [2]):
+class Foo(QtCore.QObject): + + # Define a new signal called 'trigger' that has no arguments. + trigger = QtCore.pyqtSignal() + + def connect_and_emit_trigger(self): + # Connect the trigger signal to a slot. + self.trigger.connect(self.handle_trigger) + + # Emit the signal. + self.trigger.emit() + + def handle_trigger(self): + # Show that the slot has been called. + + print "trigger signal received" ++
PyQt's new-style signal and slot mechanism provides a clean, concise, +and Pythonic syntax for defining, connecting, disconnecting, and +emitting signals. To maintain compatibility with PyQt, their new-style +signal and slot mechanism will be adopted to PySide with minor +modifications only.
+New Signal and Slot Syntax
+PySide will adopt PyQt's new signal and slot syntax as-is. The PySide +implementation will be functionally compatible with the PyQt 4.5 one, with +the exceptions listed in the next Section. As PyQt compatibility will be +the main guideline, the syntax specifics will not be described here. +Instead, PyQt behaviour and documentation [2] shall be +used as implementation guidelines.
+Differences from PyQt's syntax
+PyQt's new signal and slot style utilizes method and decorator names +specific to their implementation. These will be generalized according to +the table below:
+| Module | +PyQt factory function | +PySide class | +
|---|---|---|
| QtCore | +pyqtSignal | +Signal | +
| QtCore | +pyqtSlot | +Slot | +
In addition to the generalized class names, PyQt factory names will be +provided as a compatibility feature. They will print out a deprecation +warning, however.
+On the mailing list discussion, concerns were raised about the proposed +naming scheme. One issue was the risk of Qt implementing similarly named +C++ classes, resulting in name clashes in PySide. However, the risk may +be regarded minor during the lifespan of Qt version 4, especially now +that the signals and slots are classes and are written in the +capitalized form. Even in the case this would happen, the issue could be +circumvented in PySide by renaming the new C++ classes suitably.
+Another issue raised was the similarity of Signal and SIGNAL (as +well as Slot and SLOT) class and function names in QtCore. While +the similarity is undeniably an issue, it could still be argued that the +case difference is substantial enough to minimize any risk of confusion +in practice. It could be argued that the non-Pythonic all-caps spelling +refers to the old-style signals and slots, while the standard spelling +refers to the Pythonic new-style signals.
+Compatibility
+Since the new signal and slot syntax does not break compatibility with +the previous syntax, it will be implemented both as part of the original +and the possible future PySide API.
+References
+| [1] | PyQt v4 Reference Manual, Section Old-style +Signal and Slot Support +(http://www.riverbankcomputing.co.uk/static/Docs/PyQt4/pyqt4ref.html#old-style-signal-and-slot-support) |
| [2] | (1, 2, 3) PyQt v4 Reference Manual, Section New-style +Signal and Slot Support +(http://www.riverbankcomputing.co.uk/static/Docs/PyQt4/pyqt4ref.html#new-style-signal-and-slot-support) |
Contributors
+Hugo Lima, Mark Summerfield, Ville M. Vainio, Paul A. Giannaros, and +Douglas Soares de Andrade have contributed in the initial discussion of +this PSEP.
+After having the PSEP already accepted, Hugo Lima pointed out a naming +scheme inconsistency, which caused the PSEP to be redrawn to the draft +status to have the classes properly capitalized.
+Copyright
+This document has been placed in the public domain.
+ +
+
+
+
+ PSEP 0101
+ + +| PSEP: | 101 | +
|---|---|
| Title: | Adopt PyQt's API 2 for PySide | +
| Version: | 1 | +
| Last-Modified: | 15-Aug-2011 | +
| Author: | Mark Summerfield <mark at qtrac.eu> | +
| Status: | Final | +
| Type: | Standards Track | +
| Content-Type: | text/x-rst | +
| Created: | 14-Apr-2010 | +
| Post-History: | 14-Apr-2010, 15-Apr-2010, 16-Apr-2010, 20-Apr-2010, 22-Apr-2010, 18-May-2010 | +
+
Contents
+ +Abstract
+PyQt4 provides two different (and incompatible) APIs. API 1 is the +original API and the one supported by PySide. API 2 is a new Python +3-specific API that is much more Pythonic. This PSEP proposes that +PySide adopt PyQt4's API 2 for PySide.
+Rationale
+PyQt4 provides two different (and incompatbile) APIs [1]. API +1 is useful for those using PyQt4 to prototype C++/Qt programs since +it is very close to the C++/Qt API. However, for those who want to create +Python Qt programs in their own right, and especially for existing Python +programmers, API 1 is cumbersome and un-Pythonic when it comes to handling +QStrings and QVariants, both of which are used a lot.
+If PySide were to support API 2, it will make PySide much more attractive +to Python 3 programmers.
+Also, supporting API 2 will mean that existing Python 3/PyQt4 programs that +use API 2 by default will be able to switch to PySide.
+One key purpose of API 2 is to avoid the need for Python programmers to +have to worry or even know about QString or QVariant. For Python +programmers str is the string they are used to so translation to/from +QString should be transparent and automatic. Similarly, why should +Python programmers have to know about QVariant when that is a C++ +workaround for C++'s lack of support for duck typing etc.? Again, +translation to/from QVariant should be transparent and automatic. API 2 +achieves this and eliminates QString and (to some extent) QVariant.
+API 1 vs. API 2
+No QString and almost no QVariant
+The key difference between the APIs is that API 2 does not make QString +or (to some extent) QVariant available to programmers.
+This means using Python's native string types for strings (e.g., unicode +for Python 2 and str for Python 3).
+PyQt's approach to dealing with QVariants will be mimicked: Python +objects are automatically converted to and from QVariants wherever +QVariants must be passed as arguments and when QVariants are returned.
+By supporting automatic conversion to and from QVariants, any Python +object (including dicts, lists, and tuples) can be used wherever a +QVariant is expected, so most programmers most of the time won't have to +know or care about QVariant at all.
+For QString, API 2 goes beyond simply replacing QString with str (or +unicode on Python 2). In particular, API 2 also automatically converts +QChar and QStringRef to and from strs (or unicodes on Python 2). It also +converts QStringList to and from a Python list of strs (list of unicodes +on Python 2). (PyQt4's API 2 does not implement QLatin1Char, +QLatin1String, or QStringMatcher.)
+Native C++/Qt QStrings are mutable, so PyQt4's API 2 has changed the +signatures of some of the affected functions to return a str (or a tuple +including a str) when in the C++/Qt API a QString parameter would have been +modified.
+In addition, API 2 has added two methods to QFontMetrics and QFontMetricsF, +widthChar() and boundingRectChar(), which take a str of length one and call +QFontMetrics::width() and QFontMetrics::boundingRect() with a QChar +argument. These were added because the width of a single character may be +different from that of a string that contains a single character, even if +the characters are the same.
+If the need arises during the implementation phase, the QVariant class +may be added to the API so that programmers can pass a QVariant +explicitly if they need to. If this is done, to support the creation of +QVariants, a set of static functions named after the types in +QVariant.Type will need to be implemented, e.g.:
+QVariant.fromUInt(pythonObject) -> QVariant +QVariant.fromInt(pythonObject) -> QVariant ++
The benefit of API 2 in this regard is that programmers never have to +explicitly convert between QString and str, so programmers never get +caught out accidentally trying to use a QString method on a str or vice +versa. For the Qt APIs that accept or return QVariants, API 2 allows +programmers to pass any Python object and when a QVariant is returned +from Qt it is automatically converted to its original Python type (with +an invalid QVariant mapped to None).
+Changes to Other Types
+API 2 also affects some other types, as follows.
+Where QByteArrays are expected, bytes objects can be used, but unlike +QString, QByteArray has been retained to ease porting from API 1, so in +API 2 byte sequences can be represented by QByteArray, bytes, and +bytearray objects.
+QDate, QDateTime, QTime, and QUrl's __hash__() methods return a string +representation so that identical dates (and identical date/times or times +or URLs) will have identical hash values.
+QTextStream's bin(), hex(), and oct() functions have been renamed bin_(), +hex_(), and oct_(), to avoid conflicting with Python's built-ins of the +same names.
+Support for Keyword Arguments
+PyQt 4.7 adds support for keyword arguments which is very convenient and +much more Pythonic.
+This change represents an extension to the PyQt APIs that a compatible +PySide ought to implement.
+One problem with this is that while changes to argument names don't affect +C++/Qt, they would break the Python API. Furthermore, since changing +argument names is harmless in C++/Qt, such changes do take place between Qt +versions. This means that for PySide, sensible names must be used in the +first place---and stuck to. Naturally, for PyQt compatibility, PySide ought +to use the same names as PyQt.
+PyQt does not integrate Python and Qt's property systems, but it does allow +Qt properties to be set when an object is constructed using keyword +arguments (i.e., where the keyword is the name of a Qt property). The +same functionality will be implemented in PySide. Also, +PyQt provides the pyqtConfigure() method for all objects that have +Qt properties: this method can be called at any time and the object's Qt +properties set by passing it keyword arguments. However, since +essentially the same functionality is already provided by +QObject.setProperty() and .property() methods, pyqtConfigure() will not be +implemented as part of this PSEP.
+Compatibility
+The proposed API 2 is incompatible with API 1, but since PySide is not +yet widely used and hasn't reached version 1.0.0, it seems reasonable to +break compatibility for the sake of getting PySide "right". Furthermore, +if API 2 is adopted it means that PySide programs will have the same API +whether Python 2 or Python 3 is used which will make it much easier for +those who start out with PySide and Python 2 and later on port to Python +3---something that isn't so easy with PyQt.
+References
+| [1] | PyQt v4 Reference Manual: Potential Incompatibilities +section, Selecting Incompatible APIs section, Support for Keyword +Arguments section, and Support for Qt Properties section +(http://www.riverbankcomputing.co.uk/static/Docs/PyQt4/pyqt4ref.html) |
Contributors
+Richard Dale and Detlev Offenbach pointed out that QByteArray had been +retained in API 2.
+Richard Dale and Lauro Moura gave suggestions regarding QVariant.
+Hugo Lima proposed choosing one of PyQt's alternative APIs and implementing +only that for both Python 2 and Python 3 PySide versions.
+The section of Exceptions was dropped as a result of feedback from Matti +Airas; Matti also added to the discussion in numerous ways.
+Detlev Offenbach also contributed to the discussion on Compatibility.
+Copyright
+This document has been placed in the public domain.
+
+
+
+
+ PSEP 0102
+ +| PSEP: | 102 | +
|---|---|
| Title: | Use Python properties instead of getters and setters | +
| Version: | $Revision$ | +
| Last-Modified: | $Date$ | +
| Author: | Hugo Parente Lima <hugo.lima at openbossa.org> | +
| Status: | Draft | +
| Type: | Standards Track | +
| Content-Type: | text/x-rst | +
| Created: | 15-Jun-2010 | +
+
Contents
+ +Abstract
+Python properties are the Python way of writing what is known in the C++ +and Java world as getters and setters. This PSEP proposes the conversion +of Qt getters and setters to Python properties.
+Rationale
+A Qt property [1] is basically formed by a property name, a +getter, and a setter method (the last one of which may be omitted for +read-only properties). There are other fields but none of them are +important for the scope of this PSEP.
+The purpose of this PSEP is to use Python properties instead of getters +and setters to make PySide much more attractive to Python programmers, +avoiding the cumbersome and un-Pythonic getter/setter idiom.
+Property names and name clashes
+The property names will be the same as the Qt property names, if +possible.
+According to Qt property naming conventions, if a property is called +foo, the getter is called foo() and the setter setFoo(...), +unless foo is a boolean. In that case, the getter can be either +isFoo or hasFoo, depending on the context. So the name clashes +probably can occur only on boolean properties where the getter name is +different from the property name. However, the Qt API was specially +crafted to avoid these clashes. If any should occur nevertheless, the +conflicting Python property shall be renamed to resolve the overlap.
+Compatibility
+The proposed API is incompatible with the existing PySide and PyQt API. +Since PySide is not yet widely used and has not reached version 1.0.0, it +seems reasonable to break compatibility for the sake of getting PySide +"right".
+References
+| [1] | Qt's Property System +(http://doc.trolltech.com/latest/properties.html) |
Copyright
+This document has been placed in the public domain.
+
+
+
+
+ PSEP 0103
+ + +| PSEP: | 103 | +
|---|---|
| Title: | Support for declaring Qt meta-object properties | +
| Version: | 1 | +
| Last-Modified: | 15-Aug-2011 | +
| Author: | Matti Airas <matti.p.airas at nokia.com> | +
| Status: | Accepted | +
| Type: | Standards Track | +
| Content-Type: | text/x-rst | +
| Created: | 08-Sep-2010 | +
| Post-History: | 08-Sep-2010, 13-Sep-2010, 20-Sep-2010, 19-Oct-2010 | +
+
Contents
+ +Abstract
+This PSEP describes a method to declare Qt meta-object properties in +PySide. In a similar manner to PyQt, the new function allows for +declaring properties which simultaneously behave both as Qt and Python +properties, and have their setters and getters defined as Python +functions.
+Rationale
+The Qt meta-object system allows for declaring new properties +with custom getters and setters, accessible from the C++ code using the +Qt standard value() and setValue() getters and setters +[1]. Properties +are also used within the standard Qt class hierarchy, for example the Qt +State Machine Framework uses user-defined properties to define +object behaviour in state transitions.
+To access functionality requiring Qt properties, there needs to be a way +to declare them in PySide as well. In Qt C++, properties are declared +using the Q_PROPERTY() macro, to which the getter and setter +functions as well as several attributes modifying the property's +behaviour are given as arguments [1]. In PyQt, properties +are defined using the QtCore.pyqtProperty() function, mimicking the +C++ macro implementation [2]. pyqtProperty() also +defines a Python property, allowing Pythonic access to the property +value. An example of defining and accessing Qt Properties in PyQt is +given below:
+class MyObject(QObject): + def __init__(self,startval=42): + self.ppval = startval + + def readPP(self): + return self.ppval + + def setPP(self,val): + self.ppval = val + + pp = pyqtProperty(int, readPP, setPP) + +obj = MyObject() +obj.pp = 47 +print obj.pp ++
Since PyQt's property setting syntax is clean and already +well-established, the approach taken in PSEP 100 [3] will be +adopted: PyQt's syntax is taken as is, but the function name will be +changed to QtCore.Property. So in PySide the above example would +differ in the last line of the class definition:
+pp = Property(int, readPP, setPP) ++
PySide's Property Syntax
+PySide will adopt the property setting syntax of PyQt 4.7 as defined in +[2]. The PySide implementation will be functionally +compatible with PyQt, with three exceptions.
+First, the function name is changed from QtCore.pyqtProperty to +QtCore.Property, as explained in the section above.
+Second, PyQt's reference documentation [2] states that +fget has a default value of None. Since the C++ property requires a +mandatory getter function, the default value has been removed from the +PySide implementation.
+Third, the respective Qt Q_PROPERTY macro defines a NOTIFY flag +to specify one existing signal in that class that is emitted whenever +the value of the property changes [1]. This is not present +in PyQt documentation but will be supported by PySide.
+For reference, the arguments accepted by the function with a brief +description are given in the table below:
+| # | +Name | +Default value | +Description | +
|---|---|---|---|
| 1 | +type | ++ | type of the property | +
| 2 | +fget | ++ | getter function | +
| 3 | +fset | +None | +setter function | +
| 4 | +freset | +None | +function used to reset the +value of the property to its +default value (only in C++) | +
| 5 | +fdel | +None | +function for del'ing the property +(only in Python) | +
| 6 | +doc | +None | +docstring of the property | +
| 7 | +notify | +None | +signal emitted when the property +value changes | +
| 8 | +designable | +True | +value of Qt DESIGNABLE flag | +
| 9 | +scriptable | +True | +value of Qt SCRIPTABLE flag | +
| 10 | +stored | +True | +value of Qt STORED flag | +
| 11 | +user | +False | +value of Qt USER flag | +
| 12 | +constant | +False | +value of Qt CONSTANT flag | +
| 13 | +final | +False | +value of Qt FINAL flag | +
Discussion
+An initial implementation of Qt properties in PySide has already been +made but not announced. The present implementation is otherwise +identical to the one described in this PSEP, except that the function +name is QtCore.QProperty(). Since this name is not consistent with +the convention initiated in PSEP 100 [#psep0100] and it is easily +confused with classes in Qt class hierarchy, the name Property() is +preferred instead.
+Darren Dale brought up the possibility of retaining the PyQt naming +policy (that is, keep the QtCore.pyqtProperty() name). However, this +would make PySide internally inconsistent, and the name incompatibility +can be resolved by a simple assignment operator.
+Darren Dale also proposed a property decorator syntax for defining Qt +Properties. This, being a separate proposal, could constitute a PSEP of +its own instead of being included in the current one.
+Compatibility
+Property access is new functionality required to fully utilize some of the +standard Qt classes. Therefore, the feature will be implemented before +the 1.0 release.
+References
+| [1] | (1, 2, 3) Qt's Property System +(http://doc.trolltech.com/4.6/properties.html) |
| [2] | (1, 2, 3) PyQt Reference Guide, section "Writing Qt Designer +Plugins" +(http://www.riverbankcomputing.com/static/Docs/PyQt4/pyqt4ref.html#writing-qt-designer-plugins) |
| [3] | PSEP 100: "New-style Signals and Slots", Airas +(https://pyside.github.io/docs/pseps/psep-0100.html) |
Contributors
+Darren Dale participated in the mailing list discussion and proposed the +decorator syntax for setting properties.
+Mark Summerfield suggested indicating the PyQt syntax differences more +clearly.
+Copyright
+This document has been placed in the public domain.
+ +
+
+
+
+ PSEP 0104
+ + +| PSEP: | 104 | +
|---|---|
| Title: | Decorator syntax for declaring Qt meta-object properties | +
| Version: | 1 | +
| Last-Modified: | 15-Aug-2011 | +
| Author: | Matti Airas <matti.p.airas at nokia.com> | +
| Status: | Draft | +
| Type: | Standards Track | +
| Content-Type: | text/x-rst | +
| Created: | 19-Oct-2010 | +
| Post-History: | 19-Oct-2010, 20-Oct-2010 | +
+
Contents
+ +Abstract
+This PSEP describes a method to declare Qt meta-object properties in +PySide using an alternative syntax based on function decorators. The +presented syntax is directly analogous to the Python property decorator +syntax introduced in Python 2.6.
+Rationale
+Traditional Python properties can be defined using a syntax given below +[1]:
+class C(object): + def __init__(self): + self._x = None + + def getx(self): + return self._x + def setx(self, value): + self._x = value + def delx(self): + del self._x + x = property(getx, setx, delx, "I'm the 'x' property.") ++
In addition to this syntax, Python introduces a decorator syntax for +setting object properties in version 2.6:
+class C(object): + def __init__(self): + self._x = None + + @property + def x(self): + """I'm the 'x' property.""" + return self._x + + @x.setter + def x(self, value): + self._x = value + + @x.deleter + def x(self): + del self._x ++
Although the decorator syntax for setting properties is more verbose, it +an be argued to be clearer than the traditional syntax.
+PySide has support for Qt properties as defined in PSEP 103 +[2]. The syntax for defining Qt properties in PySide closely +mimics the traditional Python property setting syntax above, with the +exception that Qt properties are defined with the QtCore.Property +function, which also supports a few extra arguments compared to the +native property function. Once defined, the PySide Qt properties are also +usable as Python properties.
+To match the native property decorator syntax, a decorator syntax for +defining Qt properties will be added to PySide as well. The syntax is +similar to the native Python property decorator one. Recent PyQt 4.8 +snapshots also have support for a similar syntax, although that has not +been documented.
+Property Decorator Syntax
+The PySide Qt property decorator syntax is similar to the native Python +property decorators, with the exception that the initial +QtCore.Property decorator is a function call, accepting any extra +QtCore.Property arguments as the decorator arguments. The example +below illustrates how it can be used:
+class C(QObject): + def __init__(self): + self._x = None + + xChanged = Signal() + + @Property(float, doc="I'm the 'x' property.", notify=xChanged) + def x(self): + return self._x + + @x.setter + def x(self, value): + self._x = value + + @x.deleter + def x(self): + del self._x ++
The function decorated by the Property decorator defines the +property name and acts as the property getter function. +The possible arguments for the Property decorator are given in the +table below.
+| # | +Name | +Default value | +Description | +
|---|---|---|---|
| 1 | +type | ++ | type of the property | +
| 2 | +doc | +None | +docstring of the property | +
| 3 | +notify | +None | +signal emitted when the property +value changes | +
| 4 | +designable | +True | +value of Qt DESIGNABLE flag | +
| 5 | +scriptable | +True | +value of Qt SCRIPTABLE flag | +
| 6 | +stored | +True | +value of Qt STORED flag | +
| 7 | +user | +False | +value of Qt USER flag | +
| 8 | +constant | +False | +value of Qt CONSTANT flag | +
| 9 | +final | +False | +value of Qt FINAL flag | +
In addition to the arguments given, the defined properties have +getter, setter, resetter, and deleter attributes that +can be used to define the respective Qt property functions for that +property.
+Discussion
+Darren Dale noted that redefining the getter decorator is required to +override the getter in subclasses. Consequently, a getter was added to +the list of available attributes.
+Compatibility
+The described functionality does not break compatibility to existing +PySide API and can be added to PySide as soon as it has been +implemented.
+References
+| [1] | Reference documentation for Python "property" function +(http://docs.python.org/library/functions.html#property) |
| [2] | PSEP 103: Support for declaring Qt meta-object +properties, Airas (https://pyside.github.io/docs/pseps/psep-0103.html) |
Contributors
+Darren Dale initially proposed the decorator property syntax on the +PySide mailing list on 08-Sep-2010.
+Copyright
+This document has been placed in the public domain.
+ +
+
+
+
+ PSEP 0106
+ +Not rendered yet; the text version is available here
+
+
+
+
+ PySide and related tools reference
Modules
-|
- PySide |
-
- Shiboken |
|
+
+ PySide |
+
+
+ Shiboken |
+
|
+
+ PSEPs |
+