نام (NAME)

utidylib - مستندات uTidylib

پوشش‌دهنده‌ی Tidy.

من رابط اصلی با TidyLib هستم. این بسته از پردازش HTML با Tidy، به همراه تمام گزینه‌هایی که خط فرمان tidy پشتیبانی می‌کند، پشتیبانی می‌نماید.

برای اطلاعات بیشتر دربارهٔ گزینه‌های tidy، مرجع را ببینید. این گزینه‌ها را می‌توان با تبدیل خط‌تیره‌ها (-) به زیرخط (_) به عنوان آرگومان‌های کلیدواژه‌ای به parse و parseString ارسال کرد.

برای نمونه:

>>> import tidy
>>> from __future__ import print_function
>>> print(tidy.parseString(
...     '<Html>Hello Tidy!',
...     output_xhtml=1, add_xml_decl=1, indent=1, tidy_mark=0,
...     doctype='transitional'
... ))
<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title></title>
  </head>
  <body>
    Hello Tidy!
  </body>
</html>

برای گزینه‌هایی مانند newline و output_encoding که باید روی یکی از تعداد مشخصی از گزینه‌ها تنظیم شوند، می‌توانید نسخهٔ عددی یا رشته‌ای آن انتخاب را ارائه دهید؛ بنابراین هر دو دستور tidy.parseString('<HTML>foo</html>', newline=2) و tidy.parseString('<HTML>foo</html>', newline='CR') عملکرد یکسانی دارند.

هیچ برنامه‌ای برای پشتیبانی از سایر قابلیت‌های TidyLib مانند پیمایش درخت سند (document-tree traversal) وجود ندارد، چرا که پایتون چندین پیاده‌سازی باکیفیت DOM دارد. (نویسنده از پیاده‌سازی Twisted یعنی twisted.web.microdom استفاده می‌کند).

tidy.parse(filename: str, **kwargs: OPTION_TYPE) -> Document: باز کردن و پردازش filename به عنوان یک فایل HTML.
بازگرداندن یک شیء سند پردازش‌شده.

پارامترها

kwargs -- گزینه‌های نام‌دار برای ارسال به TidyLib جهت پردازش فایل ورودی.
filename -- نام فایلی که باید پردازش شود

مقدار بازگشتی: یک شیء Document

tidy.parseString(text: bytes | str, **kwargs: OPTION_TYPE) -> Document: استفاده از text به عنوان یک فایل HTML.
بازگرداندن یک شیء سند پردازش‌شده.

پارامترها

kwargs -- گزینه‌های نام‌دار برای ارسال به TidyLib جهت پردازش فایل ورودی.
text -- رشته‌ای که باید تجزیه شود

مقدار بازگشتی: یک شیء Document

class tidy.Document(options: OPTION_DICT_TYPE): شیء Document به همان شکلی که توسط parseString() یا parse() بازگردانده می‌شود.

get_errors() -> list[ReportItem]: بازگرداندن فهرست خطاها به صورت فهرستی از ReportItem.

gettext() -> str: متن یونیکد (Unicode) برای خروجی بازگردانده شده توسط tidy.

getvalue() -> bytes: رشته خام به همان شکلی که توسط tidy بازگردانده می‌شود.

write(stream: BinaryIO) -> None

پارامترها: stream -- شیء شبه‌فایل قابل نوشتن.

نوشتن سند در جریان (stream).

class tidy.ReportItem(err: str): مورد گزارش خطا به همان صورتی که توسط tidy بازگردانده می‌شود.

col: int | None: ستونی که خطا در آن رخ داده است (می‌تواند None باشد)

err: str: کل پیام خطای بازگردانده شده توسط tidy

full_severity: str: رشته کامل سطح اهمیت خطا

line: int | None: سطری که خطا در آن رخ داده است (می‌تواند None باشد)

message: str: خودِ پیام خطا

severity: str: کاراکترهای D، W، E یا C که نشان‌دهنده سطح اهمیت خطا هستند

exception tidy.TidyLibError استثنای عمومی Tidy.

exception tidy.InvalidOptionError: استثنا برای گزینهٔ نامعتبر.

exception tidy.OptionArgError: استثنا برای پارامتر نامعتبر.

برای استفاده از uTidylib، باید کتابخانهٔ HTML tidy را نصب داشته باشید. جهت مشاهدهٔ دستورالعمل‌های نحوهٔ تهیهٔ آن، <http://www.html-tidy.org> را بررسی کنید.

پس از نصب کتابخانه، uTidylib را نصب کنید:

pip install uTidylib

از مشارکت شما در GitHub استقبال می‌شود؛ ما از آن برای مدیریت کد منبع، پیگیری اشکالات و ارسال وصله‌ها استفاده می‌کنیم، ببینید: <https://github.com/nijel/utidylib>.

مجموعه آزمون را می‌توان با استفاده از pytest اجرا کرد:

pytest tidy

برای ساخت مستندات، کافی است دستور زیر را اجرا کنید:

make -C docs html

این کار مستلزم آن است که Sphinx را نصب داشته باشید.

مستندات API در دایرکتوری docs/_build/html/ ساخته خواهد شد.

مجوز MIT

بدین‌وسیله، به‌طور رایگان به هر شخصی که نسخه‌ای از این نرم‌افزار و فایل‌های مستندات ضمیمه ("نرم‌افزار") را دریافت می‌کند، اجازه داده می‌شود بدون محدودیت از جمله بدون قید حصر، حقوق استفاده، کپی، تغییر، ادغام، انتشار، توزیع، اعطای مجوز فرعی و/یا فروش نسخه‌های نرم‌افزار با آن معامله نماید و به افرادی که نرم‌افزار برای آن‌ها فراهم شده است اجازه دهد تا با رعایت شرایط زیر چنین کنند:

اعلان حق نشر بالا و این اعلان مجوز باید در کلیهٔ نسخه‌ها یا بخش‌های عمدهٔ نرم‌افزار گنجانده شود.

نرم‌افزار "همان‌طور که هست" ارائه می‌شود، بدون هرگونه ضمانت از هر نوع، صریح یا ضمنی، شامل اما نه محدود به ضمانت‌های تجاری بودن، تناسب برای یک هدف خاص و عدم نقض. در هیچ موردی نویسندگان یا دارندگان حق نشر مسئولیتی در قبال هرگونه ادعا، خسارت یا مسئولیت‌های دیگر، چه در قالب اقدام قراردادی، شبه‌جرم یا غیر آن، که ناشی از، مرتبط با یا در پیوند با نرم‌افزار یا استفاده از آن و سایر معاملات با آن باشد نخواهند داشت.

1.0.0

مدرن‌سازی بسته‌بندی.
به‌روزرسانی نسخه‌های پشتیبانی‌شدهٔ Python.
سازگاری با Homebrew.

حذف پشتیبانی از Python 3.7.
افزودن پشتیبانی از Python 3.12.
افزودن نشانه‌های نوع (type hints).
بهبود مستندات.
فراخوانی همیشگی CleanAndRepair پس از تجزیه (parsing).
رفع مشکل مدیریت آرگومان char_encoding.

0.9

حذف پشتیبانی از Python 3.6.
افزودن پشتیبانی از Python 3.10 و 3.11.
سازگاری با html-tidy 5.8.0.
افزودن پشتیبانی از تعیین مسیر کامل کتابخانه با استفاده از TIDY_LIBRARY_FULL_PATH.
افزودن getTidyVersion جهت دریافت نسخهٔ libtidy.

0.8

پاک‌سازی کد.
رفع غلط املایی در یادداشت‌های انتشار 0.7.

0.7

•: حذف پشتیبانی از Python 2.

0.6

•: نخستین انتشار رسمی در PyPI.

0.5

•: رفع مشکل سازگاری با بستهٔ وصله‌شدهٔ Debian یعنی libtidy5deb1.

0.4

سازگاری با html-tidy 5.6.0.
افزودن پشتیبانی از Python 3.

0.3

نخستین انتشار تحت نگه‌دارندهٔ جدید.
ادغام وصله‌های Debian.
رفع مشکلات گوناگون سازگاری (برای نمونه با سیستم‌های 64-bit).
پاک‌سازی‌های گوناگون کد.
مجموعه آزمون‌های جدید.
مستندات جدید.
پشتیبانی از کتابخانهٔ جدید HTML 5 tidy.

این پروژه یک انشعاب (fork) از uTidylib اصلی است که با کسب اجازه از نویسندهٔ اصلی ایجاد شده است. در ابتدا این پروژه وصله‌های مربوط به Debian و سایر توزیع‌ها را در بر می‌گرفت؛ اکنون سازگاری با نسخه‌های اخیر html-tidy را نیز فراهم کرده و با Python 3 کار می‌کند.

کد منبع اصلی همچنان در https://github.com/xdissent/utidylib در دسترس است.

نمایه <>
نمایهٔ ماژول‌ها <>
صفحهٔ جست‌وجو <> مشارکت‌کنندگان uTidylib

کپی‌رایت و تکثیر (COPYRIGHT)

مشارکت‌کنندگان uTidylib