Metadata-Version: 2.4
Name: poster-generator
Version: 1.2.0
Summary: 
License: Copyright 2025 Reyaan C.
         
         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.
License-File: LICENSE
Author: corgi-in-tights
Author-email: 59304120+corgi-in-tights@users.noreply.github.com
Requires-Python: >=3.13
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: pillow (>=12.0.0,<13.0.0)
Requires-Dist: pyyaml (>=6.0.3,<7.0.0)
Project-URL: Homepage, https://github.com/corgi-in-tights/poster-generator
Project-URL: Repository, https://github.com/corgi-in-tights/poster-generator
Description-Content-Type: text/markdown

# Poster Generator

A flexible Python library for building and rendering posters/infomatics with focus on text templates and dynamic usage.

![Poster Generator Banner](https://raw.githubusercontent.com/corgi-in-tights/poster-generator/main/docs/images/showcase.png)


[![Python Version](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

## Features

	•	🧱 Element and layer system with blend settings leveraging Pillow

	•	🗂️ Canvas element querying, grouping, deserialization and composites

	•	📄 YAML/JSON template loaders with variable substitution for reusable layouts

	•	🎯 'Canva' snapping-inspired relative positioning for quick template development

	•	🔌 Extensible, format-agnostic registry for every inheritable class

	•	🛠️ Function-driven operations (e.g., hue shifting, scaling, transforms)
    
	•	📣 Designed for automated poster and social media post generation

⸻


## Installation

### Using Poetry (recommended)

```bash
poetry add poster-generator
```

### Using pip

```bash
pip install poster-generator
```

### From source

```bash
git clone https://github.com/corgi-in-tights/poster-generator.git
cd poster-generator
poetry install
```

## Requirements

- Python >= 3.13
- Pillow >= 12.0.0
- PyYAML >= 6.0.3


## Quick Start

Check out the `examples/` directory for concrete examples and [TEMPLATES.md](https://github.com/corgi-in-tights/poster-generator/blob/main/TEMPLATES.md) for a reference on the in-built template format.


## Reference

### Elements

Elements are the basic pieces you use to build a poster.  
The library comes with a few ready-to-use ones:

- **TextElement** (`text`) – Regular text with custom fonts, wrapping, alignment, and opacity.
- **ImageElement** (`image`) – Shows an image from a file path and lets you resize it however you need.
- **RectangleElement** (`rectangle`) – A simple box shape with size, corner radius, fill, and opacity options.
- **EllipseElement** (`ellipse`) – Like a rectangle, but drawn as an oval/circle instead.


To learn how to register custom elements for templates, please see [TEMPLATES.md](https://github.com/corgi-in-tights/poster-generator/blob/main/TEMPLATES.md).


```python
canvas = Canvas(width=500, height=500)

image = ImageElement(
    image_path="image.png",
    width=500,
    height=500
)  # position defaults to (0, 0)
canvas.add_element("background", image, layer="background")

text = TextElement(
    position=(100, 100),
    text="Hello World",
    font_size=48,
    color="#000000",
    font_family="Open Sans"  # See FontManager.get_font_families() for a full list!
)
canvas.add_element("my_text_id", text, groups="titles")

image = canvas.render()
image.show()
```

#### Layers

Layers help organize elements and control rendering order:

```python
canvas.add_element("bg", background, layer="background")
canvas.add_element("title", text, layer="foreground")
```

#### Groups

Groups allow you to manage related elements:

```python
canvas.add_element("title", text, groups=["headers", "top-section"])
canvas.add_element("subtitle", subtitle, groups=["headers", "top-section"])

# Query elements by group
headers = canvas.get_elements(groups="headers")
```

### Operations

Apply transformations to elements:

```python
from poster_generator.operations import apply_hue_shift, set_hue_from_hex

# Hue shift
element.apply_operation(apply_hue_shift, degrees=45)
```

To learn how to register custom operations for templates, please see [TEMPLATES.md](https://github.com/corgi-in-tights/poster-generator/blob/main/TEMPLATES.md).

### Element Queries

Query elements by identifier, group, or layer:

```python
# Get specific elements
elements = canvas.get_first_element(identifier="my_subtitle")

# Combine filters (requires all to match by default)
specific = canvas.get_elements(
    groups="images",
    layers="background",
    # require_all=True,
)
```

There are a few other methods, mostly to do with drawing, removing elements, cropping, etc. I recommend taking a look to see if any are useful to you :)

## Contributing & Issues

Contributions are welcome! Please feel free to submit a PR. I am open to significant design changes if they match the project's intention.

If any critical bugs come up, please open a GitHub issue, feature requests are fine but a PR would be much preferred :p

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- Built with [Pillow](https://python-pillow.org/) for image processing (a Pillow wrapper really)
- Uses [PyYAML](https://pyyaml.org/) for template parsing (by default)
- This README and parts of the code were partially generated by an LLM, Claude Sonnet 4.5
