Documentation Improvement - Master Issue

[coleifer]

The purpose of this issue is to collect suggestions for how the documentation might be improved.

Some of the things I'm wondering:

• Is it easy to find the information you're looking for?
• Does the organization of the sections and subsections make it easy to find what you need?
• Are some sections too verbose? Too terse?
• Do we need more examples?
• Is there something you frequently find that you have to look-up or are confused by?

[jwkvam]

Really cool that you're doing this. The two things I look up the most are available field types and query operators. I find them easy to find via google and the table of contents so that's great!

Two things I struggled to find:

1. Using select with fields from different tables, e.g. A.select(A.name, B.date).join(B).... I wanted to get something akin to a list of namedtuples. I took me a while to find that I needed to use objects or naive in 2.x to do this. I wasn't sure what to search for so I eventually found this by looking through all the examples where select is to select certain fields. Not sure how to improve this.

2. It took me a while to realize that join uses the most recently joined table. For example if I have:

class Mother(BaseModel):
    username = CharField()
class Father(BaseModel):
    username = CharField()
class Child(BaseModel):
    mother = ForeignKeyField(Mother, backref='children')
    father = ForeignKeyField(Father, backref='children')
    username = CharField()

I try to do Child.select().join(Father).join(Mother). I now know that I need to use switch or join_from but for some reason this took me a while to realize. Since Child ⨝ Father has a ForeignKey to Mother, I had somehow expected this to automagically work 🤔. This is probably a case of me not reading the documentation thoroughly and missing http://docs.peewee-orm.com/en/latest/peewee/querying.html#joining-on-multiple-tables.

[coleifer]

Thanks for the feedback, I appreciate it!

[coleifer]

I've started a new document that discusses relationships in peewee, including addressing many of the topics you've described: http://docs.peewee-orm.com/en/latest/peewee/relationships.html

[jwkvam]

Thanks! That looks great, I like having a dedicated section for those topics. It does seem easier to find plus I learned about .c and dicts.

[coleifer]

Made some major improvements to the following sections:

• Common table expressions
• Window functions
• Table names

Hopefully these new docs help someone trying to do some advanced SQL with Peewee -- or those who are confused about table names.

[astrilchuk]

I have been bitten a few times reading the docs, trying to use features, only to realize the feature is only available in the master branch (or an updated version). It would be nice to be able to choose a specific version in read-the-docs. Or possibly make it clear which version "stable" refers to.

[vijaymarupudi]

The documentation on JSONField, specifically .tree() and .children() can be improved. Reading your blog post on the matter helped me achieve the desired goal indirectly (without using the methods), but examples on how to use the methods would be greatly appreciated.

[coleifer]

Added docs for the JSONField methods you mentioned. Thanks for the suggestion.

[darkmoon233]

i am a Chinese student.I know you try to make the document easy to read.But i real have poor english.If we can have a Document wrote by Chinese , we can use peewee more easy. Thank you for reading.

[coleifer]

Unfortunately that would require someone who knows Chinese and is very interested in putting a lot of effort into making a translation (and then keeping it up-to-date). English seems to be the lingua franca of open-source. Maybe google translate can help?

[darkmoon233]

Thank you for your reply, google translation is not bad. If there is a project on github that helps translate the document, someone might be involved.

[gustavi]

As discussed on IRC, the PostgreSQL "UPDATE FROM" feature could be really useful in documentation.

[tuukkamustonen]

Just migrated from 2.10.2 to 3.6.4 and it was mostly a smooth experience (struggled a bit because I'm overriding some internals, but public API hasn't changed much which is nice).

I plan to use CTEs that are now supported. Maybe you could mention/explain the c property (in CTE) that is used to refer to fields...?

Other than that, I've always found peewee docs pretty nice, and although I'm sometimes yearning for more examples, SQL is such a vast landscape and you just cannot cover it all.

---

Something else (sorry if this ain't the right forum to ask): When using CTEs, how can I:

WITH q AS (...) SELECT * FROM q;

I managed to run:

cte = Node.select().where(...).order_by(...).cte('nodes')
query = Node.select().join(cte, on=(Node.id == cte.c.id)).with_cte(cte)

But if I drop the join, then it fails (Node.select() produces SELECT FROM "node" not "nodes"). So, how can I do this without join? (Joining feels unnecessary and I seem to lose ordering then, too.)

(Why would I want this? In some cases, my postgres query planner is choosing non-optimal plan (skipping index), and using CTEs helps with that (as for some reason, as CTE the index gets used.)

[coleifer]

cte = Node.select().where(...).order_by(...).cte('notes')

# When using cte.select_from() it's not necessary to specify ".with_cte()"
query = cte.select_from(cte.c.id, cte.c.other_column)

[tuukkamustonen]

Yeah, I see it in http://docs.peewee-orm.com/en/latest/peewee/api.html?highlight=select_from#CTE.select_from, should have been more careful... thanks!

[Nocturem]

I would love if there was some fleshed out details on http://docs.peewee-orm.com/en/latest/peewee/database.html#adding-a-new-database-driver

I am trying to drag https://github.com/COUR4G3/peewee-mssql into peewee 3.0
problem is that the query compiler class doesn't exist anymore and I am not sure how to extend the new query API,

The immediate problem is around swapping limit & offset with either SELECT TOP or
"ORDER BY table.primary_key OFFSET %s ROWS FETCH NEXT %s ROWS ONLY"
this will at least get it compatible with tsql 2012 onwards.

[coleifer]

@Nocturem -- that's beyond the scope of the documentation I plan to write, anyways. The SQL generation code is much much better in Peewee 3.0 -- in fact that was the prime reason for the rewrite -- so hopefully you can find a way to make it work. After all, the SQL generation code can be read in its entirety in a single sitting, and won't be of much interest to the average user of Peewee...hence, no docs.

[sobfiggis]

Would probably be beneficial to remove the wildcard imports

from peewee import *

in the documentation, just to make it easier to understand what parts come from where.

[MinchinWeb]

This link from the 3.5.2 Changelog doesn't work --> [window functions in Peewee](http://docs.peewee-orm.com/en/latest/peewee/querying.htmlwindow-functions)

[coleifer]

Erm...it seems working for me? 89f563d

[MinchinWeb]

@coleifer I run a service called PyUp on some of my repo's that lets me know one of project requirements gets updated. It seems they mis-copied the link, dropping the hash mark out of it. See here --> https://pyup.io/changelogs/peewee/#3.5.2

Ah yes, we filter out #'s to remove markdown and github issue references, but our system incorrectly filter's out #'s in urls which is causing this error. Thanks for reporting it! We are working on a fix.

So everything is fine on your end. Sorry for the false alarm.

[conqp]

I would appreciate a deeper API docmentation of the design and structure of peewee.
Maybe starting with docstrings?! I'd be happy to contribute here.

[jberkel]

The quickstart doesn't mention the automagic class => table name mapping. Maybe this could be added to the info box, which currently reads:

Note that we named our model Person instead of People. This is a convention you should follow even though the table will contain multiple people, we always name the class using the singular form.

[coleifer]

I would appreciate a deeper API docmentation of the design and structure of peewee.

If it's documented, then it might be considered a public/stable API and people would then be entitled to the same expectations of stability (presumably) they would from the currently-documented APIs.

[coleifer]

Class naming / table names note added here: c8b7422

I think one should be cautious about putting too much information in the quickstart, since it's intended as the briefest of introductions...but in this case I think it's probably worth explaining.

[jberkel]

Another thing missing in the 3.x changes doc:

Renaming of

JOIN_LEFT_OUTER => JOIN.LEFT_OUTER etc.

[jberkel]

More 3.x changes: the renaming of extension_options => options also applies to FTSModel / FTS5Model (doc just mentions VirtualModel) or maybe this is clear from the context?

[jberkel]

More 3.x changes: as_entity() removed, replaced with ._meta.entity

[MinchinWeb]

I just spent far too long trying to figure out where fn came from (as in fn.COUNT()). I finally figured out it's an import from the peewee namespace. I'm not sure how to fix it yet, but it would be helpful to make it more clear.

[adontz]

I have one very small suggestion. Explicitly state all imports in documentation. I have to recover imports by greping names in source code to make examples work.

[coleifer]

I'm pretty happy with the state of things, going to close and will address subsequent improvements as they arise.