# Pony stubs
Python type hint stubs for [Pony ORM](https://github.com/ponyorm/pony)
## Goals
1. Provide type hints for Pony ORM that support both MyPy and Pyright on their strictest modes
2. Integrate the contents of this package into the official Pony ORM repository (self-deprecation)
3. Focus primarily on the aspects that users of Pony ORM most often run into (defining models, querying them)
## Usage
Install the package with your preferred Python dependency manager:
```sh
pip install pony-stubs
pipenv install pony-stubs
poetry add -D pony-stubs
```
Then define your models:
```python
# We need this to avoid `TypeError: 'type' object is not subscriptable`
# later on when forward declaring relation types with strings
from __future__ import annotations
from pony.orm import (
Database,
Required,
Optional,
Set,
PrimaryKey,
select,
max,
count,
desc
)
db = Database("sqlite", "store.sqlite", create_db=True)
# Using `db.Entity` directly won't work, as both MyPy and Pyright won't
# allow inheriting a class from a variable. For Pyright this declaration
# is enough misdirection for it not to complain, but MyPy needs an extra
# `type: ignore` comment above each model declaration to work.
DbEntity = db.Entity
class Customer(DbEntity): # type: ignore
# If we want the type checkers to know about the autogenerated ID
# field, we need to annotate it
id: int
# Otherwise, using `Required` allows `Customer.email` to be inferred
# as `str` later on
email = Required(str, unique=True)
password = Required(str)
country = Required(str)
# Using `Optional` marks the field attribute as `str | None`
address = Optional(str)
# When we forward declare a relation by using the class name as a
# string, we also need to manually annotate the field so that the
# type checkers can infer it correctly
orders: Set["Order"] = Set("Order")
class Order(DbEntity): # type: ignore
# We can also declare the primary key with Pony constructors and
# infer the type that way
id = PrimaryKey(int, auto=True)
state = Required(str)
total_price = Required(Decimal)
# When declaring relationships after a class has been declared,
# there's no need for annotations
customer = Required(Customer)
class Product(DbEntity): # type: ignore
id: int
name = Required(str)
price = Required(Decimal)
```
And use them in your code:
```python
# Here result infers as `QueryResult[Customer]` and all fields in the
# generator expression inside `select` have proper types inferred
result = select(c for c in Customer if c.country != "USA")[:]
result = select(c for c in Customer if count(c.orders) > 1)[:]
# Here result infers as `Decimal`
result = max(p.price for p in Product)
# And here as `Customer | None` (as `.first()` might not find an object)
# Here is also the first time we can't properly infer something:
# `c.orders` is declared as `Set[Order]`, but Pony allows us to access
# `c.orders.total_price` as though it was typed as a plain `Order`.
# As Python doesn't yet support type intersections, we have yet to come
# up with no choice other than to type each extra field of a `Set` as
# `Any`
result = (
select(c for c in Customer)
.order_by(lambda c: desc(sum(c.orders.total_price)))
.first()
)
```
## Limitations
1. We need misdirection with `db.Entity` for `pyright`, and `# type: ignore` for `mypy`
2. When forward declaring relations (relation to a model defined later in the file) we an additional manual annotation (`field: Set["RelatedObject"]`)
3. "Attribute lifting" of related fields is typed as `Any`. Pony would allow us to access attributes of `Set[Order]` as though it's type was `Order`, but python doesn't yet support type intersections so statically typing this seems to be impossible without a plugin (which would only fix the issue for MyPy but not Pyright)
4. `Query.where()` ([docs](https://docs.ponyorm.org/api_reference.html#Query.filter)) loses type information and it's results are typed as `Any`, as python doesn't keep track of generator expressions' initial iterables: `(o.customer for o in Order)` is inferred as `Generator[Customer, None, None]`, without any native way of storing the `Order` type in a generic for inferring.
## Contributing
Contributions are always most welcome! Please run the pre-commit hooks before setting up a pull request, and in case the Github actions fail, please try to fix those issues so the review itself can go as smoothly as possible
The development environment for this package requires `poetry` (https://python-poetry.org/docs/master/#installing-with-the-official-installer)
Using VSCode as the editor is recommended!
### Setting up the repo
1. Clone the repo
- `git clone git@github.com:Jonesus/pony-stubs.git`
2. Install dependencies
- `poetry install`
3. Install commit hooks
- `poetry run pre-commit install --install-hooks`
4. Type ahead!
## License
This project is licensed under the MIT license (see LICENSE.md)
Raw data
{
"_id": null,
"home_page": "https://github.com/Jonesus/pony-stubs",
"name": "pony-stubs",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7,<4.0",
"maintainer_email": "",
"keywords": "pony,types,stubs,mypy,pyright",
"author": "Joonas Palosuo",
"author_email": "joonas.palosuo@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/db/16/07daf8f5c69018663f9e7679371d471aee35627f70a5b591200cf5389408/pony-stubs-0.5.2.tar.gz",
"platform": null,
"description": "# Pony stubs\n\nPython type hint stubs for [Pony ORM](https://github.com/ponyorm/pony)\n\n## Goals\n1. Provide type hints for Pony ORM that support both MyPy and Pyright on their strictest modes\n2. Integrate the contents of this package into the official Pony ORM repository (self-deprecation)\n3. Focus primarily on the aspects that users of Pony ORM most often run into (defining models, querying them)\n\n## Usage\nInstall the package with your preferred Python dependency manager:\n```sh\npip install pony-stubs\n\npipenv install pony-stubs\n\npoetry add -D pony-stubs\n```\n\nThen define your models:\n```python\n# We need this to avoid `TypeError: 'type' object is not subscriptable`\n# later on when forward declaring relation types with strings\nfrom __future__ import annotations\n\nfrom pony.orm import (\n Database,\n Required,\n Optional,\n Set,\n PrimaryKey,\n select,\n max,\n count,\n desc\n)\n\ndb = Database(\"sqlite\", \"store.sqlite\", create_db=True)\n\n# Using `db.Entity` directly won't work, as both MyPy and Pyright won't\n# allow inheriting a class from a variable. For Pyright this declaration\n# is enough misdirection for it not to complain, but MyPy needs an extra\n# `type: ignore` comment above each model declaration to work.\nDbEntity = db.Entity\n\n\nclass Customer(DbEntity): # type: ignore\n # If we want the type checkers to know about the autogenerated ID\n # field, we need to annotate it\n id: int\n # Otherwise, using `Required` allows `Customer.email` to be inferred\n # as `str` later on\n email = Required(str, unique=True)\n password = Required(str)\n country = Required(str)\n # Using `Optional` marks the field attribute as `str |\u00a0None`\n address = Optional(str)\n # When we forward declare a relation by using the class name as a\n # string, we also need to manually annotate the field so that the\n # type checkers can infer it correctly\n orders: Set[\"Order\"] = Set(\"Order\")\n\nclass Order(DbEntity): # type: ignore\n # We can also declare the primary key with Pony constructors and\n # infer the type that way\n id = PrimaryKey(int, auto=True)\n state = Required(str)\n total_price = Required(Decimal)\n # When declaring relationships after a class has been declared,\n # there's no need for annotations\n customer = Required(Customer)\n\nclass Product(DbEntity): # type: ignore\n id: int\n name = Required(str)\n price = Required(Decimal)\n```\n\nAnd use them in your code:\n```python\n# Here result infers as `QueryResult[Customer]` and all fields in the\n# generator expression inside `select` have proper types inferred\nresult = select(c for c in Customer if c.country != \"USA\")[:]\nresult = select(c for c in Customer if count(c.orders) > 1)[:]\n\n# Here result infers as `Decimal`\nresult = max(p.price for p in Product)\n\n# And here as `Customer |\u00a0None` (as `.first()` might not find an object)\n# Here is also the first time we can't properly infer something:\n# `c.orders` is declared as `Set[Order]`, but Pony allows us to access\n# `c.orders.total_price` as though it was typed as a plain `Order`.\n# As Python doesn't yet support type intersections, we have yet to come\n# up with no choice other than to type each extra field of a `Set` as\n# `Any`\nresult = (\n select(c for c in Customer)\n .order_by(lambda c: desc(sum(c.orders.total_price)))\n .first()\n)\n```\n\n## Limitations\n1. We need misdirection with `db.Entity` for `pyright`, and `# type: ignore` for `mypy`\n2. When forward declaring relations (relation to a model defined later in the file) we an additional manual annotation (`field: Set[\"RelatedObject\"]`)\n3. \"Attribute lifting\" of related fields is typed as `Any`. Pony would allow us to access attributes of `Set[Order]` as though it's type was `Order`, but python doesn't yet support type intersections so statically typing this seems to be impossible without a plugin (which would only fix the issue for MyPy but not Pyright)\n4. `Query.where()` ([docs](https://docs.ponyorm.org/api_reference.html#Query.filter)) loses type information and it's results are typed as `Any`, as python doesn't keep track of generator expressions' initial iterables: `(o.customer for o in Order)` is inferred as `Generator[Customer, None, None]`, without any native way of storing the `Order` type in a generic for inferring.\n\n## Contributing\nContributions are always most welcome! Please run the pre-commit hooks before setting up a pull request, and in case the Github actions fail, please try to fix those issues so the review itself can go as smoothly as possible\n\nThe development environment for this package requires `poetry` (https://python-poetry.org/docs/master/#installing-with-the-official-installer)\n\nUsing VSCode as the editor is recommended!\n\n### Setting up the repo\n1. Clone the repo\n - `git clone git@github.com:Jonesus/pony-stubs.git`\n2. Install dependencies\n - `poetry install`\n3. Install commit hooks\n - `poetry run pre-commit install --install-hooks`\n4. Type ahead!\n\n## License\nThis project is licensed under the MIT license (see LICENSE.md)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Type stubs for Pony ORM",
"version": "0.5.2",
"project_urls": {
"Homepage": "https://github.com/Jonesus/pony-stubs",
"Repository": "https://github.com/Jonesus/pony-stubs"
},
"split_keywords": [
"pony",
"types",
"stubs",
"mypy",
"pyright"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5273e04a44e996636053dddbd56fbd3e2138db68b9d4adba73819a561f979bdc",
"md5": "874c7e35ffcc8def8ca2a35e8fac9922",
"sha256": "c446481b1e6699676e8fc5c22b59429c18e00d1e663990cd98dae843acaf395a"
},
"downloads": -1,
"filename": "pony_stubs-0.5.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "874c7e35ffcc8def8ca2a35e8fac9922",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7,<4.0",
"size": 35817,
"upload_time": "2022-04-17T20:40:56",
"upload_time_iso_8601": "2022-04-17T20:40:56.796945Z",
"url": "https://files.pythonhosted.org/packages/52/73/e04a44e996636053dddbd56fbd3e2138db68b9d4adba73819a561f979bdc/pony_stubs-0.5.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "db1607daf8f5c69018663f9e7679371d471aee35627f70a5b591200cf5389408",
"md5": "3ceb23b6c2f650ccb64466711d4e59e9",
"sha256": "65a2739d4c6848eb00e5d8c74c8f25a92f960809b011e3138694665f8a4a5adc"
},
"downloads": -1,
"filename": "pony-stubs-0.5.2.tar.gz",
"has_sig": false,
"md5_digest": "3ceb23b6c2f650ccb64466711d4e59e9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7,<4.0",
"size": 28511,
"upload_time": "2022-04-17T20:40:55",
"upload_time_iso_8601": "2022-04-17T20:40:55.522034Z",
"url": "https://files.pythonhosted.org/packages/db/16/07daf8f5c69018663f9e7679371d471aee35627f70a5b591200cf5389408/pony-stubs-0.5.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-04-17 20:40:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Jonesus",
"github_project": "pony-stubs",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pony-stubs"
}
JSON
