[ci] ready to release v2.12.0

.github/workflows/build.yml

@@ -16,7 +16,7 @@ jobs:
       matrix:
         os: [ubuntu-22.04]
         python_version: [3.7, 3.8, 3.9, '3.10', '3.11', '3.12']
-        exiv2_version: [0.27.7]
+        exiv2_version: [0.28.1]
     runs-on: ${{matrix.os}}
     env:
       PLATFORM_NAME: linux
@@ -88,7 +88,7 @@ jobs:
       matrix:
         os: [macos-12]
         python_version: [3.6, 3.7, 3.8, 3.9, '3.10', '3.11', '3.12']
-        exiv2_version: [0.27.7]
+        exiv2_version: [0.28.1]
     runs-on: ${{matrix.os}}
     env:
       PLATFORM_NAME: darwin
@@ -150,6 +150,7 @@ jobs:
 
     - name: Test
       run: |
+        brew install inih
         python -m pytest -v
 
 
@@ -160,7 +161,7 @@ jobs:
       matrix:
         os: [windows-2019]
         python_version: [3.6, 3.7, 3.8, 3.9, '3.10', '3.11', '3.12']
-        exiv2_version: [0.27.7]
+        exiv2_version: [0.28.1]
     runs-on: ${{matrix.os}}
     env:
       PLATFORM_NAME: win

.github/workflows/test.yml

@@ -9,12 +9,34 @@ on:
   workflow_dispatch:
 
 jobs:
+
   job1:
+    name: Test on ubuntu
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-22.04]
+        python_version: [3.7, 3.8, 3.9, '3.10', '3.11', '3.12']
+    runs-on: ${{ matrix.os }}
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Python ${{ matrix.python_version }}
+      uses: actions/setup-python@v2
+      with:
+        python-version: ${{ matrix.python_version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install pytest psutil
+    - name: Test
+      run: |
+        pytest -v
+
+  job2:
     name: Test
     strategy:
       fail-fast: false
       matrix:
-        os: [macos-12, macos-13, windows-2019]
+        os: [macos-12, macos-13]
         python_version: [3.6, 3.7, 3.8, 3.9, '3.10', '3.11', '3.12']
     runs-on: ${{ matrix.os }}
     steps:
@@ -28,15 +50,16 @@ jobs:
         python -m pip install pytest psutil
     - name: Test
       run: |
+        brew install inih
         pytest -v
 
-  job2:
-    name: Test on ubuntu
+  job3:
+    name: Test
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-22.04]
-        python_version: [3.7, 3.8, 3.9, '3.10', '3.11', '3.12']
+        os: [windows-2019]
+        python_version: [3.6, 3.7, 3.8, 3.9, '3.10', '3.11', '3.12']
     runs-on: ${{ matrix.os }}
     steps:
     - uses: actions/checkout@v2

.github/workflows/test_package.yml

@@ -9,11 +9,11 @@ on:
 
 jobs:
   job1:
-    name: Test package
+    name: Test package on ubuntu
     strategy:
       fail-fast: false
       matrix:
-        os: [macos-12, macos-13, windows-2019]
+        os: [ubuntu-22.04]
         python_version: [3.7, 3.8, 3.9, '3.10', '3.11', '3.12']
     runs-on: ${{ matrix.os }}
     steps:
@@ -24,7 +24,7 @@ jobs:
         python-version: ${{ matrix.python_version }}
     - name: Install dependencies
       run: |
-        python -m pip install pyexiv2==2.11.0
+        python -m pip install pyexiv2==2.12.0
         python -m pip install pytest psutil
     - name: Test
       run: |
@@ -35,11 +35,38 @@ jobs:
         PYEXIV2_MODULE: pyexiv2
 
   job2:
-    name: Test package on ubuntu
+    name: Test package
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-22.04]
+        os: [macos-12, macos-13]
+        python_version: [3.7, 3.8, 3.9, '3.10', '3.11', '3.12']
+    runs-on: ${{ matrix.os }}
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Python ${{ matrix.python_version }}
+      uses: actions/setup-python@v2
+      with:
+        python-version: ${{ matrix.python_version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install pyexiv2==2.12.0
+        python -m pip install pytest psutil
+    - name: Test
+      run: |
+        brew install inih
+        python -c "import os; os.remove('pyexiv2/__init__.py')"    # Disable pyexiv2 in the repository, to use only the installed pyexiv2
+        python -c "from pyexiv2 import Image; print(Image.__doc__)"
+        pytest -v
+      env:
+        PYEXIV2_MODULE: pyexiv2
+
+  job3:
+    name: Test package
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [windows-2019]
         python_version: [3.7, 3.8, 3.9, '3.10', '3.11', '3.12']
     runs-on: ${{ matrix.os }}
     steps:
@@ -50,7 +77,7 @@ jobs:
         python-version: ${{ matrix.python_version }}
     - name: Install dependencies
       run: |
-        python -m pip install pyexiv2==2.11.0
+        python -m pip install pyexiv2==2.12.0
         python -m pip install pytest psutil
     - name: Test
       run: |

.gitmodules

@@ -1,4 +1,4 @@
 [submodule ".github/exiv2"]
 	path = .github/exiv2
 	url = https://github.com/Exiv2/exiv2.git
-  branch = v0.27.7
+  branch = v0.28.1

docs/Tutorial-cn.md

@@ -38,6 +38,12 @@
   ```
   - 这是因为 libintl.8.dylib 不存在。你需要执行 `brew install gettext` 。
 
+- 在 MacOS 上使用 pyexiv2 时，你可能遇到以下异常：
+  ```py
+  Library not loaded: '/usr/local/opt/inih/lib/libinih.0.dylib'
+  ```
+  - 这是因为 libinih.0.dylib 不存在。你需要执行 `brew install inih` 。
+
 - 在 Windows 上使用 pyexiv2 时，你可能遇到以下异常：
   ```py
   >>> import pyexiv2
@@ -81,6 +87,10 @@ class Image:
     def clear_icc       (self)
     def clear_thumbnail (self)
 
+    def copy_to_another_image(self, another_image,
+                              exif=True, iptc=True, xmp=True,
+                              comment=True, icc=True, thumbnail=True)
+
 
 class ImageData(Image):
     def __init__(self, data: bytes)
@@ -96,11 +106,11 @@ def convert_iptc_to_xmp(data: dict, encoding='utf-8') -> dict
 def convert_xmp_to_exif(data: dict, encoding='utf-8') -> dict
 def convert_xmp_to_iptc(data: dict, encoding='utf-8') -> dict
 
-__version__ = '...'
-__exiv2_version__ = '...'
+__version__ = '2.12.0'
+__exiv2_version__ = '0.28.1'
 ```
 
-## Class Image
+## class Image
 
 - 类 `Image` 用于根据文件路径打开图片。例如：
     ```py
@@ -118,7 +128,7 @@ __exiv2_version__ = '...'
     ```
   - 另一个例子：中国地区的 Windows 电脑通常用 GBK 编码文件路径，因此它们不能被 utf-8 解码。
 
-### close
+### close()
 
 - 当你处理完图片之后，请记得调用 `img.close()` ，以释放用于存储图片数据的内存。
   - 不调用该方法会导致内存泄漏，但不会锁定文件描述符。
@@ -128,7 +138,7 @@ __exiv2_version__ = '...'
         data = img.read_exif()
     ```
 
-### read
+### read_xx()
 
 - 读取元数据的示例:
     ```py
@@ -144,7 +154,7 @@ __exiv2_version__ = '...'
 - 调用 `Image.read_*()` 是安全的。这些方法永远不会影响图片文件（md5不变）。
 - 读取 XMP 元数据时，空白字符 `\v` 和 `\f` 会被替换为空格 ` ` 。
 
-### modify
+### modify_xx()
 
 - 修改元数据的示例:
     ```py
@@ -189,7 +199,7 @@ __exiv2_version__ = '...'
     ''
     ```
 
-### clear
+### clear_xx()
 
 - 调用 `img.clear_exif()` 将删除图片的所有 EXIF 元数据。一旦清除元数据，pyexiv2 可能无法完全恢复它。
 - `img.clear_iptc()` 和 `img.clear_xmp()` 的用法同理。
@@ -229,6 +239,30 @@ __exiv2_version__ = '...'
 - EXIF 标准允许在 JPEG 图片中嵌入缩略图，通常存储在 APP1 标签（FFE1）中。
 - Exiv2 支持读写图像中的 EXIF 缩略图。但是只能插入 JPEG 缩略图（不能插入TIFF）。
 
+### copy_xx()
+
+- 以下代码用于从一个图片拷贝元数据到另一个图片：
+  ```py
+  with pyexiv2.Image(r'.\pyexiv2\tests\1.jpg') as img1:
+      with pyexiv2.Image(r'.\pyexiv2\tests\2.jpg') as img2:
+          img2.modify_exif(img1.read_exif())
+          img2.modify_iptc(img1.read_iptc())
+          img2.modify_xmp(img1.read_xmp())
+  ```
+  但更推荐以下代码：
+  ```py
+  with pyexiv2.Image(r'.\pyexiv2\tests\1.jpg') as img1:
+      with pyexiv2.Image(r'.\pyexiv2\tests\2.jpg') as img2:
+          # 如果不想保留第二张图像中已有的元数据，可以提前清除第二张图像
+          # img2.clear_exif()
+          # img2.clear_iptc()
+          # img2.clear_xmp()
+          img1.copy_to_another_image(img2, exif=True, iptc=True, xmp=True, comment=False, icc=False, thumbnail=False)
+  ```
+  理由如下：
+  - 它的效率更高，因为不需要多次执行 modify_xx() 。
+  - 一张图片的元数据可能是错误的格式，无法被 pyexiv2 解析，但仍然可以复制到另一张图片上。
+
 ## class ImageData
 
 - 类 `ImageData` 继承于类 `Image`, 用于从字节数据中打开图片。
@@ -300,7 +334,7 @@ __exiv2_version__ = '...'
 
 ## convert
 
-- Exiv2 支持将某些 EXIF 或 IPTC 标签，转换成 XMP 标签，也支持反向转换。参考：<https://github.com/Exiv2/exiv2/blob/v0.27.7/src/convert.cpp#L313>
+- Exiv2 支持将某些 EXIF 或 IPTC 标签，转换成 XMP 标签，也支持反向转换。参考：<https://github.com/Exiv2/exiv2/blob/v0.28.1/src/convert.cpp#L313>
 - 示例：
     ```py
     >>> pyexiv2.convert_exif_to_xmp({'Exif.Image.Artist': 'test-中文-', 'Exif.Image.Rating': '4'})

docs/Tutorial.md

@@ -38,6 +38,12 @@ Language: [English](./Tutorial.md) | [中文](./Tutorial-cn.md)
   ```
   - This is because libintl.8.dylib is missing. You need to execute `brew install gettext` .
 
+- When using pyexiv2 on MacOS, you may encounter the following exception:
+  ```py
+  Library not loaded: '/usr/local/opt/inih/lib/libinih.0.dylib'
+  ```
+  - This is because libinih.0.dylib is missing. You need to execute `brew install inih` .
+1
 - When using pyexiv2 on Windows, you may encounter the following exception:
   ```py
   >>> import pyexiv2
@@ -81,6 +87,10 @@ class Image:
     def clear_icc       (self)
     def clear_thumbnail (self)
 
+    def copy_to_another_image(self, another_image,
+                              exif=True, iptc=True, xmp=True,
+                              comment=True, icc=True, thumbnail=True)
+
 
 class ImageData(Image):
     def __init__(self, data: bytes)
@@ -96,8 +106,8 @@ def convert_iptc_to_xmp(data: dict, encoding='utf-8') -> dict
 def convert_xmp_to_exif(data: dict, encoding='utf-8') -> dict
 def convert_xmp_to_iptc(data: dict, encoding='utf-8') -> dict
 
-__version__ = '...'
-__exiv2_version__ = '...'
+__version__ = '2.12.0'
+__exiv2_version__ = '0.28.1'
 ```
 
 ## class Image
@@ -118,7 +128,7 @@ __exiv2_version__ = '...'
     ```
   - Another example: Windows computers in China usually encoded file paths by GBK, so they cannot be decoded by utf-8.
 
-### close
+### close()
 
 - When you're done with the image, remember to call `img.close()` to free the memory for storing image data.
     - Not calling this method causes a memory leak, but it doesn't lock the file descriptor.
@@ -128,7 +138,7 @@ __exiv2_version__ = '...'
         data = img.read_exif()
     ```
 
-### read
+### read_xx()
 
 - An example of reading metadata:
     ```py
@@ -144,7 +154,7 @@ __exiv2_version__ = '...'
 - It is safe to call `Image.read_*()`. These methods never affect image files (md5 unchanged).
 - When reading XMP metadata, the whitespace characters `\v` and `\f` are replaced with the space ` `.
 
-### modify
+### modify_xx()
 
 - An example of modifing metadata:
     ```py
@@ -189,7 +199,7 @@ __exiv2_version__ = '...'
     ''
     ```
 
-### clear
+### clear_xx()
 
 - Calling `img.clear_exif()` will delete all EXIF metadata of the image. Once cleared, pyexiv2 may not be able to recover it completely.
 - Use `img.clear_iptc()` and `img.clear_xmp()` in the similar way.
@@ -229,6 +239,30 @@ __exiv2_version__ = '...'
 - The EXIF standard allows embedding thumbnails in a JPEG image, which is typically stored in the APP1 tag (FFE1).
 - Exiv2 supports reading and writing EXIF thumbnails in images. But only JPEG thumbnails can be inserted (not TIFF thumbnails).
 
+### copy_xx()
+
+- The following code is used to copy metadata from one image to another image:
+  ```py
+  with pyexiv2.Image(r'.\pyexiv2\tests\1.jpg') as img1:
+      with pyexiv2.Image(r'.\pyexiv2\tests\2.jpg') as img2:
+          img2.modify_exif(img1.read_exif())
+          img2.modify_iptc(img1.read_iptc())
+          img2.modify_xmp(img1.read_xmp())
+  ```
+  However, the following code is more recommended:
+  ```py
+  with pyexiv2.Image(r'.\pyexiv2\tests\1.jpg') as img1:
+      with pyexiv2.Image(r'.\pyexiv2\tests\2.jpg') as img2:
+          # If you don't want to keep the metadata already in the second image, you can clear the second image in advance.
+          # img2.clear_exif()
+          # img2.clear_iptc()
+          # img2.clear_xmp()
+          img1.copy_to_another_image(img2, exif=True, iptc=True, xmp=True, comment=False, icc=False, thumbnail=False)
+  ```
+  The reasons are as follows:
+  - It's more efficient because it doesn't require multiple executions of modify_xx() .
+  - The metadata of an image may be in the wrong format and cannot be parsed by pyexiv2, but it can still be copied to another image.
+
 ## class ImageData
 
 - Class `ImageData`, inherited from class `Image`, is used to open an image from bytes data.
@@ -300,7 +334,7 @@ __exiv2_version__ = '...'
 
 ## convert
 
-- Exiv2 supports converting some EXIF or IPTC tags to XMP tags, and also supports reverse conversion. Reference: <https://github.com/Exiv2/exiv2/blob/v0.27.7/src/convert.cpp#L313>
+- Exiv2 supports converting some EXIF or IPTC tags to XMP tags, and also supports reverse conversion. Reference: <https://github.com/Exiv2/exiv2/blob/v0.28.1/src/convert.cpp#L313>
 - For example:
     ```py
     >>> pyexiv2.convert_exif_to_xmp({'Exif.Image.Artist': 'test-中文-', 'Exif.Image.Rating': '4'})