ابزارهای کاربردی پایتون

در این فصل با ابزارهای کاربردی پایتون آشنا می‌شویم: مصرف API با requests، تاریخ شمسی با jdatetime، عبارت منظم، logging و argparse برای ساخت برنامه‌های CLI حرفه‌ای.

requests – مصرف API

پکیج requests ساده‌ترین راه برای کار با HTTP در پایتون است:

pip install requests

درخواست GET ساده

import requests

# درخواست GET
response = requests.get("https://api.github.com/users/torvalds")

# بررسی وضعیت
print(response.status_code)    # 200 = موفق

# دریافت JSON
data = response.json()
print(data["name"])            # Linus Torvalds
print(data["followers"])

# هدرها
print(response.headers["Content-Type"])

# متن خام
print(response.text)

پارامترهای Query

params = {
    "q": "python tutorials",
    "lang": "fa",
    "limit": 10
}

response = requests.get("https://api.example.com/search", params=params)
# URL تولید شده: https://api.example.com/search?q=python+tutorials&lang=fa&limit=10

درخواست POST

# ارسال JSON
data = {
    "title": "مقاله جدید",
    "content": "متن مقاله"
}

response = requests.post(
    "https://api.example.com/articles",
    json=data,
    headers={"Authorization": "Bearer YOUR_TOKEN"}
)

if response.status_code == 201:
    print("ایجاد شد:", response.json())
else:
    print(f"خطا: {response.status_code}")

مدیریت خطا

try:
    response = requests.get(
        "https://api.example.com/data",
        timeout=5    # حداکثر ۵ ثانیه
    )
    response.raise_for_status()    # خطا اگر کد خطا باشد
    data = response.json()
except requests.Timeout:
    print("درخواست تایم‌اوت شد")
except requests.HTTPError as e:
    print(f"خطای HTTP: {e}")
except requests.RequestException as e:
    print(f"خطای شبکه: {e}")

دانلود فایل

url = "https://example.com/document.pdf"

response = requests.get(url, stream=True)
with open("document.pdf", "wb") as f:
    for chunk in response.iter_content(chunk_size=8192):
        f.write(chunk)

print("دانلود کامل شد")

jdatetime – تاریخ شمسی

pip install jdatetime

import jdatetime

# تاریخ امروز
today = jdatetime.date.today()
print(today)                     # 1405-02-11

# امروز با زمان
now = jdatetime.datetime.now()
print(now)                       # 1405-02-11 14:30:00

# اجزای تاریخ
print(now.year)                  # 1405
print(now.month)                 # 2
print(now.day)                   # 11
print(now.weekday())             # 0=شنبه ... 6=جمعه

# قالب‌بندی فارسی
print(now.strftime("%A %d %B %Y"))   # شنبه 11 اردیبهشت 1405
print(now.strftime("%Y/%m/%d"))      # 1405/02/11

# تبدیل میلادی به شمسی
from datetime import date
g_date = date(2026, 5, 1)
j_date = jdatetime.date.fromgregorian(date=g_date)
print(j_date)                    # 1405-02-11

# تبدیل شمسی به میلادی
g = jdatetime.date(1405, 2, 11).togregorian()
print(g)                         # 2026-05-01

# اعمال محاسبات
import datetime
yesterday = today - datetime.timedelta(days=1)
print(yesterday)

re – عبارت منظم

regex برای جستجو و دستکاری متن:

import re

# match - از ابتدا تطبیق می‌دهد
text = "Python 3.12"
m = re.match(r"Python", text)
if m:
    print(m.group())         # Python

# search - در کل رشته جستجو
text = "نسخه پایتون: 3.12.4"
m = re.search(r"d+.d+.d+", text)
if m:
    print(m.group())         # 3.12.4

# findall - همه تطبیق‌ها
text = "ali@a.com - zahra@b.com - mohammad@c.org"
emails = re.findall(r"S+@S+.S+", text)
print(emails)
# ['ali@a.com', 'zahra@b.com', 'mohammad@c.org']

# sub - جایگزینی
text = "تلفن: 09121234567 و 09384567890"
masked = re.sub(r"(09d{2})d{7}", r"1*******", text)
print(masked)
# تلفن: 0912******* و 0938*******

# split - تقسیم با الگو
text = "علی, زهرا; محمد | سارا"
parts = re.split(r"[,;|]s*", text)
print(parts)
# ['علی', 'زهرا', 'محمد', 'سارا']

الگوهای رایج

مثال‌های کاربردی

# اعتبارسنجی موبایل ایران
def is_iran_mobile(phone):
    return bool(re.match(r"^09d{9}$", phone))

print(is_iran_mobile("09121234567"))    # True
print(is_iran_mobile("0912123"))         # False

# اعتبارسنجی ایمیل
def is_email(s):
    pattern = r"^[w.+-]+@[w-]+.[w.-]+$"
    return bool(re.match(pattern, s))

# استخراج URL
text = "سایت ما https://icsd.ir و https://github.com است"
urls = re.findall(r"https?://S+", text)
print(urls)

# تبدیل اعداد فارسی به انگلیسی با regex
fa_to_en_table = str.maketrans("۰۱۲۳۴۵۶۷۸۹", "0123456789")
text = "تماس: ۰۹۱۲۱۲۳۴۵۶۷"
print(text.translate(fa_to_en_table))

logging – ثبت لاگ

import logging

# تنظیم پایه
logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s [%(levelname)s] %(message)s",
    datefmt="%Y-%m-%d %H:%M:%S"
)

logging.debug("جزئیات دیباگ")        # نمایش داده نمی‌شود
logging.info("اطلاعات عمومی")
logging.warning("هشدار")
logging.error("خطا رخ داد")
logging.critical("خطای جدی!")

سطوح لاگ

لاگ به فایل

logging.basicConfig(
    filename="app.log",
    level=logging.INFO,
    format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
    encoding="utf-8"
)

# لاگر مخصوص یک ماژول
logger = logging.getLogger(__name__)
logger.info("ماژول شروع شد")

# لاگ خطا با stack trace
try:
    1 / 0
except Exception:
    logger.exception("خطا در محاسبه")
    # خطا و stack trace هر دو ثبت می‌شود

argparse – برنامه CLI

import argparse

parser = argparse.ArgumentParser(description="ابزار تبدیل تصویر")

# آرگومان مثبت (الزامی)
parser.add_argument("input", help="فایل ورودی")
parser.add_argument("output", help="فایل خروجی")

# آرگومان اختیاری با مقدار
parser.add_argument("-q", "--quality", type=int, default=85,
                    help="کیفیت (0-100)")
parser.add_argument("-w", "--width", type=int, help="عرض جدید")

# Flag (boolean)
parser.add_argument("-v", "--verbose", action="store_true",
                    help="نمایش جزئیات")
parser.add_argument("--no-watermark", action="store_true",
                    help="بدون واترمارک")

# انتخاب از لیست
parser.add_argument("-f", "--format", choices=["jpg", "png", "webp"],
                    default="jpg")

args = parser.parse_args()

print(f"ورودی: {args.input}")
print(f"خروجی: {args.output}")
print(f"کیفیت: {args.quality}")
if args.verbose:
    print("حالت verbose فعال")

اجرا:

python convert.py input.jpg output.png -q 90 --width 800 -v
python convert.py --help    # راهنما خودکار!

مثال کامل: API هواشناسی

import requests
import logging
import argparse
from datetime import datetime

# تنظیم لاگ
logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s [%(levelname)s] %(message)s"
)
logger = logging.getLogger(__name__)

def get_weather(city, api_key):
    """دریافت هوای یک شهر"""
    url = "https://api.openweathermap.org/data/2.5/weather"
    params = {
        "q": city,
        "appid": api_key,
        "units": "metric",
        "lang": "fa"
    }
    
    try:
        logger.info(f"درخواست هوای {city}")
        response = requests.get(url, params=params, timeout=10)
        response.raise_for_status()
        return response.json()
    except requests.Timeout:
        logger.error(f"تایم‌اوت برای {city}")
        return None
    except requests.HTTPError as e:
        logger.error(f"خطای HTTP: {e}")
        return None

def display(data):
    if not data:
        print("داده‌ای دریافت نشد")
        return
    
    print(f"n=== هوای {data['name']} ===")
    print(f"دما: {data['main']['temp']}°C")
    print(f"احساس: {data['main']['feels_like']}°C")
    print(f"رطوبت: {data['main']['humidity']}%")
    print(f"وضعیت: {data['weather'][0]['description']}")

if __name__ == "__main__":
    parser = argparse.ArgumentParser(description="هواشناسی")
    parser.add_argument("city", help="نام شهر")
    parser.add_argument("--api-key", required=True, help="کلید API")
    args = parser.parse_args()
    
    weather = get_weather(args.city, args.api_key)
    display(weather)

تمرین فصل

جمع‌بندی

• requests برای مصرف REST API: GET، POST، JSON
• jdatetime برای کار با تاریخ شمسی
• عبارت منظم با re: match، findall، sub
• logging برای لاگ حرفه‌ای با سطوح مختلف
• argparse برای ساخت برنامه CLI با راهنمای خودکار