refactor(api): Add type hints and improve documentation for clarity

Signed-off-by: longhao <[email protected]>

Author: loonghao

.github/workflows/code-check.yml

@@ -29,7 +29,7 @@ jobs:
     runs-on: windows-latest
     strategy:
       matrix:
-        python-version: ["3.7", "3.8", "3.9", "3.10", "3.11", "3.12"]
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
     steps:
     - uses: actions/checkout@v4
       with:

docs/__init__.py

@@ -0,0 +1,3 @@
+"""Documentation generation module."""
+
+from __future__ import annotations

docs/gen_api_nav.py

@@ -1,13 +1,15 @@
 """Plugin for generate API docs."""
 
 # Import built-in modules
+from __future__ import annotations
+
 from pathlib import Path
 
 # Import third-party modules
 import mkdocs_gen_files
 
 
-def main():
+def main() -> None:
     nav = mkdocs_gen_files.Nav()
     root = Path(__file__).parent.parent
     api_root = root.joinpath("photoshop")
@@ -16,11 +18,7 @@ def main():
         doc_path = path.relative_to(root).with_suffix(".md")
         full_doc_path = Path("reference", doc_path)
         parts = list(module_path.parts)
-        if parts[-1] == "__init__":
-            continue
-        elif parts[-1] == "__main__":
-            continue
-        elif parts[-1] == "__version__":
+        if parts[-1] == "__init__" or parts[-1] == "__main__" or parts[-1] == "__version__":
             continue
         nav_parts = list(parts)
         if nav_parts[-1].startswith("_"):
@@ -29,7 +27,7 @@ def main():
         full_doc_path = full_doc_path.as_posix().replace("\\", "/")
         with mkdocs_gen_files.open(full_doc_path, "w") as fd:
             ident = ".".join(parts)
-            print(f"::: " + ident, file=fd)
+            print("::: " + ident, file=fd)
 
         mkdocs_gen_files.set_edit_path(full_doc_path, path.as_posix().replace("\\", "/"))
 

docs/gen_examples.py

@@ -1,14 +1,16 @@
 """Plugin for generate API docs."""
 
 # Import built-in modules
+from __future__ import annotations
+
 import os
 from pathlib import Path
 
-# Import third-party modules
-from jinja2 import Template
 import mkdocs_gen_files
 import stringcase
 
+# Import third-party modules
+from jinja2 import Template
 
 template = Template(
     r"""
@@ -22,44 +24,43 @@
 ```
 {% endfor %}
 
-"""
+""",
 )
 
 
-class Examples(object):
-    def __init__(self, root: Path):
+class Examples:
+    def __init__(self, root: Path) -> None:
         self._root = root
 
-    def get_examples(self):
-        files = [file_ for file_ in self._root.glob("*.py") if "_psd_files.py" not in file_.as_posix()]
-        return files
+    def get_examples(self) -> list[Path]:
+        return [file_ for file_ in self._root.glob("*.py") if "_psd_files.py" not in file_.as_posix()]
 
     @staticmethod
-    def convert_relative_path(file):
+    def convert_relative_path(file: str) -> str:
         path = file.split("examples")[1]
         return "../examples{}".format(path.replace("\\", "/"))
 
     @staticmethod
-    def get_name(file):
-        name = os.path.basename(file).split(".py")[0]
+    def get_name(file: str) -> str:
+        name = Path(file).name.split(".py")[0]
         return stringcase.titlecase(name)
 
     @staticmethod
-    def get_line(name):
+    def get_line(name: str) -> str:
         return "-" * len(name)
 
     @staticmethod
-    def get_content(file_):
-        with open(file_, "r") as f:
+    def get_content(file_: str) -> str:
+        with Path(file_).open() as f:
             return "".join(f.readlines())
 
 
-def main():
+def main() -> None:
     root = Path(__file__).parent.parent
     with mkdocs_gen_files.open("examples.md", "w") as nav_file:
         examples_data = Examples(root.joinpath("examples"))
         nav_file.write(template.render(Examples=examples_data))
 
 
-if __name__ == "<run_path>":
+if __name__ == "__main__":
     main()

examples/__init__.py

@@ -0,0 +1,3 @@
+"""Example scripts for photoshop-python-api."""
+
+from __future__ import annotations

examples/_psd_files.py

@@ -1,11 +1,13 @@
 # Import built-in modules
+from __future__ import annotations
+from pathlib import Path
 import os
 
 
-def get_psd_files():
+def get_psd_files() -> dict[str, str]:
     files = {}
-    this_root = os.path.dirname(__file__)
-    file_root = os.path.join(this_root, "files")
+    this_root = Path(__file__).parent
+    file_root = this_root / "files"
     for file_name in os.listdir(file_root):
-        files[file_name] = os.path.join(file_root, file_name)
+        files[file_name] = str(file_root / file_name)
     return files

examples/active_layer.py

@@ -1,20 +1,21 @@
-# Set the active layer to the last art layer of the active document, or the
-# first if the last is already active.
-
-# Import local modules
-from photoshop import Session
-
-
-with Session() as ps:
-    if len(ps.app.documents) < 1:
-        docRef = ps.app.documents.add()
-    else:
-        docRef = ps.app.activeDocument
-
-    if len(docRef.layers) < 2:
-        docRef.artLayers.add()
-
-    ps.echo(docRef.activeLayer.name)
-    new_layer = docRef.artLayers.add()
-    ps.echo(new_layer.name)
-    new_layer.name = "test"
+# Set the active layer to the last art layer of the active document, or the
+# first if the last is already active.
+
+# Import local modules
+from __future__ import annotations
+
+from photoshop import Session
+
+with Session() as ps:
+    if len(ps.app.documents) < 1:
+        docRef = ps.app.documents.add()
+    else:
+        docRef = ps.app.activeDocument
+
+    if len(docRef.layers) < 2:
+        docRef.artLayers.add()
+
+    ps.echo(docRef.activeLayer.name)
+    new_layer = docRef.artLayers.add()
+    ps.echo(new_layer.name)
+    new_layer.name = "test"

examples/add_metadata.py

@@ -1,16 +1,17 @@
 """Add metadata to current active document."""
 
 # Import built-in modules
+from __future__ import annotations
+
 import os
 
 # Import local modules
 from photoshop import Session
 
-
 with Session(action="new_document") as ps:
     doc = ps.active_document
     doc.info.author = os.getenv("USERNAME")
     doc.info.provinceState = "Beijing"
     doc.info.title = "My Demo"
-    print("Print all metadata of current active document.")
+    ps.echo("Metadata of current active document:")
     ps.echo(doc.info)

examples/add_slate.py

@@ -8,31 +8,35 @@
 """
 
 # Import built-in modules
-from datetime import datetime
+from __future__ import annotations
+
 import os
+from datetime import datetime
 from tempfile import mkdtemp
+from pathlib import Path
+from datetime import timezone
 
 # Import third-party modules
 import examples._psd_files as psd  # Import from examples.
 
 # Import local modules
 from photoshop import Session
 
-
 PSD_FILE = psd.get_psd_files()
 slate_template = PSD_FILE["slate_template.psd"]
 with Session(slate_template, action="open", auto_close=True) as ps:
     layer_set = ps.active_document.layerSets.getByName("template")
 
     data = {
         "project name": "test_project",
-        "datetime": datetime.today().strftime("%Y-%m-%d"),
+        "datetime": datetime.now(tz=timezone.utc).strftime("%Y-%m-%d"),
     }
     for layer in layer_set.layers:
         if layer.kind == ps.LayerKind.TextLayer:
             layer.textItem.contents = data[layer.textItem.contents.strip()]
 
-    jpg_file = os.path.join(mkdtemp("photoshop-python-api"), "slate.jpg")
-    ps.active_document.saveAs(jpg_file, ps.JPEGSaveOptions())
-    print(f"Save jpg to {jpg_file}")
-    os.startfile(jpg_file)
+    jpg_file = Path(mkdtemp("photoshop-python-api")) / "slate.jpg"
+    ps.active_document.saveAs(str(jpg_file), ps.JPEGSaveOptions())
+    ps.echo(f"Save jpg to {jpg_file}")
+    # Note: os.startfile is Windows-specific, consider using a cross-platform solution
+    os.startfile(str(jpg_file))

examples/add_start_application_event.py

@@ -8,17 +8,18 @@
 """
 
 # Import built-in modules
+from __future__ import annotations
+
 import os
 from tempfile import mkdtemp
+from pathlib import Path
 
 # Import local modules
 from photoshop import Session
 
-
 with Session() as ps:
-    root = mkdtemp()
-    jsx_file = os.path.join(root, "event.jsx")
-    with open(jsx_file, "w") as f:
-        f.write('alert("Start Application event.")')
-    ps.app.notifiers.add(ps.EventID.Notify, jsx_file)
-    print("Add event done.")
+    root = Path(mkdtemp())
+    jsx_file = root / "event.jsx"
+    jsx_file.write_text('alert("Start Application event.")')
+    ps.app.notifiers.add(ps.EventID.Notify, str(jsx_file))
+    ps.echo("Add event done.")