Check, fix and update examples

twisted / txmongo

asynchronous python driver for mongo

https://txmongo.readthedocs.io

Apache License 2.0

338 stars 102 forks source link

Check, fix and update examples #216

Open IlyaSkriblovsky opened 7 years ago

IlyaSkriblovsky commented 7 years ago

Unfortunately, many of our examples are of bad quality.

Some examples simply not working due to errors in the example code
Some are confusingly overengineered
Some treat Connection and ConnectionPool like Deferreds which may confuse readers
Almost all of them use the old CRUD API
Many are py3-incompatible

We need short, consice, practical (and working!) examples to simplify onboarding of new users!

(see #215)

trenton42 commented 7 years ago

Yes yes yes! I would like to help with this. Out of curiosity, I went over to the pymongo project to see if they had anything, but they didn't. Do you have a strategy or layout in mind to set these up? It might be helpful if the various examples followed some sort of template to make them easier to navigate and understand.

IlyaSkriblovsky commented 7 years ago

I'm not sure what common template do you mean? I personally prefer very short and concise examples mainly to help with bootstrapping. Longer real-life examples are optional for me.

trenton42 commented 7 years ago

Sorry I wasn't clear. I was mainly just thinking about organizing the examples so they could be run the same way and their code was laid out similarly so it would be easier to follow from one example to the next.

IlyaSkriblovsky commented 7 years ago

Extensive list of possible examples:

[ ] Single connection, Connection pool
[ ] Connecting by host/port, by url, with url options
[ ] Authentication
[ ] SSL
[ ] insert, update, replace, remove
[ ] find, find_one, sorting, iterating with cursor, find_oneand*
[ ] Misc collection methods: count, distinct, drop, create_index
[ ] Misc database methods: command, create_collection, collection_names
[ ] Bulk ops
[ ] Write concerns & Codec options
[ ] GridFS
[ ] Aggregation
[ ] Callback-style vs. inlineCallbacks-style
[ ] A couple of real-life examples: webapp, standalone command line utility
[ ] May be some useful real-life tricks: optimistic locking, incrementing integer counter, ...

IlyaSkriblovsky commented 7 years ago

I hope most of examples won't contain much of boilerplate code, so the common template might only contain an assertion that all examples connect to localhost:27017/test database. May be I'm missing something.

trenton42 commented 7 years ago

That is good 👍 I will have a go at writing some examples and send over a PR

IlyaSkriblovsky commented 7 years ago

Thanks! I will try to find some time for this too. Please ping me with the topics you are working on when you start to avoid duplicating efforts.

IlyaSkriblovsky commented 7 years ago

started to write some connection examples in #217