# 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 and EXIF 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 initializing 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.
* `order` (`ByteOrder`) – The `order` property can be used to determine the byte order
of the JPEG file. The property will report either `ByteOrder.MSB` for big endian files
or `ByteOrder.LSB` for little endian files.
* `format` (`Format`) – The `format` property can be used to determine the file format
of the JPEG file. The property will report either `Format.JPEG` for baseline formatted
JPEG files, `Format.JFIF` for JFIF formatted files and `Format.EXIF` for EXIF formatted
JPEG files.
* `encoding` (`Encoding`) – The `encoding` property can be used to determine the encoding
used for the JPEG file, which will report a `Encoding` enumeration value which includes:
* `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.
### 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` or `EXIF` subclasses, depending on the file format of the
specified JPEG file; these classes are subclasses of the library's `JPEG` base class.
<!--pytest.mark.skip-->
```python
from jpegdata import JPEG, Format, Encoding
filepath = "/path/to/file.jpeg"
# Initialize the library with the absolute file path of the JPEG file to load
jpeg = JPEG(filepath=filepath)
# 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
# If desired, iterate through the segments held within the file:
for segment in jpeg:
print(segment)
```
### 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.
Raw data
{
"_id": null,
"home_page": null,
"name": "jpegdata",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "image, metadata, jpeg, data",
"author": "Daniel Sissman",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/95/9c/bc305cf792b25b9707d1014a91a6cea0c0e6677ec6db5debb035f015967f/jpegdata-0.1.0.tar.gz",
"platform": "any",
"description": "# JPEGData\n\nThe JPEGData library for Python provides a streamlined way to work with JPEG image files\noffering the ability to extract certain file metadata.\n\n### Requirements\n\nThe JPEGData library has been tested to work with Python 3.10, 3.11, 3.12 and 3.13, but\nhas not been tested, nor is its use supported with earlier versions of Python.\n\n### Installation\n\nThe library is available from the PyPI repository, so may be added easily to a project's\ndependencies via its `requirements.txt` file or similar by referencing the library's\nname, `jpegdata`, or the library may be installed directly onto your local development\nsystem using `pip install` by entering the following command:\n\n\t$ pip install jpegdata\n\n### Classes, Methods & Properties\n\nThe JPEGData library's main class is the `JPEG` class through which JPEG image files can\nbe loaded, modified via the supported actions, and saved. The library supports reading\nseveral common JPEG file formats including JFIF and EXIF formatted JPEG files. Currently\nthe library does not support more recent JPEG formats and derivations such as JPEG XL,\nJPEG-2000, JPEG XR, etc.\n\nThe `JPEG` class offers the following methods:\n\n* `JPEG(filepath: str)` \u2013 The `JPEG()` class constructor expects an absolute filepath at\na minimum for the JPEG file you wish to open. Upon initializing the class with the file,\nthe library will then attempt to load and parse the file. Assuming that the file is a \nvalid JPEG file, the library will parse the file, identify any segments contained within\nthe file, and any data associated with each of the segments, and will determine several\nintrinsic properties of the JPEG image including the canvas width and height.\n\nThe `JPEG` class offers the following properties:\n\n * `info` (`Information`) \u2013 The `info` property can be used to access the `Information`\n class instance that is created when the `JPEG` class instance is created and the file is\n parsed. The `Information` class instance contains core information about the parsed file\n including the `filepath`, `filesize`, (byte) `order`, and `format`.\n \n This property is used internally by the class to populate the corresponding top level\n properties of the same names noted below.\n\n * `filepath` (`str`) \u2013 The `filepath` property can be used to get the original file path\n that was specified at the time the class was initialised.\n\n * `filesize` (`int`) \u2013 The `filesize` property can be used to get the original file size\n of the file that was specified at the time the class was initialised.\n\n * `order` (`ByteOrder`) \u2013 The `order` property can be used to determine the byte order\n of the JPEG file. The property will report either `ByteOrder.MSB` for big endian files\n or `ByteOrder.LSB` for little endian files.\n\n * `format` (`Format`) \u2013 The `format` property can be used to determine the file format\n of the JPEG file. The property will report either `Format.JPEG` for baseline formatted\n JPEG files, `Format.JFIF` for JFIF formatted files and `Format.EXIF` for EXIF formatted\n JPEG files.\n\n * `encoding` (`Encoding`) \u2013 The `encoding` property can be used to determine the encoding\n used for the JPEG file, which will report a `Encoding` enumeration value which includes:\n\n * `Encoding.BaselineDCT` for baseline DCT encoded images;\n * `Encoding.ProgressiveDCT` for progressive DCT encoded images.\n\n * `width` (`int`) \u2013 The `width` property can be used to access the parsed pixel width of the image.\n\n * `height` (`int`) \u2013 The `height` property can be used to access the parsed pixel height of the image.\n \n* `precision` (`int`) \u2013 The `precision` property can be used to access the parsed precision of the image.\n\n### Example of Use\n\nTo create an instance of the `JPEG` class, import the `JPEG` class from the library and\nspecify the absolute file path to the JPEG file you wish to open as the first argument.\nIf the specified file can be opened successfully, the library will return an instance of\neither the `JPEG`, `JFIF` or `EXIF` subclasses, depending on the file format of the\nspecified JPEG file; these classes are subclasses of the library's `JPEG` base class.\n\n<!--pytest.mark.skip-->\n\n```python\nfrom jpegdata import JPEG, Format, Encoding\n\nfilepath = \"/path/to/file.jpeg\"\n\n# Initialize the library with the absolute file path of the JPEG file to load\njpeg = JPEG(filepath=filepath)\n\n# Use the parsed properties of the file\nassert jpeg.format is Format.EXIF\nassert jpeg.encoding is Encoding.BaselineDCT\nassert jpeg.precision == 8\nassert jpeg.width == 600\nassert jpeg.height == 400\n\n# If desired, iterate through the segments held within the file:\nfor segment in jpeg:\n print(segment)\n```\n\n### Disclaimer\n\nWhile every effort has been made to ensure that the library works reliably with JPEG\nfiles and embedded metadata, you must ensure that all files are backed up before using\nthe JPEGData library with any files, especially as the library is in early development.\n\nFurthermore, the library may not be able to read nor preserve all metadata or other data\nwithin a JPEG file, especially if manufacturer specific, custom or other \"private\" data\nare present. As such, it is possible that loss of data could occur if an image is loaded\nand is then overwritten by saving the file back to the same file path, _when saving is\navailable in future versions of the library (currently the library is read-only)_.\n\nUse of the library is entirely at your own risk and the authors bear no responsibility\nfor losses of any kind. By using the software you assume all such risk and liability.\n\nTHIS SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,\nINCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR\nPURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE\nLIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,\nTORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE\nOR OTHER DEALINGS IN THE SOFTWARE.\n\n### Credits & References\n\nThe JPEG file format, and the related EXIF, IPTC and XMP metadata model specifications\nwere researched across various sources. Please visit these valuable online resources to\nlearn more about the JPEG file format and related metadata model specifications and to\nsupport these world class organisations and their products:\n\n * JPEG File Format\n * https://www.loc.gov/preservation/digital/formats/fdd/fdd000619.shtml\n * https://en.wikipedia.org/wiki/JPEG (JPEG)\n * https://en.wikipedia.org/wiki/JPEG_File_Interchange_Format (JFIF)\n * https://www.loc.gov/preservation/digital/formats/fdd/fdd000018.shtml (JFIF)\n * https://www.loc.gov/preservation/digital/formats/fdd/fdd000147.shtml (EXIF)\n * https://cran.r-project.org/web/packages/ctypesio/vignettes/parse-jpeg.html\n * https://dev.exiv2.org/projects/exiv2/wiki/The_Metadata_in_JPEG_files\n\n * EXIF Metadata Model & Fields\n * https://www.cipa.jp/e/index.html\n * https://www.loc.gov/preservation/digital/formats/fdd/fdd000146.shtml\n * https://exiftool.org/TagNames/EXIF.html\n * https://www.media.mit.edu/pia/Research/deepview/exif.html\n * https://exiv2.org/tags.html\n\n * IPTC Metadata Model & Fields\n * https://www.iptc.org/std/photometadata/specification/IPTC-PhotoMetadata\n * https://exiftool.org/TagNames/IPTC.html\n\n * XMP Metadata Model & Fields\n * https://www.adobe.com/products/xmp.html\n * https://exiftool.org/TagNames/XMP.html\n\n### Copyright & License Information\n\nCopyright \u00a9 2025 Daniel Sissman; licensed under the MIT License.\n",
"bugtrack_url": null,
"license": null,
"summary": "Streamlined JPEG image metadata parsing and updating.",
"version": "0.1.0",
"project_urls": {
"changelog": "https://github.com/bluebinary/jpegdata/blob/main/CHANGELOG.md",
"documentation": "https://github.com/bluebinary/jpegdata/blob/main/README.md",
"homepage": "https://github.com/bluebinary/jpegdata",
"issues": "https://github.com/bluebinary/jpegdata/issues",
"repository": "https://github.com/bluebinary/jpegdata"
},
"split_keywords": [
"image",
" metadata",
" jpeg",
" data"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b99731f0fe07a1387050258ab92ebc885a948be01a7a8cb62bb65a411f72dc3f",
"md5": "f46b11131a6102d7697ed17e4ee3f636",
"sha256": "8de226552925c13b90c92d9836048fbba9e1555c754d0b1ab4361a165c18355c"
},
"downloads": -1,
"filename": "jpegdata-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f46b11131a6102d7697ed17e4ee3f636",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 16256,
"upload_time": "2025-08-11T00:37:31",
"upload_time_iso_8601": "2025-08-11T00:37:31.794111Z",
"url": "https://files.pythonhosted.org/packages/b9/97/31f0fe07a1387050258ab92ebc885a948be01a7a8cb62bb65a411f72dc3f/jpegdata-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "959cbc305cf792b25b9707d1014a91a6cea0c0e6677ec6db5debb035f015967f",
"md5": "608aa57fb23e27da1605bcf681632b63",
"sha256": "e14ffa9401f168c7f7d92416a6d67ddfeacad725884f3d08e34cf37a6ffc209c"
},
"downloads": -1,
"filename": "jpegdata-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "608aa57fb23e27da1605bcf681632b63",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 16974,
"upload_time": "2025-08-11T00:37:33",
"upload_time_iso_8601": "2025-08-11T00:37:33.242373Z",
"url": "https://files.pythonhosted.org/packages/95/9c/bc305cf792b25b9707d1014a91a6cea0c0e6677ec6db5debb035f015967f/jpegdata-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-11 00:37:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bluebinary",
"github_project": "jpegdata",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "enumerific",
"specs": [
[
">=",
"1.0.5"
]
]
},
{
"name": "caselessly",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "deliciousbytes",
"specs": [
[
">=",
"1.0.4"
]
]
},
{
"name": "tabulicious",
"specs": [
[
">=",
"0.5.0"
]
]
}
],
"lcname": "jpegdata"
}
JSON
