Source-of-truth repo for the public publisher extensions consumed by publoader. The repo is also packaged as a Docker image (ardax/publoader-extensions) that ships every src/<ext>/ tree into the main container's extensions volume on startup.

src/
  <extension>/
    <extension>.py        # entrypoint module — must match the directory name
    manifest.json         # metadata + permissions (see below)
    manga_id_map.json     # MangaDex id ↔ publisher id mapping
    override_options.json # optional manual overrides
    requirements.txt      # extension-specific deps
schedule.json             # daily run timings
sync_extensions.py        # used by the Docker sidecar — do not invoke manually
tools/
  validate_manifests.py   # CI: schema-checks every manifest
  smoke_load.py           # CI: imports each entrypoint under publoader.api
.github/workflows/        # CI pipeline

You should be comfortable with:

• Python 3.10+
• HTTP scraping / API consumption for the publisher you're targeting

This guide is updated over time. If something is wrong or unclear, open an issue or a PR.

The fastest start is to copy an existing extension directory (e.g. mangaplus) and rename it. Read through a working extension before starting your own — the shape of the Extension class and how it returns chapters is best learned by example.

You are responsible for rate-limiting your own extension. The runner won't throttle you on the publisher's behalf.

<extension> must be lowercase ASCII with no punctuation other than _. The directory name, the entrypoint filename (without .py), and the manifest.json name field must all match. The runner skips anything that doesn't satisfy this.

Every extension must ship a manifest.json next to its entrypoint. CI (tools/validate_manifests.py) rejects PRs where this file is missing or malformed. Minimum shape:

{
  "name": "mangaplus",
  "version": "0.2.04",
  "publoader_api": "^1.0.0",
  "entrypoint": "mangaplus.py",
  "class_name": "Extension",
  "mangadex_group_id": "4f1de6a2-f0c5-4ac5-bce5-02c7dbb67deb",
  "languages": ["en", "es"],
  "allowed_hosts": [
    "jumpg-webapi.tokyo-cdn.com",
    "mangaplus.shueisha.co.jp"
  ],
  "permissions": {
    "network": true,
    "filesystem_read": ["manga_id_map.json", "override_options.json"],
    "filesystem_write": [],
    "subprocess": false
  },
  "schedule": {
    "hour": 15,
    "minute": 5,
    "timezone": "UTC"
  },
  "data_files": {
    "manga_id_map": "manga_id_map.json",
    "override_options": "override_options.json"
  },
  "maintainers": ["your-github-handle"],
  "homepage": "https://example.com/"
}

Maps MangaDex manga UUIDs to the publisher's internal identifiers. The schema varies per publisher — pick whichever fits your data:

// uuid_to_list — one MangaDex id covers many publisher ids
{"333f4d22-7753-4e3b-b0da-0a69b2cdce4f": ["100001", "200008"]}

// uuid_to_string — one-to-one
{"333f4d22-7753-4e3b-b0da-0a69b2cdce4f": "100001"}

// id_to_uuid — publisher id is the primary key
{"100001": "333f4d22-7753-4e3b-b0da-0a69b2cdce4f"}

This file is the canonical tracker list — only mappings in here are uploaded.

Optional. Used for manual overrides where the source doesn't conform to MangaDex's chapter format. Your code only needs to use these keys when the fields apply to your publisher:

{
  "empty": [],
  "noformat": [],
  "custom": {"series_id": "regex"},
  "same": {"chapter_to_keep_id": ["other_chapter_id"]},
  "custom_language": {},
  "multi_chapters": {"chapter_id": ["chapter_number"]},
  "override_chapter_numbers": {"chapter_id": "overridden_chapter_number"}
}

The runner only reads same, custom_language, multi_chapters, and override_chapter_numbers. Everything else is for the extension's own use.

Add your extension to /schedule.json at the repo root:

{
  "mangaplus": {
    "day": 0,
    "hour": 15,
    "minute": 5
  }
}

day is optional. When present it is the day-of-week index (Monday=0, Sunday=6) — every Tuesday at 15:05 is {"day": 1, "hour": 15, "minute": 5}.

Operators can override the daily timing per-extension at runtime from Discord (/schedule set <ext> <hour> <minute> [day]) — the override lives in publoader's SQLite state DB and survives restarts. The schedule.json shipped here is the fallback, not the final word.

The legacy run_at method on the extension class is ignored when schedule.json defines a timing for that extension.

Use whatever modules you need, but list them in your extension's requirements.txt. publoader installs each extension's requirements.txt on startup (skipping anything already satisfied).

The class must be named Extension. The runner instantiates it once per run with at least an extension_dirpath: Path keyword.

from pathlib import Path

class Extension:
    def __init__(self, extension_dirpath: Path, **kwargs):
        ...

None of these methods take parameters (apart from self).

Wrong return types skip the run.

def update_external_data(
    self,
    posted_chapter_ids: List[str],
    fetch_all_chapters: bool,
    **kwargs,
) -> None:
    ...

posted_chapter_ids is the set of chapters already on MangaDex from previous runs. fetch_all_chapters is True during a clean reconcile. **kwargs is required — publoader may pass more keyword arguments as the API grows.

When a chapter that publoader previously uploaded is no longer in your get_all_chapters() return value, publoader does not delete it. It strips the chapter's externalUrl on MangaDex (so the publisher link goes away) and leaves the in-page info card that was uploaded at first commit. The DB row moves to the to_unavailable collection. Duplicate cleanups still hard-delete.

You don't need to do anything new — just keep returning the current set of on-source chapters from get_all_chapters(). The runner handles the rest.

Import from the stable public API surface:

from publoader.api import Chapter, Manga

Older imports (from publoader.models.dataclasses import Chapter, Manga) still work but publoader.api is the one we'll keep guaranteeing across versions. publoader.api.__api_version__ tells you what surface you're getting.

Optional[...] fields can be None. The rest are required.

__version__ must be defined at module level so the runner can include it in logs.

The logger must be set up using setup_extension_logs:

from publoader.api import setup_extension_logs

setup_extension_logs(
    logger_name="<extension_name>",
    logger_filename="<extension_name>",
)

from publoader.api import (
    open_manga_id_map,
    open_title_regex,
    find_key_from_list_value,
    chapter_number_regex,
    create_new_event_loop,
    PubloaderWebhook,
)

Extensions are loaded with a static AST check that rejects modules using eval, exec, compile, __import__, subprocess, ctypes, and a few other footguns. The scan is not a sandbox — operators still have to trust this repo — but it catches obvious mistakes and accidental imports.

If your extension genuinely needs a banned construct, open an issue first.

python tools/validate_manifests.py     # schema-checks every src/*/manifest.json
python tools/smoke_load.py             # imports each entrypoint under publoader.api stubs

Both are gated on .github/workflows/extension-tests.yml.

Open a PR against master. Format with Black using defaults. Your extension must:

1. Have a valid manifest.json (CI enforces this).
2. Smoke-import cleanly (CI enforces this).
3. Run successfully against your publisher before merge (operator-verified).

Erroneous extensions are skipped at runtime, not rejected outright — but please don't ship anything you haven't run yourself.