Metadata-Version: 2.4
Name: webmentions
Version: 0.1.1
Summary: A general-purpose library to add Webmentions support to your website
Author-email: Fabio Manganiello <fabio@manganiello.tech>
License-Expression: AGPL-3.0-or-later
Project-URL: homepage, https://git.platypush.tech/blacklight/webmentions
Keywords: webmentions,microformats,indieweb,federation
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Development Status :: 3 - Alpha
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests
Requires-Dist: beautifulsoup4
Requires-Dist: mf2py
Provides-Extra: db
Requires-Dist: sqlalchemy; extra == "db"
Provides-Extra: fastapi
Requires-Dist: fastapi; extra == "fastapi"
Requires-Dist: uvicorn; extra == "fastapi"
Requires-Dist: python-multipart; extra == "fastapi"
Provides-Extra: flask
Requires-Dist: flask; extra == "flask"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: sqlalchemy; extra == "test"
Dynamic: license-file

![Webmentions](https://s3.fabiomanganiello.com/fabio/img/webmentions.png)

A general-purpose library to add Webmentions support to your website.

This library implements support for
[Webmentions](https://www.w3.org/TR/2016/WD-webmention-20160112/), a W3C
recommendation for federated mentions, comments and reactions on the Web.

The underlying mechanism of Webmentions is relatively simple:

- Alice publishes an article A1 on her blog A

- Bob reads A1 and mentions it in an article B1 on his blog B

- If both A and B support Webmentions, then:

  - A exposes an HTTP endpoint to receive mention notifications, and that
    endpoint is advertised on A1 as a `rel="webmention"` link in the page
    or a `Link` header in the HTTP response.

  - When Bob saves B1, its blog will scan for links in the page, discover
    which services expose a Webmention endpoint, and send a Webmention to
    A to notify them of the mention.

  - A will receive the notification and, if it accepts comments from B, the
    comment or the reaction will be rendered as a response on A1.

## Installation

For the base installation:

```bash
pip install webmentions
```

## Usage

This library provides the bindings to send and process Webmentions. It is
agnostic about how the Webmentions are stored and rendered, but it provides
a few helpers for common frameworks.

Some examples are provided under the
[examples](https://git.platypush.tech/blacklight/webmentions/src/branch/main/src/python/examples)
directory.

### SQLAlchemy + FastAPI

```bash
pip install "webmentions[db,fastapi]"
```

```python
from fastapi import FastAPI
from webmentions import WebmentionsHandler
from webmentions.storage.adapters.db import init_db_storage
from webmentions.server.adapters.fastapi import bind_webmentions_endpoint

app = FastAPI()

# Replace this with your own database URL, or an existing engine.
# Extra arguments passed to init_db_storage will be passed to create_engine
storage = init_db_storage(engine="sqlite:////tmp/webmentions.db")

# Your Webmentions handler
handler = WebmentionsHandler(
    storage=storage,
    # This should match the public base URL of your site
    base_url=f"https://example.com",
)

# ...Initialize your Web app here...

# Bind a POST /webmention to your FastAPI app
bind_webmentions_endpoint(app, handler)
```

### SQLAlchemy + Flask

```bash
pip install "webmentions[db,flask]"
```

```python
from flask import Flask
from webmentions import WebmentionsHandler
from webmentions.storage.adapters.db import init_db_storage
from webmentions.server.adapters.flask import bind_webmentions_endpoint

app = Flask(__name__)

# Replace this with your own database URL, or an existing engine.
# Extra arguments passed to init_db_storage will be passed to create_engine
storage = init_db_storage(engine="sqlite:////tmp/webmentions.db")

# Your Webmentions handler
handler = WebmentionsHandler(
    storage=storage,
    # This should match the public base URL of your site
    base_url=f"https://example.com",
)

# ...Initialize your Web app here...

# Bind a POST /webmention to your Flask app
bind_webmentions_endpoint(app, handler)
```

## Tests

```bash
pip install -e ".[tests]"
pytest tests
```
