Docs: reword the dbm.dumb introduction #114550
Conversation
Also: - consistently name the database "dumbdbm" - fix broken dumbdbm class refs - improve accuracy of the dbm.dump.open() spec
erlend-aasland
added
skip issue
skip news
needs backport to 3.11
Co-authored-by: Ezio Melotti <[email protected]>
erlend-aasland
requested review from
corona10 and
serhiy-storchaka
as code owners
Notice that for each backend, there are three names to keep in mind:
This PR aligns the name of the database manager and the name of the class. Note that I deliberately did not use the |
|
Let me expand on #114550 (comment): the docs already use |
|
ndbm and gdbm refer to external libraries and formats. Dumbdbm does not exist outside of the context of the dbm.dumb module, so why use name "dumbdbm" instead of "dbm.dumb" which directly refers to the module name? I planned to replace "a dumbdbm object" with simple "a database object", since the name of the class is not public. |
Because there is different wording depending on if you talk about a type of database or a module. If we chose to not talk about the database type ("dumbdbm"), then we have to adjust the wording even more. I can do that, since you insist.
This is what I did for the dbm.sqlite3 PR. We can do the same here. |
- Don't use "dumbdbm" as a database name; instead use the submodule name - Don't use a class name; only talk about "database objects" - Consistently use correct markup for parameters - Use param list for open()
|
I tried to address all your concerns in 4445822 @serhiy-storchaka. |
|
|
||
| The optional *flag* argument can be: | ||
| :param filename: | ||
| The basename of the database file (without extensions). |
There was a problem hiding this comment.
IMO, "without extensions" is to be understood by the term "basename". The following should suffice:
| The basename of the database file (without extensions). | |
| The basename of the database file. |
| As with other :mod:`dbm` backends, | ||
| the keys and values are always stored as :class:`bytes`. |
There was a problem hiding this comment.
This note looks strange now.
In Python 2, str and unicode was interchangeable to some degree. If you use ASCII-only, it was not important that you set db['key'] = 'value' or db[u'key'] = u'value'. But it may still be useful to know that if you set an unicode value, you get back a str value. This is what about this note. It is not about the internal format, it is about the output types.
But in Python 3 bytes and str are no longer interchangeable, they are no longer different representations of the same. So this is more serious question. The database is bytes to bytes mapping by its nature, but it accepts also str as input and automatically encode them to bytes using UTF-8. This should be true for all dbm implementations, so perhaps this explanation should be move to more generic description.
There was a problem hiding this comment.
This note looks strange now.
You prefer the old variant? "As with other persistent mappings, the keys and values are always stored as bytes."
This should be true for all dbm implementations, so perhaps this explanation should be move to more generic description.
This is already mentioned in the generic description. It is also mentioned in the docs of every dbm submodule. If we want to address this, we should do so in a separate PR; this PR is for dbm.dumb docs only.
It is tempting to grow the scope of doc PR, and end up changing a lot of things at once. This makes for complicated docs changes where it is hard to see what changes were actually done. I prefer if we try to focus on atomic doc changes.
There was a problem hiding this comment.
I just noticed that it looks strange (both old and new variants). It could be improved in a separate PR.
There was a problem hiding this comment.
I created #114609 to follow up this.
Co-authored-by: Serhiy Storchaka <[email protected]>
This comment has been minimized.
This comment has been minimized.
- consistently use correct parameter markup - consistently use submodule name as database name - improve accuracy of the dbm.dumb.open() spec - remove dumbdbm class refs and replace them with generic "database object" - use parameter list for dbm.dumb.open() (cherry picked from commit 6c2b419) Co-authored-by: Erlend E. Aasland <[email protected]>
- consistently use correct parameter markup - consistently use submodule name as database name - improve accuracy of the dbm.dumb.open() spec - remove dumbdbm class refs and replace them with generic "database object" - use parameter list for dbm.dumb.open() (cherry picked from commit 6c2b419) Co-authored-by: Erlend E. Aasland <[email protected]>
|
GH-114620 is a backport of this pull request to the 3.12 branch. |
|
GH-114621 is a backport of this pull request to the 3.11 branch. |
|
Thanks for the reviews, everyone. |
(cherry picked from commit 6c2b419) - consistently use correct parameter markup - consistently use submodule name as database name - improve accuracy of the dbm.dumb.open() spec - remove dumbdbm class refs and replace them with generic "database object" - use parameter list for dbm.dumb.open() (cherry picked from commit 6c2b419) Co-authored-by: Erlend E. Aasland <[email protected]>
(cherry picked from commit 6c2b419) - consistently use correct parameter markup - consistently use submodule name as database name - improve accuracy of the dbm.dumb.open() spec - remove dumbdbm class refs and replace them with generic "database object" - use parameter list for dbm.dumb.open() (cherry picked from commit 6c2b419) Co-authored-by: Erlend E. Aasland <[email protected]>
- consistently use correct parameter markup - consistently use submodule name as database name - improve accuracy of the dbm.dumb.open() spec - remove dumbdbm class refs and replace them with generic "database object" - use parameter list for dbm.dumb.open()
- consistently use correct parameter markup - consistently use submodule name as database name - improve accuracy of the dbm.dumb.open() spec - remove dumbdbm class refs and replace them with generic "database object" - use parameter list for dbm.dumb.open()
Also:
📚 Documentation preview 📚: https://cpython-previews--114550.org.readthedocs.build/