前のページへ
Python-Markdown3.3.6 		次のページへ
Extensions(拡張機能)

Python-Markdown 3.3.6

《 初回公開：2022/03/26 , 最終更新：未 》

PythonにはPython-MarkdownというMarkdownドキュメントをHTMLテキストに変換するライブラリがあって 以前に、旧バージョンの記事を書いたのだが

Python-Markdownも3.3.6になってしまっていろいろ変更もあったみたいなので、復習もこめて改めて3.3.6のドキュメントを読み直してまとめてみた。

【　目次　】

インストール

コマンドラインから

pip install markdown

PythonライブラリとしてMarkdownを使う(Library Reference)

基本コード

import markdown
html = markdown.markdown(your_text_string)

更に、具体例として

import markdown

makedown_text = u'''
import markdown

makedown_text = u'''
ドキュメントタイトル
===================

Markdownについては

- [MarkdownでHTMLを簡単に - 愚鈍人](http://ichitcltk.hustle.ne.jp/gudon2/index.php?pageType=file&id=markdown_memo)
- [MarkdownでHTMLを簡単に　- Sublime Tex　編 - 愚鈍人](http://ichitcltk.hustle.ne.jp/gudon2/index.php?pageType=file&id=sublime_markdown)
'''

html = markdown.markdown(makedown_text)
print(html)

実行結果

<h1>ドキュメントタイトル</h1>
<p>Markdownについては</p>
<ul>
<li><a href="http://ichitcltk.hustle.ne.jp/gudon2/index.php?pageType=file&amp;id=markdown_memo">MarkdownでHTMLを簡単に - 愚鈍人</a></li>
<li><a href="http://ichitcltk.hustle.ne.jp/gudon2/index.php?pageType=file&amp;id=sublime_markdown">MarkdownでHTMLを簡単に　- Sublime Tex　編 - 愚鈍人</a></li>
</ul>

もう少し詳しく

Python-Markdownは、2つのパブリック関数（markdown.markdownとmarkdown.markdownFromFile）を提供し、どちらもパブリッククラスmarkdown.Markdownをラップします。
一度に1つのドキュメントを処理する場合、これらの機能はニーズに対応します。
ただし、複数のドキュメントを処理する必要がある場合は、markdown.Markdownクラスの単一のインスタンスを作成し、それを介して複数のドキュメントを渡すことが有利な場合があります。
ただし、単一のインスタンスを使用する場合は、必ずresetメソッドを適切に呼び出してください（以下を参照）。

markdown.markdown(text [, **kwargs])

このmarkdown.markdown関数では、次のオプションを使用できます。

text

ソースUnicodeの文字列。 （必須）

重要

Python-Markdownは、入力としてUnicode文字列を想定し（一部の単純なASCIIバイナリ文字列は偶然の一致によってのみ機能する場合があります）、そして出力をUnicode文字列として返します。
バイナリ文字列を渡さないでください！
入力がエンコードされている場合（たとえば、UTF-8として）、それをデコードするのはユーザーの責任です。

例えば

with open("some_file.txt", "r", encoding="utf-8") as input_file:
text = input_file.read()
html = markdown.markdown(text)

出力をディスクに書き込みたい場合は、自分でエンコードする必要があります。

with open("some_file.html", "w", encoding="utf-8", errors="xmlcharrefreplace") as output_file:
    output_file.write(html)
extensions

extension(拡張機能)のリスト

Python-Markdownは、サードパーティがパーサーに拡張機能を記述して、構文に独自の追加または変更を追加するためのAPIを提供します。
使用可能な拡張機能のリストについては、拡張機能のドキュメントを参照してください。
拡張機能のリストには、拡張機能のインスタンスや拡張機能名の文字列が含まれる場合があります。

extensions=[MyExtClass(), 'myext', 'path.to.my.ext:MyExtClass']

Note

推奨される方法は、拡張機能のインスタンスを渡すことです。
文字列は、拡張クラスを直接（コマンドラインまたはテンプレートから）インポートできない場合にのみ使用してください。

extensionのインスタンスを渡す場合、各クラスインスタンスはmarkdown.extensions.Extensionのサブクラスである必要があり、extension_configsキーワードを使用するのではなく、クラスインスタンスを開始するときに構成オプションを定義する必要があります。
例えば

from markdown.extensions import Extension
class MyExtClass(Extension):
    # define your extension here...

markdown.markdown(text, extensions=[MyExtClass(option='value')])

拡張機能名が文字列として提供される場合、その文字列は、インストールされている拡張機能の登録済みエントリポイントか、Pythonのドット表記を使用したインポート可能なパスのいずれかである必要があります。

エントリポイントとして拡張機能に割り当てられた文字列名については、拡張機能に固有のドキュメントを参照してください。
ただ単に定義された名前を文字列として拡張機能のリストに含めるだけです。

たとえば、拡張機能にmyextという名前が割り当てられていて、拡張機能が正しくインストールされている場合は、次の手順を実行します。

markdown.markdown(text, extensions=['myext'])

拡張機能にエントリポイントが登録されていない場合は、代わりにPythonのドット表記を使用できます。
拡張機能は、PythonモジュールとしてPYTHONPATHにインストールする必要があります。
通常、名前にはクラス(名)を指定する必要があります。
クラスは名前の最後にあり、モジュールからコロンで区切る必要があります。

したがって、次のようにクラスをインポートする場合：

from path.to.module import MyExtClass

そして、次のように拡張機能をロードします。

markdown.markdown(text, extensions=['path.to.module:MyExtClass'])

モジュール内で拡張機能が1つだけ定義されていて、モジュールに拡張機能のインスタンスを返すmakeExtension関数が含まれている場合、クラス名は必要ありません。
たとえば、その場合、extensions = ['path.to.module']を実行できます。
目的の拡張機能のドキュメントを確認して、この機能がサポートされているかどうかを確認してください。

名前で（文字列として）拡張機能をロードする場合、extension_configsキーワードを使用することによってのみ、コンフィグレーションの設定(構成設定)を拡張機能に渡すことができます。

関連項目

拡張機能の作成を支援するためのExtension APIのドキュメントを参照。

extension_configs

extensionのコンフィグレーション設定のディクショナリ。 構成設定は、名前で（文字列として）ロードされた拡張機能にのみ渡されます。 拡張機能をクラスインスタンスとしてロードする場合、初期化時に構成設定をクラスに直接渡します。

Note

推奨される方法は、extension_configsキーワードをまったく使用する必要のない拡張機能のインスタンスを渡すことです。

構成設定の辞書は、次の形式である必要があります。

extension_configs = {
    'extension_name_1': {
        'option_1': 'value_1',
        'option_2': 'value_2'
    },
    'extension_name_2': {
        'option_1': 'value_1'
    }
}

拡張機能の名前を指定するときは、拡張機能をロードするためにextensionsキーワードで使用されているものとまったく同じ文字列を使用してください。
そうしないと、構成設定が拡張機能に適用されません。
つまり、エントリポイントをその場で使用したり、Pythonドット表記を他の場所で使用したりすることはできません。
どちらも特定の拡張機能に対して有効である可能性がありますが、Markdownによって同じ拡張機能として認識されることはありません。

その拡張機能の構成設定を指定する際のヘルプについては、使用している拡張機能に固有のドキュメントを参照してください。

output_format

出力フォーマット
サポートされている形式は

  • "xhtml": XHTMLスタイルのタグを出力. 既定値.
  • "html5": HTMLスタイルのタグを出力.

値は、小文字でも大文字でもかまいません。

tab_length
ソースのタブの長さ。既定値：4

markdown.markdownFromFile (**kwargs)

いくつかの例外を除いて、markdown.markdownFromFileはmarkdown.markdownと同じオプションを受け入れます。
テキスト（またはUnicode）文字列は受け入れません。
代わりに、次の必須オプションを受け入れます。

input (必須)

(markdown)ソース・テキストファイル

inputは次の3つのオプションのいずれかに設定できます。

ファイルシステム上の読み取り可能なファイルへのパスを含む文字列.
読み取り可能なfile-like object、
もしくは None (デフォルト) これはstdinから読み込みます。

output

出力が書き込まれるターゲット。
出力は、次の3つのオプションのいずれかに設定できます。

  • ファイルシステム上の書き込み可能ファイルへのパスを含む文字列,
  • 書き込み可能なfile-like object,
  • もしくは None (デフォルト) stdoutへ書き込みます。
encoding

ソーステキストファイルのエンコーディング。
デフォルトは「utf-8」です。
入力と出力には常に同じエンコーディングが使用されます。
xmlcharrefreplaceエラーハンドラーは、出力をエンコードするときに使用されます。

Note

これは、UnicodeのデコードとエンコードがPython-Markdownで行われる唯一の場所です。
このかなり単純なソリューションが特定のニーズを満たさない場合は、エンコード/デコードのニーズを処理するために独自のコードを作成することをお勧めします。

愚鈍人の独り言

file-like objectというのは

markdown.Markdown([**kwargs])

markdown.markdownクラスを初期化するときに、markdown.markdown関数と同じオプションを使用できますが、クラスは初期化時にソーステキスト文字列を受け入れません。
むしろ、ソーステキスト文字列を2つのインスタンスメソッドのいずれかに渡す必要があります。

警告

markdown.Markdownクラスのインスタンスは、それらが作成されたスレッド内でのみスレッドセーフです。
複数のスレッドから単一のインスタンスにアクセスしないでください。

Markdown.convert(source)

ソーステキストは、markdown.markdown関数のtext引数と同じ要件を満たしている必要があります。
文字列ごとにクラスの新しいインスタンスを作成せずに複数の文字列を処理する場合にも、このメソッドを使用する必要があります。

md = markdown.Markdown()
html1 = md.convert(text1)
html2 = md.convert(text2)

使用されているオプションや拡張機能によっては、パーサーは変換するために各呼び出しの間に状態をリセットする必要がある場合があります。

html1 = md.convert(text1)
md.reset()
html2 = md.convert(text2)

これを簡単にするために、呼び出しを チェーン(連結)させて一緒にリセットすることもできます。

html3 = md.reset().convert(text3)
Markdown.convertFile(**kwargs)

このメソッドの引数は、markdown.markdownFromFile関数（input、output、およびencoding）の同じ名前の引数と同じです。
convertメソッドと同様に、このメソッドを使用して、ドキュメントごとにクラスの新しいインスタンスを作成せずに、複数のファイルを処理するべきです。
convertの場合と同様に、convertFileを呼び出すたびに状態をリセットする必要がある場合があります。

ページのトップへ戻る