execute_sql is really confusing without any type hints.

[caner-cetin]

Look. I know your stance against type hints. I know you call them abomination

and I know how much you hate the typing system, but. Take a look at http://docs.peewee-orm.com/en/latest/peewee/api.html#Database.execute_sql. Lets say I want to execute a raw sql query

(method) def execute_sql(
    sql: Any,
    params: Any | None = ...,
    commit: ... = ...
) -> Any

okay, sql is a multiline SQL query, and rest is clear. but what does it return?

Returns

    cursor object.

Execute a SQL query by compiling a Query instance and executing the resulting SQL.

okay but what is cursor object? if cursor object is meant to exist in documentation, why is it not linked? why I have to dig so deep to find what execute_sql returns? this is not some internal function that is used once in a blue moon, if I want to execute an SQL query, I reach out to this function. yeah I can do

    for row in cursor.fetchall():

and iterate over rows as dictionary, then get the column name as cursor.description, zip them together, but why do I have to dig so deep for this? why do I have to consult stackoverflow to know that I can use the function like this? seriously, if this https://stackoverflow.com/questions/18500956/python-peewee-execute-sql-example question did not exist i wouldnt have a single fucking flying clue to how to execute raw sql.

and I know that typeshed also exists. but typeshed does not work at all if I dont use pylance or mypy.

like, most basic thing.

(method) def save(
    force_insert: bool = ...,
    only: Any | None = ...
) -> Any

what does save return? saved record? modified row count? nothing? boolean to express the status? who fucking knows, lets alt tab and google it

user.save()  # save() returns the number of rows modified.
1

ah yeah, thanks. see you in next couple of minutes because I will forget what save actually returns.

I am not insulting your work, this is a literal godsend ORM, and I dont know what is your current stance over the typing situation after 7 years, but please. I want to use Peewee because I don't want full-on ORM suite like SQLAlchemy, I need a lightweight ORM, and Peewee is the perfect candidate for it. But without stubs, and a second monitor, i am getting a strong alt-tab muscle memory.

<3

[coleifer]

but why do I have to dig so deep for this?

• http://docs.peewee-orm.com/en/latest/peewee/api.html#Database.execute_sql
• http://docs.peewee-orm.com/en/latest/peewee/api.html#Model.save

It's all documented, your examples are above. They warrant about 2 lines of explanation and are very simple. Eventually you'll learn it if you decide to stick with it. execute_sql() gives you whatever your driver's cursor implementation is, following the DB-API 2.0.

[caner-cetin]

@coleifer It is all documented, but where? Okay execute sql is right there but where is the cursor?

execute_sql(sql[, params=None])[](http://docs.peewee-orm.com/en/latest/peewee/api.html#Database.execute_sql)

    Parameters

            sql (str) – SQL string to execute.

            params (tuple) – Parameters for query.

    Returns

        cursor object.

    Execute a SQL query and return a cursor over the results.

it returns a cursor object, but, where is it? what kind of class is it? https://motor.readthedocs.io/en/stable/api-asyncio/asyncio_motor_collection.html#motor.motor_asyncio.AsyncIOMotorCollection.find take this as example, Motor does not provide type hints too, but they at least tell you that Creates a **MotorCursor**. I dont even know what class this function is returning

[caner-cetin]

By the way I understood that if I use SQLite it returns https://docs.python.org/3/library/sqlite3.html#sqlite3.Cursor but for newcomers to the project, it is hella confusing

[coleifer]

I mentioned it in my comment:

execute_sql() gives you whatever your driver's cursor implementation is, following the DB-API 2.0.