@@ -100,7 +100,8 @@ The :meth:`!setdefault` method requires two arguments.
100100
101101Key and values are always stored as :class: `bytes `. This means that when
102102strings are used they are implicitly converted to the default encoding before
103- being stored.
103+ being stored. For detailed information about accepted types, see
104+ :ref: `dbm-key-value-types `.
104105
105106These objects also support being used in a :keyword: `with ` statement, which
106107will automatically close them when done.
@@ -121,6 +122,47 @@ will automatically close them when done.
121122 :meth: `!clear ` methods are now available for all :mod: `!dbm ` backends.
122123
123124
125+ .. _dbm-key-value-types :
126+
127+ Key and value types
128+ -------------------
129+
130+ The accepted types for keys and values vary by backend. Keys and values are
131+ handled the same way, except where noted below:
132+
133+ * **Traditional backends: **
134+
135+ * :mod: `dbm.gnu ` and :mod: `dbm.ndbm `: Accept :class: `str ` and :class: `bytes `
136+ objects.
137+ * :mod: `dbm.dumb `: Accepts :class: `str ` and :class: `bytes ` objects;
138+ :class: `bytearray ` is acceptable as a value, but not as a key.
139+
140+ * **SQLite backend ** (:mod: `dbm.sqlite3 `): Accepts :class: `str `, :class: `bytes `,
141+ :class: `int `, :class: `float `, :class: `bool `, :class: `bytearray `,
142+ :class: `memoryview `, and :class: `array.array ` objects.
143+
144+ **Storage format: **
145+
146+ All keys and values are stored as :class: `bytes ` objects in the database.
147+ When retrieving, you'll always get bytes back, regardless of the original
148+ type stored.
149+
150+ **Type conversion examples: **
151+
152+ * ``db['key'] = 'string' `` stored as ``b'string' ``
153+ * ``db['key'] = bytearray(b'data') `` stored as ``b'data' ``
154+ (:mod: `dbm.dumb ` and :mod: `dbm.sqlite3 ` only)
155+ * ``db['key'] = 42 `` stored as ``b'42' `` (:mod: `dbm.sqlite3 ` only)
156+ * ``db['key'] = 3.14 `` stored as ``b'3.14' `` (:mod: `dbm.sqlite3 ` only)
157+ * ``db['key'] = True `` stored as ``b'1' `` (:mod: `dbm.sqlite3 ` only)
158+ * ``db['key'] = False `` stored as ``b'0' `` (:mod: `dbm.sqlite3 ` only)
159+ * ``db['key'] = memoryview(b'data') `` stored as ``b'data' ``
160+ (:mod: `dbm.sqlite3 ` only)
161+ * ``db['key'] = array.array('i', [1, 2, 3]) `` stored as bytes (for example, on
162+ little-endian: ``b'\x01\x00\x00\x00\x02\x00\x00\x00\x03\x00\x00\x00' ``)
163+ (:mod: `dbm.sqlite3 ` only)
164+
165+
124166The following example records some hostnames and a corresponding title, and
125167then prints out the contents of the database::
126168
@@ -142,8 +184,9 @@ then prints out the contents of the database::
142184 # Often-used methods of the dict interface work too.
143185 print(db.get('python.org', b'not present'))
144186
145- # Storing a non-string key or value will raise an exception (most
146- # likely a TypeError).
187+ # Storing a non-string key or value behavior depends on the backend:
188+ # - Traditional backends (ndbm, gnu, dumb) will raise a TypeError
189+ # - The sqlite3 backend accepts it and converts to bytes
147190 db['www.yahoo.com'] = 4
148191
149192 # db is automatically closed when leaving the with statement.
0 commit comments