Expand type annotations and add classes for path item handling

.github/workflows/import-test.yml

@@ -1,9 +1,11 @@
 name: Import Test
-on: [pull_request]
+on:
+  pull_request:
+  workflow_dispatch:
 
 jobs:
   python-check:
-    runs-on: windows-2022
+    runs-on: windows-latest
     strategy:
       max-parallel: 3
       matrix:
@@ -14,12 +16,12 @@ jobs:
       with:
         fetch-depth: 0
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v6
       with:
         python-version: ${{ matrix.python-version }}
     - name: Install dependencies
       run: |
-        python -m pip install -U pip poetry
-        poetry --version
-        poetry install -vvv || poetry install -vvv || poetry install -vvv
-        poetry run pytest
+        python -m pip install poetry
+        python -m poetry --version
+        python -m poetry install -vvv
+        python -m poetry run pytest

.github/workflows/pythonpackage.yml

@@ -28,14 +28,5 @@ jobs:
 
     - name: Run tests and linters
       run: |
-        #!/bin/sh -e
-        git config --global user.email "action@github.com"
-        git config --global user.name "GitHub Action"
-        export PREFIX="poetry run python -m "
-        if [ -d 'venv' ] ; then
-            export PREFIX="venv/bin/"
-        fi
-
-        ${PREFIX}black photoshop --check
-        ${PREFIX}isort --check-only photoshop
-        ruff check photoshop
+        poetry run ruff check photoshop
+        poetry run ruff format --check photoshop

.gitignore

@@ -19,6 +19,7 @@ result/
 .coverage
 /venv/
 venv_python
+.venv/
 
 # Docs
 docs_src/_build/

.pre-commit-config.yaml

@@ -1,11 +1,14 @@
 exclude: conf.py
 repos:
--   repo: https://github.com/ambv/black
-    rev: 22.12.0
+-   repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.9
+    hooks:
+    -   id: ruff-check
+        args: [--fix]
+    -   id: ruff-format
+-   repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
     hooks:
-    -   id: black
-        language_version: python3.10
--   hooks:
     -   id: trailing-whitespace
     -   id: end-of-file-fixer
     -   id: check-docstring-first
@@ -14,43 +17,13 @@ repos:
     -   id: debug-statements
     -   id: name-tests-test
     -   id: requirements-txt-fixer
-    repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v2.4.0
--   hooks:
-    -   additional_dependencies:
-        - flake8-typing-imports==1.5.0
-        id: flake8
-    repo: https://github.com/pycqa/flake8
-    rev: 3.7.9
--   hooks:
-    -   id: autopep8
-    repo: https://github.com/pre-commit/mirrors-autopep8
-    rev: v1.4.4
--   hooks:
+-   repo: https://github.com/pre-commit/pre-commit
+    rev: v4.6.0
+    hooks:
     -   id: validate_manifest
-    repo: https://github.com/pre-commit/pre-commit
-    rev: v1.21.0
--   hooks:
-    -   args:
-        - --py36-plus
-        id: pyupgrade
-    repo: https://github.com/asottile/pyupgrade
-    rev: v1.25.3
--   hooks:
-    -   args:
-        - --py3-plus
-        id: reorder-python-imports
-    repo: https://github.com/asottile/reorder_python_imports
-    rev: v1.9.0
--   hooks:
-    -   args:
-        - --py36-plus
-        id: add-trailing-comma
-    repo: https://github.com/asottile/add-trailing-comma
-    rev: v1.5.0
--   hooks:
+-   repo: https://github.com/commitizen-tools/commitizen
+    rev: v4.16.3
+    hooks:
     -   id: commitizen
         stages:
         - commit-msg
-    repo: https://github.com/commitizen-tools/commitizen
-    rev: v2.17.8

README.md

@@ -207,6 +207,7 @@ Useful links
 - http://shining-lucy.com/wiki/page.php?id=appwiki:photoshop:ps_script
 - http://web.archive.org/web/20140121053819/http://www.pcpix.com/Photoshop/char.html
 - http://www.tonton-pixel.com/scripts/utility-scripts/get-equivalent-id-code/index.html
+- https://github.com/Adobe-CEP/CEP-Resources/tree/master/Documentation/Product%20specific%20Documentation/Photoshop%20Scripting
 - https://github.com/Adobe-CEP/Samples/tree/master/PhotoshopEvents
 - https://evanmccall.wordpress.com/2015/03/09/how-to-develop-photoshop-tools-in-python
 
@@ -242,9 +243,7 @@ We maintain high code quality standards through automated tools and consistent s
   - Quotes: Double quotes preferred
 
 - **Quality Tools**:
-  - [Black](https://black.readthedocs.io/) - Code formatting
-  - [isort](https://pycqa.github.io/isort/) - Import organization
-  - [flake8](https://flake8.pycqa.org/) - Style enforcement
+  - [Ruff](https://docs.astral.sh/ruff/) - Linting, formatting, and import organization
   - [pre-commit](https://pre-commit.com/) - Automated checks before commits
 
 ### 🔄 Git Workflow
@@ -279,7 +278,7 @@ We value thorough testing to ensure reliability:
 
 ### 📦 Development Environment
 
-- **Python Versions**: We support Python 3.8+ (see `pyproject.toml` for specifics)
+- **Python Versions**: We support Python 3.10+ (see `pyproject.toml` for specifics)
 - **Dependency Management**: [Poetry](https://python-poetry.org/) for consistent environments
 - **Virtual Environment**: Poetry automatically creates and manages virtual environments
 
@@ -295,3 +294,18 @@ We value thorough testing to ensure reliability:
 8. **Merge**: Once approved, your PR will be merged
 
 Thank you for contributing to the Photoshop Python API project! 🎉
+
+### Development Notes
+
+One way to view the COM API structure is to use Visual Studio.
+
+1. Install Visual Studio with the .NET desktop development workload
+2. Open Visual Studio
+3. Choose View -> Object Browser
+4. In the Object Browser from the Browse dropdown choose *Edit Custom Component Set...*
+5. In the Edit Custom Component Set window's COM tab add Photoshop's Object and Type libraries
+6. After pressing OK the libraries should show up in the Object Browser
+
+If the libraries aren't visible in the COM tab make sure you have the .NET desktop development workload installed. Other things you may try are running Photoshop once as administrator and reinstalling Photoshop and/or your PC. The object library is defined usually in */your/path/to/Adobe Photoshop \<version\>/Required/Plug-ins/Extensions/ScriptingSupport.8li*
+
+The [VBS reference 2020](https://github.com/Adobe-CEP/CEP-Resources/blob/master/Documentation/Product%20specific%20Documentation/Photoshop%20Scripting/photoshop-vbs-ref-2020.pdf) is also quite trustworthy, since Adobe isn't actively developing the COM API anymore.

docs/gen_api_nav.py

@@ -1,5 +1,7 @@
 """Plugin for generate API docs."""
 
+from __future__ import annotations
+
 # Import built-in modules
 from pathlib import Path
 
@@ -29,7 +31,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,18 @@
 """Plugin for generate API docs."""
 
+from __future__ import annotations
+
 # Import built-in modules
 import os
+
 from pathlib import Path
 
 # Import third-party modules
-from jinja2 import Template
 import mkdocs_gen_files
 import stringcase
 
+from jinja2 import Template
+
 
 template = Template(
     r"""

examples/active_layer.py

@@ -12,6 +12,8 @@
 - Create a new layer and rename it
 """
 
+
+from __future__ import annotations
 # Import local modules
 from photoshop import Session
 
@@ -28,9 +30,9 @@
         docRef.artLayers.add()
 
     # Display current active layer name
-    ps.echo(docRef.activeLayer.name)
+    print(docRef.activeLayer.name)
 
     # Create and rename a new layer
     new_layer = docRef.artLayers.add()
-    ps.echo(new_layer.name)
+    print(new_layer.name)
     new_layer.name = "test"

examples/add_metadata.py

@@ -1,5 +1,7 @@
 """Add metadata to current active document."""
 
+
+from __future__ import annotations
 # Import built-in modules
 import os
 
@@ -13,4 +15,4 @@
     doc.info.provinceState = "Beijing"
     doc.info.title = "My Demo"
     print("Print all metadata of current active document.")
-    ps.echo(doc.info)
+    print(doc.info)

examples/add_slate.py

@@ -7,15 +7,17 @@
 
 """
 
+
+from __future__ import annotations
 # Import built-in modules
-from datetime import datetime
 import os
+
+from datetime import datetime
 from tempfile import mkdtemp
 
-# Import third-party modules
+# Import local modules
 import examples._psd_files as psd  # Import from examples.
 
-# Import local modules
 from photoshop import Session
 
 

examples/add_start_application_event.py

@@ -7,8 +7,11 @@
 
 """
 
+
+from __future__ import annotations
 # Import built-in modules
 import os
+
 from tempfile import mkdtemp
 
 # Import local modules

examples/apply_crystallize_filter_action.py

@@ -9,10 +9,11 @@
 
 """
 
-# Import third-party modules
-import examples._psd_files as psd  # Import from examples.
 
+from __future__ import annotations
 # Import local modules
+import examples._psd_files as psd  # Import from examples.
+
 from photoshop import Session
 
 

examples/change_color_of_background_and_foreground.py

@@ -13,6 +13,8 @@
 - Default colors
 """
 
+
+from __future__ import annotations
 # Import local modules
 from photoshop import Session
 
@@ -34,10 +36,10 @@
     ps.app.backgroundColor = bg_color
 
     # Print current colors
-    ps.echo(f"Foreground RGB: {ps.app.foregroundColor.rgb.red}, "
+    print(f"Foreground RGB: {ps.app.foregroundColor.rgb.red}, "
             f"{ps.app.foregroundColor.rgb.green}, "
             f"{ps.app.foregroundColor.rgb.blue}")
 
-    ps.echo(f"Background RGB: {ps.app.backgroundColor.rgb.red}, "
+    print(f"Background RGB: {ps.app.backgroundColor.rgb.red}, "
             f"{ps.app.backgroundColor.rgb.green}, "
             f"{ps.app.backgroundColor.rgb.blue}")

examples/compare_colors.py

@@ -13,6 +13,8 @@
 - Color model differences
 """
 
+
+from __future__ import annotations
 # Import local modules
 from photoshop import Session
 
@@ -34,4 +36,4 @@
                color1.rgb.green == color2.rgb.green and
                color1.rgb.blue == color2.rgb.blue)
 
-    ps.echo(f"Colors are {'same' if is_same else 'different'}")
+    print(f"Colors are {'same' if is_same else 'different'}")

examples/convert_smartobject_to_layer.py

@@ -13,6 +13,8 @@
 - Layer types
 """
 
+
+from __future__ import annotations
 # Import local modules
 from photoshop import Session
 
@@ -26,12 +28,12 @@
 
     # Convert to smart object
     layer.convertToSmartObject()
-    ps.echo("Layer converted to Smart Object")
+    print("Layer converted to Smart Object")
 
     # Check if it's a smart object
     if layer.kind == ps.LayerKind.SmartObjectLayer:
-        ps.echo("Layer is now a Smart Object")
+        print("Layer is now a Smart Object")
 
         # Convert back to regular layer
         layer.rasterize(ps.RasterizeType.EntireLayer)
-        ps.echo("Smart Object converted back to regular layer")
+        print("Smart Object converted back to regular layer")

examples/create_thumbnail.py

@@ -4,8 +4,11 @@
 
 """
 
+
+from __future__ import annotations
 # Import built-in modules
 import os
+
 from tempfile import mkdtemp
 
 # Import local modules

examples/current_tool.py

@@ -13,6 +13,8 @@
 - Active tool state
 """
 
+
+from __future__ import annotations
 # Import local modules
 from photoshop import Session
 
@@ -22,4 +24,4 @@
     current = ps.app.currentTool
 
     # Print current tool name
-    ps.echo(f"Current tool: {current}")
+    print(f"Current tool: {current}")