{"id":1915,"library":"atomicwrites","title":"Atomic File Writes","description":"Atomicwrites is a Python library that provides a simple, high-level API for performing atomic file writes. It achieves atomicity by writing to a temporary file in the same directory and then atomically moving it to the target location. This prevents file corruption in case of crashes or interruptions during the write process. The library is currently at version 1.4.1. While previously actively maintained, its status has shifted due to the maintainer's decision regarding PyPI 2FA requirements, leading to its deprecation. Users are encouraged to consider alternatives like `safer` for new projects.","status":"deprecated","version":"1.4.1","language":"en","source_language":"en","source_url":"https://github.com/untitaker/python-atomicwrites","tags":["file-io","atomic-operations","data-integrity","deprecation"],"install":[{"cmd":"pip install atomicwrites","lang":"bash","label":"PyPI"}],"dependencies":[],"imports":[{"note":"The primary high-level context manager for atomic file operations.","symbol":"atomic_write","correct":"from atomicwrites import atomic_write"},{"note":"A lower-level, class-based API for more granular control over atomic writes.","symbol":"AtomicWriter","correct":"from atomicwrites import AtomicWriter"}],"quickstart":{"code":"import os\nfrom atomicwrites import atomic_write\nimport json\n\nfile_path = \"my_config.json\"\nconfig_data = {\"api_key\": os.environ.get('MY_API_KEY', 'default_secret'), \"timeout\": 30}\n\ntry:\n    # Write configuration atomically\n    with atomic_write(file_path, overwrite=True, encoding='utf-8') as f:\n        json.dump(config_data, f, indent=2)\n    print(f\"Configuration successfully written to {file_path}\")\n\n    # Verify content by reading back\n    with open(file_path, 'r', encoding='utf-8') as f:\n        read_config = json.load(f)\n    print(f\"Read back configuration: {read_config}\")\n\nexcept Exception as e:\n    print(f\"An error occurred during atomic write: {e}\")\n    # In case of an error, the original file (if any) should be intact\n    # or no partial file should exist if it was a new creation.\n    if not os.path.exists(file_path):\n        print(f\"Target file {file_path} does not exist after error (expected behavior for new file).\")\n    else:\n        print(f\"Target file {file_path} exists after error (expected behavior if original was preserved).\")\n\nfinally:\n    # Clean up the created file for a runnable example\n    if os.path.exists(file_path):\n        os.remove(file_path)\n        print(f\"Cleaned up {file_path}\")","lang":"python","description":"This example demonstrates how to use `atomic_write` to safely write JSON data to a file. The `overwrite=True` parameter allows replacing an existing file. If an error occurs during the write, the original file remains untouched. The example also includes cleanup for re-runnability and demonstrates reading the content back."},"warnings":[{"fix":"For new projects, consider actively maintained alternatives like `safer`. For simple atomic renames, Python's `os.replace` (for overwriting) or a combination of `tempfile` and `os.rename` can be used.","message":"The `atomicwrites` library is officially deprecated by its maintainer as of July 2022. The maintainer indicated that Python 3's built-in `os.replace` and `os.rename` functions might suffice for many use cases, and cited PyPI's 2FA requirements as a reason for deprecation.","severity":"deprecated","affected_versions":"1.4.1 and later (effectively all versions due to maintainer's stance)"},{"fix":"Be aware of this platform-specific limitation. For critical applications on Windows requiring absolute atomicity, additional verification or platform-specific mechanisms might be necessary. Thorough testing on the target Windows environment is recommended.","message":"On Windows, the atomicity of the `MoveFileEx` system call (used by `atomicwrites`) is not universally guaranteed. It can, under certain conditions, silently fall back to a non-atomic copy-and-delete operation, potentially leading to data inconsistencies if the system crashes during this fallback.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure that the target file path is on the same filesystem as the directory where temporary files will be created (by default, `atomicwrites` creates temporary files in the same directory as the target path to mitigate this).","message":"Atomic file operations are only guaranteed if the temporary file created by `atomicwrites` and the final target file reside on the *same filesystem*. If they are on different filesystems (e.g., a network drive vs. local disk), the operation might fall back to a non-atomic copy, which is susceptible to interruption failures.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If `overwrite=False` is critical, carefully test and verify permission preservation on your target platform. Design applications to be robust against a brief dual-presence of the file.","message":"When `overwrite=False` is used in `atomic_write` (which employs `os.link` and `os.unlink` on POSIX systems), there is a brief time window where the file might be accessible under both its temporary name and the target name. Additionally, this method may lead to changes in the target file's permissions if the link operation doesn't preserve them as expected.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}