Help on function writer in module safer:

wwrriitteerr(stream: Union[Callable, NoneType, IO, pathlib.Path, str] = None, is_binary: Union[bool, NoneType] = None, close_on_exit: bool = False, temp_file: bool = False, chunk_size: int = 1048576, delete_failures: bool = True, dry_run: Union[bool, Callable] = False) -> Union[Callable, IO]
    Write safely to file streams, sockets and callables.
    
    `safer.writer` yields an in-memory stream that you can write
    to, but which is only written to the original stream if the
    context finishes without raising an exception.
    
    Because the actual writing happens at the end, it's possible to block
    indefinitely when the context exits if the underlying socket, stream or
    callable does!
    
    Args:
      stream: A file stream, a socket, or a callable that will receive data.
    
          If stream is `None`, output is written to `sys.stdout`
    
          If stream is a string or `Path`, the file with that name is
          opened for writing.
    
      is_binary: Is `stream` a binary stream?
    
          If `is_binary` is ``None``, deduce whether it's a binary file from
          the stream, or assume it's text otherwise.
    
      close_on_exit: If True, the underlying stream is closed when the writer
        closes
    
      temp_file: If `temp_file` is truthy, write to a disk file and use
          os.rename() at the end, otherwise cache the writes in memory.
    
          If `temp_file` is a string, use it as the name of the temporary
          file, otherwise select one in the same directory as the target
          file, or in the system tempfile for streams that aren't files.
    
      chunk_size: Chunk size, in bytes for transfer data from the temporary
          file to the underlying stream.
    
      delete_failures: If false, any temporary files created are not deleted
        if there is an exception.
    
      dry_run: If `dry_run` is truthy, the stream or file is left unchanged.
    
        If `dry_run` is also callable, the results of the stream are passed to
        `dry_run()` rather than being written to the stream.
Help on function open in module safer:

ooppeenn(name: Union[pathlib.Path, str], mode: str = 'r', buffering: bool = -1, encoding: Union[str, NoneType] = None, errors: Union[str, NoneType] = None, newline: Union[str, NoneType] = None, closefd: bool = True, opener: Union[Callable, NoneType] = None, make_parents: bool = False, delete_failures: bool = True, temp_file: bool = False, dry_run: bool = False) -> <class 'IO'>
    Args:
      make_parents: If true, create the parent directory of the file if needed
    
      delete_failures: If false, any temporary files created are not deleted
        if there is an exception.
    
      temp_file: If `temp_file` is truthy, write to a disk file and use
          os.rename() at the end, otherwise cache the writes in memory.
    
          If `temp_file` is a string, use it as the name of the temporary
          file, otherwise select one in the same directory as the target
          file, or in the system tempfile for streams that aren't files.
    
      dry_run:
         If dry_run is True, the file is not written to at all
    
    The remaining arguments are the same as for built-in `open()`.
    
    `safer.open() is a drop-in replacement for built-in`open()`. It returns a
    stream which only overwrites the original file when close() is called, and
    only if there was no failure.
    
    It works as follows:
    
    If a stream `fp` return from `safer.open()` is used as a context
    manager and an exception is raised, the property `fp.safer_failed` is
    set to `True`.
    
    In the method `fp.close()`, if `fp.safer_failed` is *not* set, then the
    cached results replace the original file, successfully completing the
    write.
    
    If `fp.safer_failed` is true, then if `delete_failures` is true, the
    temporary file is deleted.
    
    If the `mode` argument contains either `'a'` (append), or `'+'`
    (update), then the original file will be copied to the temporary file
    before writing starts.
    
    Note that if the `temp_file` argument is set, `safer` uses an extra
    temporary file which is renamed over the file only after the stream closes
    without failing. This uses as much disk space as the old and new files put
    together.
Help on function closer in module safer:

cclloosseerr(stream, is_binary=None, close_on_exit=True, **kwds)
    Like `safer.writer()` but with `close_on_exit=True` by default
    
    ARGUMENTS
      Same as for `safer.writer()`
Help on function dump in module safer:

dduummpp(obj, stream=None, dump=None, **kwargs)
    Safely serialize `obj` as a formatted stream to `fp`` (a
    `.write()`-supporting file-like object, or a filename),
    using `json.dump` by default
    
    ARGUMENTS
      obj:
        The object to be serialized
    
      stream:
        A file stream, a socket, or a callable that will receive data.
        If stream is `None`, output is written to `sys.stdout`.
        If stream is a string or `Path`, the file with that name is opened for
        writing.
    
      dump:
        A function or module or the name of a function or module to dump data.
        If `None`, default to `json.dump``.
    
      kwargs:
        Additional arguments to `dump`.
Help on function printer in module safer:

pprriinntteerr(name, mode='w', *args, **kwargs)
    A context manager that yields a function that prints to the opened file,
    only writing to the original file at the exit of the context,
    and only if there was no exception thrown
    
    ARGUMENTS
      Same as for `safer.open()`
Help on module safer:

NNAAMMEE
    safer - 🧿 safer: a safer writer for files and streams 🧿

DDEESSCCRRIIPPTTIIOONN
    Avoid partial writes or corruption!
    
    `safer` wraps file streams and sockets so the data is written or sent only at
    the successful completion of an entire computation, and offers a drop-in
    replacement for regular old `open()`.
    
    ## Quick summary
    
    ### A tiny example
    
        import safer
    
        with safer.open(filename, 'w') as fp:
            fp.write('one')
    
            if something_bad_happened():
                raise ValueError
                # The file is not changed
    
            print('two', file=fp)
    
         # The file only gets overwritten here.
    
    ### How to use
    
    Use [pip](https://pypi.org/project/pip) to install `safer` from the command
    line: `pip install safer`.
    
    Tested on Python 3.4 - 3.11.  An old Python 2.7 version
    is [here](https://github.com/rec/safer/tree/v2.0.5).
    
    See the Medium article [here](https://medium.com/@TomSwirly/%EF%B8%8F-safer-a-safer-file-writer-%EF%B8%8F-5fe267dbe3f5)
    
    ### The details
    
    `safer` helps prevent programmer error from corrupting files, socket
    connections, or generalized streams by writing a whole file or nothing.
    
    It does not prevent concurrent modification of files from other threads or
    processes: if you need atomic file writing, see
    https://pypi.org/project/atomicwrites/
    
    It also has a useful `dry_run` setting to let you test your code without
    actually overwriting the target file.
    
    * `safer.writer()` wraps an existing stream and writes a
      whole response or nothing, but does not close anything.
    
    * `safer.closer()` is a `safer.writer()` that also closes the underlying
      stream.
    
    * `safer.open()` is a drop-in replacement for built-in `open` that
      writes either a whole file or nothing on close of the file stream.
    
    * `safer.dump()` is like a safer `json.dump()` which can be used for any
      serialization protocol, including Yaml and Toml, and also allows you to
      write to file streams or any other callable.
    
    * `safer.printer()` is `safer.open()` except that it yields a
      a function that looks like `print`, but writers to the stream.
    
    By default, `safer` buffers the written data in memory in a `io.StringIO`
    or `io.BytesIO`.
    
    For very large files, `safer.open()` has a `temp_file` argument which
    writes the data to a temporary file on disk, which is moved over using
    `os.rename` if the operation completes successfully.  This functionality
    does not work on Windows.  (In fact, it's unclear if any of this works on
    Windows, but that certainly won't.  Windows developer solicted!)
    
    
    ### Example: `safer.writer()`
    
    `safer.writer()` wraps an existing stream - a writer, socket, or callback -
    in a temporary stream which is only copied to the target stream at close(), and
    only if no exception was raised.
    
    
        sock = socket.socket(*args)
    
        # dangerous
        try:
            write_header(sock)
            write_body(sock)   # Exception is thrown here
            write_footer(sock)
         except:
            write_error(sock)  # Oops, the header was already written
    
        # safer
        try:
            with safer.writer(sock) as s:
                write_header(s)
                write_body(s)  # Exception is thrown here
                write_footer(s)
         except:
            write_error(sock)  # Nothing has been written
    
    ### Example: `safer.open()`
    
    Writes a whole file or nothing. It's a drop-in replacement for built-in
    `open()` except that `safer.open()` leaves the original file unchanged on
    failure.
    
        # dangerous
        with open(filename, 'w') as fp:
            json.dump(data, fp)
            # If an exception is raised, the file is empty or partly written
    
        # safer
        with safer.open(filename, 'w') as fp:
            json.dump(data, fp)
            # If an exception is raised, the file is unchanged.
    
    
    `safer.open(filename)` returns a file stream `fp` like `open(filename)`
    would, except that `fp` writes to memory stream or a temporary file in the
    same directory.
    
    If `fp` is used as a context manager and an exception is raised, then the
    property `fp.safer_failed` on the stream is automatically set to `True`.
    
    And when `fp.close()` is called, the cached data is stored in `filename` -
    *unless* `fp.safer_failed` is true.
    
    
    ### Example: `safer.dump()`
    
    Serializes a whole file or nothing. It's a drop-in replacement for
    `json.dump()` except:
    
    * `safer.dump()` leaves the original file unchanged on
    * It takes a filename in preference to an open file stream
    * But it handles files, socket streams, or any callable
    
    Dangerous.
    
        with open(filename, 'w') as fp:
            json.dump(data, fp)
            # If an exception is raised, the file is empty or partly written
    
    Safer.
    
        with safer.open(filename, 'w') as fp:
            json.dump(data, fp)
            # If an exception is raised, the file is unchanged.
    
    
    `safer.open(filename)` returns a file stream `fp` like `open(filename)`
    would, except that `fp` writes to memory stream or a temporary file in the
    same directory.
    
    If `fp` is used as a context manager and an exception is raised, then the
    property `fp.safer_failed` on the stream is automatically set to `True`.
    
    And when `fp.close()` is called, the cached data is stored in `filename` -
    *unless* `fp.safer_failed` is true.
    
    ------------------------------------
    
    ### Example: `safer.printer()`
    
    `safer.printer()` is similar to `safer.open()` except it yields a function
    that prints to the open file - it's very convenient for printing text.
    
    Like `safer.open()`, if an exception is raised within its context manager,
    the original file is left unchanged.
    
        # dangerous
        with open(file, 'w') as fp:
            for item in items:
                print(item, file=fp)
            # Prints lines until the first exception
    
        # safer
        with safer.printer(file) as print:
            for item in items:
                print(item)
            # Either the whole file is written, or nothing

FFUUNNCCTTIIOONNSS
    cclloosseerr(stream, is_binary=None, close_on_exit=True, **kwds)
        Like `safer.writer()` but with `close_on_exit=True` by default
        
        ARGUMENTS
          Same as for `safer.writer()`
    
    dduummpp(obj, stream=None, dump=None, **kwargs)
        Safely serialize `obj` as a formatted stream to `fp`` (a
        `.write()`-supporting file-like object, or a filename),
        using `json.dump` by default
        
        ARGUMENTS
          obj:
            The object to be serialized
        
          stream:
            A file stream, a socket, or a callable that will receive data.
            If stream is `None`, output is written to `sys.stdout`.
            If stream is a string or `Path`, the file with that name is opened for
            writing.
        
          dump:
            A function or module or the name of a function or module to dump data.
            If `None`, default to `json.dump``.
        
          kwargs:
            Additional arguments to `dump`.
    
    ooppeenn(name: Union[pathlib.Path, str], mode: str = 'r', buffering: bool = -1, encoding: Union[str, NoneType] = None, errors: Union[str, NoneType] = None, newline: Union[str, NoneType] = None, closefd: bool = True, opener: Union[Callable, NoneType] = None, make_parents: bool = False, delete_failures: bool = True, temp_file: bool = False, dry_run: bool = False) -> <class 'IO'>
        Args:
          make_parents: If true, create the parent directory of the file if needed
        
          delete_failures: If false, any temporary files created are not deleted
            if there is an exception.
        
          temp_file: If `temp_file` is truthy, write to a disk file and use
              os.rename() at the end, otherwise cache the writes in memory.
        
              If `temp_file` is a string, use it as the name of the temporary
              file, otherwise select one in the same directory as the target
              file, or in the system tempfile for streams that aren't files.
        
          dry_run:
             If dry_run is True, the file is not written to at all
        
        The remaining arguments are the same as for built-in `open()`.
        
        `safer.open() is a drop-in replacement for built-in`open()`. It returns a
        stream which only overwrites the original file when close() is called, and
        only if there was no failure.
        
        It works as follows:
        
        If a stream `fp` return from `safer.open()` is used as a context
        manager and an exception is raised, the property `fp.safer_failed` is
        set to `True`.
        
        In the method `fp.close()`, if `fp.safer_failed` is *not* set, then the
        cached results replace the original file, successfully completing the
        write.
        
        If `fp.safer_failed` is true, then if `delete_failures` is true, the
        temporary file is deleted.
        
        If the `mode` argument contains either `'a'` (append), or `'+'`
        (update), then the original file will be copied to the temporary file
        before writing starts.
        
        Note that if the `temp_file` argument is set, `safer` uses an extra
        temporary file which is renamed over the file only after the stream closes
        without failing. This uses as much disk space as the old and new files put
        together.
    
    pprriinntteerr(name, mode='w', *args, **kwargs)
        A context manager that yields a function that prints to the opened file,
        only writing to the original file at the exit of the context,
        and only if there was no exception thrown
        
        ARGUMENTS
          Same as for `safer.open()`
    
    wwrriitteerr(stream: Union[Callable, NoneType, IO, pathlib.Path, str] = None, is_binary: Union[bool, NoneType] = None, close_on_exit: bool = False, temp_file: bool = False, chunk_size: int = 1048576, delete_failures: bool = True, dry_run: Union[bool, Callable] = False) -> Union[Callable, IO]
        Write safely to file streams, sockets and callables.
        
        `safer.writer` yields an in-memory stream that you can write
        to, but which is only written to the original stream if the
        context finishes without raising an exception.
        
        Because the actual writing happens at the end, it's possible to block
        indefinitely when the context exits if the underlying socket, stream or
        callable does!
        
        Args:
          stream: A file stream, a socket, or a callable that will receive data.
        
              If stream is `None`, output is written to `sys.stdout`
        
              If stream is a string or `Path`, the file with that name is
              opened for writing.
        
          is_binary: Is `stream` a binary stream?
        
              If `is_binary` is ``None``, deduce whether it's a binary file from
              the stream, or assume it's text otherwise.
        
          close_on_exit: If True, the underlying stream is closed when the writer
            closes
        
          temp_file: If `temp_file` is truthy, write to a disk file and use
              os.rename() at the end, otherwise cache the writes in memory.
        
              If `temp_file` is a string, use it as the name of the temporary
              file, otherwise select one in the same directory as the target
              file, or in the system tempfile for streams that aren't files.
        
          chunk_size: Chunk size, in bytes for transfer data from the temporary
              file to the underlying stream.
        
          delete_failures: If false, any temporary files created are not deleted
            if there is an exception.
        
          dry_run: If `dry_run` is truthy, the stream or file is left unchanged.
        
            If `dry_run` is also callable, the results of the stream are passed to
            `dry_run()` rather than being written to the stream.

DDAATTAA
