راهنمای توسعه پروژه پایتون من نسخه 202305

• راهنمای راه اندازی یک پروژه پایتون برای استقرار تولید.

• این راهنما فرض می کند که شما از Poetry برای مدیریت بسته استفاده می کنید و به قوانین مشخص شده پایبند هستید.

• اگر با نحوه استفاده از Poetry آشنا نیستید، لطفاً مستندات زیر را بخوانید و آن را به صورت محلی نصب کنید:

• با دنبال کردن این راهنما، می‌توانید با استفاده از Poetry به‌عنوان مدیر بسته، یک پروژه پایتون را برای استقرار تولید راه‌اندازی کنید، کیفیت کد را با لینترها و قالب‌کننده‌ها اعمال کنید، بررسی‌ها را با GitHub Actions به‌طور خودکار انجام دهید، IDE خود را برای حفظ ثبات پیکربندی کنید، و برای اطمینان از تست‌های واحد جامع بنویسید. قابلیت اطمینان پروژه در طول فرآیند توسعه

• توصیه می کنیم از پایتون نسخه 3.9 یا بالاتر برای پروژه خود استفاده کنید.

• اکثر این سند با استفاده از ChatGPT-4 ایجاد شده است.

• نمونه پروژه

1. راه اندازی پروژه/ راه اندازی محیط محلی با شعر و پینو

• یک فهرست پروژه ایجاد کنید و به آن بروید:

mkdir ${project_path}
cd ${project_path}

• از pyenv برای مدیریت نسخه‌های پایتون محلی و اطمینان از یک محیط سازگار برای همه اعضای تیم استفاده کنید. برای انجام این کار، یک فایل .python-version را در پروژه قرار دهید.

• با استفاده از pyenv نسخه پایتون مورد نظر را برای پروژه تنظیم کنید:

pyenv install ${python_version}
pyenv local ${python_version}

• ${python_version} را با نسخه دلخواه جایگزین کنید، به عنوان مثال، 3.9.7. این دستور یک فایل .python-version را در دایرکتوری پروژه ایجاد می کند.

• اطمینان حاصل کنید که همه اعضای تیم از یک نسخه پایتون مشخص شده در فایل .python-version استفاده می کنند.

• فایل pyproject.tool ارائه شده را در دایرکتوری پروژه کپی کنید و وابستگی ها را نصب کنید:

• مثال pyproject.yml را کپی کنید و خودتان ترتیب دهید

  • برای محیط محلی، از Poetry برای ایجاد یک محیط مجازی .venv در ریشه پروژه استفاده کنید. فایل poetry.toml زیر را در دایرکتوری پروژه قرار دهید:

[virtualenvs]
path = ".venv"
in-project = true

• برای راه اندازی محیط مجازی و نصب پکیج های مورد نیاز دستورات زیر را اجرا کنید

poetry env use ${python_version}
poetry install

// Run command in the created environment.
poetry run <YOUR_COMMAND>
// Enter the created environment.
poetry shell

در فایل pyproject.toml، ماژول های مختلفی را برای لینتینگ، قالب بندی و اجرای وظیفه پیکربندی می کنیم. در اینجا توضیحی در مورد این ماژول ها آورده شده است:

Taskipy یک task runner است که به شما امکان می دهد وظایف مختلف را در پروژه پایتون خود به طور خودکار انجام دهید. در این پروژه از Taskipy برای تعریف و اجرای وظایفی مانند قالب بندی، لینتینگ و تست استفاده می کنیم. وظایف در فایل pyproject.toml در زیر پیکربندی شده اند [tool.taskipy.tasks].

برای اطلاعات بیشتر در مورد Taskipy، اسناد رسمی را بررسی کنید:

این پروژه از چندین لینتر و قالب‌کننده برای حفظ کیفیت و سازگاری کد استفاده می‌کند:

مشکی: یک فرمت کننده کد که به طور خودکار کد شما را مطابق با راهنمای سبک PEP 8 قالب بندی می کند. پیکربندی در فایل pyproject.toml در زیر تنظیم شده است [tool.black].

راف: خطی که کد شما را از نظر نقض راهنمای سبک، اشکالات احتمالی و سایر مشکلات بررسی می کند. این قوانین بسیاری از جمله یکی flake8 و یکی isort را پوشش می دهد. پیکربندی در فایل pyproject.toml در زیر تنظیم شده است [tool.ruff].

مایپی: یک بررسی کننده نوع ایستا که به شناسایی اشکالات احتمالی کمک می کند و از ایمن بودن کد شما اطمینان می دهد. پیکربندی در فایل pyproject.toml در زیر تنظیم شده است [tool.mypy].

این لینترها و قالب‌کننده‌ها در وظایف پروژه و تنظیمات IDE ادغام می‌شوند و از یک سبک کد ثابت در کل پروژه اطمینان می‌دهند.

2. ساختار دایرکتوری ایجاد کنید

دایرکتوری ها و فایل های لازم را ایجاد کنید:

mkdir assets　# you can write main codes in this directory
mkdir tests # you can write test codes in this directory
touch README.md

3. تست های واحد کافی را با pytest بنویسید

اطمینان حاصل کنید که تست های واحد جامع را با استفاده از pytest برای تمام اجزای حیاتی پروژه خود می نویسید. پوشش آزمایشی کافی به حفظ کیفیت کد کمک می کند و احتمال ایجاد اشکال در حین توسعه یا بازآفرینی را کاهش می دهد.

برای نوشتن یک تست واحد، یک تست واحد ایجاد کنید، یک فایل جدید در فهرست تست ها با نامی که از الگوی test_*.py پیروی می کند ایجاد کنید.

در فایل تست، ماژول‌های لازم را وارد کنید و توابع آزمایشی را که از الگوی def test_*(): پیروی می‌کنند، تعریف کنید.

برای مقایسه مقادیر مورد انتظار و واقعی از دستور داخلی pytest استفاده کنید.

برای اجرای تست ها دستور زیر را اجرا کنید:

poetry run task test

قبل از انجام تغییرات و ایجاد یک درخواست کشش، اطمینان حاصل کنید که تمام آزمایشات انجام شده است.

4. تنظیمات IDE را پیکربندی کنید

محتویات فایل pyproject.toml ارائه شده را در فایل تنظیمات مربوط به IDE خود منعکس کنید.

به عنوان مثال، اگر از VSCode استفاده می کنید، تنظیمات زیر را به .vscode/settings.json اضافه کنید:

{
  "python.formatting.provider": "black",
  "python.formatting.blackArgs": ["--line-length", "102"],
  "python.linting.flake8Enabled": true,
  "python.linting.mypyEnabled": true,
  "python.sortImports.args": ["--profile=black", "--line-length=102"],
  "editor.codeActionsOnSave": {
    "source.organizeImports": true,
    "source.fixAll": true
  }
}

• با این تنظیمات، VSCode به طور خودکار با استفاده از Black، Flake8، Mypy و isort، کدها را فرمت می کند و کدهای پرز را در می آورد.

• اگر از IntelliJ/Pycharm استفاده می‌کنید، لطفاً از تابع File Watcher برای اجرای خودکار شعر fmt_lint استفاده کنید.

5. CI (Auto lint/test) را با GitHub Actions تنظیم کنید

پوشه .github/workflows را در ریشه پروژه ایجاد کنید:

mkdir -p .github/workflows

یک فایل test_and_lint.yml ایجاد کنید و محتوای زیر را اضافه کنید:

name: python lint and test

on:
  pull_request:
    branches:
      - main
    paths:
      - "YOUR_PROJECT/**.py"
      - "tests/**.py"
      - "poetry.toml"
      - "poetry.lock"
      - ".github/workflows/test_and_lint.yml"

jobs:
  lint_and_test:
    name: Lint and Test
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        python-version: ["3.11","3.10","3.9"]

    steps:
      - name: Checkout
        uses: actions/checkout@v2

      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v2
        with:
          python-version: ${{ matrix.python-version }}

      - name: Install Poetry
        run: |
          curl -sSL https://install.python-poetry.org | POETRY_HOME=$HOME/.poetry python3 - 
          echo "$HOME/.poetry/bin" >> $GITHUB_PATH

      # cacheがうまく効かない環境があるのでその際は以下の設定はコメントアウトする
      - uses: actions/cache@v2
        id: venv_cache
        with:
          path: .venv
          key: venv-${{ matrix.python-version }}-${{ hashFiles('**/poetry.lock') }}

      - name: Install Dependencies
        if: steps.venv_cache.outputs.cache-hit != 'true'
        run: poetry install

      - name: Python Test
        run: poetry run task test

      - name: Python Lint
        run: poetry run task lint

• نمونه

• این پیکربندی به طور خودکار شعر اجرا وظیفه fmt_lint و شعر اجرا تست وظیفه را روی درخواست‌های فشار و کشش به شاخه اصلی اجرا می‌کند.

6. Stage/Prod Environment را با Dockerfile تنظیم کنید

برای محیط مرحله/پرداخت، از یک Dockerfile برای ساخت محیط اجرا استفاده کنید. ابتدا وابستگی‌های پروژه را با استفاده از دستور زیر به فایل require.txt صادر کنید:

poetry export --without-hashes -f requirements.txt -o requirements.txt

در Dockerfile، از pip install برای نصب وابستگی ها از فایل requires.txt استفاده کنید. اطمینان حاصل کنید که نسخه Python مشخص شده در Dockerfile همان نسخه استفاده شده در محیط محلی است.

با پیروی از این قوانین، می‌توانید از یک محیط توسعه پایدار برای همه اعضای تیم اطمینان حاصل کنید و یک جدایی تمیز بین محیط‌های محلی و صحنه/محصول حفظ کنید.

علاوه بر این، توصیه می‌شود که پیکربندی این فرآیند را در GitHub Actions YAML برای 7 مرحله بعدی استقرار مداوم (CD) ادغام کنید، زیرا نیاز به کار محلی را از بین می‌برد.

7. CD (Atuo build Dockerfile) را با Github Actions تنظیم کنید