xigua 0.1.3__tar.gz

xigua-0.1.3/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: xigua
+Version: 0.1.3
+Summary: 西瓜小工具集 — 各类实用小功能
+Author-email: xigua <2587125111@qq.com>
+License: Copyright © 2024 xigua Authors. All Rights Reserve.
+Project-URL: Homepage, https://pypi.org/project/xigua
+Keywords: utilities,tools,metadata,exif,ffprobe,media
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: Pillow>=9.0.0
+Requires-Dist: PyYAML<7.0,>=6.0
+Provides-Extra: heif
+Requires-Dist: pillow-heif>=0.10.0; extra == "heif"
+
+# xigua — 小工具集
+
+各类实用小功能，按模块组织，持续扩展。
+
+## 已包含模块
+
+### media — 本地图片/视频元数据
+
+读取本地图片或视频的全部元数据（中文键名输出）。
+
+```python
+from xigua.media import MediaMetadataService
+
+# 读取为字典
+data = MediaMetadataService.read("/path/to/photo.jpg")
+
+# 直接格式化输出
+print(MediaMetadataService.format_file("/path/to/clip.mp4", fmt="text"))
+print(MediaMetadataService.format_file("/path/to/clip.mp4", fmt="yaml", include_md5=False))
+```
+
+命令行：
+
+```bash
+xigua-media /path/to/photo.jpg
+xigua-media /path/to/clip.mp4 --fmt text --no-md5
+```
+
+**依赖说明：**
+- 图片：Pillow（HEIC/HEIF 需 `pip install xigua[heif]`）
+- 视频：系统需安装 `ffprobe`
+
+## 安装
+
+```bash
+pip install xigua
+pip install xigua[heif]   # 支持 HEIC/HEIF
+```
+
+## 发布
+
+```bash
+cd /Users/xigua/pypi-publish
+./publish xigua --bump patch
+```

xigua-0.1.3/README.md

@@ -0,0 +1,45 @@
+# xigua — 小工具集
+
+各类实用小功能，按模块组织，持续扩展。
+
+## 已包含模块
+
+### media — 本地图片/视频元数据
+
+读取本地图片或视频的全部元数据（中文键名输出）。
+
+```python
+from xigua.media import MediaMetadataService
+
+# 读取为字典
+data = MediaMetadataService.read("/path/to/photo.jpg")
+
+# 直接格式化输出
+print(MediaMetadataService.format_file("/path/to/clip.mp4", fmt="text"))
+print(MediaMetadataService.format_file("/path/to/clip.mp4", fmt="yaml", include_md5=False))
+```
+
+命令行：
+
+```bash
+xigua-media /path/to/photo.jpg
+xigua-media /path/to/clip.mp4 --fmt text --no-md5
+```
+
+**依赖说明：**
+- 图片：Pillow（HEIC/HEIF 需 `pip install xigua[heif]`）
+- 视频：系统需安装 `ffprobe`
+
+## 安装
+
+```bash
+pip install xigua
+pip install xigua[heif]   # 支持 HEIC/HEIF
+```
+
+## 发布
+
+```bash
+cd /Users/xigua/pypi-publish
+./publish xigua --bump patch
+```

xigua-0.1.3/license.txt

@@ -0,0 +1 @@
+Copyright © 2024 xigua Authors. All Rights Reserve.

xigua-0.1.3/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "xigua"
+dynamic = ["version"]
+description = "西瓜小工具集 — 各类实用小功能"
+authors = [
+    {name = "xigua", email = "2587125111@qq.com"}
+]
+readme = "README.md"
+license = {file = "license.txt"}
+requires-python = ">=3.10"
+keywords = ["utilities", "tools", "metadata", "exif", "ffprobe", "media"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Multimedia",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "Pillow>=9.0.0",
+    "PyYAML>=6.0,<7.0",
+]
+
+[project.optional-dependencies]
+heif = ["pillow-heif>=0.10.0"]
+
+[project.scripts]
+xigua-media = "xigua.media.cli:main"
+
+[project.urls]
+"Homepage" = "https://pypi.org/project/xigua"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["xigua", "xigua.*"]
+
+[tool.setuptools.dynamic]
+version = {attr = "xigua.__version__.VERSION"}

xigua-0.1.3/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

xigua-0.1.3/xigua/__init__.py

@@ -0,0 +1,5 @@
+"""西瓜小工具集。"""
+
+from xigua.__version__ import VERSION
+
+__all__ = ["VERSION"]

xigua-0.1.3/xigua/__version__.py

@@ -0,0 +1 @@
+VERSION = '0.1.3'

xigua-0.1.3/xigua/_util.py

@@ -0,0 +1,12 @@
+"""通用小工具。"""
+
+from __future__ import annotations
+
+
+def fmt_size(n: float) -> str:
+    """字节数 → 易读字符串，如 12.3 MB。"""
+    for unit in ("B", "KB", "MB", "GB", "TB"):
+        if abs(n) < 1024:
+            return f"{n:.1f} {unit}"
+        n /= 1024
+    return f"{n:.1f} PB"

xigua-0.1.3/xigua/geo/__init__.py

@@ -0,0 +1,3 @@
+from xigua.geo.reverse import lookup_geo
+
+__all__ = ["lookup_geo"]

xigua-0.1.3/xigua/geo/reverse.py

@@ -0,0 +1,118 @@
+"""经纬度逆地理编码（内存缓存 + 在线查询）。"""
+
+from __future__ import annotations
+
+import json
+import threading
+import time
+import urllib.error
+import urllib.request
+
+_GEO_CACHE: dict[str, str] = {}
+_GEO_LOCK = threading.Lock()
+
+_NOM_LAST_CALL = 0.0
+_NOM_INTERVAL = 1.1
+_NOM_LOCK = threading.Lock()
+
+
+def _cache_key(lat: float, lng: float) -> str:
+    return f"{lat:.2f}:{lng:.2f}"
+
+
+def _fmt_cn(province: str, city: str) -> str:
+    province = (
+        province.replace("省", "")
+        .replace("自治区", "")
+        .replace("特别行政区", "")
+        .replace("维吾尔", "")
+        .replace("壮族", "")
+        .replace("回族", "")
+        .strip()
+    )
+    city = city.replace("市", "").strip()
+    if province and city and province != city:
+        return f"{province}·{city}"
+    return province or city
+
+
+def _fmt_abroad(country: str, city: str) -> str:
+    city = city.replace("市", "").strip()
+    if country and city and country != city:
+        return f"{country}·{city}"
+    return country or city
+
+
+def _nominatim_lookup(lat: float, lng: float) -> str:
+    with _NOM_LOCK:
+        global _NOM_LAST_CALL
+        now = time.monotonic()
+        wait = _NOM_INTERVAL - (now - _NOM_LAST_CALL)
+        if wait > 0:
+            time.sleep(wait)
+        _NOM_LAST_CALL = time.monotonic()
+
+    url = (
+        f"https://nominatim.openstreetmap.org/reverse"
+        f"?lat={lat:.7f}&lon={lng:.7f}&format=json&accept-language=zh-CN&zoom=10"
+    )
+    try:
+        req = urllib.request.Request(
+            url,
+            headers={"User-Agent": "xigua-tools/1.0 (media-metadata)"},
+        )
+        with urllib.request.urlopen(req, timeout=12) as resp:
+            r = json.loads(resp.read())
+        addr = r.get("address") or {}
+        country_code = addr.get("country_code", "").upper()
+        province = (addr.get("state") or addr.get("province") or "").strip()
+        city = (
+            addr.get("city") or addr.get("county") or addr.get("town")
+            or addr.get("village") or ""
+        ).strip()
+        country = (addr.get("country") or "").strip()
+        if country_code == "CN":
+            return _fmt_cn(province, city) or country
+        return _fmt_abroad(country, city)
+    except Exception:
+        return ""
+
+
+def _bigdata_lookup(lat: float, lng: float) -> str:
+    url = (
+        f"https://api.bigdatacloud.net/data/reverse-geocode-client"
+        f"?latitude={lat:.7f}&longitude={lng:.7f}&localityLanguage=zh"
+    )
+    try:
+        req = urllib.request.Request(url, headers={"User-Agent": "Mozilla/5.0"})
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            r = json.loads(resp.read())
+        country_code = (r.get("countryCode") or "").upper()
+        province = (r.get("principalSubdivision") or "").strip()
+        city = (r.get("city") or r.get("locality") or "").strip()
+        country = (r.get("countryName") or "").strip()
+        if country_code == "CN":
+            return _fmt_cn(province, city) or country
+        return _fmt_abroad(country, city)
+    except Exception:
+        return ""
+
+
+def lookup_geo(lat: float | None, lng: float | None) -> str | None:
+    """将经纬度转换为「省·市」格式的地区标签。"""
+    if lat is None or lng is None:
+        return None
+    try:
+        lat, lng = float(lat), float(lng)
+    except (TypeError, ValueError):
+        return None
+
+    ck = _cache_key(lat, lng)
+    with _GEO_LOCK:
+        if ck in _GEO_CACHE:
+            return _GEO_CACHE[ck] or None
+
+    label = _nominatim_lookup(lat, lng) or _bigdata_lookup(lat, lng)
+    with _GEO_LOCK:
+        _GEO_CACHE[ck] = label
+    return label or None

xigua-0.1.3/xigua/media/__init__.py

@@ -0,0 +1,3 @@
+from xigua.media.metadata import MediaMetadataService
+
+__all__ = ["MediaMetadataService"]

xigua-0.1.3/xigua/media/cli.py

@@ -0,0 +1,43 @@
+"""命令行：读取本地图片/视频元数据。"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from xigua.media.metadata import MediaMetadataService
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="读取本地图片/视频全部元数据")
+    parser.add_argument("path", help="本地文件路径")
+    parser.add_argument(
+        "--fmt", default="json", choices=sorted(MediaMetadataService.FORMATS),
+        help="输出格式（默认 json）",
+    )
+    parser.add_argument("--no-md5", action="store_true", help="不计算 MD5")
+    parser.add_argument("--no-geo", action="store_true", help="不进行 GPS 逆地理编码")
+    parser.add_argument("--full-raw", action="store_true", help="text 格式下展开原始 EXIF/ffprobe")
+    args = parser.parse_args(argv)
+
+    try:
+        text = MediaMetadataService.format_file(
+            args.path,
+            fmt=args.fmt,
+            include_md5=not args.no_md5,
+            include_geo=not args.no_geo,
+            text_full_raw=args.full_raw,
+        )
+    except FileNotFoundError:
+        print(f"文件不存在: {args.path}", file=sys.stderr)
+        return 1
+    except Exception as e:
+        print(f"错误: {e}", file=sys.stderr)
+        return 1
+
+    print(text)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

xigua-0.1.3/xigua/media/constants.py

@@ -0,0 +1,37 @@
+"""媒体相关常量。"""
+
+PHOTO_EXTS = frozenset({
+    ".jpg", ".jpeg", ".png", ".webp",
+    ".heic", ".heif", ".tiff", ".tif",
+})
+VIDEO_EXTS = frozenset({
+    ".mp4", ".mov", ".avi", ".mkv",
+    ".m4v", ".3gp", ".wmv",
+})
+
+MEDIA_KIND_ZH = {"photo": "图片", "video": "视频", "unknown": "未知"}
+
+PHOTO_SUMMARY_ZH = {
+    "width": "宽度", "height": "高度", "taken_at": "拍摄时间", "camera": "相机型号",
+    "lens": "镜头", "focal_length": "焦距", "aperture": "光圈", "shutter": "快门",
+    "iso": "ISO", "exposure_bias": "曝光补偿",
+    "gps_lat": "GPS纬度", "gps_lng": "GPS经度", "gps_alt": "GPS海拔", "geo_region": "地区",
+}
+EXIF_PARSED_ZH = {
+    "datetime": "拍摄时间原始", "make": "制造商", "model": "型号",
+    "width": "宽度", "height": "高度", "lens": "镜头", "focal_length": "焦距",
+    "aperture": "光圈", "shutter": "快门", "iso": "ISO", "exposure_bias": "曝光补偿",
+    "gps_lat": "GPS纬度", "gps_lng": "GPS经度", "gps_alt": "GPS海拔",
+}
+VIDEO_SUMMARY_ZH = {
+    "width": "宽度", "height": "高度", "codec": "编码",
+    "duration": "时长秒", "duration_sec": "时长", "fps": "帧率", "bitrate": "码率kbps",
+    "file_size": "文件大小", "format": "格式", "format_long": "容器格式",
+    "datetime": "时间标签", "taken_at": "拍摄时间",
+    "make": "制造商", "model": "型号", "camera": "相机型号",
+    "gps_lat": "GPS纬度", "gps_lng": "GPS经度", "gps_alt": "GPS海拔", "geo_region": "地区",
+}
+IMAGE_INFO_ZH = {
+    "readable": "可读", "format": "格式", "mode": "色彩模式",
+    "width": "宽度", "height": "高度", "info": "附加信息", "error": "错误",
+}

xigua-0.1.3/xigua/media/exif.py

@@ -0,0 +1,184 @@
+"""EXIF / GPS / 拍摄时间解析。"""
+
+from __future__ import annotations
+
+import re
+from datetime import datetime
+from typing import Optional
+
+
+class ExifService:
+    @staticmethod
+    def parse_gps_coord(coord, ref: str) -> Optional[float]:
+        if not coord:
+            return None
+        try:
+            d, m, s = float(coord[0]), float(coord[1]), float(coord[2])
+            val = d + m / 60.0 + s / 3600.0
+            if ref in ("S", "W"):
+                val = -val
+            return round(val, 7)
+        except Exception:
+            return None
+
+    @staticmethod
+    def apply_exif_tag(meta: dict, tag: str, value) -> None:
+        try:
+            if tag == "DateTime" and not meta.get("datetime"):
+                meta["datetime"] = str(value)
+            elif tag == "DateTimeOriginal":
+                meta["datetime"] = str(value)
+            elif tag == "Make":
+                meta["make"] = str(value).strip()
+            elif tag == "Model":
+                meta["model"] = str(value).strip()
+            elif tag == "LensModel":
+                meta["lens"] = str(value).strip()
+            elif tag == "FNumber":
+                meta["aperture"] = f"f/{float(value):.1f}"
+            elif tag == "ExposureTime":
+                v = float(value)
+                meta["shutter"] = f"1/{round(1/v)}" if 0 < v < 1 else f"{v}s"
+            elif tag in ("ISOSpeedRatings", "PhotographicSensitivity"):
+                meta["iso"] = int(value)
+            elif tag == "FocalLength":
+                meta["focal_length"] = f"{float(value):.0f}mm"
+            elif tag == "ExposureBiasValue":
+                v = float(value)
+                meta["exposure_bias"] = f"{v:+.1f}EV" if v != 0 else "0EV"
+            elif tag == "ExifImageWidth":
+                meta.setdefault("width", int(value))
+            elif tag == "ExifImageHeight":
+                meta.setdefault("height", int(value))
+        except Exception:
+            pass
+
+    @staticmethod
+    def extract_exif(path: str) -> dict:
+        try:
+            from PIL import Image, ExifTags  # type: ignore
+        except ImportError:
+            return {}
+        from xigua.media.image import ImageService
+
+        meta: dict = {}
+        try:
+            img = ImageService.open_image(path)
+            exif = img.getexif()
+            if not exif:
+                return {}
+            for tag_id, value in exif.items():
+                ExifService.apply_exif_tag(meta, ExifTags.TAGS.get(tag_id, ""), value)
+            try:
+                exif_ifd = exif.get_ifd(0x8769)
+                for tag_id, value in exif_ifd.items():
+                    ExifService.apply_exif_tag(meta, ExifTags.TAGS.get(tag_id, ""), value)
+            except Exception:
+                pass
+            try:
+                gps = exif.get_ifd(0x8825)
+                if gps:
+                    lat = ExifService.parse_gps_coord(gps.get(2), str(gps.get(1, "")))
+                    lng = ExifService.parse_gps_coord(gps.get(4), str(gps.get(3, "")))
+                    if lat is not None:
+                        meta["gps_lat"] = lat
+                    if lng is not None:
+                        meta["gps_lng"] = lng
+                    alt = gps.get(6)
+                    if alt is not None:
+                        try:
+                            alt_m = float(alt)
+                            if gps.get(5) == 1:
+                                alt_m = -alt_m
+                            meta["gps_alt"] = round(alt_m, 1)
+                        except Exception:
+                            pass
+            except Exception:
+                pass
+        except Exception:
+            pass
+        return meta
+
+    @staticmethod
+    def format_camera(make: Optional[str], model: Optional[str]) -> Optional[str]:
+        make = (make or "").strip()
+        model = (model or "").strip()
+        if not make and not model:
+            return None
+        if not make:
+            return model or None
+        if not model:
+            return make
+        make_lower, model_lower = make.lower(), model.lower()
+        if model_lower.startswith(make_lower):
+            return model
+        if model_lower.startswith(make.split()[0].lower()):
+            return model
+        return f"{make} {model}"
+
+    @staticmethod
+    def parse_exif_dt(dt_str: str) -> Optional[datetime]:
+        if not dt_str:
+            return None
+        s = str(dt_str).strip()
+        for fmt in ("%Y:%m:%d %H:%M:%S", "%Y-%m-%d %H:%M:%S", "%Y-%m-%dT%H:%M:%S"):
+            try:
+                return datetime.strptime(s[:19], fmt)
+            except Exception:
+                continue
+        m = re.match(r"(\d{4}-\d{2}-\d{2}[ T]\d{2}:\d{2}:\d{2})", s)
+        if m:
+            try:
+                return datetime.strptime(m.group(1).replace("T", " "), "%Y-%m-%d %H:%M:%S")
+            except Exception:
+                pass
+        return None
+
+    @staticmethod
+    def parse_iso6709(loc: str) -> tuple[Optional[float], Optional[float], Optional[float]]:
+        if not loc:
+            return None, None, None
+        m = re.match(
+            r"([+-])(\d+(?:\.\d+)?)([+-])(\d+(?:\.\d+)?)([+-]?)(\d+(?:\.\d+)?)?",
+            loc.strip().rstrip("/"),
+        )
+        if not m:
+            return None, None, None
+        try:
+            lat = float(m.group(2)) * (1 if m.group(1) == "+" else -1)
+            lng = float(m.group(4)) * (1 if m.group(3) == "+" else -1)
+            alt = float(m.group(6)) if m.group(6) else None
+            if alt is not None and m.group(5) == "-":
+                alt = -alt
+            return round(lat, 7), round(lng, 7), round(alt, 1) if alt is not None else None
+        except Exception:
+            return None, None, None
+
+    @staticmethod
+    def apply_video_tags(meta: dict, tags: dict) -> None:
+        if not tags:
+            return
+        dt_priority = (
+            "com.apple.quicktime.creationdate",
+            "creation_time",
+            "date",
+        )
+        for key in dt_priority:
+            val = tags.get(key)
+            if val and re.search(r"\d{4}", str(val)):
+                meta["datetime"] = str(val)
+                break
+        make = tags.get("com.apple.quicktime.make") or tags.get("make")
+        model = tags.get("com.apple.quicktime.model") or tags.get("model")
+        if make:
+            meta["make"] = str(make).strip()
+        if model:
+            meta["model"] = str(model).strip()
+        iso_loc = tags.get("com.apple.quicktime.location.ISO6709") or tags.get("location")
+        lat, lng, alt = ExifService.parse_iso6709(str(iso_loc) if iso_loc else "")
+        if lat is not None:
+            meta["gps_lat"] = lat
+        if lng is not None:
+            meta["gps_lng"] = lng
+        if alt is not None:
+            meta["gps_alt"] = alt

xigua-0.1.3/xigua/media/image.py

@@ -0,0 +1,37 @@
+"""图片打开（元数据读取用）。"""
+
+from __future__ import annotations
+
+import os
+
+
+def register_heif_opener() -> None:
+    try:
+        import pillow_heif  # type: ignore
+        pillow_heif.register_heif_opener()
+    except ImportError:
+        pass
+
+
+register_heif_opener()
+
+
+class ImageService:
+    @staticmethod
+    def open_image(path: str):
+        from PIL import Image, ImageOps, UnidentifiedImageError  # type: ignore
+
+        ext = os.path.splitext(path)[1].lower()
+        try:
+            img = Image.open(path)
+            img.load()
+            return ImageOps.exif_transpose(img)
+        except (UnidentifiedImageError, OSError) as exc:
+            if ext in (".heic", ".heif"):
+                try:
+                    import pillow_heif  # type: ignore  # noqa: F401
+                except ImportError:
+                    raise RuntimeError(
+                        "HEIC/HEIF 需要安装 pillow-heif：pip install xigua[heif]"
+                    ) from exc
+            raise

xigua-0.1.3/xigua/media/metadata.py

@@ -0,0 +1,232 @@
+"""本地图片/视频元数据读取与格式化。"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import mimetypes
+import os
+from datetime import datetime
+
+import yaml
+
+from xigua._util import fmt_size
+from xigua.geo.reverse import lookup_geo
+from xigua.media.constants import (
+    EXIF_PARSED_ZH,
+    IMAGE_INFO_ZH,
+    MEDIA_KIND_ZH,
+    PHOTO_SUMMARY_ZH,
+    VIDEO_SUMMARY_ZH,
+)
+from xigua.media.exif import ExifService
+from xigua.media.video import VideoService
+
+
+class MediaMetadataService:
+    """读取本地图片或视频的全部元数据信息。"""
+
+    FORMATS = frozenset({"json", "yaml", "text"})
+
+    @staticmethod
+    def file_md5(path: str) -> str:
+        h = hashlib.md5()
+        with open(path, "rb") as f:
+            for chunk in iter(lambda: f.read(65536), b""):
+                h.update(chunk)
+        return h.hexdigest()
+
+    @staticmethod
+    def zh_keys(data: dict, mapping: dict) -> dict:
+        out: dict = {}
+        for k, v in data.items():
+            if v is None:
+                continue
+            out[mapping.get(k, k)] = v
+        return out
+
+    @staticmethod
+    def format(
+        data: dict,
+        fmt: str = "json",
+        *,
+        indent: int = 2,
+        text_full_raw: bool = False,
+    ) -> str:
+        fmt = fmt.lower()
+        if fmt not in MediaMetadataService.FORMATS:
+            raise ValueError(f"不支持的格式: {fmt!r}，可选: {sorted(MediaMetadataService.FORMATS)}")
+
+        if fmt == "json":
+            return json.dumps(data, ensure_ascii=False, indent=indent, default=str)
+
+        if fmt == "yaml":
+            return yaml.safe_dump(
+                data,
+                allow_unicode=True,
+                default_flow_style=False,
+                sort_keys=False,
+                indent=indent,
+            )
+
+        return MediaMetadataService._format_text(data, full_raw=text_full_raw)
+
+    @staticmethod
+    def _format_text(obj, indent: int = 0, *, full_raw: bool = False, key: str = "") -> str:
+        prefix = "  " * indent
+        raw_keys = frozenset({"EXIF原始", "FFprobe原始", "图片信息"})
+
+        if isinstance(obj, dict):
+            lines: list[str] = []
+            for k, v in obj.items():
+                if not full_raw and key == "" and k in raw_keys and isinstance(v, dict):
+                    lines.append(f"{prefix}{k}: （共 {len(v)} 项，format=json 查看完整）")
+                    continue
+                if isinstance(v, dict):
+                    if not v:
+                        lines.append(f"{prefix}{k}: {{}}")
+                    else:
+                        lines.append(f"{prefix}{k}:")
+                        lines.append(MediaMetadataService._format_text(
+                            v, indent + 1, full_raw=full_raw, key=k,
+                        ))
+                elif isinstance(v, list):
+                    if not v:
+                        lines.append(f"{prefix}{k}: []")
+                    elif all(not isinstance(x, (dict, list)) for x in v):
+                        lines.append(f"{prefix}{k}: {', '.join(str(x) for x in v)}")
+                    else:
+                        lines.append(f"{prefix}{k}:")
+                        for i, item in enumerate(v):
+                            lines.append(f"{prefix}  [{i}]")
+                            lines.append(MediaMetadataService._format_text(
+                                item, indent + 2, full_raw=full_raw,
+                            ))
+                else:
+                    lines.append(f"{prefix}{k}: {v}")
+            return "\n".join(lines)
+
+        if isinstance(obj, list):
+            lines = []
+            for i, item in enumerate(obj):
+                lines.append(f"{prefix}[{i}]")
+                lines.append(MediaMetadataService._format_text(
+                    item, indent + 1, full_raw=full_raw,
+                ))
+            return "\n".join(lines)
+
+        return f"{prefix}{obj}"
+
+    @staticmethod
+    def format_file(
+        local_path: str,
+        fmt: str = "json",
+        *,
+        include_md5: bool = True,
+        include_geo: bool = True,
+        indent: int = 2,
+        text_full_raw: bool = False,
+    ) -> str:
+        data = MediaMetadataService.read(
+            local_path, include_md5=include_md5, include_geo=include_geo,
+        )
+        return MediaMetadataService.format(
+            data, fmt, indent=indent, text_full_raw=text_full_raw,
+        )
+
+    @staticmethod
+    def read(
+        local_path: str,
+        *,
+        include_md5: bool = True,
+        include_geo: bool = True,
+    ) -> dict:
+        """读取本地图片或视频的全部元数据信息。
+
+        图片：Pillow 基础信息 + 完整 EXIF + 解析后的常用字段。
+        视频：ffprobe 完整 JSON + 解析后的常用字段。
+        """
+        local_path = os.path.abspath(os.path.expanduser(local_path))
+        if not os.path.isfile(local_path):
+            raise FileNotFoundError(local_path)
+
+        errors: list[str] = []
+        ext = os.path.splitext(local_path)[1].lower()
+        filename = os.path.basename(local_path)
+        mime, _ = mimetypes.guess_type(local_path)
+        kind = VideoService.detect_media_kind(local_path)
+
+        try:
+            st = os.stat(local_path)
+            file_size = st.st_size
+            modified_at = datetime.fromtimestamp(st.st_mtime).isoformat(timespec="seconds")
+        except OSError as e:
+            file_size = None
+            modified_at = None
+            errors.append(f"stat 失败: {e}")
+
+        file_block: dict = {
+            "路径": local_path,
+            "文件名": filename,
+            "扩展名": ext,
+            "文件大小": file_size,
+            "文件大小可读": fmt_size(file_size) if file_size is not None else None,
+            "MIME类型": mime,
+            "修改时间": modified_at,
+        }
+
+        result: dict = {
+            "类型": MEDIA_KIND_ZH.get(kind, kind),
+            "文件": file_block,
+            "摘要": {},
+            "错误": errors,
+        }
+
+        if include_md5:
+            try:
+                file_block["MD5"] = MediaMetadataService.file_md5(local_path)
+            except Exception as e:
+                errors.append(f"MD5 计算失败: {e}")
+
+        if kind == "photo":
+            image_info = VideoService.dump_image_info(local_path)
+            parsed = ExifService.extract_exif(local_path)
+            summary = {
+                "width": parsed.get("width") or image_info.get("width"),
+                "height": parsed.get("height") or image_info.get("height"),
+                "taken_at": ExifService.parse_exif_dt(parsed.get("datetime", "")),
+                "camera": ExifService.format_camera(parsed.get("make"), parsed.get("model")),
+                "lens": parsed.get("lens"),
+                "focal_length": parsed.get("focal_length"),
+                "aperture": parsed.get("aperture"),
+                "shutter": parsed.get("shutter"),
+                "iso": parsed.get("iso"),
+                "exposure_bias": parsed.get("exposure_bias"),
+                "gps_lat": parsed.get("gps_lat"),
+                "gps_lng": parsed.get("gps_lng"),
+                "gps_alt": parsed.get("gps_alt"),
+            }
+            if include_geo and summary.get("gps_lat") is not None and summary.get("gps_lng") is not None:
+                summary["geo_region"] = lookup_geo(summary["gps_lat"], summary["gps_lng"])
+            result["图片信息"] = MediaMetadataService.zh_keys(image_info, IMAGE_INFO_ZH)
+            result["EXIF原始"] = VideoService.dump_exif_all(local_path)
+            result["EXIF解析"] = MediaMetadataService.zh_keys(parsed, EXIF_PARSED_ZH)
+            result["摘要"] = MediaMetadataService.zh_keys(summary, PHOTO_SUMMARY_ZH)
+
+        elif kind == "video":
+            if not VideoService.cmd_available("ffprobe"):
+                errors.append("ffprobe 不可用，无法读取视频元数据")
+            else:
+                probe = VideoService.ffprobe_all(local_path)
+                if probe:
+                    result["FFprobe原始"] = probe
+                    summary = VideoService.parse_ffprobe_summary(probe, local_path)
+                    if not include_geo:
+                        summary.pop("geo_region", None)
+                    result["摘要"] = MediaMetadataService.zh_keys(summary, VIDEO_SUMMARY_ZH)
+                else:
+                    errors.append("ffprobe 未返回有效数据")
+        else:
+            errors.append(f"无法识别媒体类型（扩展名 {ext or '(无)'}）")
+
+        return result

xigua-0.1.3/xigua/media/video.py

@@ -0,0 +1,226 @@
+"""ffprobe / 图片视频元数据探测。"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+import subprocess
+from typing import Optional
+
+from xigua.geo.reverse import lookup_geo
+from xigua.media.constants import PHOTO_EXTS, VIDEO_EXTS
+from xigua.media.exif import ExifService
+from xigua.media.image import ImageService
+
+log = logging.getLogger(__name__)
+
+
+class VideoService:
+    @staticmethod
+    def cmd_available(cmd: str) -> bool:
+        try:
+            subprocess.run([cmd, "-version"], capture_output=True, timeout=5)
+            return True
+        except Exception:
+            return False
+
+    @staticmethod
+    def ffprobe_all(path: str) -> dict | None:
+        try:
+            r = subprocess.run(
+                ["ffprobe", "-v", "quiet", "-print_format", "json",
+                 "-show_format", "-show_streams", "-show_chapters", path],
+                capture_output=True, text=True, timeout=120,
+            )
+            if r.returncode != 0:
+                return None
+            return json.loads(r.stdout)
+        except Exception as e:
+            log.warning("ffprobe 失败: %s", e)
+            return None
+
+    @staticmethod
+    def parse_ffprobe_summary(data: dict, path: str = "") -> dict:
+        meta: dict = {}
+        for stream in data.get("streams", []):
+            if stream.get("codec_type") == "video":
+                meta["width"] = int(stream.get("width") or 0) or None
+                meta["height"] = int(stream.get("height") or 0) or None
+                meta["codec"] = stream.get("codec_name")
+                if "duration" in stream:
+                    meta["duration"] = int(float(stream["duration"]))
+                for fps_key in ("r_frame_rate", "avg_frame_rate"):
+                    fps_str = stream.get(fps_key, "")
+                    if fps_str and "/" in fps_str:
+                        try:
+                            num, den = fps_str.split("/")
+                            fps = float(num) / float(den)
+                            if 1 < fps < 300:
+                                meta["fps"] = round(fps, 3)
+                                break
+                        except Exception:
+                            pass
+                br = stream.get("bit_rate")
+                if br:
+                    try:
+                        meta["bitrate"] = int(int(br) / 1000)
+                    except Exception:
+                        pass
+                break
+
+        fmt = data.get("format", {})
+        if "duration" in fmt and "duration" not in meta:
+            meta["duration_sec"] = round(float(fmt["duration"]), 3)
+            meta["duration"] = int(float(fmt["duration"]))
+        elif "duration" in meta:
+            meta["duration_sec"] = float(meta["duration"])
+        size = int(fmt.get("size", 0) or 0) or None
+        meta["file_size"] = size
+        if path and size is None:
+            try:
+                meta["file_size"] = os.path.getsize(path)
+            except OSError:
+                pass
+        if "bitrate" not in meta and fmt.get("bit_rate"):
+            try:
+                meta["bitrate"] = int(int(fmt["bit_rate"]) / 1000)
+            except Exception:
+                pass
+        fname = fmt.get("format_name", "")
+        meta["format"] = fname.split(",")[0] if fname else None
+        meta["format_long"] = fname or None
+        ExifService.apply_video_tags(meta, fmt.get("tags") or {})
+        if meta.get("datetime"):
+            meta["taken_at"] = ExifService.parse_exif_dt(meta["datetime"])
+        camera = ExifService.format_camera(meta.get("make"), meta.get("model"))
+        if camera:
+            meta["camera"] = camera
+        if meta.get("gps_lat") is not None and meta.get("gps_lng") is not None:
+            meta["geo_region"] = lookup_geo(meta["gps_lat"], meta["gps_lng"])
+        return meta
+
+    @staticmethod
+    def _serialize_bytes(data: bytes, *, max_text: int = 512) -> str:
+        if not data:
+            return ""
+        try:
+            text = data.decode("utf-8")
+        except UnicodeDecodeError:
+            return f"<binary {len(data)} bytes>"
+        printable = sum(1 for c in text if c.isprintable() or c in "\t\n\r")
+        if printable < len(text) * 0.9:
+            return f"<binary {len(data)} bytes>"
+        text = re.sub(r"\s+", " ", text).strip()
+        if len(text) > max_text:
+            return text[:max_text] + "..."
+        return text
+
+    @staticmethod
+    def serialize_exif_value(value) -> str | int | float | list | dict:
+        if isinstance(value, bytes):
+            return VideoService._serialize_bytes(value)
+        if hasattr(value, "numerator") and hasattr(value, "denominator"):
+            try:
+                return round(float(value), 6)
+            except Exception:
+                return str(value)
+        if isinstance(value, tuple):
+            return [VideoService.serialize_exif_value(v) for v in value]
+        return value
+
+    _IMAGE_INFO_SKIP = frozenset({
+        "exif", "mp", "xmp", "icc_profile", "icc", "photoshop", "XML:com.adobe.xmp",
+    })
+
+    @staticmethod
+    def dump_exif_all(path: str) -> dict:
+        try:
+            from PIL import Image, ExifTags  # type: ignore
+        except ImportError:
+            return {}
+        raw: dict = {}
+        try:
+            img = ImageService.open_image(path)
+            exif = img.getexif()
+            if not exif:
+                return {}
+
+            def _collect(ifd, prefix: str = "") -> None:
+                for tag_id, value in ifd.items():
+                    name = ExifTags.TAGS.get(tag_id, str(tag_id))
+                    key = f"{prefix}{name}" if prefix else name
+                    raw[key] = VideoService.serialize_exif_value(value)
+
+            _collect(exif)
+            try:
+                _collect(exif.get_ifd(0x8769), "Exif:")
+            except Exception:
+                pass
+            try:
+                gps = exif.get_ifd(0x8825)
+                if gps:
+                    _collect(gps, "GPS:")
+                    lat = ExifService.parse_gps_coord(gps.get(2), str(gps.get(1, "")))
+                    lng = ExifService.parse_gps_coord(gps.get(4), str(gps.get(3, "")))
+                    if lat is not None:
+                        raw["GPS:DecimalLatitude"] = lat
+                    if lng is not None:
+                        raw["GPS:DecimalLongitude"] = lng
+                    alt = gps.get(6)
+                    if alt is not None:
+                        try:
+                            alt_m = float(alt)
+                            if gps.get(5) == 1:
+                                alt_m = -alt_m
+                            raw["GPS:DecimalAltitude"] = round(alt_m, 1)
+                        except Exception:
+                            pass
+            except Exception:
+                pass
+        except Exception as e:
+            log.warning("EXIF 读取失败 (%s): %s", os.path.basename(path), e)
+        return raw
+
+    @staticmethod
+    def dump_image_info(path: str) -> dict:
+        info: dict = {"readable": False}
+        try:
+            img = ImageService.open_image(path)
+            info.update({
+                "readable": True,
+                "format": img.format,
+                "mode": img.mode,
+                "width": img.width,
+                "height": img.height,
+            })
+            if hasattr(img, "info") and img.info:
+                extra: dict = {}
+                for k, v in img.info.items():
+                    if k in VideoService._IMAGE_INFO_SKIP:
+                        continue
+                    sv = VideoService.serialize_exif_value(v)
+                    if sv not in (None, "", f"<binary 0 bytes>"):
+                        extra[k] = sv
+                if extra:
+                    info["info"] = extra
+        except Exception as e:
+            info["error"] = str(e)
+        return info
+
+    @staticmethod
+    def detect_media_kind(path: str) -> str:
+        ext = os.path.splitext(path)[1].lower()
+        if ext in PHOTO_EXTS:
+            return "photo"
+        if ext in VIDEO_EXTS:
+            return "video"
+        try:
+            ImageService.open_image(path)
+            return "photo"
+        except Exception:
+            pass
+        if VideoService.cmd_available("ffprobe") and VideoService.ffprobe_all(path):
+            return "video"
+        return "unknown"

xigua-0.1.3/xigua.egg-info/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: xigua
+Version: 0.1.3
+Summary: 西瓜小工具集 — 各类实用小功能
+Author-email: xigua <2587125111@qq.com>
+License: Copyright © 2024 xigua Authors. All Rights Reserve.
+Project-URL: Homepage, https://pypi.org/project/xigua
+Keywords: utilities,tools,metadata,exif,ffprobe,media
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: Pillow>=9.0.0
+Requires-Dist: PyYAML<7.0,>=6.0
+Provides-Extra: heif
+Requires-Dist: pillow-heif>=0.10.0; extra == "heif"
+
+# xigua — 小工具集
+
+各类实用小功能，按模块组织，持续扩展。
+
+## 已包含模块
+
+### media — 本地图片/视频元数据
+
+读取本地图片或视频的全部元数据（中文键名输出）。
+
+```python
+from xigua.media import MediaMetadataService
+
+# 读取为字典
+data = MediaMetadataService.read("/path/to/photo.jpg")
+
+# 直接格式化输出
+print(MediaMetadataService.format_file("/path/to/clip.mp4", fmt="text"))
+print(MediaMetadataService.format_file("/path/to/clip.mp4", fmt="yaml", include_md5=False))
+```
+
+命令行：
+
+```bash
+xigua-media /path/to/photo.jpg
+xigua-media /path/to/clip.mp4 --fmt text --no-md5
+```
+
+**依赖说明：**
+- 图片：Pillow（HEIC/HEIF 需 `pip install xigua[heif]`）
+- 视频：系统需安装 `ffprobe`
+
+## 安装
+
+```bash
+pip install xigua
+pip install xigua[heif]   # 支持 HEIC/HEIF
+```
+
+## 发布
+
+```bash
+cd /Users/xigua/pypi-publish
+./publish xigua --bump patch
+```

xigua-0.1.3/xigua.egg-info/SOURCES.txt

@@ -0,0 +1,21 @@
+README.md
+license.txt
+pyproject.toml
+xigua/__init__.py
+xigua/__version__.py
+xigua/_util.py
+xigua.egg-info/PKG-INFO
+xigua.egg-info/SOURCES.txt
+xigua.egg-info/dependency_links.txt
+xigua.egg-info/entry_points.txt
+xigua.egg-info/requires.txt
+xigua.egg-info/top_level.txt
+xigua/geo/__init__.py
+xigua/geo/reverse.py
+xigua/media/__init__.py
+xigua/media/cli.py
+xigua/media/constants.py
+xigua/media/exif.py
+xigua/media/image.py
+xigua/media/metadata.py
+xigua/media/video.py

xigua-0.1.3/xigua.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

xigua-0.1.3/xigua.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+xigua-media = xigua.media.cli:main

xigua-0.1.3/xigua.egg-info/requires.txt

@@ -0,0 +1,5 @@
+Pillow>=9.0.0
+PyYAML<7.0,>=6.0
+
+[heif]
+pillow-heif>=0.10.0

xigua-0.1.3/xigua.egg-info/top_level.txt

@@ -0,0 +1 @@
+xigua