Skip to content

Docs: reword the dbm.dumb introduction #114550

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.

Sign up for GitHub

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

Merged
merged 9 commits into from
Jan 26, 2024
Merged

Docs: reword the dbm.dumb introduction #114550

Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
797760e
Docs: reword the dbm.dumb introduction
erlend-aasland Jan 25, 2024
0845fb6
Update Doc/library/dbm.rst
erlend-aasland Jan 26, 2024
081a228
Merge branch 'main' into docs/dbmdumb/reword
erlend-aasland Jan 26, 2024
4445822
Address Serhiy's initial round of review
erlend-aasland Jan 26, 2024
e8f8d07
Update Doc/library/dbm.rst
erlend-aasland Jan 26, 2024
8354d44
Update Doc/library/dbm.rst
erlend-aasland Jan 26, 2024
0883480
Update Doc/library/dbm.rst
erlend-aasland Jan 26, 2024
e56d439
Update Doc/library/dbm.rst
erlend-aasland Jan 26, 2024
db3c0ee
Update Doc/library/dbm.rst
erlend-aasland Jan 26, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 36 additions & 30 deletions Doc/library/dbm.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -346,61 +346,67 @@ to locate the appropriate header file to simplify building this module.

--------------

The :mod:`dbm.dumb` module provides a persistent dictionary-like interface which
is written entirely in Python. Unlike other modules such as :mod:`dbm.gnu` no
external library is required. As with other persistent mappings, the keys and
values are always stored as bytes.

The module defines the following:
The :mod:`dbm.dumb` module provides a persistent :class:`dict`-like
interface which is written entirely in Python.
Unlike other :mod:`dbm` backends, such as :mod:`dbm.gnu`, no
external library is required.
As with other :mod:`dbm` backends,
the keys and values are always stored as :class:`bytes`.
Comment on lines +353 to +354
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I just noticed that it looks strange (both old and new variants). It could be improved in a separate PR.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I created #114609 to follow up this.


The :mod:`!dbm.dumb` module defines the following:

.. exception:: error

Raised on :mod:`dbm.dumb`-specific errors, such as I/O errors. :exc:`KeyError` is
raised for general mapping errors like specifying an incorrect key.


.. function:: open(filename[, flag[, mode]])
.. function:: open(filename, flag="c", mode=0o666)

Open a ``dumbdbm`` database and return a dumbdbm object. The *filename* argument is
the basename of the database file (without any specific extensions). When a
dumbdbm database is created, files with :file:`.dat` and :file:`.dir` extensions
are created.
Open a :mod:`!dbm.dumb` database.
The returned database object behaves similar to a :term:`mapping`,
in addition to providing :meth:`~dumbdbm.sync` and :meth:`~dumbdbm.close`
methods.

The optional *flag* argument can be:
:param filename:
The basename of the database file (without extensions).
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IMO, "without extensions" is to be understood by the term "basename". The following should suffice:

Suggested change
The basename of the database file (without extensions).
The basename of the database file.

A new database creates the following files:

.. csv-table::
:header: "Value", "Meaning"
- :file:`{filename}.dat`
- :file:`{filename}.dir`
:type database: :term:`path-like object`

``'r'``, |flag_r|
``'w'``, |flag_w|
``'c'`` (default), |flag_c|
``'n'``, |flag_n|
:param str flag:
.. csv-table::
:header: "Value", "Meaning"

The optional *mode* argument is the Unix mode of the file, used only when the
database has to be created. It defaults to octal ``0o666`` (and will be modified
by the prevailing umask).
``'r'``, |flag_r|
``'w'``, |flag_w|
``'c'`` (default), |flag_c|
``'n'``, |flag_n|

:param int mode:
The Unix file access mode of the file (default: ``0o666``),
used only when the database has to be created.

.. warning::
It is possible to crash the Python interpreter when loading a database
with a sufficiently large/complex entry due to stack depth limitations in
Python's AST compiler.

.. versionchanged:: 3.5
:func:`.open` always creates a new database when the flag has the value
``'n'``.
:func:`open` always creates a new database when *flag* is ``'n'``.

.. versionchanged:: 3.8
A database opened with flags ``'r'`` is now read-only. Opening with
flags ``'r'`` and ``'w'`` no longer creates a database if it does not
exist.
A database opened read-only if *flag* is ``'r'``.
A database is not created if it does not exist if *flag* is ``'r'`` or ``'w'``.

.. versionchanged:: 3.11
Accepts :term:`path-like object` for filename.
*filename* accepts a :term:`path-like object`.

In addition to the methods provided by the
:class:`collections.abc.MutableMapping` class, :class:`dumbdbm` objects
provide the following methods:
:class:`collections.abc.MutableMapping` class,
the following methods are provided:

.. method:: dumbdbm.sync()

Expand All @@ -409,5 +415,5 @@ The module defines the following:

.. method:: dumbdbm.close()

Close the ``dumbdbm`` database.
Close the database.