Jinja2 ile Jupyter Notebooks için Özel Şablonlar

Veri biliminde, çalışmalarınızın raporlarını karar vericilere veya teknik olmayan personele göstermeniz sıkça gerekir. Jupyter Notebook'unuzu kararlı bir PDF veya HTML belgeye dönüştürmek, Python veya Jupyter yüklü olmayan çalışma arkadaşlarına daha kolay aktarılabilir. Python, belgeleri dönüştürmek için nbconvert adlı bir kütüphane ve Jinja2 adlı bir şablon dili kullanır. Şablonlar, bir belgenin bir web sayfasında veya başka bir çıktı biçiminde nasıl görüntüleneceğini tanımlar. Şablonları nasıl özelleştireceğinizi anlamak, Notebook'larınızdan daha estetik raporlar hazırlamak için faydalıdır.

Jupyter notebook'lar, tarayıcınızda Python kodu çalıştırmanın bir yoludur. Python hakkında daha fazla bilgi edinmek isterseniz, ücretsiz Veri Bilimi için Python'a Giriş kursumuza mutlaka göz atın.

Bu derste aşağıdaki konuları ele alacaksınız:

• Şablonlar ve Jinja2 şablon tasarımcısı.
• Şablonların işlenmesi ve kalıtım.
• Notebook'larınızı dışa aktarmak için nbconvert kullanımı.
• Jupyter varsayılan şablonlarını HTML dışa aktarma için genişletmenin söz dizimi ve yapısı.
• LaTeX ve PDF biçimlerine dışa aktarmadaki farklılıklar.

Şablonlar Nedir?

Python wiki'den: "Şablonlama, özellikle web şablonlama, veriyi farklı biçimlerde temsil etmenin bir yoludur... Sıklıkla, şablon çözümleri bir belgeyi (şablon) ve veriyi içerir. Şablonlar genellikle son çıktıya çok benzer, gerçek veriler yerine yer tutucular vardır"

Jupyter Notebook, File -> Download As (Jupyter Lab'de Export Notebook As görürsünüz) kullanılarak kolayca dışa aktarılabilir. Bu seçenek, ana Jupyter ortamında tutulan varsayılan şablonları kullanır. Jinja2, bloklama ve dizgi kurallarını tanımlamak için Python'da güçlü bir şablon dilidir. Şablonların, girdinin nasıl işleneceğini söyleyen etiketlerle tanımlı bölümleri vardır. Şablon işlendiğinde, veriler değişkenlerin veya ifadelerin yerini alır.

Bir şablonun farklı bölümleri için sınırlayıcılar şunlardır:

• İfadeler için {% ... %}
• Şablon çıktısına yazdırılacak ifadeler için {{ ... }}
• Şablon çıktısına dahil edilmeyecek yorumlar için {# ... #}

Aşağıdaki kısa Jinja şablonu örneğine bakın (Jinja2 dokümantasyonu kaynaklı):

<!DOCTYPE html>

<html lang="en">

<head>

    {% block head %}
    <link rel="stylesheet" href="style.css" />
    <title>{% block title %}{% endblock %} - My Webpage </title>
    {% endblock %}
</head>

<body>

    <div id="content">{% block content %}{% endblock %}</div>
    <div id="footer">
        {% block footer %}
        &copy; Copyright 2008 by <a href="http://domain.invalid">you </a>.
        {% endblock %}
    </div>
</body>

</html>

Yukarıda görüldüğü gibi, şablonun büyük kısmı normal bir HTML belgesine benzer. Jinja'nın kodu bir şablon olarak yorumlaması için birkaç ekstra satıra ihtiyaç vardır. {% block head %}, HTML belgesinin head bölümünü ve bu şablonun biçimlendirmesini nasıl genişleteceğini tanımlar. {% block title %} bölümü, giriş başlığının nerede görüntüleneceğini açıklar. Ve {% endblock %} ibaresi, karşılık gelen şablon bloğunu sonlandırdığı için birden fazla yerde görünür.

Artık kendi özel şablonlarınızı oluşturmak için Jinja kullanmayı öğrenmeye hazırsınız!

Jinja'ya Giriş

Jinja, belgelerinizin nasıl görüntüleneceğini tanımlamanızı sağlayan bir şablon motorudur. Özellikle bu derste, Jupyter Notebook'unuzu Jinja şablonlarının yardımıyla nasıl dışa aktaracağınıza odaklanacaksınız.

Önce, Jinja2'den Template'i içe aktarın:

from jinja2 import Template

Şablonlarla Temel İşlemeyi Anlama

Jinja şablonlarında verileri işlemek oldukça basittir. Köşeli parantezler ve değişken adları kullanarak, verilerinizi şablonda görüntüleyebilirsiniz:

myTemplate = Template("My template is {{ something }}!")
myTemplate.render(something="awesome")

'My template is awesome!'

.render(input) çağrısı, şablonu Notebook'unuzda görüntülemenizi ve girdinizin şablondaki genel {{ something }} ifadesinin yerini almasını sağlar. Bu, Jinja'da expression kullanımına bir örnektir.

Jinja'nın yorumlayacağı bir Python statement'ı tanımlayarak bir şablonu daha dinamik kullanabilirsiniz.

myFancyTemplate = Template("Let's count to 10: {% for i in range(11) %}{{i}} " "{% endfor %}")
myFancyTemplate.render()

"Let's count to 10: 0 1 2 3 4 5 6 7 8 9 10 "

Dikkat bir for döngüsü tanımladınız ve şablon 0'dan 10'a kadar sayıları aralarda boşluk olacak şekilde işledi. {% expression %} söz dizimine sahip statement, özel bir şablon oluşturmak için oldukça esneklik sağlar.

Şablon Kalıtımı

Varsayılan Jupyter dışa aktarmalarını genişleten şablonlar yapmak için şablon kalıtımı kullanabilirsiniz. Kalıtım, programlamada, bir alt nesnede, üst sınıfın tanımlı işlevselliğini kullanabilen bir şey uygulayabilmeniz kavramıdır. Basit bir örnek olarak, havlama, yeme ve yürüme yetenekleri olan bir Dog nesneniz varsa, tüm bu öznitelikleri miras alan ve örneğin benekli gibi başkalarını ekleyen bir Dalmatian nesnesi oluşturmak için kalıtımı kullanabilirsiniz. Bu derste göreceğiniz üzere, kalıtım şablonlama için çok faydalıdır; çünkü çıktıyı özelleştirmek için genellikle yalnızca küçük değişikliklere ihtiyaç duyulur. Diğer kalıtım dillerinde olduğu gibi, Jinja da üst tanımlara erişmek için extends ve super gibi anahtar sözcükler kullanır.

Yukarıdaki örnek üst şablona, base.html adına sahip olana bakın:

<!DOCTYPE html>
<html lang="en">

<head>
    {% block head %}
    <link rel="stylesheet" href="style.css" />
    <title>{% block title %}{% endblock %} - My Webpage </title>
    {% endblock %}
</head>

<body>
    <div id="content">{% block content %}{% endblock %}</div>
    <div id="footer">
        {% block footer %}
        &copy; Copyright 2008 by <a href="http://domain.invalid">you </a>.
        {% endblock %}
    </div>
</body>

</html>

Bir alt şablon şöyle görünebilir (Jinja2 dokümantasyonu kaynaklı):

{% extends "base.html" %}

{% block title %}Index{% endblock %}

{% block head %}
    {{ super() }}
    <style type="text/css">
        .important { color: #336699; }
    </style>
{% endblock %}

{% block content %}
    <h1>Index</h1>
    <p class="important">
      Welcome to my awesome homepage.
    </p>
{% endblock %}

Alt şablonun {% extends "base.html" %} ile başladığına dikkat edin. Bu bildirim, Jinja şablon motoruna bu belgenin nasıl ele alınacağını söyler (bir HTML ve base.html'den kalıtımla). Bu alt şablonu kullanmak, ana sayfa için farklı öznitelikler belirtmeye olanak tanır (örneğin belirli bir CSS rengi). Ayrıca, head bloğunda alt şablonun super() çağrısıyla üst şablonun stilini devraldığını görebilirsiniz.

Jupyter Notebook'ları Dışa Aktarmak için nbconvert Kullanma

Artık şablonların temel söz dizimini ve kalıtımını anladığınıza göre, nbconvert ile Jupyter Notebook'unuzu nasıl dışa aktaracağınızı ve çıktıyı özelleştirmek için şablonları nasıl tanımlayacağınızı öğrenebilirsiniz.

Önce nbconvert'ü içe aktarın:

import nbconvert

nbconvert çeşitli biçimlerde çıktı oluşturabilir. Bu ders HTML ve LaTeX/PDF çıktısına odaklanacaktır. Çıktıyı notebook içinde görüntülemek için, IPython görüntüleme işlevini ve nbconvert çağrınızda --stdout seçeneğini kullanın.

example = !jupyter nbconvert --to html 'Example.ipynb' --stdout
from IPython.display import HTML, display
display(HTML('\n'.join(example)))

[NbConvertApp] Example.ipynb defterini html biçimine dönüştürüyor

Bu Notebook parçası, orijinal .ipynb dosyasına oldukça benzer görünüyor. Çıktı, başlıklar ve metinler Notebook'ta tipik olarak göründüğü şekilde, bağımsız bir belge olarak görüntülenir. Kod hücre blokları gri kutular halinde gösterilir ("Notebook stili" olarak bilinir). Görebileceğiniz ana fark, Jupyter varsayılan HTML şablonunun, etkin Notebook'larda olduğu gibi "Out:" istemlerini görüntülememesidir.

Jupyter Notebook'ları Dışa Aktarmak için nbconvert ve Özel Bir Alt Şablon Kullanma

Genellikle, Jupyter Notebook'un varsayılan dışa aktarma şablonlarını genişletmek ve çıktınızda küçük tasarım değişiklikleri yapmak istersiniz.

Örneğin, çıktından Markdown hücrelerini kaldıran bu basit şablona bakın (rmMkdwn.tpl adlı):

{% extends 'basic.tpl'%}

{% block markdowncell -%}
{% endblock markdowncell %}

Bir şablonu nbconvert'e uygulamak --template= seçeneğiyle yapılır:

example = !jupyter nbconvert --to html 'Example.ipynb' --template='rmMkdwn.tpl' --stdout
display(HTML('\n'.join(example)))

[NbConvertApp] Example.ipynb defterini html biçimine dönüştürüyor rmMkdwn.tpl gibi çok basit bir şablon bile çıktınızı olağanüstü şekilde özelleştirmenize yardımcı olabilir.

Hücreleri kırmızı çerçeve içine alan daha karmaşık bir şablona bakın (boxRed.tpl adlı):

{% extends 'full.tpl'%}

{% block any_cell %}
    <div style="border:thin solid red">
        {{ super() }}
    </div>
{% endblock any_cell %}

example = !jupyter nbconvert --to html 'Example.ipynb' --template='boxRed.tpl' --stdout
display(HTML('\n'.join(example)))

[NbConvertApp] Example.ipynb defterini html biçimine dönüştürüyor

Yukarıda, tek stil değişikliğinin her hücre etrafındaki kırmızı kutular olduğunu görebilirsiniz. full.tpl üst şablonundan her hücrenin bireysel stillerini koruduğundan emin olmak için super() kullanılır.

LaTeX ve PDF'e Dışa Aktarmak için Şablonlardaki Farklılıklar

LaTeX'te { } ve % özel karakterler olduğundan, (( )) ve * kullanmalısınız. Ayrıca varsayılan LaTeX şablonları, LaTeX belge sınıflarına karşılık gelen base.tplx, article.tplx ve report.tplx'tir.

Bir LaTeX alt şablonuyla Markdown hücrelerini kaldırmaya bakın:

((* extends 'article.tplx' *))

((* block markdowncell -*))
((* endblock markdowncell *))

nbconvert LaTeX veya PDF çıktısı üretebilir - PDF çıktısı LaTeX şablonlarından derlenir. Bu derste daha kolay görüntülemek için, rmMkdwn.tplx kullanarak PDF'ye dışa aktardığınızda ne olduğuna bakın.

!jupyter nbconvert --to pdf 'Example.ipynb' --template='rmMkdwn.tplx'
from IPython.display import IFrame
IFrame('Example.pdf', width=800, height=500)

[NbConvertApp] Converting notebook Example.ipynb to pdf
[NbConvertApp] Support files will be in Example_files/
[NbConvertApp] Making directory Example_files
[NbConvertApp] Writing 16047 bytes to notebook.tex
[NbConvertApp] Building PDF
[NbConvertApp] Running xelatex 3 times: ['xelatex', 'notebook.tex']
[NbConvertApp] Running bibtex 1 time: ['bibtex', 'notebook']
[NbConvertApp] WARNING | bibtex had problems, most likely because there were no citations
[NbConvertApp] PDF successfully created
[NbConvertApp] Writing 16102 bytes to Example.pdf

Dikkat edin, bu çıktı HTML sürümünden oldukça farklı oldu. LaTeX, ilk Markdown hücresini makale başlığına besler, bu nedenle çıktı da yine görüntülenir. Şablon, alt başlığı doğru şekilde kaldırdı (yani o Markdown hücresini gerçek Markdown olarak kabul etti). Makale belge sınıfı bugünün tarihiyle güncellenir - bu orijinal Notebook'ta olmayan bir şeydir. Yazı tipi ve boşluklar HTML sürümünden farklıdır. Son olarak, varsayılan olarak çıktı, "Notebook stili" yerine klasik IPython görünümünü kullanır.

Jupyter'de bulunan bir LaTeX belge sınıfını genişletmeyi seçerseniz, hangi biçimlendirmeyi kullanacağını mutlaka anlayın.

Sonuç

Şablonlar, Jinja2 ve nbconvert hakkında akılda tutulması gereken bazı temel noktalar vardır.

Şablonlar, bir belgenin bir web sayfasında veya başka bir çıktı biçiminde nasıl görüntüleneceğini tanımlar. Jupyter Notebook'lar farklı dışa aktarma biçimlerini görüntülemek için Jinja şablonlarını uygular. Şablonların, benzer sayfalar için, biraz farklı biçimlendirmelerle, üst ve alt şablonları tanımlamanıza olanak tanıyan kalıtım kuralları vardır.

Jinja şablonlarında statements, expressions ve (isteğe bağlı olarak) comments bulunur. {% statement %} ile tanımlanan statements, şablon yapısını tanımlar. {{ expression }} ile tanımlanan expressions, şablonu verilerinizle doldurur. Ve {# comment #} ile tanımlanan comments çıktıda görüntülenmez - yalnızca şablona dahili olarak aittir.

nbconvert, Jupyter Notebook'unuzu HTML, LaTeX ve PDF gibi diğer biçimlere dönüştürmenizi sağlayan bir Python kütüphanesidir. nbconvert, Jupyter Notebook'ların bu biçimlerde nasıl görüntüleneceğini tanımlamak için Jinja şablonlarını kullanır. Özel şablonlar tanımlayabilir veya kalıtım kullanarak varsayılan Jupyter şablonlarını genişletebilirsiniz.

Artık kendi şablonlarınızı oluşturmaya ve güzel Jupyter Notebook belgeleri dışa aktarmaya hazırsınız!

Kaynaklar:

Jinja2 dokümantasyonu

Python şablonlama dokümantasyonu

nbconvert dokümantasyonu