Metadata-Version: 2.4
Name: pngmeta
Version: 0.1.0
Summary: A Python library for reading and writing PNG metadata (tEXt, iTXt, zTXt chunks and XMP)
Project-URL: Homepage, https://github.com/yourusername/pngmeta
Project-URL: Issues, https://github.com/yourusername/pngmeta/issues
Project-URL: Source, https://github.com/yourusername/pngmeta
Author-email: Your Name <your.email@example.com>
License: Unlicense
License-File: LICENSE
Keywords: chunks,exif,image,itxt,metadata,png,text,xmp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: Public Domain
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Provides-Extra: dev
Requires-Dist: black>=22.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# pngmeta

A Python library for reading and writing PNG metadata, similar to `iptcinfo3` for JPEG files.

## Features

- Read and write PNG text chunks (tEXt, iTXt, zTXt)
- Handle XMP metadata in PNG files
- Simple, intuitive API similar to iptcinfo3
- Pure Python implementation with no dependencies
- Support for UTF-8 and compressed text chunks

## Installation

```bash
pip install pngmeta
```

Or with `uv`:

```bash
uv pip install pngmeta
```

## Quick Start

```python
from pngmeta import PngMeta

# Read metadata
meta = PngMeta('image.png')
print(meta.get('Title'))
print(meta.get('Author'))
print(meta.get('Copyright'))

# Write metadata
meta.set('Title', 'My Image')
meta.set('Author', 'John Doe')
meta.set('Copyright', 'Copyright 2025')
meta.save()

# Save to a new file
meta.save('image_with_metadata.png')

# Work with XMP
xmp = meta.get_xmp()
if xmp:
    print("XMP data:", xmp)

# Dictionary-style access
meta['Description'] = 'A beautiful landscape'
if 'Author' in meta:
    print(f"Author: {meta['Author']}")

# Iterate over all metadata
for key, value in meta.items():
    print(f"{key}: {value}")
```

## Common PNG Text Keywords

- `Title` - Short title or caption
- `Author` - Image author
- `Description` - Longer description
- `Copyright` - Copyright notice
- `Creation Time` - Original image creation time
- `Software` - Software used to create the image
- `Comment` - Miscellaneous comment
- `XML:com.adobe.xmp` - XMP metadata (automatically handled)

## PNG Metadata Background

PNG files store metadata in "ancillary chunks":
- **tEXt** - Latin-1 text (uncompressed)
- **iTXt** - UTF-8 text (optionally compressed), used for XMP
- **zTXt** - Compressed Latin-1 text

Unlike JPEG, PNG doesn't natively use IPTC, but XMP can be embedded in iTXt chunks for cross-format compatibility.

## Development

```bash
# Clone the repository
git clone https://github.com/yourusername/pngmeta.git
cd pngmeta

# Install with uv
uv venv
source .venv/bin/activate  # or `.venv\Scripts\activate` on Windows
uv pip install -e ".[dev]"

# Run tests
pytest

# Format code
black pngmeta tests

# Type checking
mypy pngmeta
```

## License

This is free and unencumbered software released into the public domain (Unlicense).

## See Also

- [iptcinfo3](https://pypi.org/project/IPTCInfo3/) - IPTC metadata for JPEG files
- [PNG Specification](http://www.libpng.org/pub/png/spec/1.2/PNG-Contents.html)
- [Exiv2 PNG Metadata Notes](https://exiv2.org/metadata.html)
