Added tutorial, closes #432

README.md

@@ -50,11 +50,14 @@ OSXPhotos provides the ability to interact with and query Apple's Photos.app lib
 
 ## Supported operating systems
 
-Only works on macOS (aka Mac OS X). Tested on macOS Sierra (10.12.6) until macOS Big Sur (10.16/11.1).
+Only works on macOS (aka Mac OS X). Tested on macOS Sierra (10.12.6) until macOS Big Sur (10.16/11.3).
+
+If you have access to the macOS 12 / Monterey beta and would like to help ensure osxphotos is compatible, please visit the [Discussions](https://github.com/RhetTbull/osxphotos/discussions) page and let me know!
 
 | macOS Version     | macOS name | Photos.app version |
 | ----------------- |------------|:-------------------|
-| 10.16, 11.0-11.3  | Big Sur    | 6.0 ✅             |
+| 12.0              | Monterey   | ?.0 UNKNOWN        |
+| 10.16, 11.0-11.4  | Big Sur    | 6.0 ✅             |
 | 10.15.1 - 10.15.7 | Catalina   | 5.0 ✅             |
 | 10.14.5, 10.14.6  | Mojave     | 4.0 ✅             |
 | 10.13.6           | High Sierra| 3.0 ✅             |
@@ -1565,7 +1568,7 @@ Substitution                    Description
 {lf}                            A line feed: '\n', alias for {newline}
 {cr}                            A carriage return: '\r'
 {crlf}                          a carriage return + line feed: '\r\n'
-{osxphotos_version}             The osxphotos version, e.g. '0.42.39'
+{osxphotos_version}             The osxphotos version, e.g. '0.42.40'
 {osxphotos_cmd_line}            The full command line used to run osxphotos
 
 The following substitutions may result in multiple values. Thus if specified for
@@ -3353,7 +3356,7 @@ The following template field substitutions are availabe for use the templating s
 |{lf}|A line feed: '\n', alias for {newline}|
 |{cr}|A carriage return: '\r'|
 |{crlf}|a carriage return + line feed: '\r\n'|
-|{osxphotos_version}|The osxphotos version, e.g. '0.42.39'|
+|{osxphotos_version}|The osxphotos version, e.g. '0.42.40'|
 |{osxphotos_cmd_line}|The full command line used to run osxphotos|
 |{album}|Album(s) photo is contained in|
 |{folder_album}|Folder path + album photo is contained in. e.g. 'Folder/Subfolder/Album' or just 'Album' if no enclosing folder|

README.rst

@@ -18,6 +18,8 @@ Supported operating systems
 
 Only works on macOS (aka Mac OS X). Tested on macOS Sierra (10.12.6) through macOS Big Sur (11.3).
 
+If you have access to macOS 12 / Monterey beta and would like to help ensure osxphotos is compatible, please contact me via GitHub.
+
 This package will read Photos databases for any supported version on any supported macOS version.  
 E.g. you can read a database created with Photos 5.0 on MacOS 10.15 on a machine running macOS 10.12 and vice versa.
 
@@ -108,6 +110,7 @@ Alternatively, you can also run the command line utility like this: ``python3 -m
      persons   Print out persons (faces) found in the Photos library.
      places    Print out places found in the Photos library.
      query     Query the Photos database using 1 or more search options; if...
+     tutorial  Display osxphotos tutorial.
 
 To get help on a specific command, use ``osxphotos help <command_name>``
 

osxphotos.spec

@@ -8,41 +8,50 @@ import importlib
 pathex = os.getcwd()
 
 # include necessary data files
-datas=[('osxphotos/templates/xmp_sidecar.mako', 'osxphotos/templates'), ('osxphotos/templates/xmp_sidecar_beta.mako', 'osxphotos/templates'), ('osxphotos/phototemplate.tx', 'osxphotos'), ('osxphotos/phototemplate.md', 'osxphotos')]
-package_imports = [['photoscript', ['photoscript.applescript']]]
+datas = [
+    ("osxphotos/templates/xmp_sidecar.mako", "osxphotos/templates"),
+    ("osxphotos/templates/xmp_sidecar_beta.mako", "osxphotos/templates"),
+    ("osxphotos/phototemplate.tx", "osxphotos"),
+    ("osxphotos/phototemplate.md", "osxphotos"),
+    ("osxphotos/tutorial.md", "osxphotos"),
+]
+package_imports = [["photoscript", ["photoscript.applescript"]]]
 for package, files in package_imports:
     proot = os.path.dirname(importlib.import_module(package).__file__)
     datas.extend((os.path.join(proot, f), package) for f in files)
 
 block_cipher = None
 
-a = Analysis(['cli.py'],
-             pathex=[pathex],
-             binaries=[],
-             datas=datas,
-             hiddenimports=['pkg_resources.py2_warn'],
-             hookspath=[],
-             runtime_hooks=[],
-             excludes=[],
-             win_no_prefer_redirects=False,
-             win_private_assemblies=False,
-             cipher=block_cipher,
-             noarchive=False)
+a = Analysis(
+    ["cli.py"],
+    pathex=[pathex],
+    binaries=[],
+    datas=datas,
+    hiddenimports=["pkg_resources.py2_warn"],
+    hookspath=[],
+    runtime_hooks=[],
+    excludes=[],
+    win_no_prefer_redirects=False,
+    win_private_assemblies=False,
+    cipher=block_cipher,
+    noarchive=False,
+)
 
-pyz = PYZ(a.pure, a.zipped_data,
-             cipher=block_cipher)
+pyz = PYZ(a.pure, a.zipped_data, cipher=block_cipher)
 
-exe = EXE(pyz,
-          a.scripts,
-          a.binaries,
-          a.zipfiles,
-          a.datas,
-          [],
-          name='osxphotos',
-          debug=False,
-          bootloader_ignore_signals=False,
-          strip=False,
-          upx=True,
-          upx_exclude=[],
-          runtime_tmpdir=None,
-          console=True )
+exe = EXE(
+    pyz,
+    a.scripts,
+    a.binaries,
+    a.zipfiles,
+    a.datas,
+    [],
+    name="osxphotos",
+    debug=False,
+    bootloader_ignore_signals=False,
+    strip=False,
+    upx=True,
+    upx_exclude=[],
+    runtime_tmpdir=None,
+    console=True,
+)

osxphotos/_constants.py

@@ -71,6 +71,7 @@ _TESTED_OS_VERSIONS = [
     ("11", "1"),
     ("11", "2"),
     ("11", "3"),
+    ("11", "4"),
 ]
 
 # Photos 5 has persons who are empty string if unidentified face

osxphotos/_version.py

@@ -1,3 +1,3 @@
 """ version info """
 
-__version__ = "0.42.39"
+__version__ = "0.42.40"

osxphotos/cli.py

@@ -39,7 +39,7 @@ from ._constants import (
     SIDECAR_XMP,
 )
 from ._version import __version__
-from .cli_help import ExportCommand
+from .cli_help import ExportCommand, tutorial_help
 from .configoptions import (
     ConfigOptions,
     ConfigOptionsInvalidError,
@@ -3759,3 +3759,17 @@ SOFTWARE.
     click.echo("")
     click.echo(f"Source code available at: {OSXPHOTOS_URL}")
     click.echo(license)
+
+
+@cli.command(name="tutorial")
+@click.argument(
+    "WIDTH",
+    nargs=-1,
+    type=click.INT,
+)
+@click.pass_obj
+@click.pass_context
+def tutorial(ctx, cli_obj, width):
+    """Display osxphotos tutorial."""
+    width = width[0] if width else 100
+    click.echo_via_pager(tutorial_help(width=width))

osxphotos/cli_help.py

@@ -1,6 +1,7 @@
 """Help text helper class for osxphotos CLI """
 
 import io
+import pathlib
 import re
 
 import click
@@ -250,13 +251,26 @@ def template_help(width=78):
     """Return formatted string for template system"""
     sio = io.StringIO()
     console = Console(file=sio, force_terminal=True, width=width)
-    template_help_md = strip_md_links(get_template_help())
+    template_help_md = strip_md_header_and_links(get_template_help())
     console.print(Markdown(template_help_md))
     help_str = sio.getvalue()
     sio.close()
     return help_str
 
 
+def tutorial_help(width=78):
+    """Return formatted string for tutorial"""
+    sio = io.StringIO()
+    console = Console(file=sio, force_terminal=True, width=width)
+    help_md = get_tutorial_text()
+    help_md = strip_html_comments(help_md)
+    help_md = strip_md_links(help_md)
+    console.print(Markdown(help_md))
+    help_str = sio.getvalue()
+    sio.close()
+    return help_str
+
+
 def rich_text(text, width=78):
     """Return rich formatted text"""
     sio = io.StringIO()
@@ -267,6 +281,26 @@ def rich_text(text, width=78):
     return rich_text
 
 
+def strip_md_header_and_links(md):
+    """strip markdown headers and links from markdown text md
+
+    Args:
+        md: str, markdown text
+
+    Returns:
+        str with markdown headers and links removed
+
+    Note: This uses a very basic regex that likely fails on all sorts of edge cases
+    but works for the links in the osxphotos docs
+    """
+    links = r"(?:[*#])|\[(.*?)\]\(.+?\)"
+
+    def subfn(match):
+        return match.group(1)
+
+    return re.sub(links, subfn, md)
+
+
 def strip_md_links(md):
     """strip markdown links from markdown text md
 
@@ -279,9 +313,23 @@ def strip_md_links(md):
     Note: This uses a very basic regex that likely fails on all sorts of edge cases
     but works for the links in the osxphotos docs
     """
-    links = r"(?:[*#])|\[(.*?)\]\(.+?\)"
+    links = r"\[(.*?)\]\(.+?\)"
 
     def subfn(match):
         return match.group(1)
 
     return re.sub(links, subfn, md)
+
+
+def strip_html_comments(text):
+    """Strip html comments from text (which doesn't need to be valid HTML)"""
+    return re.sub(r"<!--(.|\s|\n)*?-->", "", text)
+
+
+def get_tutorial_text():
+    """Load tutorial text from file"""
+    # TODO: would be better to use importlib.abc.ResourceReader but I can't find a single example of how to do this
+    help_file = pathlib.Path(__file__).parent / "tutorial.md"
+    with open(help_file, "r") as fd:
+        md = fd.read()
+    return md

utils/update_readme.py

@@ -22,7 +22,7 @@ from osxphotos.phototemplate import (
 )
 
 TEMPLATE_HELP = "osxphotos/phototemplate.md"
-TUTORIAL_HELP = "docsrc/source/tutorial.md"
+TUTORIAL_HELP = "osxphotos/tutorial.md"
 
 USAGE_START = (
     "<!-- OSXPHOTOS-EXPORT-USAGE:START - Do not remove or modify this section -->"