Overview

Timestamp Preserving Output File Writer.

outputfile.open_ behaves identical to open(..., mode="w"):

>>> from outputfile import open_
>>> from pathlib import Path
>>> filepath = Path('file.txt')
>>> with open_(filepath) as file:
...     file.write("foo")

but the timestamp stays the same, if the file content did not change:

>>> mtime = filepath.stat().st_mtime
>>> with open_(filepath) as file:
...     file.write("foo")
>>> mtime - filepath.stat().st_mtime
0.0

The state attribute details the file handling status:

>>> otherpath = Path('other.txt')
>>> # first write
>>> with open_(otherpath) as file:
...     file.write("foo")
>>> file.state.name
'CREATED'
>>> # same write
>>> with open_(otherpath) as file:
...     file.write("foo")
>>> file.state.name
'IDENTICAL'
>>> # other write
>>> with open_(otherpath) as file:
...     file.write("bar")
>>> file.state.name
'UPDATED'

The argument existing defines the update strategy and can Existing.KEEP ...

>>> keep = Path('keep.txt')
>>> # first write
>>> with open_(keep, existing=Existing.KEEP) as file:
...     file.write("foo")
>>> file.state.name
'CREATED'
>>> # same write
>>> with open_(keep, existing=Existing.KEEP) as file:
...     file.write("foo")
>>> file.state.name
'EXISTING'
>>> # other write
>>> with open_(keep, existing=Existing.KEEP) as file:
...     file.write("bar")
>>> file.state.name
'EXISTING'

... or Existing.OVERWRITE

>>> overwrite = Path('overwrite.txt')
>>> # first write
>>> with open_(overwrite, existing=Existing.OVERWRITE) as file:
...     file.write("foo")
>>> file.state.name
'CREATED'
>>> # same write
>>> with open_(overwrite, existing=Existing.OVERWRITE) as file:
...     file.write("foo")
>>> file.state.name
'OVERWRITTEN'
>>> # other write
>>> with open_(overwrite, existing=Existing.OVERWRITE) as file:
...     file.write("bar")
>>> file.state.name
'OVERWRITTEN'

Classes:

Name	Description
`Existing`	Strategy for Handling of existing files.
`State`	File state.
`OutputFile`	File Object Wrapper.

Functions:

Name	Description
`open_`	Return an output file handle, whose timestamp is only updated on content change.

Existing

Bases: Enum

Strategy for Handling of existing files.

State

Bases: Enum

File state.

OutputFile

File Object Wrapper.

Methods:

Name	Description
`__init__`	File object returned by `open_`.
`write`	Write to file.
`close`	Close the file.
`flush`	Flush file content.

Attributes:

Name	Type	Description
`mode`	`str`	Mode.
`is_binary`	`bool`	Binary instead of Text Mode.
`state`	`State`	State.
`closed`	`bool`	True, when the file has been closed and is not writable anymore.

mode `property`

mode

Mode.

is_binary `property`

is_binary

Binary instead of Text Mode.

state `property`

state

State.

closed `property`

closed

True, when the file has been closed and is not writable anymore.

init

__init__(
    filepath,
    mode="w",
    existing=KEEP_TIMESTAMP,
    mkdir=False,
    diffout=None,
    pre_create=None,
    post_create=None,
    pre_update=None,
    post_update=None,
    kwargs=None,
)

write

write(*args, **kwargs)

Write to file.

See :py:meth:io.TextIOBase.write for reference.

Raises:

Type	Description
`ValueError`	when the file is already closed.

close

close()

Close the file.

flush

flush()

Flush file content.

open_

open_(
    filepath,
    mode="w",
    existing=KEEP_TIMESTAMP,
    mkdir=False,
    diffout=None,
    pre_create=None,
    post_create=None,
    pre_update=None,
    post_update=None,
    **kwargs,
)

Return an output file handle, whose timestamp is only updated on content change.

By default, the filesystem timestamp of a written file is always updated on write, also when the final file content is identical to the overwritten version. The OutputFile class works around this rule.

The OutputFile class behaves like a normal file in write ('w') mode, but the output is written to a temporary file. On close() the temporary file and the target file are compared. If both files are identical, the temporary file is removed. If they differ, the temporary file is moved to the target file location.

Parameters:

Name	Type	Description	Default
`filepath`	`str`	Path to the target file.	required

Other Parameters:

Name	Type	Description
`mode`	`str`	Mode, except 'r', 'a' or '+'.
`existing`	`(Existing, str)`	Handling of existing output files: `Existing.ERROR`: raise an `FileExistsError`open` if the file exists already. `Existing.KEEP`: continue, without modifying the existing file. `Existing.OVERWRITE`: always overwrite the output file, like python's `open` would do. `Existing.KEEP_TIMESTAMP`: write to temporary file and move to target file if content differs.
`mkdir`	`bool`	create the output directory if it not exists.
`diffout`	`Diffout \| None`	function receiving file diff on update.
`pre_create`	`Hookup \| None`	Function called before opening a file for creating
`post_create`	`Hookup \| None`	Function called after creating
`pre_update`	`Hookup \| None`	Function called before opening a file for update
`post_update`	`Hookup \| None`	Function called after writing