Merge the changes to support ExifTool.set_json_loads() for final 0.5.6 release

Author: sylikc

.github/workflows/lint-and-test.yml

@@ -68,7 +68,8 @@ jobs:
         echo "PATH=`pwd`:$PATH" >> $GITHUB_ENV
     - name: Install pyexiftool
       run: |
-        python -m pip install .
+        # install all supported json processors for tests
+        python -m pip install .[json,test]
     - name: Lint with flake8
       run: |
         # stop the build if there are Python syntax errors or undefined names

CHANGELOG.md

@@ -9,6 +9,7 @@ Date (Timezone)              | Version | Comment
 03/26/2022 06:48:01 AM (PDT) | 0.5.3   | Quite a few docstring changes<br>ExifToolHelper's get_tags() and set_tags() checks tag names to prevent inadvertent write behavior<br>Renamed a few of the errors to make sure the errors are explicit<br>ExifToolHelper() has some static helper methods which can be used when extending the class (ExifToolAlpha.set_keywords_batch() demonstrates a sample usage).<br>setup.py tweaked to make it Beta rather than Alpha<br>ExifToolAlpha.get_tag() updated to make it more robust.<br>Fixed ujson compatibility<br>Cleaned up and refactored testing.
 08/27/2022 06:06:32 PM (PDT) | 0.5.4   | New Feature: added raw_bytes parameter to ExifTool.execute() to return bytes only with no decoding conversion.<br>Changed: ExifTool.execute() now accepts both [str,bytes].  When given str, it will encode according to the ExifTool.encoding property.<br>Changed: ExifToolHelper.execute() now accepts Any type, and will do a str() on any non-str parameter.<br>Technical change: Popen() no longer uses an -encoding parameter, therefore working with the socket is back to bytes when interfacing with the exiftool subprocess.  This should be invisible to most users as the default behavior will still be the same.<br>Tests: Created associated test with a custom makernotes example to write and read back bytes.<br>Docs: Updated documentation with comprehensive samples, and a better FAQ section for common problems.
 12/30/2022 02:35:18 PM (PST) | 0.5.5   | No functional changes, only a huge speed improvement with large operations :: Update: Speed up large responses from exiftool.  Instead of using + string concatenation, uses list appends and reverse(), which results in a speedup of 10x+ for large operations.  See more details from the [reported issue](https://github.com/sylikc/pyexiftool/issues/60) and [PR 61](https://github.com/sylikc/pyexiftool/pull/61) by [prutschman](https://github.com/prutschman)
+10/22/2023 03:21:46 PM (PDT) | 0.5.6   | New Feature: added method ExifTool.set_json_loads() which allows setting a method to replace the json.loads() called in ExifTool.execute_json().<br>This permits passing additional configuration parameters to address the [reported issue](https://github.com/sylikc/pyexiftool/issues/76).<br>All documentation has been updated and two accompanying FAQ entries have been written to describe the new functionality.  Test cases have been written to test the new functionality and some baseline exiftool tests to ensure that the behavior remains consistent across tests.
 
 
 Follow maintenance/release-process.html when releasing a version.
@@ -61,9 +62,10 @@ Check for changes at the following resources to see if anyone has added some nif
 
 We can also direct users here or answer existing questions as to how to use the original version of ExifTool.
 
-(last checked 2/28/2022 all)
+(last checked 10/23/2023 all)
 
 search "pyexiftool github" to see if you find any more random ports/forks
 check for updates https://github.com/smarnach/pyexiftool/pulls
 check for new open issues https://github.com/smarnach/pyexiftool/issues?q=is%3Aissue+is%3Aopen
 
+answer relevant issues on stackoverflow (make sure it's related to the latest version) https://stackoverflow.com/search?tab=newest&q=pyexiftool&searchOn=3

COPYING.BSD

@@ -1,4 +1,4 @@
-Copyright 2012 Sven Marnach, 2019-2022 Kevin M (sylikc)
+Copyright 2012 Sven Marnach, 2019-2023 Kevin M (sylikc)
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

LICENSE

@@ -1,6 +1,6 @@
 PyExifTool <http://github.com/sylikc/pyexiftool>
 
-Copyright 2019-2022 Kevin M (sylikc)
+Copyright 2019-2023 Kevin M (sylikc)
 Copyright 2012-2014 Sven Marnach
 
 PyExifTool is free software: you can redistribute it and/or modify

docs/source/conf.py

@@ -31,7 +31,7 @@
 
 # General information about the project.
 project = 'PyExifTool'
-copyright = '2022, Kevin M (sylikc)'
+copyright = '2023, Kevin M (sylikc)'
 author = 'Kevin M (sylikc)'
 
 # read directly from exiftool's version instead of hard coding it here

docs/source/faq.rst

@@ -103,6 +103,97 @@ So if you want to have the ouput match (*useful for debugging*) between PyExifTo
 		Y Resolution                    : 72
 
 
+.. _set_json_loads faq:
+
+PyExifTool json turns some text fields into numbers
+===================================================
+
+A strange behavior of *exiftool* is documented in the `exiftool documentation`_::
+
+	-j[[+]=JSONFILE] (-json)
+
+		Note that ExifTool quotes JSON values only if they don't look like numbers
+		(regardless of the original storage format or the relevant metadata specification).
+
+.. _`exiftool documentation`: https://exiftool.org/exiftool_pod.html#OPTIONS
+
+This causes a peculiar behavior if you set a text metadata field to a string that looks like a number:
+
+.. code-block::
+
+	import exiftool
+	with exiftool.ExifToolHelper() as et:
+		# Comment is a STRING field
+		et.set_tags("rose.jpg", {"Comment": "1.10"})  # string: "1.10" != "1.1"
+
+		# FocalLength is a FLOAT field
+		et.set_tags("rose.jpg", {"FocalLength": 1.10})  # float: 1.10 == 1.1
+		print(et.get_tags("rose.jpg", ["Comment", "FocalLength"]))
+
+		# Prints: [{'SourceFile': 'rose.jpg', 'File:Comment': 1.1, 'EXIF:FocalLength': 1.1}]
+
+Workaround to enable output as string
+-------------------------------------
+
+There is no universal fix which wouldn't affect other behaviors in PyExifTool, so this is an advanced workaround if you encounter this specific problem.
+
+PyExifTool does not do any processing on the fields returned by *exiftool*.  In effect, what is returned is processed directly by ``json.loads()`` by default.
+
+You can change the behavior of the json string parser, or specify a different one using :py:meth:`exiftool.ExifTool.set_json_loads`.
+
+The `documentation of CPython's json.load`_ allows ``parse_float`` to be any parser of choice when a float is encountered in a JSON file.  Thus, you can force the float to be interpreted as a string.
+However, as you can see below, it also *changes the behavior of all float fields*.
+
+
+.. _`documentation of CPython's json.load`: https://docs.python.org/3/library/json.html#json.load
+
+.. code-block::
+
+	import exiftool, json
+	with exiftool.ExifToolHelper() as et:
+		et.set_json_loads(json.loads, parse_float=str)
+
+		# Comment is a STRING field
+		et.set_tags("rose.jpg", {"Comment": "1.10"})  # string: "1.10" == "1.10"
+
+		# FocalLength is a FLOAT field
+		et.set_tags("rose.jpg", {"FocalLength": 1.10})  # float: 1.1 == "1.1"
+		print(et.get_tags("rose.jpg", ["Comment", "FocalLength"]))
+
+		# Prints: [{'SourceFile': 'rose.jpg', 'File:Comment': '1.10', 'EXIF:FocalLength': '1.1'}]
+
+.. warning::
+
+	Unfortunately you can either change all float fields to a string, or possibly lose some float precision when working with floats in string metadata fields.
+
+	There isn't any known universal workaround which wouldn't break one thing or the other, as it is an underlying *exiftool* quirk.
+
+There are other edge cases which may exhibit quirky behavior when storing numbers and whitespace only to text fields (See `test cases related to numeric tags`_).  Since PyExifTool cannot accommodate all possible edge cases,
+this workaround will allow you to configure PyExifTool to work in your environment!
+
+.. _`test cases related to numeric tags`: https://github.com/sylikc/pyexiftool/blob/master/tests/test_helper_tags_float.py
+
+
+I would like to use a faster json string parser
+===============================================
+
+By default, PyExifTool uses the built-in ``json`` library to load the json string returned by *exiftool*.  If you would like to use an alternate library, set it manually using :py:meth:`exiftool.ExifTool.set_json_loads`
+
+
+.. code-block::
+
+	import exiftool, json
+	with exiftool.ExifToolHelper() as et:
+		et.set_json_loads(ujson.loads)
+		...
+
+.. note::
+
+	In PyExifTool version before 0.5.6, ``ujson`` was supported automatically if the package was installed.
+
+	To support any possible alternative JSON library, this behavior has now been changed and it must be enabled manually.
+
+
 I'm getting an error! How do I debug PyExifTool output?
 =======================================================
 

docs/source/maintenance/release-process.rst

@@ -9,6 +9,7 @@ Source Preparation
 ==================
 
 #. Update the version number in ``exiftool/__init__.py``
+#. Update the docs copyright year ``docs/source/conf.py`` and in source files
 #. Add any changelog entries to ``CHANGELOG.md``
 #. Run Tests
 #. Generate docs

exiftool/__init__.py

@@ -4,7 +4,7 @@
 #
 # PyExifTool <http://github.com/sylikc/pyexiftool>
 #
-# Copyright 2019-2022 Kevin M (sylikc)
+# Copyright 2019-2023 Kevin M (sylikc)
 # Copyright 2012-2014 Sven Marnach
 #
 # Community contributors are listed in the CHANGELOG.md for the PRs
@@ -61,7 +61,7 @@
 
 # version number using Semantic Versioning 2.0.0 https://semver.org/
 # may not be PEP-440 compliant https://www.python.org/dev/peps/pep-0440/#semantic-versioning
-__version__ = "0.5.5"
+__version__ = "0.5.6"
 
 
 # while we COULD import all the exceptions into the base library namespace,

exiftool/constants.py

@@ -4,7 +4,7 @@
 #
 # PyExifTool <http://github.com/sylikc/pyexiftool>
 #
-# Copyright 2019-2022 Kevin M (sylikc)
+# Copyright 2019-2023 Kevin M (sylikc)
 # Copyright 2012-2014 Sven Marnach
 #
 # Community contributors are listed in the CHANGELOG.md for the PRs

exiftool/exceptions.py

@@ -4,7 +4,7 @@
 #
 # PyExifTool <http://github.com/sylikc/pyexiftool>
 #
-# Copyright 2019-2022 Kevin M (sylikc)
+# Copyright 2019-2023 Kevin M (sylikc)
 # Copyright 2012-2014 Sven Marnach
 #
 # Community contributors are listed in the CHANGELOG.md for the PRs
@@ -53,19 +53,18 @@ class ExifToolRunning(ExifToolProcessStateError):
 	"""
 	ExifTool is already running
 	"""
-	def __init__(self, message):
+	def __init__(self, message: str):
 		super().__init__(f"ExifTool instance is running: {message}")
 
 
 class ExifToolNotRunning(ExifToolProcessStateError):
 	"""
 	ExifTool is not running
 	"""
-	def __init__(self, message):
+	def __init__(self, message: str):
 		super().__init__(f"ExifTool instance not running: {message}")
 
 
-
 ###########################################################
 #################### Execute Exception ####################
 ###########################################################
@@ -94,7 +93,6 @@ def __init__(self, message, exit_status, cmd_stdout, cmd_stderr, params):
 		self.stderr: str = cmd_stderr
 
 
-
 class ExifToolExecuteError(ExifToolExecuteException):
 	"""
 	ExifTool executed the command but returned a non-zero exit status.
@@ -139,7 +137,6 @@ def __init__(self, exit_status, cmd_stdout, cmd_stderr, params):
 		super().__init__("execute_json received invalid JSON output from exiftool", exit_status, cmd_stdout, cmd_stderr, params)
 
 
-
 #########################################################
 #################### Other Exception ####################
 #########################################################
@@ -159,4 +156,3 @@ class ExifToolTagNameError(ExifToolException):
 	"""
 	def __init__(self, bad_tag):
 		super().__init__(f"Invalid Tag Name found: \"{bad_tag}\"")
-