chore: Update .gitignore and dependencies for better project management

Update .gitignore to include new example files directories and update dependencies with Poetry 1.8.5.

Signed-off-by: longhao <hal.long@outlook.com>

.github/workflows/code-check.yml

@@ -2,6 +2,11 @@ name: Code Quality Check
 
 on: [pull_request]
 
+# Add concurrency configuration
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   lint:
     runs-on: ubuntu-latest
@@ -27,9 +32,11 @@ jobs:
 
   test:
     runs-on: windows-latest
+    needs: lint  # Add dependency on lint job
     strategy:
       matrix:
         python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
+      fail-fast: false  # Continue with other versions if one fails
     steps:
     - uses: actions/checkout@v4
       with:

.github/workflows/python-publish.yml

@@ -5,6 +5,11 @@ on:
     tags:
       - "v*"
 
+# Add concurrency configuration
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   deploy:
     runs-on: ubuntu-latest

.gitignore

@@ -32,7 +32,11 @@ venv_python
 # Docs
 docs_src/_build/
 /run_pycharm.bat
-
-
-# windsurf rules
-.windsurfrules
+
+
+# windsurf rules
+.windsurfrules
+/examples/files/bg/
+/examples/files/blue/
+/examples/files/green/
+/examples/files/red/

docs/gen_examples.py

@@ -3,7 +3,6 @@
 # Import built-in modules
 from __future__ import annotations
 
-import os
 from pathlib import Path
 
 import mkdocs_gen_files

examples/_psd_files.py

@@ -1,7 +1,8 @@
 # Import built-in modules
 from __future__ import annotations
-from pathlib import Path
+
 import os
+from pathlib import Path
 
 
 def get_psd_files() -> dict[str, str]:

examples/active_layer.py

@@ -1,21 +1,48 @@
-# 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"
+"""Demonstrate how to work with active layers in Photoshop.
+
+This example shows how to:
+1. Create a new document if none exists
+2. Add new art layers to the document
+3. Get and set the active layer
+4. Rename layers
+
+Example:
+    ```python
+    with Session() as ps:
+        docRef = ps.app.documents.add()  # Create new document
+        new_layer = docRef.artLayers.add()  # Add new layer
+        new_layer.name = "test"  # Rename layer
+    ```
+
+Note:
+    The script will create a new document if none exists,
+    and will add a new layer if the document has less than 2 layers.
+"""
+
+# Import built-in modules
+from __future__ import annotations
+
+# Import local modules
+from photoshop import Session
+
+# Create a new Photoshop session
+with Session() as ps:
+    # Create a new document if none exists
+    if len(ps.app.documents) < 1:
+        docRef = ps.app.documents.add()
+    else:
+        docRef = ps.app.activeDocument
+
+    # Add a new layer if document has less than 2 layers
+    if len(docRef.layers) < 2:
+        docRef.artLayers.add()
+
+    # Print the name of the current active layer
+    ps.echo(docRef.activeLayer.name)
+
+    # Create a new art layer and make it active
+    new_layer = docRef.artLayers.add()
+    ps.echo(new_layer.name)
+
+    # Rename the new layer
+    new_layer.name = "test"

examples/add_metadata.py

@@ -1,4 +1,21 @@
-"""Add metadata to current active document."""
+"""Demonstrate how to add metadata to a Photoshop document.
+
+This example shows how to add and modify metadata properties of the active document,
+such as author, location, and title information.
+
+Example:
+    ```python
+    with Session(action="new_document") as ps:
+        doc = ps.active_document
+        doc.info.author = "John Doe"
+        doc.info.title = "My Project"
+    ```
+
+Note:
+    - The script automatically creates a new document using the Session action parameter
+    - The author is set to the current system username by default
+    - You can view metadata in Photoshop via: File > File Info
+"""
 
 # Import built-in modules
 from __future__ import annotations
@@ -8,10 +25,16 @@
 # Import local modules
 from photoshop import Session
 
+# Create a new Photoshop session and document
 with Session(action="new_document") as ps:
+    # Get reference to active document
     doc = ps.active_document
-    doc.info.author = os.getenv("USERNAME")
-    doc.info.provinceState = "Beijing"
-    doc.info.title = "My Demo"
+
+    # Set metadata properties
+    doc.info.author = os.getenv("USERNAME")  # Set author to system username
+    doc.info.provinceState = "Beijing"  # Set location information
+    doc.info.title = "My Demo"  # Set document title
+
+    # Print the metadata information
     ps.echo("Metadata of current active document:")
     ps.echo(doc.info)

examples/add_slate.py

@@ -1,42 +1,69 @@
-"""Add slate information dynamically.
+"""Demonstrate how to add and update slate information in a Photoshop template.
 
-- Open template.
-- Update info.
-- Save as jpg.
-- Close current document.
+This example shows how to:
+1. Open a PSD template file
+2. Update text layers with dynamic information
+3. Save the result as a JPG file
+4. Display the saved file
 
+The script uses a template PSD file that contains text layers within a layer set
+named "template". It updates specific text layers with dynamic content like
+project name and current date.
+
+Example:
+    ```python
+    with Session(template_file, action="open") as ps:
+        layer_set = ps.active_document.layerSets.getByName("template")
+        for layer in layer_set.layers:
+            if layer.kind == ps.LayerKind.TextLayer:
+                layer.textItem.contents = dynamic_data[layer.textItem.contents]
+    ```
+
+Note:
+    - Requires a PSD template file with text layers in a layer set named "template"
+    - Text layers should have placeholder text matching keys in the data dictionary
+    - The script uses os.startfile which is Windows-specific
 """
 
 # Import built-in modules
 from __future__ import annotations
 
 import os
-from datetime import datetime
-from tempfile import mkdtemp
+from datetime import datetime, timezone
 from pathlib import Path
-from datetime import timezone
+from tempfile import mkdtemp
 
 # Import third-party modules
 import examples._psd_files as psd  # Import from examples.
 
 # Import local modules
 from photoshop import Session
 
+# Get path to template PSD file
 PSD_FILE = psd.get_psd_files()
 slate_template = PSD_FILE["slate_template.psd"]
+
+# Open template file in Photoshop
 with Session(slate_template, action="open", auto_close=True) as ps:
+    # Get the layer set named "template"
     layer_set = ps.active_document.layerSets.getByName("template")
 
+    # Prepare dynamic data for text layers
     data = {
         "project name": "test_project",
         "datetime": datetime.now(tz=timezone.utc).strftime("%Y-%m-%d"),
     }
+
+    # Update text layers with dynamic content
     for layer in layer_set.layers:
         if layer.kind == ps.LayerKind.TextLayer:
             layer.textItem.contents = data[layer.textItem.contents.strip()]
 
+    # Save the document as JPG in a temporary directory
     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}")
+
+    # Open the saved JPG file (Windows-specific)
     # Note: os.startfile is Windows-specific, consider using a cross-platform solution
     os.startfile(str(jpg_file))

examples/add_start_application_event.py

@@ -1,25 +1,46 @@
 """Add event for Photoshop start application.
 
-In the current example, every time we start photoshop it will
-alert "Start Application Event".
+This example demonstrates how to add an event listener that triggers when Photoshop starts.
+Every time Photoshop is launched, it will display an alert message saying "Start Application Event".
 
-Just like you manually in Script> Script Events Manager to enable the event.
+This is equivalent to manually setting up an event in Photoshop through:
+File > Scripts > Script Events Manager
 
+Example:
+    ```python
+    with Session() as ps:
+        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))
+    ```
+
+Note:
+    The event will persist even after the script finishes running.
+    To remove the event, use the Script Events Manager in Photoshop.
 """
 
 # Import built-in modules
 from __future__ import annotations
 
-import os
-from tempfile import mkdtemp
 from pathlib import Path
+from tempfile import mkdtemp
 
 # Import local modules
 from photoshop import Session
 
+# Create a new Photoshop session
 with Session() as ps:
+    # Create a temporary directory to store the JSX script
     root = Path(mkdtemp())
     jsx_file = root / "event.jsx"
+
+    # Write the JavaScript code that will be executed when Photoshop starts
     jsx_file.write_text('alert("Start Application event.")')
+
+    # Add the event notifier to Photoshop
+    # EventID.Notify is triggered when Photoshop starts
     ps.app.notifiers.add(ps.EventID.Notify, str(jsx_file))
+
+    # Confirm the event was added successfully
     ps.echo("Add event done.")