tags - start from
2. Section titles → with one emoji prefix
3. Sub-sections → with emoji prefix
4. Code blocks in
5. Lists use /
6. Function/class reference sections use name(args) — description` block, these are literal characters and should be preserved
- `If E present and has a .keys() method, does: for k in E: D[k] = E[k]` - same
- `If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v` - same
- `In either case, this is followed by: for k, v in F.items(): D[k] = v` - same
- `PEP 585 generic type` - fine
Now for class reference sections, I should use `name(args) — descriptionname(args) — description tags for copyability."
So the methods sections should be formatted as lists. This is a big restructuring, but the rule says it's important for scannability.
Looking at the volume, this document is quite long. Let me think about how to structure it efficiently while staying under 128k characters.
Let me look at the description section. There are several code blocks and explanations. I'll preserve them carefully.
Let me think about the strategy:
- NAME section → 📛 NAME
- Quick Reference → 🚀 Quick Reference
(NEW - I'll generate from content)
- Module Reference → 📚 Module Reference
- Description → 📝 Description
- Classes → 🏛️ Classes
with sub-sections for each class
- Functions → 🔧 Functions
- Data → 📊 Data
- File → 📁 File
For the class methods, I'll convert them to `name(args) — description
` format per rule 12.
For the BsdDbShelf methods, I need to handle the inheritance. The methods defined here include:
- __init__(self, dict, protocol=None, writeback=False, keyencoding='utf-8')
- first(self)
- last(self)
- next(self)
- previous(self)
- set_location(self, key)
I'll need to summarize inherited methods as well. Let me condense to keep under the character limit.
Let me also think about the code blocks. The description has multiple code examples that need to be in .
Let me start writing:
```html
📛 NAME
shelve - Manage shelves of pickled objects.
🚀 Quick Reference
Use Case Command Description Open a shelf shelve.open(filename)Open a persistent dictionary-like object Store data d[key] = dataStore arbitrary Python object at key Retrieve data data = d[key]Returns a copy of stored entry (raises KeyError if missing) Delete data del d[key]Remove entry at key (raises KeyError if missing) Check key key in dTest if key exists in the shelf List keys d.keys()Get all existing keys (slow on large shelves) Close shelf d.close()Flush changes and close the persistent dictionary Sync cache d.sync()Write back cached entries and synchronize to disk Mutable entries shelve.open(filename, writeback=True)Enable writeback for safe mutation of stored objects
📚 Module Reference
https://docs.python.org/3.10/library/shelve.html
The following documentation is automatically generated from the Python source files. It may be incomplete, incorrect or include features that are considered implementation detail and may vary between Python implementations. When in doubt, consult the module reference at the location listed above.
📝 Description
A "shelf" is a persistent, dictionary-like object. The difference with dbm databases is that the values (not the keys!) in a shelf can be essentially arbitrary Python objects -- anything that the "pickle" module can handle. This includes most class instances, recursive data types, and objects containing lots of shared sub-objects. The keys are ordinary strings.
To summarize the interface (key is a string, data is an arbitrary object):
import shelve
d = shelve.open(filename) # open, with (g)dbm filename -- no suffix
d[key] = data # store data at key (overwrites old data if
# using an existing key)
data = d[key] # retrieve a COPY of the data at key (raise
# KeyError if no such key) -- NOTE that this
# access returns a *copy* of the entry!
del d[key] # delete data stored at key (raises KeyError
# if no such key)
flag = key in d # true if the key exists
list = d.keys() # a list of all existing keys (slow!)
d.close() # close it
Dependent on the implementation, closing a persistent dictionary may or may not be necessary to flush changes to disk.
Normally, d[key] returns a COPY of the entry. This needs care when mutable entries are mutated: for example, if d[key] is a list,
d[key].append(anitem)
does NOT modify the entry d[key] itself, as stored in the persistent mapping -- it only modifies the copy, which is then immediately discarded, so that the append has NO effect whatsoever. To append an item to d[key] in a way that will affect the persistent mapping, use:
data = d[key]
data.append(anitem)
d[key] = data
To avoid the problem with mutable entries, you may pass the keyword argument writeback=True in the call to shelve.open. When you use:
d = shelve.open(filename, writeback=True)
then d keeps a cache of all entries you access, and writes them all back to the persistent mapping when you call d.close(). This ensures that such usage as d[key].append(anitem) works as intended.
However, using keyword argument writeback=True may consume vast amount of memory for the cache, and it may make d.close() very slow, if you access many of d's entries after opening it in this way: d has no way to check which of the entries you access are mutable and/or which ones you actually mutate, so it must cache, and write back at close, all of the entries that you access. You can call d.sync() to write back all the entries in the cache, and empty the cache (d.sync() also synchronizes the persistent dictionary on disk, if feasible).
🏛️ Classes
Class hierarchy:
collections.abc.MutableMapping(collections.abc.Mapping)
Shelf
BsdDbShelf
DbfilenameShelf
🔷 BsdDbShelf (Shelf)
BsdDbShelf(dict, protocol=None, writeback=False, keyencoding='utf-8')
Shelf implementation using the "BSD" db interface.
This adds methods first(), next(), previous(), last() and set_location() that have no counterpart in [g]dbm databases.
The actual database must be opened using one of the "bsddb" modules "open" routines (i.e. bsddb.hashopen, bsddb.btopen or bsddb.rnopen) and passed to the constructor.
See the module's __doc__ string for an overview of the interface.
Method resolution order:
BsdDbShelf
Shelf
collections.abc.MutableMapping
collections.abc.Mapping
collections.abc.Collection
collections.abc.Sized
collections.abc.Iterable
collections.abc.Container
builtins.object
Methods defined here:
__init__(self, dict, protocol=None, writeback=False, keyencoding='utf-8') — Initialize self. See help(type(self)) for accurate signature.first(self) — Move cursor to first item.last(self) — Move cursor to last item.next(self) — Move cursor to next item.previous(self) — Move cursor to previous item.set_location(self, key) — Move cursor to the position of key.
Data and other attributes defined here:
__abstractmethods__ — frozenset()
Methods inherited from Shelf:
__contains__(self, key)__del__(self)__delitem__(self, key)__enter__(self)__exit__(self, type, value, traceback)__getitem__(self, key)__iter__(self)__len__(self)__setitem__(self, key, value)close(self)get(self, key, default=None) — D.get(k[,d]) -> D[k] if k in D, else d. d defaults to None.sync(self)
Data descriptors inherited from Shelf:
__dict__ — dictionary for instance variables (if defined)__weakref__ — list of weak references to the object (if defined)
Methods inherited from collections.abc.MutableMapping:
clear(self) — D.clear() -> None. Remove all items from D.pop(self, key, default=<object object at 0x7fec86544190>) — D.pop(k[,d]) -> v, remove specified key and return the corresponding value. If key is not found, d is returned if given, otherwise KeyError is raised.popitem(self) — D.popitem() -> (k, v), remove and return some (key, value) pair as a 2-tuple; but raise KeyError if D is empty.setdefault(self, key, default=None) — D.setdefault(k[,d]) -> D.get(k,d), also set D[k]=d if k not in Dupdate(self, other=(), /, **kwds) — D.update([E, ]**F) -> None. Update D from mapping/iterable E and F.
```
Wait, I have to be careful with the pop default value. The original has `default=<object object at 0x7fec86544190>` which is correctly escaped. In my output inside a tag, the `<` and `>` will render as ``. Hmm, but the HTML character references work anywhere. Actually in tags, the character references also work fine. Let me preserve the original escaping.
Actually, wait. The original uses `<object object at 0x7fec86544190>` which is a properly escaped HTML way to display this. Let me preserve it.
Hmm, but in a list item with a code tag, I need to be careful. Let me think... Actually using `<` and `>` in HTML is fine and renders as ``. So I can write `pop(self, key, default=<object object at 0x7fec86544190>) — D.pop(k[,d])...` tags.
For the `__subclasshook__` part, I have:
```
__subclasshook__(C) from abc.ABCMeta
Abstract classes can override this to customize issubclass().
This is invoked early on by abc.ABCMeta.__subclasscheck__().
It should return True, False or NotImplemented. If it returns
NotImplemented, the normal algorithm is used. Otherwise, it
overrides the normal algorithm (and the outcome is cached).
```
No special chars here, just text.
For `__class_getitem__`:
```
__class_getitem__ = GenericAlias(...) from abc.ABCMeta
Represent a PEP 585 generic type
E.g. for t = list[int], t.__origin__ is list and t.__args__ is (int,).
```
No special chars.
Let me think about what to put for class method entries. The format from the original pydoc has many spaces and unusual indentation. I should clean it up but preserve information.
Actually, let me re-read rule 12 more carefully:
"For function, method, and class reference sections (pydoc modules, ruby ri classes, perldoc function lists): use name(args) — description tags for copyability. Emoji-per-item in long lists hurts scannability — only the section heading needs an emoji."
OK so the rule is clear: I should use that format, not the bizarre pydoc formatting. This is going to make the output much cleaner.
Let me now consider: the `update` method description in MutableMapping is long with multi-line text. The format like:
```
update(self, other=(), /, **kwds)
D.update([E, ]**F) -> None. Update D from mapping/iterable E and F.
If E present and has a .keys() method, does: for k in E: D[k] = E[k]
If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v
In either case, this is followed by: for k, v in F.items(): D[k] = v
```
This has `[k]`, `[]` etc which are fine in code tags. No `` to escape.
Hmm but wait, in the original, the lines like `D[k] = E[k]` are part of method descriptions. The `D[k]` contains `[k]` which is just a bracket, not a tag. So no escaping needed. Good.
For the `__subclasshook__` description:
"This is invoked early on by abc.ABCMeta.__subclasscheck__()."
Contains `.` and `()` but no `` to escape. Good.
For `__class_getitem__`:
"E.g. for t = list[int], t.__origin__ is list and t.__args__ is (int,)."
Has brackets and parens, no ``. Good.
OK let me write the final HTML. I'll be efficient with the inherited methods since they appear in multiple classes. Since rule says "preserve structure", I should keep them.
Actually, let me focus on keeping it concise but preserving all content. I'll skip some of the verbose descriptions where the method name is self-explanatory, but I'll keep all method names and the key documentation.
Let me draft the final HTML now:
```html
📛 NAME
shelve - Manage shelves of pickled objects.
🚀 Quick Reference
Use Case Command Description 🆕 Open a shelf shelve.open(filename)Open a persistent dictionary for reading/writing 💾 Store data d[key] = dataStore arbitrary pickled object at key (overwrites) 📤 Retrieve data data = d[key]Returns a COPY of the entry (raises KeyError if missing) 🗑️ Delete data del d[key]Remove entry at key (raises KeyError if missing) 🔍 Check existence key in dTest if key exists in the shelf 📋 List keys d.keys()Get all existing keys (slow on large shelves) 🔌 Close shelf d.close()Flush changes and close the persistent dictionary 🔄 Sync cache d.sync()Write back cached entries to disk and empty cache ✏️ Mutable entries shelve.open(filename, writeback=True)Enable writeback cache for safe in-place mutation 🧱 BSD DB backend BsdDbShelf(dict, ...)Shelf using bsddb (hashopen/btopen/rnopen) backend 📁 Filename DB backend DbfilenameShelf(filename, ...)Shelf using generic dbm backend
```
Wait, the rules say use case column has emoji but the description column might also have. Let me check rule 19: "Add descriptive emoji to option descriptions and list item text". So yes, emoji are appropriate.
But rule 11 says "NEVER use emoji characters... as visual bullet replacements at the start of paragraphs". This is fine because we're using a table, not paragraphs.
Rule 20: Emoji should be standard Unicode, widely supported. Using 🆕, 💾, 📤, 🗑️, 🔍, 📋, 🔌, 🔄, ✏️, 🧱, 📁 - all standard.
Hmm wait, rule 21 says "Use a
with one emoji prefix
3. Sub-sections → with emoji prefix
4. Code blocks in
5. Lists use /
6. Function/class reference sections use name(args) — description` block, these are literal characters and should be preserved
- `If E present and has a .keys() method, does: for k in E: D[k] = E[k]` - same
- `If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v` - same
- `In either case, this is followed by: for k, v in F.items(): D[k] = v` - same
- `PEP 585 generic type` - fine
Now for class reference sections, I should use `name(args) — descriptionname(args) — description tags for copyability."
So the methods sections should be formatted as lists. This is a big restructuring, but the rule says it's important for scannability.
Looking at the volume, this document is quite long. Let me think about how to structure it efficiently while staying under 128k characters.
Let me look at the description section. There are several code blocks and explanations. I'll preserve them carefully.
Let me think about the strategy:
- NAME section → 📛 NAME
- Quick Reference → 🚀 Quick Reference
(NEW - I'll generate from content)
- Module Reference → 📚 Module Reference
- Description → 📝 Description
- Classes → 🏛️ Classes
with sub-sections for each class
- Functions → 🔧 Functions
- Data → 📊 Data
- File → 📁 File
For the class methods, I'll convert them to `name(args) — description
` format per rule 12.
For the BsdDbShelf methods, I need to handle the inheritance. The methods defined here include:
- __init__(self, dict, protocol=None, writeback=False, keyencoding='utf-8')
- first(self)
- last(self)
- next(self)
- previous(self)
- set_location(self, key)
I'll need to summarize inherited methods as well. Let me condense to keep under the character limit.
Let me also think about the code blocks. The description has multiple code examples that need to be in .
Let me start writing:
```html
📛 NAME
shelve - Manage shelves of pickled objects.
🚀 Quick Reference
Use Case Command Description Open a shelf shelve.open(filename)Open a persistent dictionary-like object Store data d[key] = dataStore arbitrary Python object at key Retrieve data data = d[key]Returns a copy of stored entry (raises KeyError if missing) Delete data del d[key]Remove entry at key (raises KeyError if missing) Check key key in dTest if key exists in the shelf List keys d.keys()Get all existing keys (slow on large shelves) Close shelf d.close()Flush changes and close the persistent dictionary Sync cache d.sync()Write back cached entries and synchronize to disk Mutable entries shelve.open(filename, writeback=True)Enable writeback for safe mutation of stored objects
📚 Module Reference
https://docs.python.org/3.10/library/shelve.html
The following documentation is automatically generated from the Python source files. It may be incomplete, incorrect or include features that are considered implementation detail and may vary between Python implementations. When in doubt, consult the module reference at the location listed above.
📝 Description
A "shelf" is a persistent, dictionary-like object. The difference with dbm databases is that the values (not the keys!) in a shelf can be essentially arbitrary Python objects -- anything that the "pickle" module can handle. This includes most class instances, recursive data types, and objects containing lots of shared sub-objects. The keys are ordinary strings.
To summarize the interface (key is a string, data is an arbitrary object):
import shelve
d = shelve.open(filename) # open, with (g)dbm filename -- no suffix
d[key] = data # store data at key (overwrites old data if
# using an existing key)
data = d[key] # retrieve a COPY of the data at key (raise
# KeyError if no such key) -- NOTE that this
# access returns a *copy* of the entry!
del d[key] # delete data stored at key (raises KeyError
# if no such key)
flag = key in d # true if the key exists
list = d.keys() # a list of all existing keys (slow!)
d.close() # close it
Dependent on the implementation, closing a persistent dictionary may or may not be necessary to flush changes to disk.
Normally, d[key] returns a COPY of the entry. This needs care when mutable entries are mutated: for example, if d[key] is a list,
d[key].append(anitem)
does NOT modify the entry d[key] itself, as stored in the persistent mapping -- it only modifies the copy, which is then immediately discarded, so that the append has NO effect whatsoever. To append an item to d[key] in a way that will affect the persistent mapping, use:
data = d[key]
data.append(anitem)
d[key] = data
To avoid the problem with mutable entries, you may pass the keyword argument writeback=True in the call to shelve.open. When you use:
d = shelve.open(filename, writeback=True)
then d keeps a cache of all entries you access, and writes them all back to the persistent mapping when you call d.close(). This ensures that such usage as d[key].append(anitem) works as intended.
However, using keyword argument writeback=True may consume vast amount of memory for the cache, and it may make d.close() very slow, if you access many of d's entries after opening it in this way: d has no way to check which of the entries you access are mutable and/or which ones you actually mutate, so it must cache, and write back at close, all of the entries that you access. You can call d.sync() to write back all the entries in the cache, and empty the cache (d.sync() also synchronizes the persistent dictionary on disk, if feasible).
🏛️ Classes
Class hierarchy:
collections.abc.MutableMapping(collections.abc.Mapping)
Shelf
BsdDbShelf
DbfilenameShelf
🔷 BsdDbShelf (Shelf)
BsdDbShelf(dict, protocol=None, writeback=False, keyencoding='utf-8')
Shelf implementation using the "BSD" db interface.
This adds methods first(), next(), previous(), last() and set_location() that have no counterpart in [g]dbm databases.
The actual database must be opened using one of the "bsddb" modules "open" routines (i.e. bsddb.hashopen, bsddb.btopen or bsddb.rnopen) and passed to the constructor.
See the module's __doc__ string for an overview of the interface.
Method resolution order:
BsdDbShelf
Shelf
collections.abc.MutableMapping
collections.abc.Mapping
collections.abc.Collection
collections.abc.Sized
collections.abc.Iterable
collections.abc.Container
builtins.object
Methods defined here:
__init__(self, dict, protocol=None, writeback=False, keyencoding='utf-8') — Initialize self. See help(type(self)) for accurate signature.first(self) — Move cursor to first item.last(self) — Move cursor to last item.next(self) — Move cursor to next item.previous(self) — Move cursor to previous item.set_location(self, key) — Move cursor to the position of key.
Data and other attributes defined here:
__abstractmethods__ — frozenset()
Methods inherited from Shelf:
__contains__(self, key)__del__(self)__delitem__(self, key)__enter__(self)__exit__(self, type, value, traceback)__getitem__(self, key)__iter__(self)__len__(self)__setitem__(self, key, value)close(self)get(self, key, default=None) — D.get(k[,d]) -> D[k] if k in D, else d. d defaults to None.sync(self)
Data descriptors inherited from Shelf:
__dict__ — dictionary for instance variables (if defined)__weakref__ — list of weak references to the object (if defined)
Methods inherited from collections.abc.MutableMapping:
clear(self) — D.clear() -> None. Remove all items from D.pop(self, key, default=<object object at 0x7fec86544190>) — D.pop(k[,d]) -> v, remove specified key and return the corresponding value. If key is not found, d is returned if given, otherwise KeyError is raised.popitem(self) — D.popitem() -> (k, v), remove and return some (key, value) pair as a 2-tuple; but raise KeyError if D is empty.setdefault(self, key, default=None) — D.setdefault(k[,d]) -> D.get(k,d), also set D[k]=d if k not in Dupdate(self, other=(), /, **kwds) — D.update([E, ]**F) -> None. Update D from mapping/iterable E and F.
```
Wait, I have to be careful with the pop default value. The original has `default=<object object at 0x7fec86544190>` which is correctly escaped. In my output inside a tag, the `<` and `>` will render as ``. Hmm, but the HTML character references work anywhere. Actually in tags, the character references also work fine. Let me preserve the original escaping.
Actually, wait. The original uses `<object object at 0x7fec86544190>` which is a properly escaped HTML way to display this. Let me preserve it.
Hmm, but in a list item with a code tag, I need to be careful. Let me think... Actually using `<` and `>` in HTML is fine and renders as ``. So I can write `pop(self, key, default=<object object at 0x7fec86544190>) — D.pop(k[,d])...` tags.
For the `__subclasshook__` part, I have:
```
__subclasshook__(C) from abc.ABCMeta
Abstract classes can override this to customize issubclass().
This is invoked early on by abc.ABCMeta.__subclasscheck__().
It should return True, False or NotImplemented. If it returns
NotImplemented, the normal algorithm is used. Otherwise, it
overrides the normal algorithm (and the outcome is cached).
```
No special chars here, just text.
For `__class_getitem__`:
```
__class_getitem__ = GenericAlias(...) from abc.ABCMeta
Represent a PEP 585 generic type
E.g. for t = list[int], t.__origin__ is list and t.__args__ is (int,).
```
No special chars.
Let me think about what to put for class method entries. The format from the original pydoc has many spaces and unusual indentation. I should clean it up but preserve information.
Actually, let me re-read rule 12 more carefully:
"For function, method, and class reference sections (pydoc modules, ruby ri classes, perldoc function lists): use name(args) — description tags for copyability. Emoji-per-item in long lists hurts scannability — only the section heading needs an emoji."
OK so the rule is clear: I should use that format, not the bizarre pydoc formatting. This is going to make the output much cleaner.
Let me now consider: the `update` method description in MutableMapping is long with multi-line text. The format like:
```
update(self, other=(), /, **kwds)
D.update([E, ]**F) -> None. Update D from mapping/iterable E and F.
If E present and has a .keys() method, does: for k in E: D[k] = E[k]
If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v
In either case, this is followed by: for k, v in F.items(): D[k] = v
```
This has `[k]`, `[]` etc which are fine in code tags. No `` to escape.
Hmm but wait, in the original, the lines like `D[k] = E[k]` are part of method descriptions. The `D[k]` contains `[k]` which is just a bracket, not a tag. So no escaping needed. Good.
For the `__subclasshook__` description:
"This is invoked early on by abc.ABCMeta.__subclasscheck__()."
Contains `.` and `()` but no `` to escape. Good.
For `__class_getitem__`:
"E.g. for t = list[int], t.__origin__ is list and t.__args__ is (int,)."
Has brackets and parens, no ``. Good.
OK let me write the final HTML. I'll be efficient with the inherited methods since they appear in multiple classes. Since rule says "preserve structure", I should keep them.
Actually, let me focus on keeping it concise but preserving all content. I'll skip some of the verbose descriptions where the method name is self-explanatory, but I'll keep all method names and the key documentation.
Let me draft the final HTML now:
```html
📛 NAME
shelve - Manage shelves of pickled objects.
🚀 Quick Reference
Use Case Command Description 🆕 Open a shelf shelve.open(filename)Open a persistent dictionary for reading/writing 💾 Store data d[key] = dataStore arbitrary pickled object at key (overwrites) 📤 Retrieve data data = d[key]Returns a COPY of the entry (raises KeyError if missing) 🗑️ Delete data del d[key]Remove entry at key (raises KeyError if missing) 🔍 Check existence key in dTest if key exists in the shelf 📋 List keys d.keys()Get all existing keys (slow on large shelves) 🔌 Close shelf d.close()Flush changes and close the persistent dictionary 🔄 Sync cache d.sync()Write back cached entries to disk and empty cache ✏️ Mutable entries shelve.open(filename, writeback=True)Enable writeback cache for safe in-place mutation 🧱 BSD DB backend BsdDbShelf(dict, ...)Shelf using bsddb (hashopen/btopen/rnopen) backend 📁 Filename DB backend DbfilenameShelf(filename, ...)Shelf using generic dbm backend
```
Wait, the rules say use case column has emoji but the description column might also have. Let me check rule 19: "Add descriptive emoji to option descriptions and list item text". So yes, emoji are appropriate.
But rule 11 says "NEVER use emoji characters... as visual bullet replacements at the start of paragraphs". This is fine because we're using a table, not paragraphs.
Rule 20: Emoji should be standard Unicode, widely supported. Using 🆕, 💾, 📤, 🗑️, 🔍, 📋, 🔌, 🔄, ✏️, 🧱, 📁 - all standard.
Hmm wait, rule 21 says "Use a
5. Lists use /
6. Function/class reference sections use name(args) — description` block, these are literal characters and should be preserved
- `If E present and has a .keys() method, does: for k in E: D[k] = E[k]` - same
- `If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v` - same
- `In either case, this is followed by: for k, v in F.items(): D[k] = v` - same
- `PEP 585 generic type` - fine
Now for class reference sections, I should use `name(args) — descriptionname(args) — description tags for copyability."
So the methods sections should be formatted as lists. This is a big restructuring, but the rule says it's important for scannability.
Looking at the volume, this document is quite long. Let me think about how to structure it efficiently while staying under 128k characters.
Let me look at the description section. There are several code blocks and explanations. I'll preserve them carefully.
Let me think about the strategy:
- NAME section → 📛 NAME
- Quick Reference → 🚀 Quick Reference
(NEW - I'll generate from content)
- Module Reference → 📚 Module Reference
- Description → 📝 Description
- Classes → 🏛️ Classes
with sub-sections for each class
- Functions → 🔧 Functions
- Data → 📊 Data
- File → 📁 File
For the class methods, I'll convert them to `name(args) — description
` format per rule 12.
For the BsdDbShelf methods, I need to handle the inheritance. The methods defined here include:
- __init__(self, dict, protocol=None, writeback=False, keyencoding='utf-8')
- first(self)
- last(self)
- next(self)
- previous(self)
- set_location(self, key)
I'll need to summarize inherited methods as well. Let me condense to keep under the character limit.
Let me also think about the code blocks. The description has multiple code examples that need to be in .
Let me start writing:
```html
📛 NAME
shelve - Manage shelves of pickled objects.
🚀 Quick Reference
Use Case Command Description Open a shelf shelve.open(filename)Open a persistent dictionary-like object Store data d[key] = dataStore arbitrary Python object at key Retrieve data data = d[key]Returns a copy of stored entry (raises KeyError if missing) Delete data del d[key]Remove entry at key (raises KeyError if missing) Check key key in dTest if key exists in the shelf List keys d.keys()Get all existing keys (slow on large shelves) Close shelf d.close()Flush changes and close the persistent dictionary Sync cache d.sync()Write back cached entries and synchronize to disk Mutable entries shelve.open(filename, writeback=True)Enable writeback for safe mutation of stored objects
📚 Module Reference
https://docs.python.org/3.10/library/shelve.html
The following documentation is automatically generated from the Python source files. It may be incomplete, incorrect or include features that are considered implementation detail and may vary between Python implementations. When in doubt, consult the module reference at the location listed above.
📝 Description
A "shelf" is a persistent, dictionary-like object. The difference with dbm databases is that the values (not the keys!) in a shelf can be essentially arbitrary Python objects -- anything that the "pickle" module can handle. This includes most class instances, recursive data types, and objects containing lots of shared sub-objects. The keys are ordinary strings.
To summarize the interface (key is a string, data is an arbitrary object):
import shelve
d = shelve.open(filename) # open, with (g)dbm filename -- no suffix
d[key] = data # store data at key (overwrites old data if
# using an existing key)
data = d[key] # retrieve a COPY of the data at key (raise
# KeyError if no such key) -- NOTE that this
# access returns a *copy* of the entry!
del d[key] # delete data stored at key (raises KeyError
# if no such key)
flag = key in d # true if the key exists
list = d.keys() # a list of all existing keys (slow!)
d.close() # close it
Dependent on the implementation, closing a persistent dictionary may or may not be necessary to flush changes to disk.
Normally, d[key] returns a COPY of the entry. This needs care when mutable entries are mutated: for example, if d[key] is a list,
d[key].append(anitem)
does NOT modify the entry d[key] itself, as stored in the persistent mapping -- it only modifies the copy, which is then immediately discarded, so that the append has NO effect whatsoever. To append an item to d[key] in a way that will affect the persistent mapping, use:
data = d[key]
data.append(anitem)
d[key] = data
To avoid the problem with mutable entries, you may pass the keyword argument writeback=True in the call to shelve.open. When you use:
d = shelve.open(filename, writeback=True)
then d keeps a cache of all entries you access, and writes them all back to the persistent mapping when you call d.close(). This ensures that such usage as d[key].append(anitem) works as intended.
However, using keyword argument writeback=True may consume vast amount of memory for the cache, and it may make d.close() very slow, if you access many of d's entries after opening it in this way: d has no way to check which of the entries you access are mutable and/or which ones you actually mutate, so it must cache, and write back at close, all of the entries that you access. You can call d.sync() to write back all the entries in the cache, and empty the cache (d.sync() also synchronizes the persistent dictionary on disk, if feasible).
🏛️ Classes
Class hierarchy:
collections.abc.MutableMapping(collections.abc.Mapping)
Shelf
BsdDbShelf
DbfilenameShelf
🔷 BsdDbShelf (Shelf)
BsdDbShelf(dict, protocol=None, writeback=False, keyencoding='utf-8')
Shelf implementation using the "BSD" db interface.
This adds methods first(), next(), previous(), last() and set_location() that have no counterpart in [g]dbm databases.
The actual database must be opened using one of the "bsddb" modules "open" routines (i.e. bsddb.hashopen, bsddb.btopen or bsddb.rnopen) and passed to the constructor.
See the module's __doc__ string for an overview of the interface.
Method resolution order:
BsdDbShelf
Shelf
collections.abc.MutableMapping
collections.abc.Mapping
collections.abc.Collection
collections.abc.Sized
collections.abc.Iterable
collections.abc.Container
builtins.object
Methods defined here:
__init__(self, dict, protocol=None, writeback=False, keyencoding='utf-8') — Initialize self. See help(type(self)) for accurate signature.first(self) — Move cursor to first item.last(self) — Move cursor to last item.next(self) — Move cursor to next item.previous(self) — Move cursor to previous item.set_location(self, key) — Move cursor to the position of key.
Data and other attributes defined here:
__abstractmethods__ — frozenset()
Methods inherited from Shelf:
__contains__(self, key)__del__(self)__delitem__(self, key)__enter__(self)__exit__(self, type, value, traceback)__getitem__(self, key)__iter__(self)__len__(self)__setitem__(self, key, value)close(self)get(self, key, default=None) — D.get(k[,d]) -> D[k] if k in D, else d. d defaults to None.sync(self)
Data descriptors inherited from Shelf:
__dict__ — dictionary for instance variables (if defined)__weakref__ — list of weak references to the object (if defined)
Methods inherited from collections.abc.MutableMapping:
clear(self) — D.clear() -> None. Remove all items from D.pop(self, key, default=<object object at 0x7fec86544190>) — D.pop(k[,d]) -> v, remove specified key and return the corresponding value. If key is not found, d is returned if given, otherwise KeyError is raised.popitem(self) — D.popitem() -> (k, v), remove and return some (key, value) pair as a 2-tuple; but raise KeyError if D is empty.setdefault(self, key, default=None) — D.setdefault(k[,d]) -> D.get(k,d), also set D[k]=d if k not in Dupdate(self, other=(), /, **kwds) — D.update([E, ]**F) -> None. Update D from mapping/iterable E and F.
```
Wait, I have to be careful with the pop default value. The original has `default=<object object at 0x7fec86544190>` which is correctly escaped. In my output inside a tag, the `<` and `>` will render as ``. Hmm, but the HTML character references work anywhere. Actually in tags, the character references also work fine. Let me preserve the original escaping.
Actually, wait. The original uses `<object object at 0x7fec86544190>` which is a properly escaped HTML way to display this. Let me preserve it.
Hmm, but in a list item with a code tag, I need to be careful. Let me think... Actually using `<` and `>` in HTML is fine and renders as ``. So I can write `pop(self, key, default=<object object at 0x7fec86544190>) — D.pop(k[,d])...` tags.
For the `__subclasshook__` part, I have:
```
__subclasshook__(C) from abc.ABCMeta
Abstract classes can override this to customize issubclass().
This is invoked early on by abc.ABCMeta.__subclasscheck__().
It should return True, False or NotImplemented. If it returns
NotImplemented, the normal algorithm is used. Otherwise, it
overrides the normal algorithm (and the outcome is cached).
```
No special chars here, just text.
For `__class_getitem__`:
```
__class_getitem__ = GenericAlias(...) from abc.ABCMeta
Represent a PEP 585 generic type
E.g. for t = list[int], t.__origin__ is list and t.__args__ is (int,).
```
No special chars.
Let me think about what to put for class method entries. The format from the original pydoc has many spaces and unusual indentation. I should clean it up but preserve information.
Actually, let me re-read rule 12 more carefully:
"For function, method, and class reference sections (pydoc modules, ruby ri classes, perldoc function lists): use name(args) — description tags for copyability. Emoji-per-item in long lists hurts scannability — only the section heading needs an emoji."
OK so the rule is clear: I should use that format, not the bizarre pydoc formatting. This is going to make the output much cleaner.
Let me now consider: the `update` method description in MutableMapping is long with multi-line text. The format like:
```
update(self, other=(), /, **kwds)
D.update([E, ]**F) -> None. Update D from mapping/iterable E and F.
If E present and has a .keys() method, does: for k in E: D[k] = E[k]
If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v
In either case, this is followed by: for k, v in F.items(): D[k] = v
```
This has `[k]`, `[]` etc which are fine in code tags. No `` to escape.
Hmm but wait, in the original, the lines like `D[k] = E[k]` are part of method descriptions. The `D[k]` contains `[k]` which is just a bracket, not a tag. So no escaping needed. Good.
For the `__subclasshook__` description:
"This is invoked early on by abc.ABCMeta.__subclasscheck__()."
Contains `.` and `()` but no `` to escape. Good.
For `__class_getitem__`:
"E.g. for t = list[int], t.__origin__ is list and t.__args__ is (int,)."
Has brackets and parens, no ``. Good.
OK let me write the final HTML. I'll be efficient with the inherited methods since they appear in multiple classes. Since rule says "preserve structure", I should keep them.
Actually, let me focus on keeping it concise but preserving all content. I'll skip some of the verbose descriptions where the method name is self-explanatory, but I'll keep all method names and the key documentation.
Let me draft the final HTML now:
```html
📛 NAME
shelve - Manage shelves of pickled objects.
🚀 Quick Reference
Use Case Command Description 🆕 Open a shelf shelve.open(filename)Open a persistent dictionary for reading/writing 💾 Store data d[key] = dataStore arbitrary pickled object at key (overwrites) 📤 Retrieve data data = d[key]Returns a COPY of the entry (raises KeyError if missing) 🗑️ Delete data del d[key]Remove entry at key (raises KeyError if missing) 🔍 Check existence key in dTest if key exists in the shelf 📋 List keys d.keys()Get all existing keys (slow on large shelves) 🔌 Close shelf d.close()Flush changes and close the persistent dictionary 🔄 Sync cache d.sync()Write back cached entries to disk and empty cache ✏️ Mutable entries shelve.open(filename, writeback=True)Enable writeback cache for safe in-place mutation 🧱 BSD DB backend BsdDbShelf(dict, ...)Shelf using bsddb (hashopen/btopen/rnopen) backend 📁 Filename DB backend DbfilenameShelf(filename, ...)Shelf using generic dbm backend
```
Wait, the rules say use case column has emoji but the description column might also have. Let me check rule 19: "Add descriptive emoji to option descriptions and list item text". So yes, emoji are appropriate.
But rule 11 says "NEVER use emoji characters... as visual bullet replacements at the start of paragraphs". This is fine because we're using a table, not paragraphs.
Rule 20: Emoji should be standard Unicode, widely supported. Using 🆕, 💾, 📤, 🗑️, 🔍, 📋, 🔌, 🔄, ✏️, 🧱, 📁 - all standard.
Hmm wait, rule 21 says "Use a
