update the README.rst

[morotti]

Update the README.rst:

• step by step explanation on how to use the library (read/write/etc). "it's just dict with a commit" really doesn't cut it.
• add section on performance. this thing work effectively with large files, even larger than memory. it's AWESOME. that alone is a reason to use, much better than a json.dumps(allobjects) when starting up a project.
• highlight support for JSON. json is great, pickle is blanket banned in many places due to critical security vulnerability.

I wanted to say this library is AMAZING. I am gonna use that for so many things! And to think I almost skipped it because the intro was meh for a first use.

[mpenkov]

Not sure about this. @mpenkov do you reckon this really improves the documentation?

Yeah, I think it's a step in the right direction (the project doesn't get a lot of attention), but obviously needs more effort.

[morotti]

What python version does the project support?

• The doc said 2.5 to 3.4
• The travis.yaml says 2.6 to 3.6.

2.6 is long end of life.

• Officially end of life in 2013.
• It's used in /usr/bin/python RHEL/Centos 6 though, so supported by RedHat. The extended extended extended paid support is ending on November 2020.

I am surprised Travis stills offers python 2.6. It's probably the stage where they might drop it any minute.

Might want to drop python 2.6 and add 3.7+ 3.8

[piskvorky]

Might want to drop python 2.6 and add 3.7+ 3.8

I agree. Moving sqlitedict to support only 3.6+ would be awesome – people who still need older Pythons can install older versions of sqlitedict.

And I believe existing data (DB files on disk) will remain readable, because newer Pythons still support the old pickle protocol versions.

Vice versa is not true though – new pickles won't be readable in old Pythons.

[morotti]

I have a problem with getting doctest to work. I think the idea of testing the examples is great but the implementation clearly doesn't work.

Trying to run doctest.testfile("README.rst") on the file currently in master fails with a variety of errors. 1 items had failures: 7 of 21 in old.rst Test Failed 7 failures. TestResults(failed=7, attempted=21)

It doesn't work and it's not part part of the travis build+test. I'd go as far as saying the examples never worked under doctest.

I won't be able to get the documentation to use this doctest thing. If you really want it, the current examples should first be fixed to work and run under travis.

[mpenkov]

I'd rather have broken doctests (14 out of 21 ain't that bad) then no doctests at all.

What's the actual problem with the tests? It shouldn't be that hard to fix.

[morotti]

After fixing the print statement (need parenthesis on python 3). doctest is throwing random errors about unexpected end of file, syntax error, indentation errors, expected output but got something else, etc... Just run and see for yourself doctest.testfile("README.rst"). I tried to investigate but it's nonsense to me, looks like it's failing to parse or it's expecting a quite different format. There are 5 code blocks in total, there shouldn't be 21 tests founds in the first place.

[morotti]

I think I've edited everything that was mentioned. There's only the issue with doctest left that is not due to my edit, it didn't work before.