{"id":23002844,"url":"https://github.com/likianta/hot-shelve","last_synced_at":"2026-04-27T22:32:35.089Z","repository":{"id":57437570,"uuid":"469364040","full_name":"likianta/hot-shelve","owner":"likianta","description":"A wrapper for Python shelve to support updating nested dictionary in an elegant way.","archived":false,"fork":false,"pushed_at":"2022-12-18T13:59:10.000Z","size":34,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-08-18T05:47:10.398Z","etag":null,"topics":["database","nested-dictionary","python","python-shelve","shelve"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/likianta.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-03-13T12:25:23.000Z","updated_at":"2023-07-17T23:35:26.000Z","dependencies_parsed_at":"2023-01-29T19:15:57.716Z","dependency_job_id":null,"html_url":"https://github.com/likianta/hot-shelve","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/likianta/hot-shelve","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/likianta%2Fhot-shelve","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/likianta%2Fhot-shelve/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/likianta%2Fhot-shelve/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/likianta%2Fhot-shelve/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/likianta","download_url":"https://codeload.github.com/likianta/hot-shelve/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/likianta%2Fhot-shelve/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32358509,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-27T20:07:02.737Z","status":"ssl_error","status_checked_at":"2026-04-27T20:07:00.910Z","response_time":128,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["database","nested-dictionary","python","python-shelve","shelve"],"created_at":"2024-12-15T07:12:26.287Z","updated_at":"2026-04-27T22:32:35.075Z","avatar_url":"https://github.com/likianta.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hot Shelve\n\nA wrapper for Python shelve that supports updating nested dictionaries in a simple way.\n\nEssentially, you don't need this any more:\n\n```python\nimport shelve\ndb = shelve.open('some_file.db')\ndb['key'] = {'a': 1, 'b': 2}\ntemp = db['key']\ntemp['c'] = 3\ndb['key'] = temp\ndb.sync()\n```\n\nTo use:\n\n```python\nimport hot_shelve\ndb = hot_shelve.FlatShelve('some_file.db')\ndb['key'] = {'a': 1, 'b': 2}\ndb['key']['c'] = 3\ndb.sync()\n```\n\n## Basic Usages\n\n```python\n# hot_shelve provides `HotShelve` and `FlatShelve` classes.\n# but currently (v0.1.0) only `FlatShelve` is available.\nfrom hot_shelve import FlatShelve\n\n# open a database\n# ===============\n# a database is a file with extension `.db`.\ndb = FlatShelve('path/to/db.db')\n\n# add an immutable key-value pair\n# ==============================\ndb['name'] = 'Bob'\n\n# add a mutable key-value pair\n# ============================\ndb['info'] = {'address': 'Tokyo'}\ndb['info']['phone_number'] = ['123-456-7890']\n\n# print\n# =====\n# there are two ways to show its dict structure.\n# 1. `db.to_dict()` shows user-oriented dict.\n# 2. `db.to_internal_dict()` shows the real internal dict.\n# ps: don't use `dict(db)`, it exposes mutable nodes with delegates, you can \n#   not see it clearly like `db.to_dict` does.\nprint(db.to_dict())\n# -\u003e {'name': 'Bob', \n#     'info': {'address': 'Tokyo', \n#              'phone_number': ['123-456-7890']}}\nprint(db.to_internal_dict())\n# -\u003e {'name': 'Bob', \n#     'info.address': 'Tokyo',\n#     'info.phone_number': ['123-456-7890']}\n\n# delete a key\n# ============\ndb.pop('name')  # -\u003e 'Bob'\ndb['info'].pop('address')  # -\u003e 'Tokyo'\nprint(db.to_dict())\n# -\u003e {'info': {'phone_number': ['123-456-7890']}}\n\n# update a key\n# ============\ndb['info']['phone_number'].append('987-654-3210')\nprint(db.to_dict())\n# -\u003e {'info': {'phone_number': ['123-456-7890', \n#                               '987-654-3210']}}\n\n# don't forget sync to disk\n# =========================\ndb.sync()  # now it's safely saved.\n\n# you can do whatever like a Shelve object does\n# =============================================\n# get, keys, values, items, setdefault, pop, update, clear, sync, close, etc.\nfor k, v in db.items():\n    print(k, v)  # -\u003e 'info', {'phone_number': ['123-456-7890', '987-654-3210']}\n    \ndb.setdefault('name', 'Alice')  # -\u003e 'Alice'\nprint(db.to_dict())\n# -\u003e {'name': 'Alice',\n#     'info': {'phone_number': ['123-456-7890', \n#                               '987-654-3210']}}\n\ndb.clear()  # -\u003e {}\n\n...\n\ndb.close()\n```\n\n## Advanced Usages\n\n```python\nfrom hot_shelve import FlatShelve\n\ndb = FlatShelve('path/to/db.db')\n\ndb['info'] = {'address': 'Tokyo'}\n\n# use `db['a.b.c']` instead of `db['a']['b']['c']`\ndb['info.phone_number'] = ['123-456-7890']\n#   it has the same effect as `db['info']['phone_number'] = ['123-456-7890']`.\n```\n\n## Tricks\n\nFollow the instructions to get a (little) better performance (in theoretical).\n\n1.  `db['a.b.c']` is better than `db['a']['b']['c']`.\n    \n    ```python\n    # good\n    db['a']['b']['c'] = 'xxx'\n    \n    # better\n    db['a.b.c'] = 'xxx'\n    ```\n\n2.  To frequently update a node, assign it to a new variable.\n\n    ```python\n    # good\n    db['a']['b']['0'] = '000'\n    db['a']['b']['1'] = '111'\n    db['a']['b']['2'] = '222'\n    ...\n\n    # better\n    db['a.b.0'] = '000'\n    db['a.b.1'] = '111'\n    db['a.b.2'] = '222'\n    ...\n\n    # best\n    node = db['a.b']\n    node['0'] = '000'\n    node['1'] = '111'\n    node['2'] = '222'\n    ...\n    ```\n\n## Cautions\n\n-   Do not use '.' in your own key name, the period symbol is reserved for key chain derivation.\n\n    ```\n    # wrong\n    words_db['splash'] = {\n        'e.g.': 'there was a splash, and then silence.'\n    }\n    ''' it will generate...\n        print(words_db.to_dict())\n        # -\u003e {'splash': {'e': {'g': {'': 'there was a splash, and then silence.'}}}}\n        print(words_db.to_internal_dict())\n        # -\u003e {'splash.e.g.': 'there was a splash, and then silence.'}\n    '''\n    \n    # right\n    words_db['splash'] = {\n        'example': 'there was a splash, and then silence.'\n    }\n    print(words_db.to_dict())\n    # -\u003e {'splash': {'example': 'there was a splash, and then silence.'}}\n    print(words_db.to_internal_dict())\n    # -\u003e {'splash.example': 'there was a splash, and then silence.'}\n    ```\n\n-   The file size will be larger than `shelve.Shelve`, because it uses a flat key-value structure.\n\n    Illustration:\n\n    A normal `Shelve` object:\n\n    ```yaml\n    data:\n        name: 'Bob'\n        info:\n            address: 'Tokyo'\n            phone_number:\n                - 123-456-7890\n                - 987-654-3210\n    ```\n\n    A `FlatShelve` object:\n\n    ```yaml\n    data.name: 'Bob'\n    data.info.address: 'Tokyo'\n    data.info.phone_number:\n        - 123-456-7890\n        - 987-654-3210\n    ```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flikianta%2Fhot-shelve","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flikianta%2Fhot-shelve","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flikianta%2Fhot-shelve/lists"}