| Name | cgmetadata JSON |
| Version |
0.1.6
JSON |
| download |
| home_page | None |
| Summary | Use native Core Graphics / ImageIO API on macOS to access and change image metadata |
| upload_time | 2024-04-01 15:28:09 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >3.9 |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# CGMetadata
Read and write image metadata on macOS from Python using the native [ImageIO / Core Graphics frameworks](https://developer.apple.com/documentation/imageio).
CGMetadata is a Python wrapper around the macOS ImageIO and Core Graphics frameworks. It provides a simple interface for reading and writing image metadata, including EXIF, IPTC, and XMP data. Reading is supported for all image formats supported by ImageIO. Reading is also supported for video formats using AVFoundation.
Writing is not currently supported for RAW file formats nor for video formats. Writing of metadata has been tested on JPEG, PNG, TIFF, and HEIC files however it should be considered experimental. If you are using CGMetadata to write metadata to image files, please make sure you have tested the results before using it in production.
## Synopsis
<!--
Setup for doctest:
```pycon
>>> import shutil
>>> import os
>>> try:
... os.remove("test.jpeg")
... except Exception:
... pass
...
>>> try:
... os.remove("test.xmp")
... except Exception:
... pass
...
>>> try:
... os.remove("test.MOV")
... except Exception:
... pass
...
>>>
>>> cwd = os.getcwd()
>>> _ = shutil.copy("tests/data/test.jpeg", os.path.join(cwd, "test.jpeg"))
>>>
>>> _ = shutil.copy("tests/data/test.MOV", os.path.join(cwd, "test.MOV"))
>>>
```
-->
```pycon
>>> from cgmetadata import ImageMetadata, VideoMetadata, IPTC, XMP
>>> md = ImageMetadata("test.jpeg")
>>> md.exif["LensMake"]
'Apple'
>>> md.iptc["Keywords"]
['fruit', 'tree']
>>> md.xmp["dc:description"]
['A pair of pears on a tree']
>>> # get XMP sidecar as a str
>>> xmp = md.xmp_dumps()
>>> # write an XMP sidecar file for the image
>>> with open("test.xmp", "w") as f:
... md.xmp_dump(f)
...
>>> # read metadata from XMP sidecar file and apply to image
>>> with open("test.xmp", "r") as f:
... md.xmp_load(f)
...
>>>
>>> md.write()
>>> # set metadata
>>> md.set(XMP, "dc:description", ["Test image"])
>>> md.set(IPTC, "Keywords", ["foo", "bar"])
>>> md.write()
>>> md.xmp["dc:description"]
['Test image']
>>> md.iptc["Keywords"]
['foo', 'bar']
>>>
>>> # update values with context manager
>>> with ImageMetadata("test.jpeg") as md:
... md.set(IPTC, "Keywords", ["Fizz", "Buzz"])
... md.set(XMP, "dc:creator", ["CGMetadata"])
...
>>> md.iptc["Keywords"]
['Fizz', 'Buzz']
>>>
>>> # read metadata from video file
>>> md = VideoMetadata("test.MOV")
>>> md.xmp.get("dc:subject")
['Coffee', 'Espresso']
>>>
```
CGMetadata also include a utility function for reading an XMP file and returning a dictionary of metadata using native macOS APIs. This may be useful by itself as it doesn't require the use of external libraries or XML parsers.
<!--
Setup for doctest:
```pycon
>>> import shutil
>>> import os
>>> try:
... os.remove("test.xmp")
... except Exception:
... pass
...
>>>
>>> cwd = os.getcwd()
>>> _ = shutil.copy("tests/data/test.MOV.xmp", os.path.join(cwd, "test.xmp"))
>>>
```
-->
```pycon
>>> from cgmetadata import metadata_dictionary_from_xmp_packet
>>> xmp_data = open("test.xmp").read()
>>> metadata_dictionary_from_xmp_packet(xmp_data)
{'dc:subject': ['Coffee', 'Espresso'], 'iio:hasXMP': 'True'}
>>>
```
## Installation
```bash
pip install cgmetadata
```
## Documentation
The documentation for CGMetadata is available at [https://RhetTbull.github.io/CGMetadata/](https://RhetTbull.github.io/CGMetadata/).
## Source Code
The source code for this project is available on [GitHub](https://github.com/RhetTbull/CGMetadata).
## Command Line Interface
The package will install a small command line interface (CLI), `cgmd`, which prints
metadata for an image file in tabular, JSON, CSV, TSV, or XMP formats. The CLI can also
be run by executing `python3 -m cgmetadata`.
```
usage: cgmd [-h] [--version] [--csv] [--tsv] [--json] [--xmp] [--indent INDENT] [--no-header] IMAGE_OR_VIDEO
Print metadata for image files in various formats.
positional arguments:
IMAGE_OR_VIDEO path to image or video file
options:
-h, --help show this help message and exit
--version, -v show program's version number and exit
--csv, -c output as comma separated values (CSV); see also --no-header
--tsv, -t output as tab separated values (TSV); see also --no-header
--json, -j output as JSON; see also --indent
--xmp, -x output XMP sidecar for image; see also --no-header
--indent INDENT, -i INDENT
indent level for JSON; default 4, use 0 for no indentation
--no-header, -H when used with --csv, --tsv, omit column headers; when used with --xmp, omit XMP packet header
```
## Supported Versions
CGMetadata has been tested on macOS 13 (Ventura) but should work on macOS 11 (Big Sur) and later. It will not work on earlier versions of macOS due to the use of certain APIs that were introduced in macOS 11. It is compatible with Python 3.9 and later.
## License
MIT License, copyright Rhet Turnbull, 2023.
<!--
Cleanup for doctest:
```pycon
>>> import os
>>> os.remove("test.jpeg")
>>> os.remove("test.xmp")
>>> os.remove("test.MOV")
>>>
```
-->
Raw data
{
"_id": null,
"home_page": null,
"name": "cgmetadata",
"maintainer": null,
"docs_url": null,
"requires_python": ">3.9",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": "Rhet Turnbull <rturnbull+git@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/37/27/c4e4c2c019ff5894abe4431a6237da6493919bd4c5b99970100a0b6e6c5e/cgmetadata-0.1.6.tar.gz",
"platform": null,
"description": "# CGMetadata\n\nRead and write image metadata on macOS from Python using the native [ImageIO / Core Graphics frameworks](https://developer.apple.com/documentation/imageio).\n\nCGMetadata is a Python wrapper around the macOS ImageIO and Core Graphics frameworks. It provides a simple interface for reading and writing image metadata, including EXIF, IPTC, and XMP data. Reading is supported for all image formats supported by ImageIO. Reading is also supported for video formats using AVFoundation.\n\nWriting is not currently supported for RAW file formats nor for video formats. Writing of metadata has been tested on JPEG, PNG, TIFF, and HEIC files however it should be considered experimental. If you are using CGMetadata to write metadata to image files, please make sure you have tested the results before using it in production.\n\n## Synopsis\n\n<!--\nSetup for doctest:\n\n```pycon\n>>> import shutil\n>>> import os\n>>> try:\n... os.remove(\"test.jpeg\")\n... except Exception:\n... pass\n...\n>>> try:\n... os.remove(\"test.xmp\")\n... except Exception:\n... pass\n...\n>>> try:\n... os.remove(\"test.MOV\")\n... except Exception:\n... pass\n...\n>>> \n>>> cwd = os.getcwd()\n>>> _ = shutil.copy(\"tests/data/test.jpeg\", os.path.join(cwd, \"test.jpeg\"))\n>>> \n>>> _ = shutil.copy(\"tests/data/test.MOV\", os.path.join(cwd, \"test.MOV\"))\n>>> \n```\n-->\n\n```pycon\n>>> from cgmetadata import ImageMetadata, VideoMetadata, IPTC, XMP\n>>> md = ImageMetadata(\"test.jpeg\")\n>>> md.exif[\"LensMake\"]\n'Apple'\n>>> md.iptc[\"Keywords\"]\n['fruit', 'tree']\n>>> md.xmp[\"dc:description\"]\n['A pair of pears on a tree']\n>>> # get XMP sidecar as a str\n>>> xmp = md.xmp_dumps()\n>>> # write an XMP sidecar file for the image\n>>> with open(\"test.xmp\", \"w\") as f:\n... md.xmp_dump(f)\n...\n>>> # read metadata from XMP sidecar file and apply to image\n>>> with open(\"test.xmp\", \"r\") as f:\n... md.xmp_load(f)\n...\n>>> \n>>> md.write()\n>>> # set metadata\n>>> md.set(XMP, \"dc:description\", [\"Test image\"])\n>>> md.set(IPTC, \"Keywords\", [\"foo\", \"bar\"])\n>>> md.write()\n>>> md.xmp[\"dc:description\"]\n['Test image']\n>>> md.iptc[\"Keywords\"]\n['foo', 'bar']\n>>> \n>>> # update values with context manager\n>>> with ImageMetadata(\"test.jpeg\") as md:\n... md.set(IPTC, \"Keywords\", [\"Fizz\", \"Buzz\"])\n... md.set(XMP, \"dc:creator\", [\"CGMetadata\"])\n...\n>>> md.iptc[\"Keywords\"]\n['Fizz', 'Buzz']\n>>> \n>>> # read metadata from video file\n>>> md = VideoMetadata(\"test.MOV\")\n>>> md.xmp.get(\"dc:subject\")\n['Coffee', 'Espresso']\n>>> \n```\n\nCGMetadata also include a utility function for reading an XMP file and returning a dictionary of metadata using native macOS APIs. This may be useful by itself as it doesn't require the use of external libraries or XML parsers.\n\n<!--\nSetup for doctest:\n\n```pycon\n>>> import shutil\n>>> import os\n>>> try:\n... os.remove(\"test.xmp\")\n... except Exception:\n... pass\n...\n>>> \n>>> cwd = os.getcwd()\n>>> _ = shutil.copy(\"tests/data/test.MOV.xmp\", os.path.join(cwd, \"test.xmp\"))\n>>> \n```\n-->\n\n```pycon\n>>> from cgmetadata import metadata_dictionary_from_xmp_packet\n>>> xmp_data = open(\"test.xmp\").read()\n>>> metadata_dictionary_from_xmp_packet(xmp_data)\n{'dc:subject': ['Coffee', 'Espresso'], 'iio:hasXMP': 'True'}\n>>>\n```\n\n## Installation\n\n```bash\npip install cgmetadata\n```\n\n## Documentation\n\nThe documentation for CGMetadata is available at [https://RhetTbull.github.io/CGMetadata/](https://RhetTbull.github.io/CGMetadata/).\n\n## Source Code\n\nThe source code for this project is available on [GitHub](https://github.com/RhetTbull/CGMetadata).\n\n## Command Line Interface\n\nThe package will install a small command line interface (CLI), `cgmd`, which prints\nmetadata for an image file in tabular, JSON, CSV, TSV, or XMP formats. The CLI can also\nbe run by executing `python3 -m cgmetadata`.\n\n```\nusage: cgmd [-h] [--version] [--csv] [--tsv] [--json] [--xmp] [--indent INDENT] [--no-header] IMAGE_OR_VIDEO\n\nPrint metadata for image files in various formats.\n\npositional arguments:\n IMAGE_OR_VIDEO path to image or video file\n\noptions:\n -h, --help show this help message and exit\n --version, -v show program's version number and exit\n --csv, -c output as comma separated values (CSV); see also --no-header\n --tsv, -t output as tab separated values (TSV); see also --no-header\n --json, -j output as JSON; see also --indent\n --xmp, -x output XMP sidecar for image; see also --no-header\n --indent INDENT, -i INDENT\n indent level for JSON; default 4, use 0 for no indentation\n --no-header, -H when used with --csv, --tsv, omit column headers; when used with --xmp, omit XMP packet header\n```\n\n## Supported Versions\n\nCGMetadata has been tested on macOS 13 (Ventura) but should work on macOS 11 (Big Sur) and later. It will not work on earlier versions of macOS due to the use of certain APIs that were introduced in macOS 11. It is compatible with Python 3.9 and later.\n\n## License\n\nMIT License, copyright Rhet Turnbull, 2023.\n\n<!--\nCleanup for doctest:\n\n```pycon\n>>> import os\n>>> os.remove(\"test.jpeg\")\n>>> os.remove(\"test.xmp\")\n>>> os.remove(\"test.MOV\")\n>>> \n```\n-->",
"bugtrack_url": null,
"license": null,
"summary": "Use native Core Graphics / ImageIO API on macOS to access and change image metadata",
"version": "0.1.6",
"project_urls": {
"Home": "https://github.com/RhetTbull/cgmetadata",
"Issues": "https://github.com/RhetTbull/cgmetadata/issues",
"Source": "https://github.com/RhetTbull/cgmetadata"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b3b1b0edaf23d65a6d3590e457286a5727514daa5ae50fae61ac2a7b4f9488c5",
"md5": "dc67cb3873308a5a7a77d8f0e712c5a7",
"sha256": "1879471d63d700cc6de3992eb7617d63aa7b744163e00de9282d129fda53cc52"
},
"downloads": -1,
"filename": "cgmetadata-0.1.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "dc67cb3873308a5a7a77d8f0e712c5a7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">3.9",
"size": 20266,
"upload_time": "2024-04-01T15:28:06",
"upload_time_iso_8601": "2024-04-01T15:28:06.836006Z",
"url": "https://files.pythonhosted.org/packages/b3/b1/b0edaf23d65a6d3590e457286a5727514daa5ae50fae61ac2a7b4f9488c5/cgmetadata-0.1.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "3727c4e4c2c019ff5894abe4431a6237da6493919bd4c5b99970100a0b6e6c5e",
"md5": "3e62ef95e48fb344997fe26c76d19b7a",
"sha256": "e9c16e3e905947ba0b54978bf04cb3f8c5fa9dadf56467f1e559a25b8e00c359"
},
"downloads": -1,
"filename": "cgmetadata-0.1.6.tar.gz",
"has_sig": false,
"md5_digest": "3e62ef95e48fb344997fe26c76d19b7a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">3.9",
"size": 20669,
"upload_time": "2024-04-01T15:28:09",
"upload_time_iso_8601": "2024-04-01T15:28:09.262778Z",
"url": "https://files.pythonhosted.org/packages/37/27/c4e4c2c019ff5894abe4431a6237da6493919bd4c5b99970100a0b6e6c5e/cgmetadata-0.1.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-01 15:28:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "RhetTbull",
"github_project": "cgmetadata",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "cgmetadata"
}
