إنشاء حزم Python: دليل التطوير إلى PyPI

[build-system]
requires = ["setuptools>=68.0", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "mypackage"
version = "0.1.0"
description = "حزمة رائعة لـ Python"
readme = "README.md"
requires-python = ">=3.8"
license = {text = "MIT"}
authors = [
    {name = "الاسم", email = "you@example.com"}
]
keywords = ["مثال", "دورة تدريبية", "حزمة"]
classifiers = [
    "الحالة التطويرية :: 4 - بيتا",
    "الجمهور المستهدف :: المطورين",
    "الترخيص :: مُوافقة OSI :: ترخيص MIT",
    "لغة البرمجة :: Python :: 3",
    "لغة البرمجة :: Python :: 3.8",
    "لغة البرمجة :: Python :: 3.9",
    "لغة البرمجة :: Python :: 3.10",
    "لغة البرمجة :: Python :: 3.11",
    "لغة البرمجة :: Python :: 3.12",
]
dependencies = [
    "requests>=2.28.0",
    "click>=8.1.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.4.0",
    "black>=23.0.0",
    "flake8>=6.0.0",
    "mypy>=1.5.0",
]
docs = [
    "sphinx>=7.0.0",
    "sphinx-rtd-theme>=1.3.0",
]

[project.urls]
Homepage = "https://github.com/yourusername/mypackage"
Documentation = "https://mypackage.readthedocs.io"
Repository = "https://github.com/yourusername/mypackage"
Issues = "https://github.com/yourusername/mypackage/issues"

[project.scripts]
mypackage-cli = "mypackage.cli:main"

[tool.setuptools.packages.find]
where = ["src"]

[build-system]
requires = ["setuptools>=68.0", "wheel"]
build-backend = "setuptools.build_meta"

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[build-system]
requires = ["poetry-core>=1.0.0"]
build-backend = "poetry.core.masonry.api"

[tool.poetry]
name = "mypackage"
version = "0.1.0"
description = "حزمة رائعة لـ Python"
authors = ["الاسم <you@example.com>"]

[tool.poetry.dependencies]
python = "^3.8"
requests = "^2.28.0"

[build-system]
requires = ["flit_core >=3.2,<4"]
build-backend = "flit_core.buildapi"

# تثبيت الأداة الحديثة للبناء
pip install build

# أو لـ Poetry
pip install poetry

# أو لـ Hatchling
pip install hatch

# تنظيف البناءات السابقة
rm -rf dist/ build/ *.egg-info

# بناء التوزيع المصدر والوهل
python -m build

# هذا ينشئ:
# dist/mypackage-0.1.0.tar.gz    (توزيع المصدر)
# dist/mypackage-0.1.0-py3-none-any.whl  (وهل)

poetry build

hatch build

# تثبيت twine
pip install twine

# تحقق من الحزمة قبل الرفع
twine check dist/*

# رفع إلى TestPyPI أولاً (مُوصى به)
twine upload --repository testpypi dist/*

# اختبار التثبيت من TestPyPI
pip install --index-url https://test.pypi.org/simple/ mypackage

# رفع إلى PyPI الإنتاجي
twine upload dist/*

[distutils]
index-servers =
    pypi
    testpypi

[pypi]
username = __token__
password = pypi-AgEIcHlwaS5vcmc...

[testpypi]
repository = https://test.pypi.org/legacy/
username = __token__
password = pypi-AgENdGVzdC5weXBpLm9yZw...

name: Publish to PyPI

on:
  release:
    types: [published]

permissions:
  contents: read

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      
      - name: Install build dependencies
        run: |
          python -m pip install --upgrade pip
          pip install build          
      
      - name: Build package
        run: python -m build
      
      - name: Store distribution packages
        uses: actions/upload-artifact@v3
        with:
          name: python-package-distributions
          path: dist/

  publish:
    needs: build
    runs-on: ubuntu-latest
    environment: release
    permissions:
      id-token: write
    
    steps:
      - name: Download distributions
        uses: actions/download-artifact@v3
        with:
          name: python-package-distributions
          path: dist/
      
      - name: Publish to PyPI
        uses: pypa/gh-action-pypi-publish@release/v1

# تثبيت أداة رفع الإصدار
pip install bump2version

# رفع الإصدار
bump2version patch  # 0.1.0 -> 0.1.1
bump2version minor  # 0.1.1 -> 0.2.0
bump2version major  # 0.2.0 -> 1.0.0

[bumpversion]
current_version = 0.1.0
commit = True
tag = True

[bumpversion:file:pyproject.toml]
search = version = "{current_version}"
replace = version = "{new_version}"

[bumpversion:file:src/mypackage/__init__.py]
search = __version__ = "{current_version}"
replace = __version__ = "{new_version}"

# تثبيت التبعيات الخاصة بالاختبار
pip install pytest pytest-cov

# قم باختبار مع التغطية
pytest --cov=mypackage tests/

# أنشئ تقرير التغطية
pytest --cov=mypackage --cov-report=html tests/

[tool.pytest.ini_options]
testpaths = ["tests"]
python_files = ["test_*.py"]
python_functions = ["test_*"]
addopts = "--strict-markers --cov=mypackage"

# التنسيق
black src/ tests/

# التنقيح
flake8 src/ tests/

# التحقق من النوع
mypy src/

# ترتيب الواردات
isort src/ tests/

repos:
  - repo: https://github.com/psf/black
    rev: 23.9.1
    hooks:
      - id: black
  
  - repo: https://github.com/pycqa/flake8
    rev: 6.1.0
    hooks:
      - id: flake8
  
  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.5.1
    hooks:
      - id: mypy

# تثبيت Sphinx
pip install sphinx sphinx-rtd-theme

# تهيئة الوثائق
cd docs
sphinx-quickstart

# بناء الوثائق
make html

pip install mkdocs mkdocs-material
mkdocs new .
mkdocs serve

name: CI

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        python-version: ['3.8', '3.9', '3.10', '3.11', '3.12']
    
    steps:
      - uses: actions/checkout@v4
      
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: ${{ matrix.python-version }}
      
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -e ".[dev]"          
      
      - name: Run tests
        run: pytest --cov=mypackage --cov-report=xml
      
      - name: Upload coverage
        uses: codecov/codecov-action@v3
        with:
          file: ./coverage.xml
  
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      
      - name: Install dependencies
        run: |
          pip install black flake8 mypy          
      
      - name: Black formatting check
        run: black --check src/ tests/
      
      - name: Flake8
        run: flake8 src/ tests/
      
      - name: MyPy
        run: mypy src/

[tool.setuptools.packages.find]
where = ["src"]
include = ["mypackage*"]

[project]
dependencies = [
    "requests>=2.28.0",
    "click>=8.1.0",
]

# إنشاء بيئة مُفصولة
python -m venv .venv
source .venv/bin/activate  # على Windows: .venv\Scripts\activate

# تثبيت في وضع تطوير قابل للتحرير
pip install -e ".[dev]"

[project.scripts]
mypackage = "mypackage.cli:main"

import click

@click.command()
@click.option('--name', default='World', help='اسم للاستقبال')
def main(name):
    """مثال بسيط لواجهة سطر الأوامر"""
    click.echo(f'مرحبا، {name}!')

if __name__ == '__main__':
    main()

[project.entry-points."mypackage.plugins"]
plugin_a = "mypackage_plugin_a:PluginA"

[tool.setuptools.ext-modules]
name = "mypackage._speedups"
sources = ["src/mypackage/_speedups.c"]

[tool.setuptools.packages.find]
where = ["src"]
include = ["company.*"]

[tool.setuptools.package-data]
"company.mypackage" = ["py.typed"]