Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 5 additions & 6 deletions .github/workflows/tests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -20,24 +20,23 @@ jobs:
matrix:
# 3.11 is the floor: mullion and the app's StrEnum use need it.
python-version: ["3.11", "3.13"]
defaults:
run:
working-directory: image_grid_app
steps:
- uses: actions/checkout@v5

- uses: actions/setup-python@v6
with:
python-version: ${{ matrix.python-version }}
cache: pip
cache-dependency-path: image_grid_app/requirements*.txt
cache-dependency-path: pyproject.toml

# The preview-video tests encode real files; without ffmpeg they skip.
- name: Install ffmpeg
run: sudo apt-get update && sudo apt-get install --yes --no-install-recommends ffmpeg

- name: Install dependencies
run: pip install -r requirements-dev.txt
# A regular (not editable) install, so the tests run against the built
# package and fail if a template or static file is left out of it.
- name: Install
run: pip install ".[dev]"

# Lint first: a slip fails in seconds rather than after the suite.
- name: Lint
Expand Down
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,3 +1,6 @@
__pycache__/
*.py[cod]
.venv/
build/
dist/
*.egg-info/
102 changes: 63 additions & 39 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,61 +1,69 @@
# mar_place

## MVP Overview
`mar_place` contains **Image Grid App**, a FastAPI + vanilla JS tool that:
- scans an input folder for supported images,
- estimates page count,
- composes a fixed **4x3 image grid** (12 images) per page,
- exports generated pages as PNG or JPG at a chosen DPI,
- optionally cleans a near-white background off each image before placing it,
- lets the UI toggle between single-folder and batch-folder generation modes.

Project root:
- `image_grid_app/` — runnable application.

---

## Installation and Run Commands

Requires Python 3.11 or newer. The optional preview video also needs
# Pasteup

Turn a folder of clip art into listing images: preview sheets, a cover collage
and a short preview video, ready for Etsy and other marketplaces. Pasteup runs
on your own computer and works in your browser.

The name comes from *paste-up*, how clip art was used before desktop
publishing: cut out by hand and pasted onto a layout board.

## What it does
- **Preview sheets:** 4x3 grids of your images on a white page, as PNG or JPG
at a chosen DPI.
- **Cover collage:** a single page in one of three layouts, for a listing's
main image.
- **Preview video:** an MP4 slideshow of the sheets, exactly as long as you ask
(Etsy's listing videos run 5 to 15 s).
- **Clean-up:** transparent PNGs land on white instead of black, phone photos
are turned upright, and near-white backgrounds can be removed.
- **Batch mode:** process every bundle folder under a parent folder in one go.

## Install
Requires Python 3.11 or newer. The preview video also needs
[ffmpeg](https://ffmpeg.org/) on `PATH`.

### 1) Install dependencies
```bash
cd image_grid_app
git clone https://github.com/ftymoshchuk/pasteup.git
cd pasteup
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install .
```

### 2) Run the app
## Run
```bash
cd image_grid_app
uvicorn app.main:app --reload
pasteup
```
Then open `http://127.0.0.1:8000/` (API docs: `http://127.0.0.1:8000/docs`).
`pasteup --help` lists the options, and `python -m pasteup` works too.

### 3) Open in browser
- UI: `http://127.0.0.1:8000/`
- API docs (Swagger): `http://127.0.0.1:8000/docs`

The app reads and writes files at the paths you give it and has no login, so
Pasteup reads and writes files at the paths you give it and has no login, so
keep it on `127.0.0.1` (the default). See [SECURITY.md](SECURITY.md).

### Optional environment variables
- `IMAGE_GRID_INPUT_FOLDER`: prefills the input-folder field, e.g.
`IMAGE_GRID_INPUT_FOLDER=~/Pictures/clip-art uvicorn app.main:app`.
- `IMAGE_GRID_ALLOWED_HOSTS`: comma-separated host names to accept besides
- `PASTEUP_INPUT_FOLDER`: prefills the input-folder field, e.g.
`PASTEUP_INPUT_FOLDER=~/Pictures/clip-art pasteup`.
- `PASTEUP_ALLOWED_HOSTS`: comma-separated host names to accept besides
`localhost`, `127.0.0.1` and `[::1]`. Only for serving the app under another
name on purpose.

### Development
## Development
```bash
cd image_grid_app
pip install -r requirements-dev.txt
pip install -e ".[dev]"
ruff check .
pytest
```
CI runs the same on Python 3.11 and 3.13, with ffmpeg installed so the
preview-video tests encode real files.
CI runs the same on Python 3.11 and 3.13, against a regular install of the
package and with ffmpeg present, so the preview-video tests encode real files.

Project layout:
- `src/pasteup/main.py`: the FastAPI app
- `src/pasteup/routes/`: the page and the `/api/jobs` endpoints
- `src/pasteup/services/`: scanning, page composition, collages, export, video
- `src/pasteup/models/`: request and response schemas
- `src/pasteup/templates/` and `src/pasteup/static/`: the UI
- `src/pasteup/cli.py`: the `pasteup` command
- `tests/`

---

Expand All @@ -74,7 +82,7 @@ Notes:

## Default Setting Values
Default UI values:
- input folder: empty (set `IMAGE_GRID_INPUT_FOLDER` to prefill it)
- input folder: empty (set `PASTEUP_INPUT_FOLDER` to prefill it)
- `page_width`: `3000`
- `page_height`: `3000`
- `gap`: `30`
Expand Down Expand Up @@ -361,6 +369,22 @@ Fixes:

---

## How images are loaded
Opening, background cleaning and page geometry live in
[mullion](https://github.com/sigrix-io/mullion), a small library Pasteup
depends on (`mullion~=0.2.1`, from PyPI).

`mullion.open_path()` is the one place a source image is opened. It composites
transparency onto white (a bare `convert("RGB")` drops the alpha and leaves the
black underneath showing) and applies EXIF orientation, so a phone photo is not
placed sideways. `mullion.clean_background()` is the border-seeded cleaner
described above, and `mullion.resolve_page_geometry()` turns `page_unit` and
`dpi` into the pixel size the exporter stamps. mullion's own suite tests these
directly; Pasteup's tests check the same claims through its composer and
exporter, so a bad mullion upgrade still fails here.

---

## License
Apache License 2.0, see [LICENSE](LICENSE). Security reports: see
[SECURITY.md](SECURITY.md).
12 changes: 6 additions & 6 deletions SECURITY.md
Original file line number Diff line number Diff line change
@@ -1,22 +1,22 @@
# Security

## Image Grid App is a local tool
## Pasteup is a local tool

The app reads and writes files at whatever paths it is given — that is its job.
Pasteup reads and writes files at whatever paths it is given — that is its job.
It has no accounts and no authentication, so run it only on your own machine,
bound to `127.0.0.1` (uvicorn's default):
bound to `127.0.0.1` (the default):

```bash
uvicorn app.main:app # fine: only this machine can reach it
uvicorn app.main:app --host 0.0.0.0 # don't: anyone on your network can read and write your files
pasteup # fine: only this machine can reach it
pasteup --host 0.0.0.0 # don't: anyone on your network can read and write your files
```

Two guards back that up:

- **Host check.** Requests are only answered when addressed to `localhost` or
`127.0.0.1`. That stops a web page that points its own domain at your machine
(DNS rebinding) from driving the app through your browser. If you deliberately
serve the app under another name, list it in `IMAGE_GRID_ALLOWED_HOSTS`
serve the app under another name, list it in `PASTEUP_ALLOWED_HOSTS`
(comma-separated).
- **Bounded requests.** Output files stay inside the output folder you chose, and
page size and video length are capped, so a single request cannot overwrite
Expand Down
84 changes: 0 additions & 84 deletions image_grid_app/README.md

This file was deleted.

Empty file.
5 changes: 0 additions & 5 deletions image_grid_app/requirements-dev.txt

This file was deleted.

11 changes: 0 additions & 11 deletions image_grid_app/requirements.txt

This file was deleted.

7 changes: 0 additions & 7 deletions image_grid_app/ruff.toml

This file was deleted.

11 changes: 0 additions & 11 deletions image_grid_app/tests/conftest.py

This file was deleted.

62 changes: 62 additions & 0 deletions pyproject.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
[build-system]
requires = ["hatchling>=1.27"]
build-backend = "hatchling.build"

[project]
name = "pasteup"
dynamic = ["version"]
description = "Turn a folder of clip art into listing images: preview sheets, cover collages and preview videos."
readme = "README.md"
license = "Apache-2.0"
license-files = ["LICENSE"]
requires-python = ">=3.11"
# Compatible-release pins: bug-fix releases flow in, while anything that may
# change behaviour (a new minor of a 0.x package, a new major elsewhere) is a
# deliberate bump. mullion is pre-1.0, so its minor is pinned too.
dependencies = [
"fastapi~=0.143.2",
"uvicorn~=0.54.0",
"jinja2~=3.1",
"pillow~=12.3",
"pydantic~=2.14",
"mullion~=0.2.1",
]
classifiers = [
"Development Status :: 3 - Alpha",
"Framework :: FastAPI",
"Intended Audience :: End Users/Desktop",
"Programming Language :: Python :: 3",
"Topic :: Multimedia :: Graphics",
]

[project.optional-dependencies]
dev = [
"pytest~=9.1",
# starlette.testclient uses httpx2; plain httpx is deprecated there.
"httpx2~=2.13",
"ruff==0.17.1",
]

[project.scripts]
pasteup = "pasteup.cli:main"

[project.urls]
Source = "https://github.com/ftymoshchuk/pasteup"

[tool.hatch.version]
path = "src/pasteup/__init__.py"

[tool.hatch.build.targets.wheel]
packages = ["src/pasteup"]

[tool.pytest.ini_options]
testpaths = ["tests"]

[tool.ruff]
target-version = "py311"

[tool.ruff.lint]
# Pyflakes plus pycodestyle's error classes: real bugs such as undefined names
# and unused imports, without a formatting pass over existing code. Widening the
# rule set, or adding `ruff format --check`, is a separate decision.
select = ["E4", "E7", "E9", "F"]
3 changes: 3 additions & 0 deletions src/pasteup/__init__.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
"""Pasteup: turn a folder of clip art into listing images."""

__version__ = "0.1.0"
Loading
Loading