poster-generator 1.2.0

No project description provided

Poster Generator

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

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)

poetry add poster-generator

Using pip

pip install poster-generator

From source

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 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.

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:

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

Groups

Groups allow you to manage related elements:

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:

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.

Element Queries

Query elements by identifier, group, or layer:

# 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 file for details.

Acknowledgments

• Built with Pillow for image processing (a Pillow wrapper really)
• Uses PyYAML for template parsing (by default)
• This README and parts of the code were partially generated by an LLM, Claude Sonnet 4.5