کادرهای توجه
مستندات پر از کادرهای رنگی و عبارتهای کوچک راهنماست. این هشت تا میگویند کدام جمله نکته است، کدام هشدار، و کجا نویسنده میخواهد مثال بزند یا همان حرف را سادهتر بگوید.
جملهی امری
کادرهای مستندات مستقیم با تو حرف میزنند، پس فعل بدون فاعل و بدون s اول جمله میآید: «Note that…» (توجه کن که…)، «See also…» (این را هم ببین)، «Use a list instead». برای نهی، Do not یا Never را اول میگذارند: «Never share your password». این لحن بیادبانه نیست؛ در راهنماها کاملاً عادی است.
هشت کلمهی این درس
note (نُوت): نکته؛ یادداشت
note یعنی یادداشت. در مستندات کادرهای رنگی کوچکی هست که با Note: شروع میشوند و نکتهای را میگویند که خوب است بدانی ولی خطرناک نیست. جملهی معروفش «Note that…» است، یعنی «توجه کن که…». هر وقت این را دیدی، یعنی نویسنده فکر میکند ممکن است اینجا اشتباه برداشت کنی.
Note that the index starts at zero, not one.
توجه کن که اندیس از صفر شروع میشود، نه از یک.
tip (تیپ): ترفند؛ پیشنهاد مفید
tip در انگلیسی یعنی یک پیشنهاد کوچک و بهدردبخور. کادر Tip در مستندات راه بهتر یا سریعترِ یک کار را نشانت میدهد. اگر آن را نخوانی چیزی خراب نمیشود، ولی اگر بخوانی کارت راحتتر میشود. معمولاً رنگش سبز است.
Tip: press Tab to complete the command automatically.
ترفند: برای اینکه دستور خودکار کامل شود، Tab را بزن.
caution (کاشِن): احتیاط؛ مراقب باش
caution یعنی احتیاط، همان کلمهای که روی تابلوهای زرد «زمین خیس است» مینویسند. کادر Caution در مستندات میگوید این کار میتواند چیزی را خراب کند: داده پاک شود، برنامه از کار بیفتد یا رمزی لو برود. این کادرها را هیچوقت نخوانده رد نکن. Warning هم تقریباً همین معنی را دارد.
Caution: this command deletes all files in the folder.
احتیاط: این دستور همهی فایلهای پوشه را پاک میکند.
important (ایمپورتِنت): مهم
important یعنی مهم. کادر Important در مستندات چیزی را میگوید که اگر ندانی، کارت درست پیش نمیرود: مثلاً «قبل از ادامه باید نسخهی ۳ را نصب کرده باشی». از Note جدیتر است و از Caution آرامتر. در جملهها هم زیاد میآید: «It is important to…» یعنی «مهم است که…».
It is important to close the file after writing.
مهم است که فایل را بعد از نوشتن ببندی.
see also (سی آلسو): این را هم ببین
see یعنی دیدن و also یعنی «هم، همچنین». See also عنوان بخشی در پایین صفحههای مستندات است که پیوند چیزهای مرتبط را میدهد: تابعهای شبیه، صفحهی توضیح بیشتر، یا راه دیگرِ همین کار. اگر تابعی که پیدا کردهای دقیقاً آن چیزی نیست که میخواستی، جواب معمولاً در همین بخش است.
See also the sorted function, which returns a new list.
تابع sorted را هم ببین که یک فهرست تازه برمیگرداند.
for example (فور ایگزَمپِل): برای مثال؛ مثلاً
for example یعنی «برای مثال». نویسنده اول یک قانون کلی میگوید و بعد با for example یک نمونهی واقعی میآورد تا روشن شود. هر وقت جملهی کلی را نفهمیدی، چشمت دنبال همین عبارت بگردد؛ جملهی بعدش معمولاً سادهتر است. بعدش کاما میآید. for instance هم دقیقاً همین معنی را دارد.
Some methods change the list; for example, append adds an item.
بعضی متدها فهرست را عوض میکنند؛ مثلاً append یک آیتم اضافه میکند.
in other words (این آدِر وِردز): به بیان دیگر؛ یعنی
کلمه به کلمه یعنی «در کلمههای دیگر». نویسنده اول چیزی را دقیق و فنی میگوید و بعد با in other words همان را سادهتر تکرار میکند. پس حرف تازهای در کار نیست؛ همان حرف قبلی است با زبان آسانتر. اگر جملهی اول سخت بود، جملهی بعد از این عبارت را بخوان.
Strings are immutable; in other words, you cannot change them.
رشتهها تغییرناپذیرند؛ به بیان دیگر، نمیتوانی عوضشان کنی.
such as (ساچ اَز): مانند؛ از قبیل
such as یعنی «مانند» و بعدش یکی دو نمونه از یک گروه میآید. الگو: «گروه + such as + چند نمونه»، مثل «languages such as Python and JavaScript». فرقش با for example این است که such as وسط جمله و چسبیده به اسم میآید، ولی for example معمولاً یک جملهی تازه را شروع میکند.
Use a mutable type, such as a list or a dictionary.
از یک نوع تغییرپذیر استفاده کن، مانند فهرست یا دیکشنری.
کادرهای یک صفحهی راهنما
Saving files
Use save() to write your data to a file.
Note: save() creates the file if it does not exist.
Caution: If the file already exists, save() replaces it. In other words, the old content is lost.
Tip: Add the date to the file name, for example "report-2025-03-02.txt". Then you never lose an old report.
Important: Close programs that use the file, such as Excel, before you save.
See also: load(), backup()
ذخیرهی فایلها
برای نوشتن دادههایت در یک فایل از save() استفاده کن.
نکته: اگر فایل وجود نداشته باشد، save() آن را میسازد.
احتیاط: اگر فایل از قبل وجود داشته باشد، save() آن را جایگزین میکند. به بیان دیگر، محتوای قدیمی از دست میرود.
ترفند: تاریخ را به اسم فایل اضافه کن، مثلاً «report-2025-03-02.txt». اینطوری هیچوقت گزارش قدیمی را از دست نمیدهی.
مهم: قبل از ذخیره، برنامههایی را که از فایل استفاده میکنند، مانند Excel، ببند.
اینها را هم ببین: load()، backup()