Wrangler.py
1.0.0
Wrangler adalah generator situs statis untuk orang-orang yang tidak membuat blog.
Fitur:
Di Springload, kami sering kali perlu menyiapkan situs statis, tetapi kami kesulitan menemukan alat yang, ya.. memungkinkan kami melanjutkannya. Masuk ke Wrangler. Konten Anda tidak akan diformat sebagai rangkaian postingan blog. Itu tidak menyalin aset statis atau memproses SaSS atau membuat kopi.
Ia melakukan satu hal, dan melakukan satu hal itu dengan cukup baik.
Kami harap Anda menyukainya.
Instal wrangler melalui pip:
pip install wrangler
Hasilkan proyek baru di direktori saat ini .
wrangler create .
Ini akan membuat banyak direktori. Untuk memeriksanya berfungsi, buat situs kecil yang dibuat secara otomatis:
wrangler build content www
Sajikan situs Anda melalui mesin pilihan Anda, atau server bawaan yang praktis di http://127.0.0.1:8000/ :
wrangler serve www
Ingin melihat konten dan template Anda untuk melihat perubahan dan membuatnya kembali secara otomatis? Ada aplikasi untuk itu. Tugas watch mengambil semua opsi yang sama seperti build .
wrangler watch content www
Wrangler mengikuti konvensi sistem file yang cukup sederhana:
my-site/
| --content
| ----index.yaml
| --lib
| --templates
| ----template.j2
| --var
| --wrangler.yaml
| --wwwcontent - direktori konten. Struktur situs Anda akan mencerminkan direktori ini. Jika Anda punya content/index.yaml , Anda akan mendapatkan www/index.htmltemplates - tempat templat jinja2 .j2 Anda beradawww - folder akar web. Sungguh, Anda dapat melakukan output ke mana saja, kami hanya memilih www sebagai default yang masuk akal.lib - ekstensi khusus, kelas, kait, dll masuk ke sini. Tulis beberapa modul python dan berikan hasilnya kembali ke wranglervar - menyimpan cache template dan cache objek file (wrangler menggunakan kombinasi Pickle dan Shelve yang siap pakai) Semua jalur ini dapat diubah di wrangler.yaml
Wrangler berasumsi Anda sedang bekerja dengan beberapa jenis data terstruktur, dan Anda ingin menerjemahkan file data tersebut ke HTML (atau bahkan ASP klasik, jika itu yang Anda inginkan).
Tiga parser disertakan dalam paket: json, yaml, dan markdown (dengan materi depan yaml). Mereka beroperasi pada basis per file, jadi ini benar-benar valid:
my-site/
| --content
| ----index.yaml
| ----page-2.json
| ----page-3.md meta :
title : My title
template : template.j2
description : " My cool page! "
data :
content : " Here's some page content! "
blocks :
- " Lots of content "
- " even more content "
- " wow, so much content! " {
"meta" : {
"title" : " My title " ,
"template" : " template.j2 " ,
"description" : " My cool page! "
},
"data" : {
"content" : " Here's some page content! " ,
"blocks" : [
" Lots of content " ,
" even more content " ,
" wow, so much content! "
]
}
} ---
title : My title
template : template.j2
description : " Markdown uses yaml front-matter "
---
# A heading!
Some paragraph text
## Another heading!
Even more text
---
Nice HR you got there.
* A list
* with some
* list items
Ini lembar contekan penurunan harga yang bagus
Gunakan metadata untuk apa pun yang terkait dengan halaman tersebut. Anda dapat memasukkan apa pun yang Anda suka ke sini, tetapi ada beberapa kata khusus:
meta :
title : " Musings on the pronounciation of doge "
alias : " Doge "
template : " template.j2 "
class : DogePage
hide_from_nav : true
description : " Is it dog-e, doog, douge, douche? How do I properly refer to this meme? "
keywords : ["much", "analytics", "such", "SEO"]
output_file_extension : asp
weight : 1
thumbnail : /assets/images/thumb/doge-100x100.jpg
related :
- content/other-page.yaml
- content/pages/this-page-here.yaml Nama halaman di navigasi (dan mungkin tag judul Anda juga)
Jalur templat, relatif terhadap templates_dir wrangler.yaml Anda
Singkatan dari judul, yang dapat digunakan dalam navigasi
Mencoba mengganti kelas Python untuk objek halaman. Harus merupakan subkelas dari wrangler.Core.Page
Sembunyikan halaman ini dari pohon navigasi.
Apa yang tertulis di kaleng
Daftar kata kunci
Ganti output_file_extension default dari wrangler.yaml. Halaman akan dirender dengan ekstensi ini.
Berguna untuk memesan halaman, dari rendah ke tinggi. Secara default, wrangler akan menggunakan pengurutan berdasarkan abjad pada sistem file.
Jalur ke gambar mini
Daftar halaman terkait. Di template Anda, ini memungkinkan Anda mendapatkan beberapa informasi dasar tentang halaman lain (seperti judul dan deskripsi).
Wrangler menambahkan beberapa hal ke metadata Anda secara otomatis, di templat Anda, Anda dapat mengakses:
{{ meta.url }}
{{ meta.segments }}
{{ meta.filepath }}
{{ meta.mtime }}
{{ meta.children }}
{{ meta.parents }}
{{ meta.parents_siblings }}
Jalur ke file yang dibuat, relatif terhadap output_dir , misalnya /
Daftar semua segmen url: ["sub-directory", "index.html"]
Nama file masukan
Waktu yang dimodifikasi. Anda dapat menggunakan ini untuk membuat stempel waktu blog, misalnya.
Semua turunan langsung dari direktori saat ini
Semua node antara file saat ini dan /
Saudara kandung dari direktori induk.
Data halaman sepenuhnya opsional.
Mari kita lihat halaman kecil ini, custom-page.yaml Anda dapat menampilkan halaman tanpa data pada wrangler, dan melakukan hard-code semua yang ada di template, custom-page.j2 jika Anda mau.
meta :
title : No content!
template : custom-page.j2
output_file_extension : txt Ini akan membangun www/custom-page.txt .
Wrangler dikirimkan dengan filter penurunan harga jinja2. Jika Anda menggunakan file penurunan harga, penurunan harga tersedia di data.content . Masukkan konten ke filter penurunan harga, dan selesai.
< div class = " content " >
{{ data.content|markdown }}
</ div > Penurunan harga adalah format penulisan yang fantastis, namun dapat menimbulkan beberapa keterbatasan saat Anda berurusan dengan data yang lebih terstruktur. Untuk file YAML dan JSON, akses bagian kamus data dan sambungkan sesuai keinginan Anda:
< div class = " content " >
{{ data.content }}
{% for block in data . blocks %}
< p >{{ block }}</ p >
{% endfor %}
</ div > Opsi yang dapat diedit untuk wrangler disimpan dalam file wrangler.yaml di root proyek Anda.
Bukalah, dan Anda akan menemukan tiga node: wrangler , site , dan extensions
Ini adalah konfigurasi inti, hal-hal inti. Tampilannya seperti ini:
wrangler :
# Template directory relative to your project root
templates_dir : templates
# Default template to load if no template is specified for a page
default_template : template.j2
# Default output file extension. Note this can be overwritten in the content
# by specifying 'output_file_extension' in the 'meta' area
output_file_extension : html
# Supported data formats. Ensure a parser is registered for each type.
# More information about parsers can be found in the link at the top of the file.
data_formats : ['yaml', 'yml', 'json', 'js', 'md', 'markdown']
# Ignore hidden files, and files starting with underscores
ignore : ['.','_']
# Prints all the internal plumbing output to stdout
verbose : false
# Always force all pages to be rendered
force : false
# Run without the cache (useful for developing custom page classes, to prevent them
# from being cached each run).
nocache : false
# The location of the template cache zip file.
# Ensure the var path exists and is writeable by the user
build_cache_file : var/build.cache
compiled_templates_file : var/jinja
compiled_templates_log : var/jinja.log
# Custom methods/classes go in the lib directory, for instance
# lib/Page.py or lib/Extensions.py or lib/Filters.py
lib_path : lib
# file continues.... Konfigurasikan ekstensi apa pun yang Anda siapkan di sini. Ekstensi memungkinkan Anda menjalankan fungsi python apa pun yang Anda inginkan, dan memasukkan hasilnya ke dalam templat Anda.
# wrangler.yaml continued...
extensions :
# Sitemap generates a tree structure of your entire site, relative to the
# webroot specified here
#
# {{ extensions.sitemap }}
#
# We leave it up to you to iterate over the sitemap and print everything in
# a pretty manner, but this gist might get you started:
# https://gist.github.com/joshbarr/111
sitemap :
webroot : / {{ extensions.cachebuster }} Beberapa ekstensi default disertakan: sitemap , fileinfo , dan cachebuster
Var situs adalah variabel seluruh situs, tersedia di dalam templat Anda sebagai turunan dari objek site .
Misalnya, untuk mendapatkan jalur gambar, Anda dapat memanggil {{ site.paths.images }} dan tidak perlu mengetik lagi.
# wrangler.yaml continued...
site :
paths :
css : assets/css
js : assets/js
assets : assets {# Hey, it's those handy vars I set in my site_vars #}
{{ site.paths.css }} Semua dokumentasi ini juga ada di file wrangler.yaml , jadi Anda tidak akan tersesat!
Mengambil argumen posisi tunggal, jalur untuk membuat proyek baru Anda:
cd my-sweet-site && wrangler create .
# or
wrangler create my-sweet-site
input_dir Direktori masukan seperti site/content output_dir Direktori keluaran seperti www
wrangler build content wwwPaksa rendering terlepas dari kapan konten Anda terakhir diubah:
wrangler build content www --forceCache ulang semua objek halaman
wrangler build content www --nocache Ubah ekstensi file keluaran untuk semua halaman menjadi asp klasik. (Mengapa ada orang yang melakukan itu?)
wrangler build content www -o ".asp"
Ubah format data yang akan dicari di input_dir menjadi json
wrangler build content www -d 'json'
Ubah lokasi direktori templat
wrangler build content www -t other-templates-dir
Ubah lokasi file konfigurasi
wrangler build content www -c site/config/wrangler.yaml
Memiliki semua opsi yang sama dengan wrangler build
Cetak semua pipa setiap kali file berubah:
wrangler watch content www --verbose Menerima satu argumen posisi (direktori yang akan dilayani) dan --port opsional (default 8000).
wrangler serve www --port 8001Hapus cache templat dan cache objek dari direktori 'var'.
wrangler clean Wrangler memuat semua modul python yang ditemukan di direktori lib proyek Anda saat boot.
Hal ini memberi Anda kemampuan untuk memperluas fungsi inti dan memanipulasi data halaman - misalnya Anda dapat memuat beberapa nilai dari database dan membuatnya tersedia di templat Anda.
Saat Anda memanggil build , wrangler membuat representasi struktur pohon di direktori content/ Anda.
Ini menggunakan daftar objek Node yang tertaut ganda, yang digabungkan menjadi NodeGraph , wadah yang berguna untuk menangani node.
# Pseudocode
NodeGraph :
# The nodes in their hierarchical structure, eg:
tree :
Node :
children :
- Node :
children :
- Node
- Node :
children :
- Node
- Node
- Node
# The 'all' dictionary is the same nodes represented in a flat structure.
# This can be much quicker to iterate over than the tree, and you can
# access both from within your hooks and extensions.
# The filepath is used as the unique key.
all :
content/index.md :
Node :
# node's data...
content/other-page.md :
Node :
# node's data...Node dapat mengakses anak-anaknya, dan juga orang tuanya:
# More pseudocode
Node :
path : " content/index.md "
children :
- Node :
- Node :
- Node :
parent :
Node :Agar semuanya tetap rapi, objek Node tidak menyimpan representasi data halaman secara langsung – node hanyalah wadah.
Mengikuti ide-ide dalam diskusi ini, Node memiliki properti kargo yang menampung kelas halaman sebenarnya :
from wrangler . Core import Node
class GoldBullion ( object ):
price = 1200
the_node = Node ( "index" , "content/index.md" , parent = None , cargo = None )
the_node . add_cargo ( GoldBullion ())
cargo = the_node . get_cargo ()
print cargo . price Halaman menyimpan representasi dict dari data file sumber Anda, dan menyediakan cara yang konsisten bagi Renderer untuk mengakses data. Untuk membuat halaman khusus, cukup subkelas wrangler.Core.Page dan itu akan dimuat secara otomatis.
Tip praktis: Jika kelas khusus Anda memiliki nama Page , itu akan menimpa objek Page default untuk semua halaman.
# lib/Page.py
import wrangler . Core as wrangler
class Page ( wrangler . Page ):
def get_content ( self ):
return self . data [ "data" ]
def get_metadata ( self ):
return self . data [ "meta" ]
def get_properties ( self ):
print "Hey, I'm a custom page instance!"
return {
"title" : self . get_title (),
"alias" : self . get_short_title (),
"description" : self . get_meta_description (),
"url" : self . get_tidy_url (),
"show_in_navigation" : self . show_in_navigation (),
"weight" : self . get_weight (),
"thumbnail" : self . get_thumbnail ()
} Dalam contoh di atas, kami memodifikasi tiga metode halaman utama, get_content() , get_metadata() , dan get_properties()
Dipanggil saat Halaman dirender, ini tersedia di template Anda sebagai objek data :
<!doctype html>
< div class = ' dump-of-data-object ' >
{{ data.content }}
</ div > Dipanggil ketika Halaman dirender, ini adalah objek meta :
<!doctype html>
< title >{{ meta.title }} Sedikit lebih rumit untuk dijelaskan, tapi tetap mengagumkan. Ketika sebuah Node dirender, ia meminta informasi tertentu tentang halaman yang terkait dengan halaman saat ini, seperti halaman anak, saudara, orang tua, dan halaman yang terkait secara manual.
Daripada berbagi semuanya dengan yang lain , setiap kelas Page menjelaskan informasi dasar yang dengan senang hati dibagikan dengan halaman lain.
def get_properties ( self ):
return {
"title" : self . get_title (),
"alias" : self . get_short_title (),
"url" : self . get_tidy_url (),
"show_in_navigation" : self . show_in_navigation (),
"weight" : self . get_weight (),
# Let's add the modified time, so our theoretical parent
# page could know when we last saved the file.
"mtime" : self . getmtime ()
}Mari kita lihat contoh yang sangat sederhana, kelas halaman khusus yang membalikkan semua teks pada halaman. Sangat praktis.
Pertama, atur properti class di meta halaman Anda untuk memberi tahu penengkar kelas mana yang akan dimuat:
konten/custom.md:
---
class : RightToLeft
---
# My custom page
With its custom content. Kemudian buat kelas baru di suatu tempat di direktori lib/ Anda yang merupakan subkelas Page . Tidak masalah di mana direktori lib/ Anda berakhir, satu-satunya aturan adalah ia harus membuat subkelas objek Page :
lib/halaman.py
import wrangler . Core as wrangler
class RightToLeft ( wrangler . Page )
def get_content ( self ):
for key , val in self . data [ "data" ]:
self . data [ "data" ][ key ] = val [:: - 1 ]
return self . data [ "data" ]Besar! Halaman kami akan dicetak dengan teks kanan ke kiri.
Jika Anda melihat file wrangler.yaml , Anda akan melihat file tersebut menerima tiga jenis file: ["yaml", "json", "md"]
Wrangler menyertakan tiga parser secara default, Yaml , Markdown dan Json , yang menggunakan file input dan mewakilinya sebagai data yang bermakna.
Pemuat otomatis mencari apa pun yang menggantikan wrangler.Core.Parser .
Misalnya, Anda dapat melakukan ini di suatu tempat di lib/Parsers.py untuk mendukung format teks
from wrangler . Core import Parser
from lxml import objectify
from collections import defaultdict
class XmlParser ( Parser ):
accepts = [ "xml" , "robotlanguage" ]
def interpret ( self , file_contents ):
return root = objectify . fromstring ( file_contents )
Wrangler menggunakan sinyal penutup mata untuk memproses kait dan ekstensi.
Hooks adalah sinyal yang ditembakkan pada titik kritis dalam proses render. Objek tersebut diproses sesuai urutan kemunculannya di modul Anda, dan dapat memodifikasi objek yang masuk secara langsung. Mereka juga mendapat akses ke config , renderer , dan reporter penengkar.
from wrangler . Core import before_render , after_render , load_item , save_item , render_item
@ before_render
def before ( ** kw ):
nodes = kw [ 'nodes' ]
config = kw [ 'config' ]
renderer = kw [ 'renderer' ]
reporter = kw [ 'reporter' ]
print "Hey, I'm a hook!"
return "foo!"
@ after_render
def after ( ** kw ):
nodes = kw [ 'nodes' ]
config = kw [ 'config' ]
renderer = kw [ 'renderer' ]
reporter = kw [ 'reporter' ]
print "Hey, I'm a hook!"
return "" Ekstensi adalah skrip python yang mengembalikan data berguna ke kamus extensions templat Anda.
Mari kita ambil skrip kecil ini:
# lib/my_extensions.py
from wrangler . Core import extension
@ extension
def my_extension ( sender , ** kwargs ):
# Add some config to your YAML file and access it here:
config = kwargs [ 'config' ][ 'extensions' ][ 'my_extension' ]
return config [ "string_to_print" ] Akan dapat diakses dari template Anda di extensions.YOUR_EXTENSION_NAME :
< em class = " extension " >
{{ extensions.my_extension }}
</ em >Yang menghasilkan output ini:
< i > "This is my basic extension!" </ i > Di wrangler.yaml Anda ada bagian untuk mengelola ekstensi Anda:
# My extension just prints a string... not very exciting!
my_extension :
string_to_print : " This is my basic extension! " Wrangler memungkinkan Anda memperluas Jinja2 dengan Filter khusus.
Filter dapat dimasukkan ke dalam file apa pun di direktori lib Anda, lib/ . Mereka terhubung melalui dekorator, yang diberi nama template_filter
#lib/filters.py
from wrangler . Core import template_filter
from jinja2 import contextfilter
@ template_filter
def my_filter ( value ):
return value . lower () Jika Anda memerlukan akses ke contextfilter atau envcontextfilter jinja, Anda dapat mengimpornya dan menerapkannya ke fungsi Anda juga:
Baca selengkapnya tentang filter konteks jinja2
#lib/filters.py
from wrangler . Core import template_filter
from jinja2 import contextfilter
@ template_filter
@ contextfilter
def my_filter ( context , value ):
print context
return value
