Quick start

Validate the format of a file, in this case a JPEG image, by passing the file path(s) to the corresponding FileFormat, fileformats.image.Jpeg,

>>> from fileformats.image import Jpeg
>>> jpeg_file = Jpeg("/path/to/an-image.jpeg")  # check exist., file ext. and magic num.
>>> str(jpeg_file)  # returns the file path
"/path/to/an-image.jpeg

For JPEG files, this validation will check the file extension and for the JPEG magic number (0xffd8ffe0) at the start of the file. If the file doesn't match the format, the init method will raise a FormatMismatchError.

For a conditional check instead of validation, use the matches method.

>>> if Jpeg.matches("/path/to/an-image.jpeg"):
...     print("File is a JPEG image")

The created FileSet object implements os.PathLike so can used in place of str or pathlib.Path, e.g. when opening files

>>> fp = open(jpeg_file, "rb")
>>> contents = fp.read()

or in string templates, e.g.

>>> import subprocess
>>> subprocess.run(f"cp {jpeg_file} new-dest.jpeg", shell=True)

You can use the find_matching method to detect the format that matches a given file, or set of files.

>>> from fileformats.core import find_matching
>>> find_matching("/path/to/an-image.jpeg")
[fileformats.image.raster.Jpeg]

And use the to_mime and from_mime methods to convert between file formats and their MIME types.

>>> mime = to_mime(Jpeg)
>>> mime
"image/jpeg"
>>> from_mime(mime)
fileformats.image.raster.Jpeg

To copy or move the files in a FileSet to a new directory, use the copy or move methods, respectively.

>>> new_jpeg = jpeg_file.copy(dest_dir="/path/to/destination")
>>> new_jpeg.fspaths
{"/path/to/destination/an-image.jpeg"}

The copy method also supports creating links (both soft and hard) instead of copying the file (see Copy-mode).

>>> new_jpeg = jpeg_file.copy(
...    dest_dir="/path/on/same/mount", mode="hardlink_or_copy"
)  # will perform a hardlink
>>> new_jpeg2 = jpeg_file.copy(
...    dest_dir="/path/to/different/mount", mode="hardlink_or_copy"
)  # will fallback to a copy

To quickly generate a hash of the file set use the FileSet.hash() method.

>>> jpeg_file.hash()
"d41d8cd98f00b204e9800998ecf8427e"

For selected pairs of formats converter methods have been implement that can be used to convert between equivalent formats, e.g. to convert a JPEG image to a PNG format.

>>> from fileformats.image import Png
>>> png_file = Png.convert(jpeg_file)
>>> repr(png_file)
Png("/path/to/an-image.png")

For some select formats there are also methods to read metadata, in which case the metadata can be accessed as a dictionary attribute.

>>> from fileformats.application import Dicom
>>> dcm = Dicom("/path/to/dicom-file.dcm")
>>> dcm.metadata["SeriesDescription"]
"t1_mprage_sag_p2_iso_1"

Note

Only a small fraction of formats have extra functionality added in the main package. Extra functionality is only planned to be implemented as required. See the Extras for information on how to implement new file formats, converters and extra functionality.