# hhursev/recipe-scrapers architecture

> Architecture diagram of the GitHub repository hhursev/recipe-scrapers, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hhursev/recipe-scrapers
- Repository: https://github.com/hhursev/recipe-scrapers

## Overview

recipe-scrapers is a Python library that turns recipe-page HTML into a consistent recipe API. The main workflow accepts HTML and its source URL (or optionally fetches a page), selects a site-specific scraper, parses recipe fields, and exposes structured results such as JSON. Schema.org and OpenGraph parsing, ingredient grouping, normalization helpers, configurable plugins, and image selection support that workflow. The graph combines README-documented behavior with SOURCE INDEX references; unsampled site implementations and plugin wiring are represented only where documented or indexed.

Main entry points: [`recipe_scrapers/_abstract.py`](https://github.com/hhursev/recipe-scrapers/blob/main/recipe_scrapers/_abstract.py) (Scraper base), [`recipe_scrapers`](https://github.com/hhursev/recipe-scrapers/tree/main/recipe_scrapers) (Site-specific scrapers), [`recipe_scrapers/__init__.py`](https://github.com/hhursev/recipe-scrapers/blob/main/recipe_scrapers/__init__.py) (Public API), [`recipe_scrapers/plugins/_interface.py`](https://github.com/hhursev/recipe-scrapers/blob/main/recipe_scrapers/plugins/_interface.py) (Plugin interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and dispatch"]
  node_api["Public API<br/>[__init__.py]"]
  node_factory["Scraper factory<br/>[_factory.py]"]
  node_site_registry["Supported-site registry<br/>[__init__.py]"]
end

subgraph group_scrapers["Site scrapers"]
  node_scraper_modules["Site-specific scrapers"]
end

subgraph group_parsing["Parsing and fields"]
  node_abstract["Scraper base<br/>[_abstract.py]"]
  node_schema["Schema.org parser<br/>[_schemaorg.py]"]
  node_opengraph["OpenGraph parser<br/>[_opengraph.py]"]
  node_utils["Parsing utilities<br/>[_utils.py]"]
  node_grouping["Ingredient grouping<br/>[_grouping_utils.py]"]
  node_wprm["WPRM support<br/>[_wprm.py]"]
  node_exceptions["Domain exceptions<br/>[_exceptions.py]"]
  node_version["Package version<br/>[__version__.py]"]
end

subgraph group_extensions["Plugins and settings"]
  node_plugin_interface["Plugin interface<br/>[_interface.py]"]
  node_image_plugin["Best-image selection<br/>[best_image.py]"]
  node_stripper_plugin["HTML tag stripping"]
  node_static_plugin["Static-value handling<br/>[static_values.py]"]
  node_settings["Runtime settings<br/>[__init__.py]"]
end

node_user(("Library caller"))
node_websites(("Recipe websites"))

node_user -->|"provides HTML"| node_api
node_user -->|"requests scrape"| node_api
node_api -->|"selects scraper"| node_factory
node_api -->|"looks up host"| node_site_registry
node_site_registry -->|"dispatches host"| node_scraper_modules
node_scraper_modules -->|"extends base"| node_abstract
node_abstract -->|"parses schema"| node_schema
node_abstract -->|"parses metadata"| node_opengraph
node_abstract -->|"reads settings"| node_settings
node_schema -->|"uses helpers"| node_utils
node_scraper_modules -->|"uses helpers"| node_utils
node_scraper_modules -->|"groups ingredients"| node_grouping
node_scraper_modules -->|"uses WPRM"| node_wprm
node_abstract -->|"raises errors"| node_exceptions
node_exceptions -->|"formats version"| node_version
node_abstract -->|"checks and applies"| node_plugin_interface
node_plugin_interface -->|"plugin contract"| node_image_plugin
node_plugin_interface -->|"plugin contract"| node_stripper_plugin
node_plugin_interface -->|"plugin contract"| node_static_plugin
node_image_plugin -->|"reads settings"| node_settings
node_stripper_plugin -->|"reads settings"| node_settings
node_static_plugin -->|"handles exceptions"| node_exceptions
node_api -.->|"may fetch HTML"| node_websites

click node_api "https://github.com/hhursev/recipe-scrapers/blob/main/recipe_scrapers/__init__.py"
click node_factory "https://github.com/hhursev/recipe-scrapers/blob/main/recipe_scrapers/_factory.py"
click node_site_registry "https://github.com/hhursev/recipe-scrapers/blob/main/recipe_scrapers/__init__.py"
click node_scraper_modules "https://github.com/hhursev/recipe-scrapers/tree/main/recipe_scrapers"
click node_abstract "https://github.com/hhursev/recipe-scrapers/blob/main/recipe_scrapers/_abstract.py"
click node_schema "https://github.com/hhursev/recipe-scrapers/blob/main/recipe_scrapers/_schemaorg.py"
click node_opengraph "https://github.com/hhursev/recipe-scrapers/blob/main/recipe_scrapers/_opengraph.py"
click node_utils "https://github.com/hhursev/recipe-scrapers/blob/main/recipe_scrapers/_utils.py"
click node_grouping "https://github.com/hhursev/recipe-scrapers/blob/main/recipe_scrapers/_grouping_utils.py"
click node_wprm "https://github.com/hhursev/recipe-scrapers/blob/main/recipe_scrapers/_wprm.py"
click node_exceptions "https://github.com/hhursev/recipe-scrapers/blob/main/recipe_scrapers/_exceptions.py"
click node_version "https://github.com/hhursev/recipe-scrapers/blob/main/recipe_scrapers/__version__.py"
click node_plugin_interface "https://github.com/hhursev/recipe-scrapers/blob/main/recipe_scrapers/plugins/_interface.py"
click node_image_plugin "https://github.com/hhursev/recipe-scrapers/blob/main/recipe_scrapers/plugins/best_image.py"
click node_stripper_plugin "https://github.com/hhursev/recipe-scrapers/blob/main/recipe_scrapers/plugins/html_tags_stripper.py"
click node_static_plugin "https://github.com/hhursev/recipe-scrapers/blob/main/recipe_scrapers/plugins/static_values.py"
click node_settings "https://github.com/hhursev/recipe-scrapers/blob/main/recipe_scrapers/settings/__init__.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_factory,node_site_registry toneBlue
class node_scraper_modules toneAmber
class node_abstract,node_schema,node_opengraph,node_utils,node_grouping,node_wprm,node_exceptions,node_version toneMint
class node_plugin_interface,node_image_plugin,node_stripper_plugin,node_static_plugin,node_settings toneRose
class node_user,node_websites toneIndigo
```

## Components

### Entry and dispatch

- [Public API](https://github.com/hhursev/recipe-scrapers/blob/main/recipe_scrapers/__init__.py): `recipe_scrapers/__init__.py`
- [Scraper factory](https://github.com/hhursev/recipe-scrapers/blob/main/recipe_scrapers/_factory.py): `recipe_scrapers/_factory.py`
- [Supported-site registry](https://github.com/hhursev/recipe-scrapers/blob/main/recipe_scrapers/__init__.py): `recipe_scrapers/__init__.py`

### Site scrapers

- [Site-specific scrapers](https://github.com/hhursev/recipe-scrapers/tree/main/recipe_scrapers): `recipe_scrapers`

### Parsing and fields

- [Scraper base](https://github.com/hhursev/recipe-scrapers/blob/main/recipe_scrapers/_abstract.py): `recipe_scrapers/_abstract.py`
- [Schema.org parser](https://github.com/hhursev/recipe-scrapers/blob/main/recipe_scrapers/_schemaorg.py): `recipe_scrapers/_schemaorg.py`
- [OpenGraph parser](https://github.com/hhursev/recipe-scrapers/blob/main/recipe_scrapers/_opengraph.py): `recipe_scrapers/_opengraph.py`
- [Parsing utilities](https://github.com/hhursev/recipe-scrapers/blob/main/recipe_scrapers/_utils.py): `recipe_scrapers/_utils.py`
- [Ingredient grouping](https://github.com/hhursev/recipe-scrapers/blob/main/recipe_scrapers/_grouping_utils.py): `recipe_scrapers/_grouping_utils.py`
- [WPRM support](https://github.com/hhursev/recipe-scrapers/blob/main/recipe_scrapers/_wprm.py): `recipe_scrapers/_wprm.py`
- [Domain exceptions](https://github.com/hhursev/recipe-scrapers/blob/main/recipe_scrapers/_exceptions.py): `recipe_scrapers/_exceptions.py`
- [Package version](https://github.com/hhursev/recipe-scrapers/blob/main/recipe_scrapers/__version__.py): `recipe_scrapers/__version__.py`

### Plugins and settings

- [Plugin interface](https://github.com/hhursev/recipe-scrapers/blob/main/recipe_scrapers/plugins/_interface.py): `recipe_scrapers/plugins/_interface.py`
- [Best-image selection](https://github.com/hhursev/recipe-scrapers/blob/main/recipe_scrapers/plugins/best_image.py): `recipe_scrapers/plugins/best_image.py`
- [HTML tag stripping](https://github.com/hhursev/recipe-scrapers/blob/main/recipe_scrapers/plugins/html_tags_stripper.py): `recipe_scrapers/plugins/html_tags_stripper.py`
- [Static-value handling](https://github.com/hhursev/recipe-scrapers/blob/main/recipe_scrapers/plugins/static_values.py): `recipe_scrapers/plugins/static_values.py`
- [Runtime settings](https://github.com/hhursev/recipe-scrapers/blob/main/recipe_scrapers/settings/__init__.py): `recipe_scrapers/settings/__init__.py`

### Other components

- **Library caller**
- **Recipe websites**

## Connections

- Library caller → Public API: provides HTML (evidence: `README.rst`)
- Library caller → Public API: requests scrape (evidence: `README.rst`)
- Public API → Scraper factory: selects scraper (evidence: `recipe_scrapers/__init__.py`)
- Public API → Supported-site registry: looks up host (evidence: `recipe_scrapers/__init__.py`)
- Supported-site registry → Site-specific scrapers: dispatches host (evidence: `recipe_scrapers/__init__.py`)
- Site-specific scrapers → Scraper base: extends base (evidence: `recipe_scrapers/aberlehome.py`)
- Scraper base → Schema.org parser: parses schema (evidence: `recipe_scrapers/_abstract.py`)
- Scraper base → OpenGraph parser: parses metadata (evidence: `recipe_scrapers/_abstract.py`)
- Scraper base → Runtime settings: reads settings (evidence: `recipe_scrapers/_abstract.py`)
- Schema.org parser → Parsing utilities: uses helpers (evidence: `recipe_scrapers/_schemaorg.py`)
- Site-specific scrapers → Parsing utilities: uses helpers (evidence: `recipe_scrapers/aberlehome.py`)
- Site-specific scrapers → Ingredient grouping: groups ingredients (evidence: `recipe_scrapers/acouplecooks.py`)
- Site-specific scrapers → WPRM support: uses WPRM (evidence: `recipe_scrapers/abeautifulmess.py`)
- Scraper base → Domain exceptions: raises errors (evidence: `recipe_scrapers/_abstract.py`)
- Domain exceptions → Package version: formats version (evidence: `recipe_scrapers/_exceptions.py`)
- Scraper base → Plugin interface: checks and applies (evidence: `recipe_scrapers/_abstract.py`)
- Plugin interface → Best-image selection: plugin contract (evidence: `recipe_scrapers/plugins/best_image.py`)
- Plugin interface → HTML tag stripping: plugin contract (evidence: `recipe_scrapers/plugins/html_tags_stripper.py`)
- Plugin interface → Static-value handling: plugin contract (evidence: `recipe_scrapers/plugins/static_values.py`)
- Best-image selection → Runtime settings: reads settings (evidence: `recipe_scrapers/plugins/best_image.py`)
- HTML tag stripping → Runtime settings: reads settings (evidence: `recipe_scrapers/plugins/html_tags_stripper.py`)
- Static-value handling → Domain exceptions: handles exceptions (evidence: `recipe_scrapers/plugins/static_values.py`)
- Public API → Recipe websites: may fetch HTML (evidence: `README.rst`)
