format-img 0.1.0__tar.gz

format_img-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.DS_Store
+*.jpg
+*.JPG
+*.png
+*.PNG
+*jpeg
+*.pyc
+.venv/
+__pycache__
+dist/

format_img-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 Martin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

format_img-0.1.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: format-img
+Version: 0.1.0
+Summary: A python tool to format images based on EXIF information and edit EXIF data.
+License-File: LICENSE
+Requires-Python: >=3.8
+Requires-Dist: exif>=1.3.5
+Requires-Dist: exifread>=2.3.2
+Description-Content-Type: text/markdown
+
+# 图片名称格式化工具
+## 根据 EXIF 信息来格式化图片名字，方便管理
+
+## 环境与安装
+
+本工具使用 `uv` 管理依赖和运行环境。
+
+### 安装依赖并同步环境：
+```bash
+uv sync
+```
+
+---
+
+## 用法
+
+### 1. format-img
+
+格式化当前目录下的图片文件名。
+
+#### 基本用法
+```bash
+uv run format-img [-f format] [-s suffixs] [-h]
+```
+
+- `-f` 文件名的格式，默认值为 `%Y%m%d%H%M%S`。支持的占位符列表见下表。
+- `-s` 要格式化文件名的后缀名列表（以逗号分隔，不区分大小写），默认值为 `jpg,png,jpeg,heic`。例如 `-s "jpg,png"`。
+- `-h` 获取帮助信息。
+
+#### 支持的格式占位符：
+
+| 格式 | 含义 |
+|---|---|
+| %a | 本地（locale）简化星期名称 |
+| %A | 本地完整星期名称 |
+| %b | 本地简化月份名称 |
+| %B | 本地完整月份名称 |
+| %c | 本地相应的日期和时间表示 |
+| %d | 一个月中的第几天（01 - 31） |
+| %H | 一天中的第几个小时（24小时制，00 - 23） |
+| %I | 第几个小时（12小时制，01 - 12） |
+| %j | 一年中的第几天（001 - 366） |
+| %m | 月份（01 - 12） |
+| %M | 分钟数（00 - 59） |
+| %p | 本地am或者pm的相应符 |
+| %S | 秒（01 - 61） |
+| %U | 一年中的星期数（00 - 53，星期天为一个星期的开始） |
+| %w | 一个星期中的第几天（0 - 6，0是星期天） |
+| %W | 和 %U 基本相同，不同的是以星期一为一个星期的开始 |
+| %x | 本地相应日期 |
+| %X | 本地相应时间 |
+| %y | 去掉世纪的年份（00 - 99） |
+| %Y | 完整的年份 |
+| %Z | 时区的名字 |
+| %% | '%' 字符 |
+
+#### 示例
+把当前目录下的 `jpg` 和 `png` 文件的名称格式化成 `2017-10-01 10:17:01` 的形式：
+```bash
+uv run format-img -s "jpg,png" -f "%Y-%m-%d %H:%M:%S"
+```
+
+---
+
+### 2. modify-exif
+
+用于读取/修改图片的 EXIF 信息。
+
+#### 基本用法
+```bash
+# 读取属性详情
+uv run modify-exif -f file -r property [-s]
+
+# 读取拍摄时间与数字化时间（only output value if -s is set）
+uv run modify-exif -f file -rt [-s]
+
+# 写入指定属性
+uv run modify-exif -f file -w property -v value
+
+# 写入拍摄时间与数字化时间
+uv run modify-exif -f file -wt -v value
+
+# 查看帮助
+uv run modify-exif -h
+```
+
+具体示例可以参考 `scripts/update-datetime.ps1`，用于批量修改目标文件夹里面 `yyyyMMddHHmmss` 这样命名规则图片的 EXIF 时间信息。
+
+## 注意事项
+
+**跨路径调用**：如果要在其他路径（即不是项目根目录）下调用本工具，建议使用 `--project` 参数指定项目路径，例如：
+
+```powershell
+uv --project D:\Development\format-img run format-img
+```
+
+使用 `--project` 可以确保 `uv` 能够找到该项目的环境与依赖，同时**不会**改变当前的工作路径（cwd），从而正确地对你当前所在的命令行路径下的图片进行格式化操作。
+

format_img-0.1.0/README.md

@@ -0,0 +1,98 @@
+# 图片名称格式化工具
+## 根据 EXIF 信息来格式化图片名字，方便管理
+
+## 环境与安装
+
+本工具使用 `uv` 管理依赖和运行环境。
+
+### 安装依赖并同步环境：
+```bash
+uv sync
+```
+
+---
+
+## 用法
+
+### 1. format-img
+
+格式化当前目录下的图片文件名。
+
+#### 基本用法
+```bash
+uv run format-img [-f format] [-s suffixs] [-h]
+```
+
+- `-f` 文件名的格式，默认值为 `%Y%m%d%H%M%S`。支持的占位符列表见下表。
+- `-s` 要格式化文件名的后缀名列表（以逗号分隔，不区分大小写），默认值为 `jpg,png,jpeg,heic`。例如 `-s "jpg,png"`。
+- `-h` 获取帮助信息。
+
+#### 支持的格式占位符：
+
+| 格式 | 含义 |
+|---|---|
+| %a | 本地（locale）简化星期名称 |
+| %A | 本地完整星期名称 |
+| %b | 本地简化月份名称 |
+| %B | 本地完整月份名称 |
+| %c | 本地相应的日期和时间表示 |
+| %d | 一个月中的第几天（01 - 31） |
+| %H | 一天中的第几个小时（24小时制，00 - 23） |
+| %I | 第几个小时（12小时制，01 - 12） |
+| %j | 一年中的第几天（001 - 366） |
+| %m | 月份（01 - 12） |
+| %M | 分钟数（00 - 59） |
+| %p | 本地am或者pm的相应符 |
+| %S | 秒（01 - 61） |
+| %U | 一年中的星期数（00 - 53，星期天为一个星期的开始） |
+| %w | 一个星期中的第几天（0 - 6，0是星期天） |
+| %W | 和 %U 基本相同，不同的是以星期一为一个星期的开始 |
+| %x | 本地相应日期 |
+| %X | 本地相应时间 |
+| %y | 去掉世纪的年份（00 - 99） |
+| %Y | 完整的年份 |
+| %Z | 时区的名字 |
+| %% | '%' 字符 |
+
+#### 示例
+把当前目录下的 `jpg` 和 `png` 文件的名称格式化成 `2017-10-01 10:17:01` 的形式：
+```bash
+uv run format-img -s "jpg,png" -f "%Y-%m-%d %H:%M:%S"
+```
+
+---
+
+### 2. modify-exif
+
+用于读取/修改图片的 EXIF 信息。
+
+#### 基本用法
+```bash
+# 读取属性详情
+uv run modify-exif -f file -r property [-s]
+
+# 读取拍摄时间与数字化时间（only output value if -s is set）
+uv run modify-exif -f file -rt [-s]
+
+# 写入指定属性
+uv run modify-exif -f file -w property -v value
+
+# 写入拍摄时间与数字化时间
+uv run modify-exif -f file -wt -v value
+
+# 查看帮助
+uv run modify-exif -h
+```
+
+具体示例可以参考 `scripts/update-datetime.ps1`，用于批量修改目标文件夹里面 `yyyyMMddHHmmss` 这样命名规则图片的 EXIF 时间信息。
+
+## 注意事项
+
+**跨路径调用**：如果要在其他路径（即不是项目根目录）下调用本工具，建议使用 `--project` 参数指定项目路径，例如：
+
+```powershell
+uv --project D:\Development\format-img run format-img
+```
+
+使用 `--project` 可以确保 `uv` 能够找到该项目的环境与依赖，同时**不会**改变当前的工作路径（cwd），从而正确地对你当前所在的命令行路径下的图片进行格式化操作。
+

format_img-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "format-img"
+version = "0.1.0"
+description = "A python tool to format images based on EXIF information and edit EXIF data."
+readme = "README.md"
+requires-python = ">=3.8"
+dependencies = [
+    "exif>=1.3.5",
+    "exifread>=2.3.2",
+]
+
+[project.scripts]
+format-img = "format_img.format_img:main"
+modify-exif = "format_img.modify_exif:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/format_img"]

format_img-0.1.0/scripts/update-datetime.ps1

@@ -0,0 +1,53 @@
+<#
+.DESCRIPTION
+增加某个路径下的图片拍摄时间信息，文件名必须是 yyyyMMddHHmmss 这样的形式
+.PARAMETER Folder
+要查找的路径，默认是当前路径
+.PARAMETER Suffix
+要查找的文件后缀名，默认是 jpg
+.PARAMETER Recurse
+是否递归查找，默认不递归
+#>
+
+# Parameter
+[CmdletBinding()]
+param (
+    [Parameter(Position = 0)]
+    [string]$Folder = ".",
+    [Parameter(Position = 1)]
+    [string]$Suffix = "jpg",
+    [Parameter()]
+    [switch]$Recurse
+)
+
+$ProjectDir = (Resolve-Path "$PSScriptRoot\..").Path
+
+<#
+.DESCRIPTION
+传入 yyyyMMddHHmmss 形式的文件名返回 yyyy:MM:dd HH:mm:ss 这样的字符串
+#>
+function formatDatetime {
+
+    param (
+        [Parameter(Mandatory)]
+        [string]$fileName
+    )
+    return $($fileName.substring(0, 4) + ":" + $fileName.substring(4, 2) + ":" + $fileName.substring(6, 2) + " " + $fileName.substring(8, 2) + ":" + $fileName.substring(10, 2) + ":" + $fileName.substring(12, 2))
+    
+}
+
+if ($Recurse) {
+    $files = Get-ChildItem -LiteralPath $Folder -Recurse -Filter "*.${Suffix}"
+}
+else {
+    $files = Get-ChildItem -LiteralPath $Folder -Filter "*.${Suffix}"
+}
+foreach ( $f in $files) {
+    $v = $(uv run --project "$ProjectDir" modify-exif -f $f.FullName -rt -s)
+    if ($v.count -eq 0) {
+        $dateTime = $(formatDatetime $f.Name)
+        uv run --project "$ProjectDir" modify-exif -f $f.FullName -wt -v $dateTime
+    }
+}
+
+

format_img-0.1.0/src/format_img/__init__.py

@@ -0,0 +1 @@
+# format_img package

format_img-0.1.0/src/format_img/format_img.py

@@ -0,0 +1,84 @@
+"""
+格式化图片名称
+"""
+import sys
+import getopt
+import exifread
+import time
+import os
+from .my_utility import get_imgs, get_suffixes, get_format, get_file_suffix
+
+HELP = """
+format-img
+            [-f format]   default is '%Y%m%d%H%M%S'
+            [-s suffixs]  default is 'jpg,png,jpeg,heic'
+            -h            help
+"""
+
+
+def main():
+    """主入口函数"""
+    fmt = ''
+    suffixes = []
+    try:
+        options, args = getopt.getopt(sys.argv[1:], 'hs:f:')
+        for option, value in options:
+            if option == '-f':
+                fmt = value
+            elif option == '-s':
+                suffixes = value.split(',')
+            elif option == '-h':
+                print(HELP)
+                sys.exit(0)
+    except Exception as e:
+        sys.stderr.write(f"Error parsing options: {e}\n")
+        sys.exit(1)
+
+    if not fmt:
+        fmt = get_format()
+    if not suffixes:
+        suffixes = get_suffixes()
+
+    ok_cnt = 0
+    ng_cnt = 0
+    
+    for img in get_imgs(suffixes):
+        # 遍历出图片的EXIF时间或者文件创建时间并且按照格式重新命名文件
+        try:
+            with open(img, 'rb') as f_img:
+                tags = exifread.process_file(f_img, stop_tag='EXIF DateTimeOriginal')
+        except Exception as e:
+            sys.stderr.write(f"Failed to read EXIF from {img}: {e}\n")
+            ng_cnt += 1
+            continue
+
+        if 'EXIF DateTimeOriginal' in tags:
+            try:
+                img_time = time.strptime(str(tags['EXIF DateTimeOriginal']), "%Y:%m:%d %H:%M:%S")
+            except ValueError:
+                img_time = time.localtime(os.path.getmtime(img))
+        else:
+            img_time = time.localtime(os.path.getmtime(img))
+
+        # 重命名文件
+        i = 0
+        img_suffix = get_file_suffix(img)
+        img_new_name = time.strftime(fmt, img_time) + "." + img_suffix
+        while os.path.exists(img_new_name):
+            i += 1
+            img_new_name = time.strftime(fmt, img_time) + "_" + str(i) + "." + img_suffix
+        try:
+            os.rename(img, img_new_name)
+            print("%-25s\t→\t%-25s\tsuccess" % (img, img_new_name))
+            ok_cnt += 1
+        except Exception as e:
+            print("%-25s\t→\t%-25s\tfailed" % (img, img_new_name))
+            sys.stderr.write(f"Error: {e}\n")
+            ng_cnt += 1
+
+    # 输出统计信息
+    print("\nProcess completed\nSuccess: %d\nFailed: %d" % (ok_cnt, ng_cnt))
+
+
+if __name__ == '__main__':
+    main()

format_img-0.1.0/src/format_img/modify_exif.py

@@ -0,0 +1,93 @@
+"""
+编辑图片的EXIF信息
+"""
+import sys
+import getopt
+from .my_utility import get_file_exif, set_file_exif
+
+HELP = """
+modify-exif 
+              -f file -r property [-s]         read property, only output value if s is set
+              -f file -rt [-s]                 read datetime_original and datetime_digitized, only output value if s is set
+              -f file -w property -v value     write property
+              -f file -wt -v value             write datetime_original and datetime_digitized
+              -h                               help
+"""
+
+
+def read_property(filename, property_name, simple_out=False):
+    """读取属性并打印详情"""
+    value = get_file_exif(filename, property_name)
+    if simple_out:
+        if value != "":
+            print(value)
+    else:
+        print(f"read {property_name} from {filename}")
+        print(f"value is {value}")
+
+
+def write_property(filename, property_name, value):
+    """写入属性并打印详情"""
+    print(f"write '{property_name}={value}' to {filename}")
+    set_file_exif(filename, property_name, value)
+
+
+def main():
+    """主入口函数"""
+    process_file = ""
+    process_mode = ""
+    process_property = ""
+    process_value = ""
+    simple_out = False
+
+    try:
+        options, args = getopt.getopt(sys.argv[1:], 'hf:r:w::v:s')
+        for option, value in options:
+            if option == '-f':
+                process_file = value
+            elif option == '-r':
+                process_mode = "r"
+                process_property = value
+            elif option == '-w':
+                process_mode = "w"
+                process_property = value
+            elif option == '-v':
+                process_value = value
+            elif option == '-s':
+                simple_out = True
+            elif option == '-h':
+                print(HELP)
+                sys.exit(0)
+
+        if process_file == "":
+            raise Exception("file is empty")
+        if process_mode == "":
+            raise Exception("r or w flag is necessary")
+        if process_property == "":
+            raise Exception("property is necessary")
+        if process_mode == "w" and process_value == "":
+            raise Exception("value is necessary")
+    except Exception as e:
+        sys.stderr.write("".join(e.args) + "\n")
+        sys.exit(1)
+
+    try:
+        if process_mode == 'r':
+            if process_property == "t":
+                read_property(process_file, "datetime_original", simple_out)
+                read_property(process_file, "datetime_digitized", simple_out)
+            else:
+                read_property(process_file, process_property, simple_out)
+        else:
+            if process_property == "t":
+                write_property(process_file, "datetime_original", process_value)
+                write_property(process_file, "datetime_digitized", process_value)
+            else:
+                write_property(process_file, process_property, process_value)
+    except Exception as e:
+        sys.stderr.write("".join(e.args) + "\n")
+        sys.exit(1)
+
+
+if __name__ == '__main__':
+    main()

format_img-0.1.0/src/format_img/my_utility.py

@@ -0,0 +1,75 @@
+"""
+自定义工具集
+"""
+from datetime import datetime
+import os
+import re
+from exif import Image, DATETIME_STR_FORMAT
+
+
+def get_imgs(suffixs=None):
+    """获取指定后缀的图片文件名"""
+    if suffixs is None:
+        suffixs = get_suffixes()
+    
+    # 构造匹配表达式
+    img_pattern = '$|.*\\.'.join(suffixs)
+    if img_pattern != "":
+        img_pattern += '$'
+        img_pattern = '.*\\.' + img_pattern
+    
+    try:
+        dirs = os.listdir('.')
+    except Exception:
+        dirs = []
+        
+    imgs = []
+    for img in dirs:
+        if re.match(img_pattern, img, re.I):
+            imgs.append(img)
+    return imgs
+
+
+def get_suffixes():
+    """获取默认的文件后缀"""
+    return ['jpg', 'png', 'jpeg', 'heic']
+
+
+def get_format():
+    """获取默认的命名格式"""
+    return '%Y%m%d%H%M%S'
+
+
+def get_file_suffix(filename=''):
+    """获取文件后缀"""
+    if filename != '':
+        tmp = filename.split('.')
+        if len(tmp) > 0:
+            return tmp.pop()
+    return ''
+
+
+def get_file_exif(filename='', property=''):
+    """获取指定文件的EXIF信息，默认获取所有信息"""
+    image = Image(filename)
+    if not image.has_exif:
+        return ""
+    if property == "":
+        return image.list_all()
+    else:
+        return image.get(property, "")
+
+
+def set_file_exif(filename='', property='datetime_original', value=''):
+    """设定指定文件的EXIF信息，默认设置datetime_original为当前时间"""
+    image = Image(filename)
+    if value == '':
+        value = datetime.now().strftime(DATETIME_STR_FORMAT)
+    image.set(property, value)
+    with open(filename, 'wb') as f:
+        f.write(image.get_file())
+
+
+if __name__ == '__main__':
+    # 模块测试
+    pass

format_img-0.1.0/uv.lock

@@ -0,0 +1,48 @@
+version = 1
+revision = 3
+requires-python = ">=3.8"
+
+[[package]]
+name = "exif"
+version = "1.6.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "plum-py" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/52/21/34c46fbda54648afdcc66f0eec0ac91675361017abcdcdd23bd88fa74cc5/exif-1.6.1.tar.gz", hash = "sha256:763599b89b9b67495713060a703f32d1874abf8f0628c9d77711c2c06a5f44c8", size = 24052, upload-time = "2024-12-10T04:38:35.812Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/67/07/a47a78be02b0a2d273358312f3e2eecc4981d4604f8a6e6b8ef27c1e9c2d/exif-1.6.1-py3-none-any.whl", hash = "sha256:2879830e2d8f0e5f1503110736bceb83a1e9c2121b32c23208c04284be5afbec", size = 30461, upload-time = "2024-12-10T04:38:33.547Z" },
+]
+
+[[package]]
+name = "exifread"
+version = "3.5.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/e2/4e/d8fce8810d819db47f5b159e75223511c5ccd7ad07c2feca64cf7fab2477/exifread-3.5.1.tar.gz", hash = "sha256:9f998f80d3062741c976dfc4fd033424bc40932937994e4d2181eb70c4b6aedd", size = 56552, upload-time = "2025-08-23T21:59:18.123Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/e2/a3/20e34a55c7b225110d3822d07c3cab9e8653d9c179e36783f2ed632a96a7/exifread-3.5.1-py3-none-any.whl", hash = "sha256:e5426ce2857423ad401e575ea9d159dc97449dc041fb6e61b35109caea72c311", size = 59742, upload-time = "2025-08-23T21:59:16.633Z" },
+]
+
+[[package]]
+name = "format-img"
+version = "0.1.0"
+source = { editable = "." }
+dependencies = [
+    { name = "exif" },
+    { name = "exifread" },
+]
+
+[package.metadata]
+requires-dist = [
+    { name = "exif", specifier = ">=1.3.5" },
+    { name = "exifread", specifier = ">=2.3.2" },
+]
+
+[[package]]
+name = "plum-py"
+version = "0.8.7"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/3a/2a/a650b0cde5a15f4a9375df43bd7eacaffb65b30c8395b6b6cd84df2bf7ae/plum-py-0.8.7.tar.gz", hash = "sha256:40a25a70f7fd213f57cdd1decc65874df2d213d19d63478a1addcca748c13c4e", size = 116231, upload-time = "2024-05-12T02:01:48.18Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/2f/da/8a9bdf5d3ea4b13d3142e0c77d6e85e4c2668aef6e4b9d5e9a6619049bdc/plum_py-0.8.7-py3-none-any.whl", hash = "sha256:d791f059ef159adbe3c3b036557b5b431fa07db226a9de106a74e5e57441741d", size = 69991, upload-time = "2023-08-14T21:56:31.953Z" },
+]