
تو این پست قراره با نوشتن اسکریپت پایتون فایل های با فرمت ipynb رو به HTML تبدیل کنیم و به صورت خودکار با استفاده از github actions تو github pages منتشرش کنیم.
فایل IPYNB یک سند نوت بوکه که توسط jupyter notebook ایجاد شده، یک محیط محاسباتی تعاملی که به ما تو دستکاری و تجزیه و تحلیل داده ها با استفاده از پایتون کمک می کنه.
به کمک ویژگی github actions خیلی از کارا رو مثل تست کد یا دیپلوی کردن کد جدید یا تو مورد ما، تبدیل فایل ها و انتقالشون به github pages رو به صورت خودکار میشه انجام داد.
اسکریپتی که قراره بنویسیم رو میتونین از مخزن اصلی گیت هاب ایرانی پای بردارید.
import os import pathlib import shutil import sys from concurrent.futures import ThreadPoolExecutor
تو این قسمت ماژول های مورد نیاز رو ایمپورت میکنیم. همشون از لایبرری های استاندارد و built-in پایتون هستن، پس نیازی به نصب چیزی نیست.
_DOCS_PATH = 'docs' _PROJECTS_PATH = 'projects' _IPYNB_GLOB = '**/*.ipynb' _GIT_MAIN_BRANCH_NAME = 'main' _GIT_EMAIL = '[email protected]' _GIT_USERNAME = 'iranipy' _GIT_COMMIT_MESSAGE = 'new rendered docs added by ipynb_docs_renderer action' _CONVERTED_FILE_FORMAT = 'html' _CONVERT_COMMAND = f'jupyter nbconvert --to {_CONVERTED_FILE_FORMAT}' _DEPENDENCIES = ['jupyterlab', 'nbconvert']
اینا متغیر هایی هستن که ادامه کار بهشون نیاز داریم و مقدارشون تغییری نمیکنه. مقادیر رو به خواست خودتون تغییر بدین، مثلا مقدار GIT_EMAIL_ رو به ایمیل حساب خودتون تغییر بدین. دلیل استفاده از حروف بزرگ و آندرلاین قبل اسمشون اینه که میخوایم نشون بدیم ثابت (constant) هستن و خصوصی (private) اما از اونجایی که تو پایتون این ویژگی ها به صورت داخلی و تو سطح مفسر (interpreter) وجود نداره، این موضوع فقط به صورت قرار دادیه؛ یعنی شما هرجای کد که بخواید میتونید مقدارشون رو عوض یا تو هر ماژولی ایمپورتشون کنین. ولی خب نکنین :)
ماژول های جدیدی که تو این بخش به عنوان وابستگی (dependency) دیده میشه nbconvert و jupyterlab هستن که نیازی به نصبشون نیست و در ادامه بهشون میرسیم.
def _install_dependencies(): with ThreadPoolExecutor() as executer: executer.map(os.system, [f'pip install {d}' for d in _DEPENDENCIES])
وظیفه این تابع نصب پیش نیاز های برنامه (اعضای لیست DEPENDENCIES_) تو محیط اجرای برنامه ست.
از کلاس ThreadPoolExecutor استفاده میکنیم. متغیر executer یک instance از ThreadPoolExecutor حساب میشه. (آشنایی بیشتر با context manager)
تو خط سوم از یکی از متد های ThreadPoolExecutor به اسم map استفاده کردیم. عملکرد این متد دقیقا مثل تابع map خود پایتونه. یعنی یک تابع و یک iterable به عنوان پارامتر میگیره و اون تابع رو روی تک تک اعضای اون iterable اجرا میکنه ولی فرقش اینه که هر عضو اون iterable رو تو یک رشته (Thread) جداگونه اجرا می کنه. تابعی که اینجا استفاده شده system از کتابخونه os هستش. این تابع دستوری که به شکل رشته (string) به عنوان یک پارامتر بهش میدید رو تو یک subshell اجرا میکنه.
def _render_ipynb(ipynb: list): directory, file = os.path.split(ipynb) rendered_file = f'{os.path.splitext(file)[0]}.{_CONVERTED_FILE_FORMAT}' rendered_file_path = os.path.join(directory, rendered_file) os.system(f'{_CONVERT_COMMAND} {ipynb.absolute()}') shutil.move(rendered_file_path, os.path.join(_DOCS_PATH, rendered_file)) def _run_rendering(): IPYNB_DOCS = list(pathlib.Path(_PROJECTS_PATH).glob(_IPYNB_GLOB)) with ThreadPoolExecutor() as executer: executer.map(_render_ipynb, IPYNB_DOCS)
تو تابع render_ipynb_ یک ابجکت pathlib.Path به عنوان پارامتر دریافت میشه و عملیات تبدیل فرمت و انتقالش به دایرکتوری مورد نظر (معادل با مقدار DOCS_PATH_) انجام میشه.
def _commit_push(): commands = [ f'git config --global user.email "{_GIT_EMAIL}" && git config --global user.name "{_GIT_USERNAME}"', 'git add .', f'git commit -m "{_GIT_COMMIT_MESSAGE}"', f'git fetch origin {_GIT_MAIN_BRANCH_NAME}', f'git push origin {_GIT_MAIN_BRANCH_NAME}', ] list(map(os.system, commands))
تو این تابع تمام دستوراتی که برای کامیت و پوش کردن لازم هست رو یک لیست قرار دادیم و با استفاده از map تابع os.system روی اعضای لیست اجرا کردیم. دلیل استفاده از تابع list این هستش که اگه این کارو انجام ندیم تنها اتفاقی که میوفته اینه که تابع map یک map object بهمون میده و هیچکدوم از دستورات رو اجرا نمیکنه. به عبارت دیگه برای اجرا این دستورات باید روی map object، یک iterate بزنیم (به هرشکلی، مهم نیست).
def main(): task = { 'install-dependencies': _install_dependencies, 'render': _run_rendering, 'commit-push': _commit_push, }[sys.argv[1]] task()
تو این تابع یک دیکشنری داریم که تو این دیکشنری به هر کدوم از تابع هایی که بالاتر تعریف کردیم یک کلیدواژه اختصاص داده شده. هر کدوم از این کلیدواژه ها که موقع اجرای ماژول به عنوان آرگومان خط فرمان وارد بشه، برنامه همون تابع رو اجرا میکنه؛ در واقع روشیه برای شبیه سازی عبارت swicth-case موجود تو سایر زبان های برنامه نویسی. (sys.argv)
به عنوان مثال، اینجوری میتونیم تابع run_rendering_ رو اجرا کنیم:
python ipynb_docs_renderer.py render
if __name__ == '__main__': main()
توضیحات بیشتر در مورد __main__
پایان بخش اول ...
امیدواریم از اولین بخش این پست استفاده کافی رو برده باشید. اگه شما هم مثل ما از خوندن مطالب پایتونی لذت میبرید، خوشحال میشیم ما رو تو شبکه های اجتماعی دنبال و در صورت داشتن انتقاد و پیشنهاد ما رو ازش مطلع کنید. لایک هم یادتون نره :)
با دنبال کردن ما در
یا کمک مالی به مبلغ دلخواه از طریق درگاه آیدی پی میتونید از ما حمایت کنید.
وب سایت (به زودی): iranipy.ir