{"id":6666,"library":"heapdict","title":"Heapdict","description":"Heapdict is a Python library that implements a mutable mapping (like a dictionary) but with the properties of a min-heap. It provides efficient decrease-key and increase-key operations, making it particularly suitable for priority queue implementations in algorithms such as Dijkstra's or A*. Unlike Python's built-in `heapq` module, heapdict allows for efficient modification of item priorities. The current version is 1.0.1, with its last release in September 2019.","status":"maintenance","version":"1.0.1","language":"python","source_language":"en","source_url":"https://github.com/DanielStutzbach/heapdict","tags":["data-structures","heap","priority-queue","dijkstra","a-star"],"install":[{"cmd":"pip install heapdict","lang":"bash","label":"Install with pip"}],"dependencies":[],"imports":[{"symbol":"heapdict","correct":"from heapdict import heapdict"}],"quickstart":{"code":"from heapdict import heapdict\n\n# Create a new heapdict\nhd = heapdict()\n\n# Add items with priorities (key, priority)\nhd['task_A'] = 5\nhd['task_B'] = 1\nhd['task_C'] = 10\n\nprint(f\"Initial heapdict: {list(hd.items())}\")\n\n# Access the item with the lowest priority without removing it\nlowest_priority_item = hd.peekitem()\nprint(f\"Lowest priority item (peek): {lowest_priority_item}\")\n\n# Remove and return the item with the lowest priority\nfirst_task, first_priority = hd.popitem()\nprint(f\"Popped: {first_task} with priority {first_priority}\")\nprint(f\"Heapdict after pop: {list(hd.items())}\")\n\n# Change the priority of an existing item (decrease-key)\nhd['task_C'] = 2 # task_C now has higher priority than task_A\nprint(f\"Heapdict after changing task_C priority: {list(hd.items())}\")\n\n# Pop the next lowest priority item\nsecond_task, second_priority = hd.popitem()\nprint(f\"Popped: {second_task} with priority {second_priority}\")","lang":"python","description":"This example demonstrates how to create a `heapdict`, add items with associated priorities, peek at the lowest priority item, pop the lowest priority item, and efficiently change an item's priority."},"warnings":[{"fix":"As of the last stable release (1.0.1), there is no official fix. Users may need to downgrade Python, manually patch the library to use `collections.abc.MutableMapping`, or consider alternative priority queue implementations that are actively maintained for modern Python versions.","message":"Heapdict uses `collections.MutableMapping` which was deprecated in Python 3.8 and subsequently removed in Python 3.13. This causes an `AttributeError` when importing or using `heapdict` in Python 3.8+ (specifically 3.11, 3.12, 3.13 reported).","severity":"breaking","affected_versions":"Python 3.8 and above"},{"fix":"If stable sorting for equal priorities is critical, an alternative priority queue implementation should be considered, or a tie-breaking mechanism (e.g., adding an insertion index to the priority tuple) must be implemented by the user.","message":"Heapdict does not guarantee stable sorting for items with equal priorities. If multiple items have the same priority, their retrieval order is not guaranteed to be FIFO (First-In, First-Out), which differs from `heapq.nsmallest`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Users should be aware of the maintenance status and thoroughly test `heapdict` in their target Python environment, especially with Python versions newer than 3.7. Consider contributing fixes or using more actively maintained alternatives if long-term support is critical.","message":"The project has not seen a new release since September 2019, and several open issues exist regarding compatibility with newer Python versions and potential minor bugs. This indicates limited active maintenance.","severity":"gotcha","affected_versions":"All versions (due to lack of recent updates)"}],"env_vars":null,"search_vec":"'1.0.1':71 '2019':78 'a-star':87 'algorithm':44 'allow':60 'built':55 'built-in':54 'current':68 'data':80 'data-structur':79 'decreas':28 'decrease-key':27 'dictionari':14 'dijkstra':47,86 'effici':26,62 'heap':23,82 'heapdict':1,2,59 'heapq':57 'implement':8,42 'increas':32 'increase-key':31 'item':65 'key':29,33 'last':74 'librari':6 'like':12 'make':35 'map':11 'min':22 'min-heap':21 'modif':63 'modul':58 'mutabl':10 'oper':34 'particular':37 'prioriti':40,66,84 'priority-queu':83 'properti':18 'provid':25 'python':5,52 'queue':41,85 'releas':75 'septemb':77 'star':89 'structur':81 'suitabl':38 'unlik':51 'version':69","created_at":"2026-04-15T18:37:43.569250+00:00","updated_at":"2026-04-16T15:33:35.246009+00:00","problems":[{"fix":"Install the package using pip: `pip install heapdict`","cause":"The 'heapdict' library is not installed in your Python environment or the environment is not correctly activated.","error":"ModuleNotFoundError: No module named 'heapdict'"},{"fix":"Before accessing a key, check for its existence using the `in` operator (e.g., `if key in hd:`), use the `get()` method with a default value (e.g., `hd.get(key, default_value)`), or wrap the access in a `try-except KeyError` block.","cause":"You are attempting to access, delete, or modify a key that does not exist in the heapdict instance. Like a standard Python dictionary, heapdict raises KeyError for non-existent keys.","error":"KeyError: 'your_key_here'"},{"fix":"Ensure that any objects (keys or values) you retrieve from `heapdict` and subsequently operate on are not `None` or a type that doesn't support the `len()` function when such an operation is performed. Add checks for `None` or validate the type of the retrieved object before calling `len()`.","cause":"This error occurs when an operation attempts to call `len()` on an object that is `None`. This often happens if a key or value retrieved from the `heapdict` is `None` (or another type without a `__len__` method), and subsequent code tries to get its length.","error":"TypeError: object of type 'NoneType' has no len()"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.0.1","cli_name":"","cli_version":null,"type":"library","homepage":"http://stutzbachenterprises.com/","github":null,"docs":null,"changelog":null,"pypi":"https://pypi.org/project/heapdict/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":null}}