jpegdata 0.1.3
Streamlined JPEG image metadata parsing and updating.
Requires Python: >=3.10
Keywords: image, metadata, jpeg, data

# JPEGData

The JPEGData library for Python provides a streamlined way to work with JPEG image files
offering the ability to extract certain file metadata.

### Requirements

The JPEGData library has been tested to work with Python 3.10, 3.11, 3.12 and 3.13, but
has not been tested, nor is its use supported with earlier versions of Python.

### Installation

The library is available from the PyPI repository, so may be added easily to a project's
dependencies via its `requirements.txt` file or similar by referencing the library's
name, `jpegdata`, or the library may be installed directly onto your local development
system using `pip install` by entering the following command:

	$ pip install jpegdata

### Classes, Methods & Properties

The JPEGData library's main class is the `JPEG` class through which JPEG image files can
be loaded, modified via the supported actions, and saved. The library supports reading
several common JPEG file formats including JFIF, EXIF, CCIF and SPIFF formatted JPEG files.
Currently the library does not support more recent JPEG formats and derivations such as
JPEG XL, JPEG-2000, JPEG XR, etc.

The `JPEG` class offers the following methods:

* `JPEG(filepath: str)` – The `JPEG()` class constructor expects an absolute filepath at
a minimum for the JPEG file you wish to open. Upon initialising the class with the file,
the library will then attempt to load and parse the file. Assuming that the file is a 
valid JPEG file, the library will parse the file, identify any segments contained within
the file, and any data associated with each of the segments, and will determine several
intrinsic properties of the JPEG image including the canvas width and height.

The `JPEG` class offers the following properties:

 * `info` (`Information`) – The `info` property can be used to access the `Information`
 class instance that is created when the `JPEG` class instance is created and the file is
 parsed. The `Information` class instance contains core information about the parsed file
 including the `filepath`, `filesize`, (byte) `order`, and `format`.
 
 This property is used internally by the class to populate the corresponding top level
 properties of the same names noted below.

 * `filepath` (`str`) – The `filepath` property can be used to get the original file path
 that was specified at the time the class was initialised.

 * `filesize` (`int`) – The `filesize` property can be used to get the original file size
 of the file that was specified at the time the class was initialised.

 * `datetime_created` (`datetime`) – The `datetime_created` property can be used to access
 the date/time that the loaded JPEG file was created according to filesystem metadata.

 * `datetime_modified` (`datetime`) – The `datetime_modified` property can be used to access
 the date/time that the loaded JPEG file was modified according to filesystem metadata.

 * `order` (`ByteOrder`) – The `order` property can be used to determine the byte order
 of the JPEG file. As all JPEG files are encoded as big-endian, the property will always
 report `ByteOrder.BigEndian`.

 * `format` (`Format`) – The `format` property can be used to determine the file format
 of the JPEG file. The property will report one of the following `Format` enumeration values:

   * `Format.JPEG` for baseline formatted JPEG files;
   * `Format.JFIF` for JPEG File Interchange Format (JFIF) formatted JPEG files;
   * `Format.EXIF` for Extensible Image Format (EXIF) formatted JPEG files;
   * `Format.CCIF` for Canon Camera Image File Format (CCIF) formatted JPEG files;
   * `Format.SPIFF` for Still Picture Interchange File Format (SPIFF) formatted JPEG files.

 * `encoding` (`Encoding`) – The `encoding` property can be used to determine the encoding
 used for the JPEG file, which will report one of the following `Encoding` enumeration values:

   * `Encoding.BaselineDCT` for baseline DCT encoded images;
   * `Encoding.ProgressiveDCT` for progressive DCT encoded images.

 * `width` (`int`) – The `width` property can be used to access the parsed pixel width of the image.

 * `height` (`int`) – The `height` property can be used to access the parsed pixel height of the image.
 
 * `precision` (`int`) – The `precision` property can be used to access the parsed precision of the image.

 * `transform` (`ColourTransform`) – The `transform` property can be used to determine the
 colour transform used for the JPEG file, which will report one of the following `ColourTransform` enumeration
 values:

   * `ColourTransform.Unknown` used when the colour transform cannot be determined.
   * `ColourTransform.RGB` for RGB images.
   * `ColourTransform.YCbCr` for YCbCr images.
   * `ColourTransform.YCCK` for YCCK images.
   * `ColourTransform.Greyscale` (also available as the aliased `Grayscale`) for greyscale images.
   * `ColourTransform.CMYK` for CMYK images.

 * `components` (`int`) – The `components` property can be used to determine the number
 of colour components used for the JPEG file, reported as an integer value.

### Example of Use

To create an instance of the `JPEG` class, import the `JPEG` class from the library and
specify the absolute file path to the JPEG file you wish to open as the first argument.
If the specified file can be opened successfully, the library will return an instance of
either the `JPEG`, `JFIF`, `EXIF`, `CCIF` or `SPIFF` subclasses, depending on the file
format of the specified JPEG file; these subclasses are all subclasses of the library's
`JPEG` base class.

<!--pytest.mark.skip-->

```python
from jpegdata import JPEG, Format, Encoding, ColourTransform

filepath = "/path/to/file.jpeg"

# Initialize the library with the absolute file path of the JPEG file to load
jpeg = JPEG(filepath=filepath)

assert isinstance(jpeg, JPEG)

# Use the parsed properties of the file
assert jpeg.format is Format.EXIF
assert jpeg.encoding is Encoding.BaselineDCT
assert jpeg.precision == 8
assert jpeg.width == 600
assert jpeg.height == 400
assert jpeg.components == 3
assert jpeg.transform is ColourTransform.YCbCr

# If desired, iterate through the segments held within the file:
for segment in jpeg:
    print(segment)
```

### Command Line Tool

The `jpegdata` command line tool, installed alongside the library, provides a command
line interface to print out the information parsed from the specified JPEG file.

The tool can print out the information directly to the command line either as plain text
or as a JSON-serialised payload.

To print the help information for the tool, pass the `--help` argument.

```shell
$ jpegdata ./path/to/file.jpeg
```

The above command will generate output similar to the following:

```plain
File Name:           ./path/to/file.jpeg
File Path:           /absolute/path/to/file.jpeg
File Size:           3890 bytes
File Created Date:   2025-08-10 17:15:13.892694
File Modified Date:  2025-08-10 17:15:07.312874
Byte Order:          MSB
Format:              JPEG Extensible Image File (EXIF) format
Encoding:            Baseline DCT
Image Width:         3 pixels
Image Height:        3 pixels
Image Size:          3x3 pixels
Megapixels:          0.000009
Bits Per Sample:     8
Colour Components:   3
Colour Transform:    YCbCr
```

To emit the parsed information as a JSON-serialised payload, pass the `--format json`
argument to the command:

```shell
$ jpegdata ./path/to/file.jpeg --format json
```

The above command will generate output similar to the following:

```json
{
  "filename": "./path/to/file.jpeg",
  "filepath": "/absolute/path/to/file.jpeg",
  "filesize": 3890,
  "filedate": {
    "created": "2025-08-10 17:15:13.892694",
    "modified": "2025-08-10 17:15:07.312874"
  },
  "byte_oder": "MSB",
  "encoding": "BaselineDCT",
  "precision": 8,
  "width": 3,
  "height": 3,
  "colour": {
    "components": 3,
    "transform": "YCbCr"
  }
}
```

To emit the verbose form of output, pass the `--verbose` argument, which will include
information about the parsed segment markers found in the file. This is included in both
the plain text and JSON-serialised output formats.

### Disclaimer

While every effort has been made to ensure that the library works reliably with JPEG
files and embedded metadata, you must ensure that all files are backed up before using
the JPEGData library with any files, especially as the library is in early development.

Furthermore, the library may not be able to read nor preserve all metadata or other data
within a JPEG file, especially if manufacturer specific, custom or other "private" data
are present. As such, it is possible that loss of data could occur if an image is loaded
and is then overwritten by saving the file back to the same file path, _when saving is
available in future versions of the library (currently the library is read-only)_.

Use of the library is entirely at your own risk and the authors bear no responsibility
for losses of any kind. By using the software you assume all such risk and liability.

THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
OR OTHER DEALINGS IN THE SOFTWARE.

### Credits & References

The JPEG file format, and the related EXIF, IPTC and XMP metadata model specifications
were researched across various sources. Please visit these valuable online resources to
learn more about the JPEG file format and related metadata model specifications and to
support these world class organisations and their products:

 * JPEG File Format
   * https://www.loc.gov/preservation/digital/formats/fdd/fdd000619.shtml
   * https://en.wikipedia.org/wiki/JPEG (JPEG)
   * https://en.wikipedia.org/wiki/JPEG_File_Interchange_Format (JFIF)
   * https://www.loc.gov/preservation/digital/formats/fdd/fdd000018.shtml (JFIF)
   * https://www.loc.gov/preservation/digital/formats/fdd/fdd000147.shtml (EXIF)
   * https://cran.r-project.org/web/packages/ctypesio/vignettes/parse-jpeg.html
   * https://dev.exiv2.org/projects/exiv2/wiki/The_Metadata_in_JPEG_files

 * EXIF Metadata Model & Fields
   * https://www.cipa.jp/e/index.html
   * https://www.loc.gov/preservation/digital/formats/fdd/fdd000146.shtml
   * https://exiftool.org/TagNames/EXIF.html
   * https://www.media.mit.edu/pia/Research/deepview/exif.html
   * https://exiv2.org/tags.html

 * IPTC Metadata Model & Fields
   * https://www.iptc.org/std/photometadata/specification/IPTC-PhotoMetadata
   * https://exiftool.org/TagNames/IPTC.html

 * XMP Metadata Model & Fields
   * https://www.adobe.com/products/xmp.html
   * https://exiftool.org/TagNames/XMP.html

### Copyright & License Information

Copyright © 2025 Daniel Sissman; licensed under the MIT License.