{ "content": [ { "type": "text", "text": "# shelve (pydoc)\n\n**Summary:** shelve - Manage shelves of pickled objects.\n\n## Section Outline\n\n- **NAME** (2 lines)\n- **MODULE REFERENCE** (8 lines)\n- **DESCRIPTION** (55 lines)\n- **CLASSES** (5 lines) — 3 subsections\n - class BsdDbShelf (145 lines)\n - class DbfilenameShelf (129 lines)\n - class Shelf (125 lines)\n- **FUNCTIONS** (1 lines) — 1 subsections\n - open (11 lines)\n- **DATA** (2 lines)\n- **FILE** (3 lines)\n\n## Full Content\n\n### NAME\n\nshelve - Manage shelves of pickled objects.\n\n### MODULE REFERENCE\n\nhttps://docs.python.org/3.10/library/shelve.html\n\nThe following documentation is automatically generated from the Python\nsource files. It may be incomplete, incorrect or include features that\nare considered implementation detail and may vary between Python\nimplementations. When in doubt, consult the module reference at the\nlocation listed above.\n\n### DESCRIPTION\n\nA \"shelf\" is a persistent, dictionary-like object. The difference\nwith dbm databases is that the values (not the keys!) in a shelf can\nbe essentially arbitrary Python objects -- anything that the \"pickle\"\nmodule can handle. This includes most class instances, recursive data\ntypes, and objects containing lots of shared sub-objects. The keys\nare ordinary strings.\n\nTo summarize the interface (key is a string, data is an arbitrary\nobject):\n\nimport shelve\nd = shelve.open(filename) # open, with (g)dbm filename -- no suffix\n\nd[key] = data # store data at key (overwrites old data if\n# using an existing key)\ndata = d[key] # retrieve a COPY of the data at key (raise\n# KeyError if no such key) -- NOTE that this\n# access returns a *copy* of the entry!\ndel d[key] # delete data stored at key (raises KeyError\n# if no such key)\nflag = key in d # true if the key exists\nlist = d.keys() # a list of all existing keys (slow!)\n\nd.close() # close it\n\nDependent on the implementation, closing a persistent dictionary may\nor may not be necessary to flush changes to disk.\n\nNormally, d[key] returns a COPY of the entry. This needs care when\nmutable entries are mutated: for example, if d[key] is a list,\nd[key].append(anitem)\ndoes NOT modify the entry d[key] itself, as stored in the persistent\nmapping -- it only modifies the copy, which is then immediately\ndiscarded, so that the append has NO effect whatsoever. To append an\nitem to d[key] in a way that will affect the persistent mapping, use:\ndata = d[key]\ndata.append(anitem)\nd[key] = data\n\nTo avoid the problem with mutable entries, you may pass the keyword\nargument writeback=True in the call to shelve.open. When you use:\nd = shelve.open(filename, writeback=True)\nthen d keeps a cache of all entries you access, and writes them all back\nto the persistent mapping when you call d.close(). This ensures that\nsuch usage as d[key].append(anitem) works as intended.\n\nHowever, using keyword argument writeback=True may consume vast amount\nof memory for the cache, and it may make d.close() very slow, if you\naccess many of d's entries after opening it in this way: d has no way to\ncheck which of the entries you access are mutable and/or which ones you\nactually mutate, so it must cache, and write back at close, all of the\nentries that you access. You can call d.sync() to write back all the\nentries in the cache, and empty the cache (d.sync() also synchronizes\nthe persistent dictionary on disk, if feasible).\n\n### CLASSES\n\ncollections.abc.MutableMapping(collections.abc.Mapping)\nShelf\nBsdDbShelf\nDbfilenameShelf\n\n#### class BsdDbShelf\n\n| BsdDbShelf(dict, protocol=None, writeback=False, keyencoding='utf-8')\n|\n| Shelf implementation using the \"BSD\" db interface.\n|\n| This adds methods first(), next(), previous(), last() and\n| setlocation() that have no counterpart in [g]dbm databases.\n|\n| The actual database must be opened using one of the \"bsddb\"\n| modules \"open\" routines (i.e. bsddb.hashopen, bsddb.btopen or\n| bsddb.rnopen) and passed to the constructor.\n|\n| See the module's doc string for an overview of the interface.\n|\n| Method resolution order:\n| BsdDbShelf\n| Shelf\n| collections.abc.MutableMapping\n| collections.abc.Mapping\n| collections.abc.Collection\n| collections.abc.Sized\n| collections.abc.Iterable\n| collections.abc.Container\n| builtins.object\n|\n| Methods defined here:\n|\n| init(self, dict, protocol=None, writeback=False, keyencoding='utf-8')\n| Initialize self. See help(type(self)) for accurate signature.\n|\n| first(self)\n|\n| last(self)\n|\n| next(self)\n|\n| previous(self)\n|\n| setlocation(self, key)\n|\n| ----------------------------------------------------------------------\n| Data and other attributes defined here:\n|\n| abstractmethods = frozenset()\n|\n| ----------------------------------------------------------------------\n| Methods inherited from Shelf:\n|\n| contains(self, key)\n|\n| del(self)\n|\n| delitem(self, key)\n|\n| enter(self)\n|\n| exit(self, type, value, traceback)\n|\n| getitem(self, key)\n|\n| iter(self)\n|\n| len(self)\n|\n| setitem(self, key, value)\n|\n| close(self)\n|\n| get(self, key, default=None)\n| D.get(k[,d]) -> D[k] if k in D, else d. d defaults to None.\n|\n| sync(self)\n|\n| ----------------------------------------------------------------------\n| Data descriptors inherited from Shelf:\n|\n| dict\n| dictionary for instance variables (if defined)\n|\n| weakref\n| list of weak references to the object (if defined)\n|\n| ----------------------------------------------------------------------\n| Methods inherited from collections.abc.MutableMapping:\n|\n| clear(self)\n| D.clear() -> None. Remove all items from D.\n|\n| pop(self, key, default=)\n| D.pop(k[,d]) -> v, remove specified key and return the corresponding value.\n| If key is not found, d is returned if given, otherwise KeyError is raised.\n|\n| popitem(self)\n| D.popitem() -> (k, v), remove and return some (key, value) pair\n| as a 2-tuple; but raise KeyError if D is empty.\n|\n| setdefault(self, key, default=None)\n| D.setdefault(k[,d]) -> D.get(k,d), also set D[k]=d if k not in D\n|\n| update(self, other=(), /, kwds)\n| D.update([E, ]F) -> None. Update D from mapping/iterable E and F.\n| If E present and has a .keys() method, does: for k in E: D[k] = E[k]\n| If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v\n| In either case, this is followed by: for k, v in F.items(): D[k] = v\n|\n| ----------------------------------------------------------------------\n| Methods inherited from collections.abc.Mapping:\n|\n| eq(self, other)\n| Return self==value.\n|\n| items(self)\n| D.items() -> a set-like object providing a view on D's items\n|\n| keys(self)\n| D.keys() -> a set-like object providing a view on D's keys\n|\n| values(self)\n| D.values() -> an object providing a view on D's values\n|\n| ----------------------------------------------------------------------\n| Data and other attributes inherited from collections.abc.Mapping:\n|\n| hash = None\n|\n| reversed = None\n|\n| ----------------------------------------------------------------------\n| Class methods inherited from collections.abc.Collection:\n|\n| subclasshook(C) from abc.ABCMeta\n| Abstract classes can override this to customize issubclass().\n|\n| This is invoked early on by abc.ABCMeta.subclasscheck().\n| It should return True, False or NotImplemented. If it returns\n| NotImplemented, the normal algorithm is used. Otherwise, it\n| overrides the normal algorithm (and the outcome is cached).\n|\n| ----------------------------------------------------------------------\n| Class methods inherited from collections.abc.Iterable:\n|\n| classgetitem = GenericAlias(...) from abc.ABCMeta\n| Represent a PEP 585 generic type\n|\n| E.g. for t = list[int], t.origin is list and t.args is (int,).\n\n#### class DbfilenameShelf\n\n| DbfilenameShelf(filename, flag='c', protocol=None, writeback=False)\n|\n| Shelf implementation using the \"dbm\" generic dbm interface.\n|\n| This is initialized with the filename for the dbm database.\n| See the module's doc string for an overview of the interface.\n|\n| Method resolution order:\n| DbfilenameShelf\n| Shelf\n| collections.abc.MutableMapping\n| collections.abc.Mapping\n| collections.abc.Collection\n| collections.abc.Sized\n| collections.abc.Iterable\n| collections.abc.Container\n| builtins.object\n|\n| Methods defined here:\n|\n| init(self, filename, flag='c', protocol=None, writeback=False)\n| Initialize self. See help(type(self)) for accurate signature.\n|\n| ----------------------------------------------------------------------\n| Data and other attributes defined here:\n|\n| abstractmethods = frozenset()\n|\n| ----------------------------------------------------------------------\n| Methods inherited from Shelf:\n|\n| contains(self, key)\n|\n| del(self)\n|\n| delitem(self, key)\n|\n| enter(self)\n|\n| exit(self, type, value, traceback)\n|\n| getitem(self, key)\n|\n| iter(self)\n|\n| len(self)\n|\n| setitem(self, key, value)\n|\n| close(self)\n|\n| get(self, key, default=None)\n| D.get(k[,d]) -> D[k] if k in D, else d. d defaults to None.\n|\n| sync(self)\n|\n| ----------------------------------------------------------------------\n| Data descriptors inherited from Shelf:\n|\n| dict\n| dictionary for instance variables (if defined)\n|\n| weakref\n| list of weak references to the object (if defined)\n|\n| ----------------------------------------------------------------------\n| Methods inherited from collections.abc.MutableMapping:\n|\n| clear(self)\n| D.clear() -> None. Remove all items from D.\n|\n| pop(self, key, default=)\n| D.pop(k[,d]) -> v, remove specified key and return the corresponding value.\n| If key is not found, d is returned if given, otherwise KeyError is raised.\n|\n| popitem(self)\n| D.popitem() -> (k, v), remove and return some (key, value) pair\n| as a 2-tuple; but raise KeyError if D is empty.\n|\n| setdefault(self, key, default=None)\n| D.setdefault(k[,d]) -> D.get(k,d), also set D[k]=d if k not in D\n|\n| update(self, other=(), /, kwds)\n| D.update([E, ]F) -> None. Update D from mapping/iterable E and F.\n| If E present and has a .keys() method, does: for k in E: D[k] = E[k]\n| If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v\n| In either case, this is followed by: for k, v in F.items(): D[k] = v\n|\n| ----------------------------------------------------------------------\n| Methods inherited from collections.abc.Mapping:\n|\n| eq(self, other)\n| Return self==value.\n|\n| items(self)\n| D.items() -> a set-like object providing a view on D's items\n|\n| keys(self)\n| D.keys() -> a set-like object providing a view on D's keys\n|\n| values(self)\n| D.values() -> an object providing a view on D's values\n|\n| ----------------------------------------------------------------------\n| Data and other attributes inherited from collections.abc.Mapping:\n|\n| hash = None\n|\n| reversed = None\n|\n| ----------------------------------------------------------------------\n| Class methods inherited from collections.abc.Collection:\n|\n| subclasshook(C) from abc.ABCMeta\n| Abstract classes can override this to customize issubclass().\n|\n| This is invoked early on by abc.ABCMeta.subclasscheck().\n| It should return True, False or NotImplemented. If it returns\n| NotImplemented, the normal algorithm is used. Otherwise, it\n| overrides the normal algorithm (and the outcome is cached).\n|\n| ----------------------------------------------------------------------\n| Class methods inherited from collections.abc.Iterable:\n|\n| classgetitem = GenericAlias(...) from abc.ABCMeta\n| Represent a PEP 585 generic type\n|\n| E.g. for t = list[int], t.origin is list and t.args is (int,).\n\n#### class Shelf\n\n| Shelf(dict, protocol=None, writeback=False, keyencoding='utf-8')\n|\n| Base class for shelf implementations.\n|\n| This is initialized with a dictionary-like object.\n| See the module's doc string for an overview of the interface.\n|\n| Method resolution order:\n| Shelf\n| collections.abc.MutableMapping\n| collections.abc.Mapping\n| collections.abc.Collection\n| collections.abc.Sized\n| collections.abc.Iterable\n| collections.abc.Container\n| builtins.object\n|\n| Methods defined here:\n|\n| contains(self, key)\n|\n| del(self)\n|\n| delitem(self, key)\n|\n| enter(self)\n|\n| exit(self, type, value, traceback)\n|\n| getitem(self, key)\n|\n| init(self, dict, protocol=None, writeback=False, keyencoding='utf-8')\n| Initialize self. See help(type(self)) for accurate signature.\n|\n| iter(self)\n|\n| len(self)\n|\n| setitem(self, key, value)\n|\n| close(self)\n|\n| get(self, key, default=None)\n| D.get(k[,d]) -> D[k] if k in D, else d. d defaults to None.\n|\n| sync(self)\n|\n| ----------------------------------------------------------------------\n| Data descriptors defined here:\n|\n| dict\n| dictionary for instance variables (if defined)\n|\n| weakref\n| list of weak references to the object (if defined)\n|\n| ----------------------------------------------------------------------\n| Data and other attributes defined here:\n|\n| abstractmethods = frozenset()\n|\n| ----------------------------------------------------------------------\n| Methods inherited from collections.abc.MutableMapping:\n|\n| clear(self)\n| D.clear() -> None. Remove all items from D.\n|\n| pop(self, key, default=)\n| D.pop(k[,d]) -> v, remove specified key and return the corresponding value.\n| If key is not found, d is returned if given, otherwise KeyError is raised.\n|\n| popitem(self)\n| D.popitem() -> (k, v), remove and return some (key, value) pair\n| as a 2-tuple; but raise KeyError if D is empty.\n|\n| setdefault(self, key, default=None)\n| D.setdefault(k[,d]) -> D.get(k,d), also set D[k]=d if k not in D\n|\n| update(self, other=(), /, kwds)\n| D.update([E, ]F) -> None. Update D from mapping/iterable E and F.\n| If E present and has a .keys() method, does: for k in E: D[k] = E[k]\n| If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v\n| In either case, this is followed by: for k, v in F.items(): D[k] = v\n|\n| ----------------------------------------------------------------------\n| Methods inherited from collections.abc.Mapping:\n|\n| eq(self, other)\n| Return self==value.\n|\n| items(self)\n| D.items() -> a set-like object providing a view on D's items\n|\n| keys(self)\n| D.keys() -> a set-like object providing a view on D's keys\n|\n| values(self)\n| D.values() -> an object providing a view on D's values\n|\n| ----------------------------------------------------------------------\n| Data and other attributes inherited from collections.abc.Mapping:\n|\n| hash = None\n|\n| reversed = None\n|\n| ----------------------------------------------------------------------\n| Class methods inherited from collections.abc.Collection:\n|\n| subclasshook(C) from abc.ABCMeta\n| Abstract classes can override this to customize issubclass().\n|\n| This is invoked early on by abc.ABCMeta.subclasscheck().\n| It should return True, False or NotImplemented. If it returns\n| NotImplemented, the normal algorithm is used. Otherwise, it\n| overrides the normal algorithm (and the outcome is cached).\n|\n| ----------------------------------------------------------------------\n| Class methods inherited from collections.abc.Iterable:\n|\n| classgetitem = GenericAlias(...) from abc.ABCMeta\n| Represent a PEP 585 generic type\n|\n| E.g. for t = list[int], t.origin is list and t.args is (int,).\n\n### FUNCTIONS\n\n#### open\n\nOpen a persistent dictionary for reading and writing.\n\nThe filename parameter is the base filename for the underlying\ndatabase. As a side-effect, an extension may be added to the\nfilename and more than one file may be created. The optional flag\nparameter has the same interpretation as the flag parameter of\ndbm.open(). The optional protocol parameter specifies the\nversion of the pickle protocol.\n\nSee the module's doc string for an overview of the interface.\n\n### DATA\n\nall = ['Shelf', 'BsdDbShelf', 'DbfilenameShelf', 'open']\n\n### FILE\n\n/usr/lib/python3.10/shelve.py\n\n" } ], "structuredContent": { "command": "shelve", "section": "", "mode": "pydoc", "summary": "shelve - Manage shelves of pickled objects.", "synopsis": null, "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "MODULE REFERENCE", "lines": 8, "subsections": [] }, { "name": "DESCRIPTION", "lines": 55, "subsections": [] }, { "name": "CLASSES", "lines": 5, "subsections": [ { "name": "class BsdDbShelf", "lines": 145 }, { "name": "class DbfilenameShelf", "lines": 129 }, { "name": "class Shelf", "lines": 125 } ] }, { "name": "FUNCTIONS", "lines": 1, "subsections": [ { "name": "open", "lines": 11 } ] }, { "name": "DATA", "lines": 2, "subsections": [] }, { "name": "FILE", "lines": 3, "subsections": [] } ] } }