New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation Improvement - Master Issue #1640

Open
coleifer opened this Issue Jun 21, 2018 · 30 comments

Comments

Projects
None yet
@coleifer
Owner

coleifer commented Jun 21, 2018

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

This comment has been minimized.

jwkvam commented Jun 23, 2018

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

This comment has been minimized.

Owner

coleifer commented Jun 24, 2018

Thanks for the feedback, I appreciate it!

@coleifer

This comment has been minimized.

Owner

coleifer commented Jun 26, 2018

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

This comment has been minimized.

jwkvam commented Jun 27, 2018

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

This comment has been minimized.

Owner

coleifer commented Jul 3, 2018

Made some major improvements to the following sections:

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

@astrilchuk

This comment has been minimized.

astrilchuk commented Jul 4, 2018

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.

@vijaygopal1234

This comment has been minimized.

vijaygopal1234 commented Jul 19, 2018

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 a commit that referenced this issue Jul 19, 2018

@coleifer

This comment has been minimized.

Owner

coleifer commented Jul 24, 2018

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

@darkmoon233

This comment has been minimized.

darkmoon233 commented Jul 27, 2018

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

This comment has been minimized.

Owner

coleifer commented Jul 27, 2018

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

This comment has been minimized.

darkmoon233 commented Jul 27, 2018

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

This comment has been minimized.

gustavi commented Jul 30, 2018

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

coleifer added a commit that referenced this issue Jul 31, 2018

@tuukkamustonen

This comment has been minimized.

tuukkamustonen commented Aug 1, 2018

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

This comment has been minimized.

Owner

coleifer commented Aug 1, 2018

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

This comment has been minimized.

tuukkamustonen commented Aug 2, 2018

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

This comment has been minimized.

Nocturem commented Aug 7, 2018

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

This comment has been minimized.

Owner

coleifer commented Aug 7, 2018

@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

This comment has been minimized.

sobfiggis commented Aug 14, 2018

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 comment has been minimized.

MinchinWeb commented Aug 22, 2018

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

This comment has been minimized.

Owner

coleifer commented Aug 23, 2018

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

@MinchinWeb

This comment has been minimized.

MinchinWeb commented Aug 24, 2018

@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

This comment has been minimized.

Contributor

conqp commented Sep 19, 2018

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

This comment has been minimized.

Contributor

jberkel commented Sep 26, 2018

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

This comment has been minimized.

Owner

coleifer commented Sep 27, 2018

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 added a commit that referenced this issue Sep 27, 2018

@coleifer

This comment has been minimized.

Owner

coleifer commented Sep 27, 2018

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

This comment has been minimized.

Contributor

jberkel commented Sep 27, 2018

Another thing missing in the 3.x changes doc:

Renaming of

JOIN_LEFT_OUTER => JOIN.LEFT_OUTER etc.

coleifer added a commit that referenced this issue Sep 27, 2018

@jberkel

This comment has been minimized.

Contributor

jberkel commented Sep 29, 2018

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

This comment has been minimized.

Contributor

jberkel commented Sep 30, 2018

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

@MinchinWeb

This comment has been minimized.

MinchinWeb commented Oct 15, 2018

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

This comment has been minimized.

adontz commented Nov 18, 2018

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment