Metadata-Version: 2.4
Name: pinforge
Version: 0.1.0
Summary: Build 1000x1500 Pinterest pin images, and order your publishing queue from a Google Search Console export — per locale.
Project-URL: Homepage, https://tarot-magic.com
Author: Oleg Kolesnykov
License: MIT
License-File: LICENSE
Keywords: images,multilingual,pillow,pinterest,search-console,seo
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Internet :: WWW/HTTP :: Site Management
Classifier: Topic :: Multimedia :: Graphics
Requires-Python: >=3.9
Requires-Dist: pillow>=9.0
Description-Content-Type: text/markdown

# pinforge

Build vertical **1000×1500 Pinterest pins** from an image and a few lines of text,
and work out **what to publish first** from a Google Search Console export —
counted separately for every locale.

Two small things that turned out to matter when running a multilingual site's
Pinterest account for a month.

```bash
pip install pinforge
```

## Why per-locale ranking

If your site has several language versions, demand in each one is different.
Summing impressions across the whole site and reusing that single order for every
language sends your best material to the wrong audience.

Concrete example from the site this was written for — same 78 tarot cards, four
languages, the most-searched card in each:

| Locale | Top item | Impressions |
|---|---|---|
| Ukrainian | Six of Wands | 308 |
| Russian | Ten of Cups | 270 |
| English | Four of Wands | 158 |
| French | The Magician | 19 |

Four different answers. Not the same list in a different order — different items.

```python
from pinforge import rank_by_locale

queues = rank_by_locale(
    "pages.csv",                   # Pages export from Search Console
    item_pattern=r"/card/([^/?]+)$",
    locales=("ru", "uk", "fr"),    # anything else falls into default_locale
    default_locale="en",
)

for slug, impressions in queues["uk"][:5]:
    print(slug, impressions)
```

Works with the CSV as Search Console exports it, in any interface language —
column names are detected, not hard-coded.

## Composing a pin

```python
from pinforge import PinStyle, compose

style = PinStyle(
    script_font="GreatVibes-Regular.ttf",   # brand name
    body_font="PlaypenSans.ttf",            # title and subtitle
    seed=7,                                 # same seed = same starfield
)

compose(
    out="pin.png",
    image="six-of-wands.jpg",
    title="Six of Wands",
    subtitle="Victory · Recognition · Success",
    footer="example.com",
    brand="Example",
    style=style,
)
```

Produces a dark, starfield-backed pin: brand at the top, the image framed and
glowing in the middle, title and subtitle below, site address at the bottom.
Colours, size, star density and fonts are all on `PinStyle`.

Fonts are optional — without them Pillow's default is used and the result is
plain but valid.

## Command line

```bash
pinforge compose --image card.jpg --title "Six of Wands" \
  --subtitle "Victory · Recognition · Success" \
  --footer example.com --brand Example --out pin.png

pinforge rank --pages pages.csv --pattern '/card/([^/?]+)$' \
  --locales ru,uk,fr --top 5
```

## Where it came from

Written for [tarot-magic.com](https://tarot-magic.com), a tarot reference covering
all 78 cards in English, Russian, Ukrainian and French. It generates the card pins
for four language boards, and the ranking decides the order they go out in — which
is how the per-locale difference above was discovered in the first place.

MIT licensed.
