| Name | types-PySide2 JSON |
| Version |
5.15.2.1.5
JSON |
| download |
| home_page | |
| Summary | The most accurate stubs for PySide2 |
| upload_time | 2023-04-18 20:10:06 |
| maintainer | |
| docs_url | None |
| author | Chad Dombrova |
| requires_python | |
| license | LGPL v2.1 |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Type stubs for PySide2 (and soon PySide6)
The most accurate type stubs for PySide! They have been tested using `mypy` on a code base with many thousands of lines of PySide code.
## Comparison to other PySide stubs
I tried a number of projects before deciding to create my own. Here's my super-biased assessment:
| Stub Project | Technique | Rating |
|----------------------------------------------------------------------|-----------------------------------------------------------------------------------|----------|
| Official stubs | Uses PySide's `generate_pyi` stub generator | abysmal |
| [PySide2-Stubs-Gen](https://github.com/HareInWeed/PySide2-Stubs-Gen) | Uses a modified version of `generate_pyi` | marginal |
| [PySide2-stubs](https://pypi.org/project/PySide2-stubs/) | Reprocesses official stubs using [libcst](https://libcst.readthedocs.io/en/latest/) | better |
| [types-PySide2](https://pypi.org/project/types-PySide2/) | Uses mypy's [stubgen](https://mypy.readthedocs.io/en/stable/stubgen.html) | best |
[PySide2-stubs](https://pypi.org/project/PySide2-stubs/) is pretty good, but it still produced hundreds of errors in our code base.
I considered contributing new features to that project, but the approach of using an AST/CST parser to modify
an upstream set of bad official stubs to make them good is convoluted and prone to errors from upstream changes.
This project uses mypy's official `stubgen` tool to directly generate stubs, with a set of corrections applied.
## Features and fixes
### General fixes
* Fixed an issue where methods/attributes were not detected, due to presence of `QObject.__getattr__()`
* Added all signals and made new-style signal patterns work
* e.g. `myobject.mysignal.connect(func)` and `myobject.mysignal[type].connect(func)`
* Fixed slot arg of `SignalInstance.connect()` to be `typing.Callable` instead of `object`
* Fixed `Signal.emit()`
* Fixed `Signal.connect()` return value to `bool` instead of `None`
* Fixed `Object.disconnect()`
* Added all methods to flag classes: `__or__`, `__xor__`, ...
### Rule-based fixes
* When instantiating subclasses of `QObject` it is possible to pass the values of properties and signals as `**kwargs` to `__init__`. The stubs have been fix to include these args on all relevant `__init__` methods.
* Qt/PySide has special "flag" enumerator classes that work as pairs: one represents a single flag value, while the other represents multiple combined. The stubs have been fix to allow either type of flag -- single or multiple -- anywhere that one of the would have been accepted, which is the correct behavior (technically `typing.SupportsInt` is the most correct, but using this would undermine the type enforcement provided by the stubs).
* Removed redundant overlapping overloads, so that satisfying mypy/liskov on subclassed methods is easier
* For methods that implement both classmethod and instancemethod overloads, the classmethod overloads have been removed. Unfortunately, mypy disallows mixing these and does not correctly analyze them.
* Corrected all arguments typed as `typing.Sequence` to be `typing.Iterable`. Tests so far have indicated that this is true as a general rule.
* Added sub-types to `Iterable` annotations, e.g. `Iterable[str]`, `Iterable[int]`, etc
* Replaced `object` with `typing.Any` in return types. e.g.:
* `QSettings.value() -> Any`
* `QModelIndex.internalPointer() -> Any`
* `QPersistentModelIndex.internalPointer() -> Any`
### Specific fixes
* Certain argument types implicitly accept alternative types for brevity. Below are the known fixes so far (Note that I've debated not including these, since one of the advantages of static typing is it gives you the confidence to be explicit rather than ambiguous. I could introduce a strict mode in the future that would disable these):
* `QKeySequence`: `str`
* `QColor`: `Qt.GlobalColor` and `int`
* `QBrush`: `QLinearGradient` and `QColor` (and by extension `Qt.GlobalColor`)
* `QCursor`: `Qt.CursorShape`
* `QEasingCurve`: `QEasingCurve.Type`
* Corrected numerous annotations from `bytes/QByteArray` to `str`:
* `QObject.setProperty()`
* `QObject.property()`
* `QState.assignProperty()`
* `QCoreApplication.translate()`
* `format` args on all methods
* Fixed `QTreeWidgetItemIterator.__iter__()` to return `Iterator[QTreeWidgetItemIterator]`
* Added missing `QDialog.exec()` method
* Fixed numerous methods which accept `None`:
* `QPainter.drawText(..., br)`
* `QPainter.drawPolygon(..., arg__2)`
* `QProgressDialog.setCancelButton(button)`
* `*.setModel(model)`
* `QLabel.setPixmap(arg__1)`
* Fixed numerous arguments that accept `QModelIndex` which were typed as `int`
* Fixed return type for `QApplication.instance()` and `QGuiApplication.instance()`
* Fixed return type for `QObject.findChild()` and `QObject.findChildren()`
* Fixed support for initializing `QDate` from `datetime.date`
* Fixed support for initializing `QDateTime` from `datetime.datetime`
* Fixed `QByteArray.__iter__()` to return `Iterator[bytes]`
* Fixed support for `bytes(QByteArray(b'foo'))`
* Added support for all `QSize` and `QSizeF` operations
* Added support for all `QPolygon` operations
* Fixed `QTextEdit.setFontWeight()` to accept `QFont.Weight`
* Fixed return type for `qVersion()`
* Add `QSpacerItem.__init__/changeSize` overloads that use alternate names: `hData`->`hPolicy`, `vData`->`vPolicy`
## Licensing
As a derived work from PySide2, the stubs are delivered under the LGPL v2.1 . See file LICENSE for more details.
## Installation
Install the latest stub packages from pypi:
$ pip install types-PySide2
This will add the `PySide2-stubs` and `shiboken2-stubs` packages into your site-packages directory.
Yes, the name of the pypi package is `types-PySide2` but the python package it installs is `PySide2-stubs`.
It's confusing, but [PEP 561](https://peps.python.org/pep-0561/) requires that the installed package name is of the form `$PACKAGE-stubs`, so all of us PySide stub developers are installing a package with the same name.
Note, you may need to uninstall other PySide2 stubs first:
$ pip uninstall PySide2-stubs
## Help improve the stubs
If you notice incorrect or missing typing information (i.e. mypy reports errors even though your code is correct), please report it or make a PR to fix it.
## Testing
```
python3 -m venv .venv
. .venv/bin/activate
tox
```
## TODO
* Build PySide6 stubs
* Merge overloads where a `Union` would do instead of multiple overloads
* Add type enforcement for signal types, to protect against incorrect callables provided to `connect()`
Raw data
{
"_id": null,
"home_page": "",
"name": "types-PySide2",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Chad Dombrova",
"author_email": "",
"download_url": "",
"platform": null,
"description": "\n# Type stubs for PySide2 (and soon PySide6)\n\nThe most accurate type stubs for PySide! They have been tested using `mypy` on a code base with many thousands of lines of PySide code.\n\n## Comparison to other PySide stubs\n\nI tried a number of projects before deciding to create my own. Here's my super-biased assessment:\n\n| Stub Project | Technique | Rating |\n|----------------------------------------------------------------------|-----------------------------------------------------------------------------------|----------|\n| Official stubs | Uses PySide's `generate_pyi` stub generator | abysmal |\n| [PySide2-Stubs-Gen](https://github.com/HareInWeed/PySide2-Stubs-Gen) | Uses a modified version of `generate_pyi` | marginal |\n| [PySide2-stubs](https://pypi.org/project/PySide2-stubs/) | Reprocesses official stubs using [libcst](https://libcst.readthedocs.io/en/latest/) | better |\n| [types-PySide2](https://pypi.org/project/types-PySide2/) | Uses mypy's [stubgen](https://mypy.readthedocs.io/en/stable/stubgen.html) | best |\n\n[PySide2-stubs](https://pypi.org/project/PySide2-stubs/) is pretty good, but it still produced hundreds of errors in our code base.\nI considered contributing new features to that project, but the approach of using an AST/CST parser to modify\nan upstream set of bad official stubs to make them good is convoluted and prone to errors from upstream changes.\nThis project uses mypy's official `stubgen` tool to directly generate stubs, with a set of corrections applied.\n\n\n## Features and fixes\n\n### General fixes\n\n* Fixed an issue where methods/attributes were not detected, due to presence of `QObject.__getattr__()`\n* Added all signals and made new-style signal patterns work\n * e.g. `myobject.mysignal.connect(func)` and `myobject.mysignal[type].connect(func)`\n * Fixed slot arg of `SignalInstance.connect()` to be `typing.Callable` instead of `object`\n * Fixed `Signal.emit()`\n * Fixed `Signal.connect()` return value to `bool` instead of `None`\n * Fixed `Object.disconnect()`\n* Added all methods to flag classes: `__or__`, `__xor__`, ...\n\n### Rule-based fixes\n\n* When instantiating subclasses of `QObject` it is possible to pass the values of properties and signals as `**kwargs` to `__init__`. The stubs have been fix to include these args on all relevant `__init__` methods.\n* Qt/PySide has special \"flag\" enumerator classes that work as pairs: one represents a single flag value, while the other represents multiple combined. The stubs have been fix to allow either type of flag -- single or multiple -- anywhere that one of the would have been accepted, which is the correct behavior (technically `typing.SupportsInt` is the most correct, but using this would undermine the type enforcement provided by the stubs).\n* Removed redundant overlapping overloads, so that satisfying mypy/liskov on subclassed methods is easier \n* For methods that implement both classmethod and instancemethod overloads, the classmethod overloads have been removed. Unfortunately, mypy disallows mixing these and does not correctly analyze them.\n* Corrected all arguments typed as `typing.Sequence` to be `typing.Iterable`. Tests so far have indicated that this is true as a general rule. \n* Added sub-types to `Iterable` annotations, e.g. `Iterable[str]`, `Iterable[int]`, etc\n* Replaced `object` with `typing.Any` in return types. e.g.:\n * `QSettings.value() -> Any`\n * `QModelIndex.internalPointer() -> Any`\n * `QPersistentModelIndex.internalPointer() -> Any`\n\n### Specific fixes\n\n* Certain argument types implicitly accept alternative types for brevity. Below are the known fixes so far (Note that I've debated not including these, since one of the advantages of static typing is it gives you the confidence to be explicit rather than ambiguous. I could introduce a strict mode in the future that would disable these):\n * `QKeySequence`: `str`\n * `QColor`: `Qt.GlobalColor` and `int`\n * `QBrush`: `QLinearGradient` and `QColor` (and by extension `Qt.GlobalColor`)\n * `QCursor`: `Qt.CursorShape`\n * `QEasingCurve`: `QEasingCurve.Type`\n* Corrected numerous annotations from `bytes/QByteArray` to `str`:\n * `QObject.setProperty()`\n * `QObject.property()`\n * `QState.assignProperty()`\n * `QCoreApplication.translate()`\n * `format` args on all methods\n* Fixed `QTreeWidgetItemIterator.__iter__()` to return `Iterator[QTreeWidgetItemIterator]`\n* Added missing `QDialog.exec()` method\n* Fixed numerous methods which accept `None`:\n * `QPainter.drawText(..., br)`\n * `QPainter.drawPolygon(..., arg__2)`\n * `QProgressDialog.setCancelButton(button)`\n * `*.setModel(model)`\n * `QLabel.setPixmap(arg__1)`\n* Fixed numerous arguments that accept `QModelIndex` which were typed as `int`\n* Fixed return type for `QApplication.instance()` and `QGuiApplication.instance()`\n* Fixed return type for `QObject.findChild()` and `QObject.findChildren()`\n* Fixed support for initializing `QDate` from `datetime.date`\n* Fixed support for initializing `QDateTime` from `datetime.datetime`\n* Fixed `QByteArray.__iter__()` to return `Iterator[bytes]`\n* Fixed support for `bytes(QByteArray(b'foo'))`\n* Added support for all `QSize` and `QSizeF` operations\n* Added support for all `QPolygon` operations\n* Fixed `QTextEdit.setFontWeight()` to accept `QFont.Weight`\n* Fixed return type for `qVersion()`\n* Add `QSpacerItem.__init__/changeSize` overloads that use alternate names: `hData`->`hPolicy`, `vData`->`vPolicy`\n\n## Licensing\n\nAs a derived work from PySide2, the stubs are delivered under the LGPL v2.1 . See file LICENSE for more details.\n\n## Installation\n\nInstall the latest stub packages from pypi:\n\n $ pip install types-PySide2\n\nThis will add the `PySide2-stubs` and `shiboken2-stubs` packages into your site-packages directory. \nYes, the name of the pypi package is `types-PySide2` but the python package it installs is `PySide2-stubs`. \nIt's confusing, but [PEP 561](https://peps.python.org/pep-0561/) requires that the installed package name is of the form `$PACKAGE-stubs`, so all of us PySide stub developers are installing a package with the same name.\n\nNote, you may need to uninstall other PySide2 stubs first:\n\n $ pip uninstall PySide2-stubs\n\n## Help improve the stubs\n\nIf you notice incorrect or missing typing information (i.e. mypy reports errors even though your code is correct), please report it or make a PR to fix it. \n\n## Testing\n\n```\npython3 -m venv .venv\n. .venv/bin/activate\ntox\n```\n\n## TODO\n\n* Build PySide6 stubs\n* Merge overloads where a `Union` would do instead of multiple overloads\n* Add type enforcement for signal types, to protect against incorrect callables provided to `connect()`\n",
"bugtrack_url": null,
"license": "LGPL v2.1",
"summary": "The most accurate stubs for PySide2",
"version": "5.15.2.1.5",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "87c0e1893f7d42800554d2e0f7b3fb2cefe1165210b5ec9c3b4f4a25453e1847",
"md5": "1fa41d11a27d5e9f0a3fad0988195054",
"sha256": "4bbee2c8f09961101013d05bb5c506b7351b3020494fc8b5c3b73c95014fa1b0"
},
"downloads": -1,
"filename": "types_PySide2-5.15.2.1.5-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "1fa41d11a27d5e9f0a3fad0988195054",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 577579,
"upload_time": "2023-04-18T20:10:06",
"upload_time_iso_8601": "2023-04-18T20:10:06.840068Z",
"url": "https://files.pythonhosted.org/packages/87/c0/e1893f7d42800554d2e0f7b3fb2cefe1165210b5ec9c3b4f4a25453e1847/types_PySide2-5.15.2.1.5-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-04-18 20:10:06",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "types-pyside2"
}
