zim.fs.File

class documentation

class File(FilePath): (source)

Known subclasses: zim.fs.TmpFile

Class representing a single file.

This class implements much more complex logic than the default python file objects. E.g. on writing we first write to a temporary files, then flush and sync and finally replace the file we intended to write with the temporary file. This makes it much more difficult to loose file contents when something goes wrong during the writing.

Also it implements logic to check the modification time before writing to prevent overwriting a file that was changed on disk in between read and write operations. If this mtime check fails MD5 sums are used to verify before raising an exception (because some share drives do not maintain mtime very precisely). This logic is not atomic, so your mileage may vary.

Method	`__eq__`	Undocumented
Method	`__init__`	Constructor
Method	`check_has_changed_on_disk`	Returns `True` when this file has changed on disk
Method	`cleanup`	Remove this file and cleanup any empty parent folder. Convenience method calling `File.remove()` and `Dir.cleanup()`.
Method	`compare`	No summary
Method	`copyto`	No summary
Method	`exists`	No summary
Method	`get_endofline`	Get the end-of-line character(s) used for writing this file. @returns: the end-of-line character(s)
Method	`get_mimetype`	No summary
Method	`isimage`	No summary
Method	`raw`	No summary
Method	`read`	No summary
Method	`readlines`	Get the file contents as a list of lines. Takes case of decoding UTF-8 and fixes line endings.
Method	`remove`	Remove (delete) this file and cleanup any related temporary files we created. This action can not be un-done. Ignores silently if the file did not exist in the first place.
Method	`touch`	No summary
Method	`write`	No summary
Method	`writelines`	No summary
Instance Variable	`checkoverwrite`	Undocumented
Instance Variable	`endofline`	Undocumented
Method	`_assertoverwrite`	Undocumented
Method	`_checkoverwrite`	Undocumented
Method	`_read`	Undocumented
Method	`_write_check`	Undocumented
Instance Variable	`_md5`	Undocumented
Instance Variable	`_mtime`	Undocumented

Inherited from UnixPath:

Class Method	`new_from_zim_config`	Returns a new object based on the string representation for that path
Method	`__add__`	Concatenates paths, only creates objects of the same class. See `Dir.file()` and `Dir.subdir()` instead to create other objects.
Method	`__iter__`	Undocumented
Method	`__ne__`	Undocumented
Method	`__repr__`	Undocumented
Method	`__str__`	Undocumented
Method	`commonparent`	No summary
Method	`ctime`	Get the creation time of the file path. @returns: the mtime timestamp
Method	`ischild`	Check if this path is a child path of a folder @returns: `True` if this path is a child path of `parent`
Method	`isdir`	Check if this path is a folder or not. Used to detect if e.g. a `File` object should have really been a `Dir` object. @returns: `True` when this path is a folder
Method	`isequal`	No summary
Method	`iswritable`	Check if a file or folder is writable. Uses permissions of parent folder if the file or folder does not (yet) exist. @returns: `True` if the file or folder is writable
Method	`monitor`	Creates a `FSObjectMonitor` for this path
Method	`mtime`	Get the modification time of the file path. @returns: the mtime timestamp
Method	`relpath`	No summary
Method	`rename`	No summary
Method	`serialize_zim_config`	Returns the file path as string for serializing the object
Method	`size`	Get file size in bytes See `format_file_size()` to get a human readable label @returns: file size in bytes
Method	`split`	No summary
Instance Variable	`path`	the absolute file path as string file system encoding (should only be used by low-level functions)
Property	`basename`	Basename property
Property	`dir`	Returns a `Dir` object for the parent dir
Property	`dirname`	Dirname property
Property	`uri`	File uri property
Property	`user_path`	User_path property
Static Method	`_parse_uri`	Undocumented
Method	`_set_path`	Undocumented
Instance Variable	`_serialized`	Undocumented

def __eq__(self, other): (source)

overrides zim.fs.UnixPath.__eq__

Undocumented

def __init__(self, path, checkoverwrite=False, endofline=None): (source)

overrides zim.fs.UnixPath.__init__

overridden in zim.fs.TmpFile

Constructor

Parameters
path	an absolute file path, file URL, `FilePath` object or a list of path elements. When a list is given, the first element is allowed to be an absolute path, URL or `FilePath` object as well.
checkoverwrite	when `True` this object checks the modification time before writing to prevent overwriting a file that was changed on disk in between read and write operations.
endofline	the line end style used when writing, can be one of "unix" ('\n') or "dos" ('\r\n'). Whan `None` the local default is used.

def check_has_changed_on_disk(self): (source)

Returns True when this file has changed on disk

def cleanup(self): (source)

Remove this file and cleanup any empty parent folder. Convenience method calling File.remove() and Dir.cleanup().

def compare(self, other): (source)

Check if file contents are the same. This differs from isequal() because files can be different physical locations.

Parameters
other	another `File` object
Returns
`True` when the files have the same content

def copyto(self, dest): (source)

Copy this file to another location. Preserves all file attributes (by using shutil.copy2())

Parameters
dest	a `File` or `Dir` object for the destination. If the destination is a folder, we will copy to a file below that folder of the same name

def exists(self): (source)

overrides zim.fs.UnixPath.exists

Check if a file or folder exists.

Returns
`True` if the file or folder exists
Unknown Field: implementation
must be implemented by sub classes in order that they enforce the type of the resource as well

def get_endofline(self): (source)

Get the end-of-line character(s) used for writing this file.

Returns
the end-of-line character(s)

def get_mimetype(self): (source)

Get the mime-type for this file. Will use the XDG mimetype system if available, otherwise fallsback to the standard library mimetypes.

Returns
the mimetype as a string, e.g. "text/plain"

def isimage(self): (source)

Check if this is an image file. Convenience method that works even when no real mime-type suport is available. If this method returns True it is no guarantee this image type is actually supported by Gtk.

Returns
`True` when this is an image file

def raw(self): (source)

Get the raw content without UTF-8 decoding, newline logic, etc. Used to read binary data, e.g. when serving files over www. Note that this function also does not integrates with checking mtime, so intended for read only usage.

Returns
file content as string

def read(self): (source)

Get the file contents as a string. Takes case of decoding UTF-8 and fixes line endings.

Returns
the content as (unicode) string.
Raises
`FileNotFoundError`	when the file does not exist.

def readlines(self): (source)

Get the file contents as a list of lines. Takes case of decoding UTF-8 and fixes line endings.

Returns
the content as a list of lines.
Raises
`FileNotFoundError`	when the file does not exist.

def remove(self): (source)

Remove (delete) this file and cleanup any related temporary files we created. This action can not be un-done. Ignores silently if the file did not exist in the first place.

def touch(self): (source)

Create this file and any parent folders if it does not yet exist. (Parent folders are also created when writing to a file, so you only need to call this method in special cases - e.g. when an external program requires the file to exist.)

def write(self, text): (source)

Write file contents from string. This overwrites the current content. Will automatically create all parent folders. If writing fails the file will either have the new content or the old content, but it should not be possible to have the content truncated.

Parameters
text	new content as (unicode) string
Unknown Field: emits
path-created if the file did not yet exist

def writelines(self, lines): (source)

Write file contents from a list of lines. Like write() but input is a list instead of a string.

Parameters
lines	new content as list of lines
Unknown Field: emits
path-created if the file did not yet exist

checkoverwrite = (source)

Undocumented

endofline = (source)

Undocumented

def _assertoverwrite(self): (source)

Undocumented

def _checkoverwrite(self, content): (source)

Undocumented

def _read(self): (source)

Undocumented

def _write_check(self): (source)

Undocumented

_md5 = (source)

Undocumented

_mtime = (source)

Undocumented