oEmbedPyを使って、ドキュメントに○○○を埋め込もう

author:

Kazuya Takei / @attakei

date:

2025-11-08

event:

PyCon mini 東海 2025

hashtags:

#pycontokai

Overview

Who am I ?

Kazuya Takei

• attakei (X, GitHub, etc)

• OSS Writer

  • Sphinx extensions

  • Client library

• Speaker of 東海2024

  • pytestでRust製CLIをe2eテストしてみよう

I talked at PyCon JP 2025 Day 1

https://slides.attakei.net/pyconjp-2025/

oEmbed

When you want to embed move on YouTube

I can get HTML to share from website, but it is troublesome.

https://www.youtube.com/watch?v=t-5nKuouoMo

1. Open in browser https://www.youtube.com/watch?v=t-5nKuouoMo

2. Click "share".

3. Click "embed".

4. Copy code.

What is oEmbed ?

https://oembed.com/

oEmbed is a format for allowing an embedded representation of a URL on third party sites. The simple API allows a website to display embedded content (such as photos or videos) when a user posts a link to that resource, without having to parse the resource directly.

Many providers!

https://oembed.com/providers.json

Bluesky, CodePen, Dailymotion, Docswell, Facebook, Gyazo, Instagram, SlideShare, SpeakerDeck, YouTube, X, and more

Convenience

I can get embed HTML by API request.

Example: Using PyCon JP TV

https://www.youtube.com/watch?v=t-5nKuouoMo

Convenience

By manual

1. Open in browser https://www.youtube.com/watch?v=t-5nKuouoMo

2. Click "share".

3. Click "embed".

4. Copy code.

Convenience

By oEmbed

1. Call https://www.youtube.com/oembed?url={URL}

$ uvx --from=httpie http https://www.youtube.com/oembed url=='https://www.youtube.com/watch?v=t-5nKuouoMo' | jq -r '.html'
<iframe
    width="200"
    height="113"
    src="https://www.youtube.com/embed/t-5nKuouoMo?feature=oembed"
    frameborder="0"
    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
    referrerpolicy="strict-origin-when-cross-origin"
    allowfullscreen
    title="PyCon JP TV #58: 地域コミュニティ座談会">
</iframe>

oEmbedPy

"Morden" oEmbed Python client

https://oembedpy.readthedocs.io/

• Return dataclass object

• Support https://oembed.com/providers.json

• Support auto discovery

• Integration for document builder

Usage

# /// script
# dependencies = [
#   "oembedpy",
# ]
# ///
from oembedpy.application import Oembed

oembed = Oembed()
oembed.init()
content = oembed.fetch("https://www.youtube.com/watch?v=t-5nKuouoMo")
print(content.html)

Usage

uvx --from='oembedpy[cli]' oembed.py https://www.youtube.com/watch?v=t-5nKuouoMo
Installed 15 packages in 172ms
type:             video
version:          1.0
html:             <iframe width="200" height="113" src="https://www.youtube.com/embed/t-5nKuouoMo?feature=oembed" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen title="PyCon JP TV #58: 地域コミュニティ座談会"></iframe>
width:            200
height:           113
title:            PyCon JP TV #58: 地域コミュニティ座談会
author_name:      PyCon JP
author_url:       https://www.youtube.com/@PyConJP
provider_name:    YouTube
provider_url:     https://www.youtube.com/
cache_age:        None
thumbnail_url:    https://i.ytimg.com/vi/t-5nKuouoMo/hqdefault.jpg
thumbnail_width:  480
thumbnail_height: 360

Integration for document

Sphinx integration

pip install 'oembedpy[sphinx]'

extensions = [
    "oembedpy.adapters.sphinx",
]

Integration for document

Sphinx integration

.. oembed:: https://www.youtube.com/watch?v=t-5nKuouoMo
    :maxwidth: 960
    :maxheight: 640

Integration for document

Sphinx integration

.. oembed:: https://x.com/PyConTokai/status/1976619849364189271

Python好き集まれ！🐍
PyCon mini 東海 2025 が11/8(土)に名古屋・栄で開催。
実践的なハンズオン＆多彩なトークで学びを深めよう。
学生割・お弁当付き・懇親会あり🍱🎓
🎫 チケット好評販売中！

— PyCon mini 東海 (@PyConTokai) October 10, 2025

Integration for document

Sphinx integration

.. oembed:: https://bsky.app/profile/did:plc:tjf4apt65s75xiojhiqzvcan/post/3m526oyp3q225

ミッションその4: 手羽先を食べる #青空ごはん部 PyCon mini 東海の前夜祭で、風来坊で手羽先&鶏鍋+きしめん

— kAZUYA kAKEI (@attakei.dev) 2025-11-07T13:28:57.489Z

Integration for document

Q: I don't use Sphinx!!!

A: OK, do you use MkDocs?

Integration for document

MkDocs Integration

pip install 'oembedpy[mkdocs]'

plugins:
  # - oembedpy
  - oembedpy:
    fallback_type: true

Integration for document

MkDocs Integration

```oembed
https://bsky.app/profile/did:plc:tjf4apt65s75xiojhiqzvcan/post/3m526oyp3q225
```

ミッションその4: 手羽先を食べる #青空ごはん部 PyCon mini 東海の前夜祭で、風来坊で手羽先&鶏鍋+きしめん

— kAZUYA kAKEI (@attakei.dev) 2025-11-07T13:28:57.489Z

Why did I make it ?

There are already python implementations

pyoembed

• Last update is 8 years ago

• Classifier is Python 2 only!!

pyembed

• Last update is 5 years ago

• Classifier is Python 2 and Python 3.3!!

python-oembed

• Last update is 9 years ago

• Classifier is Python 2.5, 2.6 and 3.4!!

What do you do if there is not lib matched for you ?

Thank you

attakei/oEmbedPy