{"id":1228,"library":"boltons","title":"boltons","description":"boltons is a collection of over 250 pure-Python utilities designed to fill gaps in Python's standard library. It provides high-performance data structures and convenient functions for common tasks across various domains like file systems, iteration, caching, and time management. The library maintains an active development status, with major releases occurring roughly annually, interspersed with minor updates bringing enhancements and bug fixes. [1, 4, 5, 6, 8, 11]","status":"active","version":"25.0.0","language":"python","source_language":"en","source_url":"https://github.com/mahmoud/boltons","tags":["utilities","stdlib-enhancements","collections","functional-programming","files","iteration","caching"],"install":[{"cmd":"pip install boltons","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"A dictionary subclass that remembers insertion order and allows multiple values per key.","symbol":"OrderedMultiDict","correct":"from boltons.dictutils import OrderedMultiDict"},{"note":"For recursively traversing and transforming nested data structures.","symbol":"remap","correct":"from boltons.iterutils import remap"},{"note":"A dictionary-like Least Recently Used (LRU) cache.","symbol":"LRU","correct":"from boltons.cacheutils import LRU"},{"note":"Creates a directory and any necessary parent directories, similar to 'mkdir -p'.","symbol":"mkdir_p","correct":"from boltons.fileutils import mkdir_p"}],"quickstart":{"code":"from boltons.dictutils import OrderedMultiDict\n\n# Initialize the OrderedMultiDict\nomd = OrderedMultiDict()\n\n# Add items - supports multiple values for a single key\nomd['fruit'] = 'apple'\nomd['fruit'] = 'banana'\nomd['vegetable'] = 'carrot'\n\n# Access all values for a key\nprint(f\"All fruits: {omd['fruit']}\")\n# Expected output: All fruits: ['apple', 'banana']\n\n# Get the first value for a key\nprint(f\"First fruit: {omd.get_first('fruit')}\")\n# Expected output: First fruit: apple\n\n# Iterate through all key-value pairs (maintaining insertion order)\nprint(\"\\nAll items:\")\nfor key, value in omd.items():\n    print(f\"{key}: {value}\")\n# Expected output:\n# All items:\n# fruit: apple\n# fruit: banana\n# vegetable: carrot","lang":"python","description":"This example demonstrates the `OrderedMultiDict` from `boltons.dictutils`, which allows storing multiple values for a single key while preserving insertion order. It's useful for scenarios where a standard dictionary's behavior is insufficient. [5, 6]"},"warnings":[{"fix":"Upgrade to Python 3.7+ or pin boltons to a version less than 24.0.0 (e.g., `pip install 'boltons<24.0.0'`).","message":"Version 24.0.0 dropped support for Python 2. boltons is now Python 3 only (3.7+). If you are on Python 2, you must pin your dependency to `boltons<24.0.0`.","severity":"breaking","affected_versions":">=24.0.0"},{"fix":"Replace `datetime.utcnow()` with `datetime.now(timezone.utc)`.","message":"In version 25.0.0, the use of `datetime.utcnow()` was replaced internally due to its deprecation in Python 3.12. While this was an internal change, direct usage of `utcnow()` in user code, especially when interacting with boltons' `timeutils`, should be updated to `datetime.now(timezone.utc)` for future compatibility and best practice.","severity":"deprecated","affected_versions":">=25.0.0"},{"fix":"Consider copying individual modules into your project if you only need a small subset of functionality or prefer zero dependencies for those specific utilities. Refer to the 'Integration' section of the boltons documentation for more details. [7, 11]","message":"Due to its nature as a collection of self-contained utilities with no external dependencies, boltons supports 'vendorization' of individual modules. If the full library is too large for your project, or for tighter integration, you can copy specific modules (e.g., `fileutils.py`) directly into your project.","severity":"gotcha","affected_versions":"All"},{"fix":"Replace `omd.get_first(key)` with `omd.getlist(key)[0]` if you expect at least one value to exist. For safer access that handles empty lists, consider `(omd.getlist(key) or [None])[0]` or `next(iter(omd.getlist(key)), None)`.","message":"The `get_first` method was removed from `boltons.dictutils.OrderedMultiDict`. This method was associated with `NamedMapping`, which was removed in boltons version 23.1.0. Direct usage of `get_first` on `OrderedMultiDict` will now result in an `AttributeError`.","severity":"breaking","affected_versions":">=23.1.0"},{"fix":"Replace `omd.get_first(key)` with `omd.get(key)` for the first value, or `omd.getlist(key)` for all values. Alternatively, pin `boltons` to a version less than 23.0.0 (e.g., `pip install 'boltons<23.0.0'`).","message":"In version 23.0.0, the `OrderedMultiDict.get_first()` method was removed. Code relying on this method will raise an AttributeError. Use `OrderedMultiDict.get(key)` to retrieve the first value, or `OrderedMultiDict.getlist(key)` to get all values as a list.","severity":"breaking","affected_versions":">=23.0.0"}],"env_vars":null,"search_vec":"'1':68 '11':73 '250':8 '4':69 '5':70 '6':71 '8':72 'across':35 'activ':50 'annual':58 'bolton':1,2 'bring':63 'bug':66 'cach':42,84 'collect':5,78 'common':33 'conveni':30 'data':27 'design':13 'develop':51 'domain':37 'enhanc':64,77 'file':39,82 'fill':15 'fix':67 'function':31,80 'functional-program':79 'gap':16 'high':25 'high-perform':24 'interspers':59 'iter':41,83 'librari':21,47 'like':38 'maintain':48 'major':54 'manag':45 'minor':61 'occur':56 'perform':26 'program':81 'provid':23 'pure':10 'pure-python':9 'python':11,18 'releas':55 'rough':57 'standard':20 'status':52 'stdlib':76 'stdlib-enhanc':75 'structur':28 'system':40 'task':34 'time':44 'updat':62 'util':12,74 'various':36","created_at":"2026-04-06T16:55:31.787910+00:00","updated_at":"2026-04-16T00:33:38.699297+00:00","problems":[{"fix":"Ensure `boltons` is installed in your current environment using `pip install boltons`.","cause":"The `boltons` library or a specific submodule was not found in the Python environment, typically because it was not installed or the wrong environment is active.","error":"ModuleNotFoundError: No module named 'boltons'"},{"fix":"Verify `boltons` is installed and then ensure the import statement correctly reflects the module structure, e.g., `from boltons.cacheutils import cachedproperty`.","cause":"While `boltons` might be installed, a specific submodule like `cacheutils` is being imported incorrectly or is missing, or the Python environment is not correctly configured to find the installed package.","error":"ModuleNotFoundError: No module named 'boltons.cacheutils'"},{"fix":"Check your Python version (`python --version`) against `boltons`'s supported versions (>=3.7). Ensure pip is up-to-date (`pip install --upgrade pip`) and try installing in a fresh virtual environment: `python -m venv myenv && source myenv/bin/activate && pip install boltons`.","cause":"This error usually occurs during installation when pip cannot find a compatible version of `boltons` for your Python version or due to network issues preventing access to PyPI.","error":"ERROR: Could not find a version that satisfies the requirement boltons"},{"fix":"Convert the string to bytes before passing it to the `boltons` utility. For example, instead of `f.write('Happy IO')`, use `f.write(b'Happy IO')`.","cause":"This error occurs when a `boltons` utility, such as `SpooledBytesIO` from `boltons.ioutils`, expects bytes-like objects but receives a string (str) instead.","error":"TypeError: bytes expected, got <type 'str'>"}],"ecosystem":"pypi","meta_description":null,"install_score":80,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"25.0.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/mahmoud/boltons","docs":null,"changelog":null,"pypi":"https://pypi.org/project/boltons/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["data","serialization","devops","observability"],"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":"verified"}}