Updated README, version

doc: start with examples before the export reference, thanks to @synox

CHANGELOG.md

@@ -4,7 +4,33 @@ All notable changes to this project will be documented in this file. Dates are d
 
 Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 
-#### [v0.39.5](https://github.com/RhetTbull/osxphotos/compare/v0.39.3...v0.39.5)
+#### [v0.39.7](https://github.com/RhetTbull/osxphotos/compare/v0.39.6...v0.39.7)
+
+> 3 January 2021
+
+- doc: start with examples before the export reference, thanks to @synox  [`#327`](https://github.com/RhetTbull/osxphotos/pull/327)
+- Added tag_groups arg to ExifTool.asdict(), issue #324 [`2480f2a`](https://github.com/RhetTbull/osxphotos/commit/2480f2a325dbb09689f8c417618b7b9e976bfcb9)
+- doc: start with examples before the export reference [`7c7bf1b`](https://github.com/RhetTbull/osxphotos/commit/7c7bf1be6b6382a995a4e17906adfd8720d0a1c3)
+- Updated dependencies in README.md [`b1cab32`](https://github.com/RhetTbull/osxphotos/commit/b1cab32ff4c7b65ae4c9a5a9a11c175dbd487c0a)
+- remove extra spaces [`a59bb5b`](https://github.com/RhetTbull/osxphotos/commit/a59bb5b02f10fa554dae346a7271be37f50d8bcc)
+- Adding back  dependency https://github.com/RhetTbull/PhotoScript) [`7c8bfc8`](https://github.com/RhetTbull/osxphotos/commit/7c8bfc811ab3a93dabadf1655f7d0e217d6c7b01)
+
+#### [v0.39.6](https://github.com/RhetTbull/osxphotos/compare/v0.39.5...v0.39.6)
+
+> 3 January 2021
+
+- Make readme easier for beginners, thanks to @synox  [`#326`](https://github.com/RhetTbull/osxphotos/pull/326)
+- doc simplify readme [`02ef0f9`](https://github.com/RhetTbull/osxphotos/commit/02ef0f9a254e83a3729a09cea1ae523407074896)
+- Added exception handling/capture for convert-to-jpeg, issue #322 [`05f111a`](https://github.com/RhetTbull/osxphotos/commit/05f111a287e882ed6b451a550a87753501316aba)
+-  Add @synox as a contributor [`83915c6`](https://github.com/RhetTbull/osxphotos/commit/83915c65abb880036f80ebd830eb1e34292f9599)
+
+#### [v0.39.5](https://github.com/RhetTbull/osxphotos/compare/v0.39.4...v0.39.5)
+
+> 3 January 2021
+
+- Cleanup up the readme [`38842ff`](https://github.com/RhetTbull/osxphotos/commit/38842ff9249e6f5b3069a88a759c8df97ddce51c)
+
+#### [v0.39.4](https://github.com/RhetTbull/osxphotos/compare/v0.39.3...v0.39.4)
 
 > 3 January 2021
 

README.md

@@ -11,7 +11,8 @@
   * [Supported operating systems](#supported-operating-systems)
   * [Installation instructions](#installation-instructions)
   * [Command Line Usage](#command-line-usage)
-  * [Example uses of the package](#example-uses-of-the-package)
+    + [Command line examples](#command-line-examples)
+    + [Command line reference: export](#command-line-reference-export)
   * [Package Interface](#package-interface)
     + [PhotosDB](#photosdb)
     + [PhotoInfo](#photoinfo)
@@ -91,7 +92,6 @@ I recommend you create a [virtual environment](https://docs.python.org/3/tutoria
 
 This package will install a command line utility called `osxphotos` that allows you to query the Photos database.  Alternatively, you can also run the command line utility like this: `python3 -m osxphotos`
 
-After installing per instructions above, you should be able to run `osxphotos` on the command line:
 
 ```
 > osxphotos
@@ -126,7 +126,37 @@ Commands:
 
 To get help on a specific command, use `osxphotos help <command_name>`
 
-Example: `osxphotos help export`
+### Command line examples
+
+#### export all photos to ~/Desktop/export group in folders by date created
+
+`osxphotos export --export-by-date ~/Pictures/Photos\ Library.photoslibrary ~/Desktop/export`
+
+**Note**: Photos library/database path can also be specified using `--db` option:
+
+`osxphotos export --export-by-date --db ~/Pictures/Photos\ Library.photoslibrary ~/Desktop/export`
+
+#### find all photos with keyword "Kids" and output results to json file named results.json:
+
+`osxphotos query --keyword Kids --json ~/Pictures/Photos\ Library.photoslibrary >results.json`
+
+#### export photos to file structure based on 4-digit year and full name of month of photo's creation date:
+
+`osxphotos export ~/Desktop/export --directory "{created.year}/{created.month}"`
+
+(by default, it will attempt to use the system library)
+
+#### export photos to file structure based on 4-digit year of photo's creation date and add keywords for media type and labels (labels are only awailable on Photos 5 and higher):
+
+`osxphotos export ~/Desktop/export --directory "{created.year}" --keyword-template "{label}" --keyword-template "{media_type}"` 
+
+#### export default library using 'country name/year' as output directory (but use "NoCountry/year" if country not specified), add persons, album names, and year as keywords, write exif metadata to files when exporting, update only changed files, print verbose ouput
+
+`osxphotos export ~/Desktop/export --directory "{place.name.country,NoCountry}/{created.year}"  --person-keyword --album-keyword --keyword-template "{created.year}" --exiftool --update --verbose`
+
+### Command line reference: export
+
+`osxphotos help export`
 
 ```
 Usage: osxphotos export [OPTIONS] [PHOTOS_LIBRARY]... DEST
@@ -961,29 +991,7 @@ Substitution              Description
                           algorithms).
 ```
 
-Example: export all photos to ~/Desktop/export group in folders by date created
 
-`osxphotos export --export-by-date ~/Pictures/Photos\ Library.photoslibrary ~/Desktop/export`
-
-**Note**: Photos library/database path can also be specified using --db option:
-
-`osxphotos export --export-by-date --db ~/Pictures/Photos\ Library.photoslibrary ~/Desktop/export`
-
-Example: find all photos with keyword "Kids" and output results to json file named results.json:
-
-`osxphotos query --keyword Kids --json ~/Pictures/Photos\ Library.photoslibrary >results.json`
-
-Example: export photos to file structure based on 4-digit year and full name of month of photo's creation date:
-
-`osxphotos export ~/Desktop/export --directory "{created.year}/{created.month}"`
-
-Example: export photos to file structure based on 4-digit year of photo's creation date and add keywords for media type and labels (labels are only awailable on Photos 5 and higher):
-
-`osxphotos export ~/Desktop/export --directory "{created.year}" --keyword-template "{label}" --keyword-template "{media_type}"` 
-
-Example: export default library using 'country name/year' as output directory (but use "NoCountry/year" if country not specified), add persons, album names, and year as keywords, write exif metadata to files when exporting, update only changed files, print verbose ouput
-
-`osxphotos export ~/Desktop/export --directory "{place.name.country,NoCountry}/{created.year}"  --person-keyword --album-keyword --keyword-template "{created.year}" --exiftool --update --verbose`
 
 
 ## Example uses of the package 
@@ -1730,7 +1738,7 @@ exiftool must be installed in the path for this to work.  If exiftool cannot be
 
 `ExifTool` provides the following methods:
 
-- `asdict()`: returns all EXIF metadata found in the file as a dictionary in following form (Note: this shows just a subset of available metadata).  See [exiftool](https://exiftool.org/) documentation to understand which metadata keys are available.
+- `asdict(tag_groups=True)`: returns all EXIF metadata found in the file as a dictionary in following form (Note: this shows just a subset of available metadata).  See [exiftool](https://exiftool.org/) documentation to understand which metadata keys are available. If `tag_groups` is True (default) dict keys are in form "GROUP:TAG", e.g. "IPTC:Keywords". If `tag_groups` is False, dict keys do not have group names, e.g. "Keywords".
 
 ```python
 {'Composite:Aperture': 2.2,
@@ -2609,6 +2617,7 @@ For additional details about how osxphotos is implemented or if you would like t
 - [pathvalidate](https://pypi.org/project/pathvalidate/)
 - [wurlitzer](https://pypi.org/project/wurlitzer/)
 - [toml](https://github.com/uiri/toml)
+- [PhotoScript](https://github.com/RhetTbull/PhotoScript)
 
 
 ## Acknowledgements

osxphotos/_version.py

@@ -1,5 +1,5 @@
 """ version info """
 
-__version__ = "0.39.6"
+__version__ = "0.39.8"
 
 

osxphotos/exiftool.py

@@ -9,11 +9,11 @@
 import json
 import logging
 import os
+import re
 import shutil
 import subprocess
 from functools import lru_cache  # pylint: disable=syntax-error
 
-
 # exiftool -stay_open commands outputs this EOF marker after command is run
 EXIFTOOL_STAYOPEN_EOF = "{ready}"
 EXIFTOOL_STAYOPEN_EOF_LEN = len(EXIFTOOL_STAYOPEN_EOF)
@@ -300,17 +300,28 @@ class ExifTool:
         ver, _, _ = self.run_commands("-ver", no_file=True)
         return ver.decode("utf-8")
 
-    def asdict(self):
+    def asdict(self, tag_groups=True):
         """return dictionary of all EXIF tags and values from exiftool
         returns empty dict if no tags
+
+        Args:
+            tag_groups: if True (default), dict keys have tag groups, e.g. "IPTC:Keywords"; if False, drops groups from keys, e.g. "Keywords"
         """
         json_str, _, _ = self.run_commands("-json")
-        if json_str:
-            exifdict = json.loads(json_str)
-            return exifdict[0]
-        else:
+        if not json_str:
             return dict()
 
+        exifdict = json.loads(json_str)
+        exifdict = exifdict[0]
+        if not tag_groups:
+            # strip tag groups
+            exif_new = {}
+            for k, v in exifdict.items():
+                k = re.sub(r".*:", "", k)
+                exif_new[k] = v
+            exifdict = exif_new
+        return exifdict
+
     def json(self):
         """ returns JSON string containing all EXIF tags and values from exiftool """
         json, _, _ = self.run_commands("-json")

tests/test_exiftool.py

@@ -57,6 +57,36 @@ EXIF_UUID = {
         "IPTC:DateCreated": "2019:04:15",
     },
 }
+EXIF_UUID_NO_GROUPS = {
+    "6191423D-8DB8-4D4C-92BE-9BBBA308AAC4": {
+        "DateTimeOriginal": "2019:07:04 16:24:01",
+        "LensModel": "XF18-55mmF2.8-4 R LM OIS",
+        "Keywords": [
+            "Digital Nomad",
+            "Indoor",
+            "Reiseblogger",
+            "Stock Photography",
+            "Top Shot",
+            "close up",
+            "colorful",
+            "design",
+            "display",
+            "fake",
+            "flower",
+            "outdoor",
+            "photography",
+            "plastic",
+            "stock photo",
+            "vibrant",
+        ],
+        "DocumentNotes": "https://flickr.com/e/l7FkSm4f2lQkSV3CG6xlv8Sde5uF3gVu4Hf0Qk11AnU%3D",
+    },
+    "E9BC5C36-7CD1-40A1-A72B-8B8FAC227D51": {
+        "Make": "NIKON CORPORATION",
+        "Model": "NIKON D810",
+        "DateCreated": "2019:04:15",
+    },
+}
 EXIF_UUID_NONE = ["A1DD1F98-2ECD-431F-9AC9-5AFEFE2D3A5C"]
 
 try:
@@ -319,6 +349,14 @@ def test_as_dict():
     assert exifdata["XMP:TagsList"] == "wedding"
 
 
+def test_as_dict_no_tag_groups():
+    import osxphotos.exiftool
+
+    exif1 = osxphotos.exiftool.ExifTool(TEST_FILE_ONE_KEYWORD)
+    exifdata = exif1.asdict(tag_groups=False)
+    assert exifdata["TagsList"] == "wedding"
+
+
 def test_json():
     import osxphotos.exiftool
     import json
@@ -349,6 +387,19 @@ def test_photoinfo_exiftool():
             assert exif_dict[key] == val
 
 
+def test_photoinfo_exiftool_no_groups():
+    """ test PhotoInfo.exiftool which returns ExifTool object for photo without tag group names"""
+    import osxphotos
+
+    photosdb = osxphotos.PhotosDB(dbfile=PHOTOS_DB)
+    for uuid in EXIF_UUID_NO_GROUPS:
+        photo = photosdb.photos(uuid=[uuid])[0]
+        exiftool = photo.exiftool
+        exif_dict = exiftool.asdict(tag_groups=False)
+        for key, val in EXIF_UUID_NO_GROUPS[uuid].items():
+            assert exif_dict[key] == val
+
+
 def test_photoinfo_exiftool_none():
     import osxphotos