الصفحة الرئيسية>المتعلقة بالبرمجة>كود الذكاء الاصطناعي
تنزيل

مثال PYPI (فهرس حزمة Python) الحزمة والتعليمي / التعليم / سير العمل لعام 2021

هذا مثال على حزمة PYPI (فهرس حزمة Python) مع اختبارات آلية وسير عمل للنشر الحزمة باستخدام إجراءات GITHUB CI/CD. إنه مصنوع بشكل أساسي لمستخدمي GitHub + VS Code (Windows / Mac / Linux) الذين هم على وشك كتابة ونشر حزمة PYPI الأولى. يمكن أن تكون الحزمة بمثابة بداية / boilerplate / العرض التوضيحي ، ويمكن أن يمنحك البرنامج التعليمي شرحًا سريعًا وموجزًا ​​لحل بعض المشكلات الصغيرة ولكن المزعجة التي قد تواجهها ، مثل حزمة / الوحدة النمطية للارتباك ، ومشكلات تكوين اختبار الكود.

الاختلافات من pypa/sampleProject (انقر لإظهار/إخفاء)

هذه الحزمة مثال مستوحاة من / بناءً على عينة الرسمية مشروع PYPA / SampleProject ، ولكن هذه الحزمة:

  • هو إصدار مبسط من PYPA/SampleProject (ودليل مستخدم عبوات Python الرسمي)
  • يستخدم إجراءات github لكل من الاختبار والنشر ، بدلاً من Travis CI
  • يتم اختباره عند دفع master أو الفرع main ، ويتم نشره عند إنشاء إصدار
  • يتضمن ملفات الاختبار في توزيع المصدر
  • يستخدم SETUP.CFG للإصدار أحادي المصادر (Setuptools 46.4.0+)
  • لديه .vscode settings.json و vscode.env الذي يضيف SRC/ Folder إلى PYTHONPATH ، بحيث لا تحتوي ملفات الاختبار على أخطاء وقد تعمل مع Pytest في VS Code
  • لا يستخدم Flake8 للانطفاف الآلي - فهو في بعض الأحيان صارم للغاية وغير مرن ، يمكنك استخدام Pylint محليًا بدلاً من ذلك
  • لديه هذا البرنامج التعليمي الذي يغطي كل ما تحتاج إلى معرفته في صفحة واحدة. كل ما قد لا يكون مفيدًا للغاية ، يتم إخفاءه في الأقسام القابلة للطي التي يمكنك النقر عليها لإظهارها
  • لديه ملف .editorConfig

قم بإجراء التغييرات اللازمة

استخدم كقالب

(انقر فوق الزر أعلاه لاستخدام حزمة المثال هذا كقالب لإعادة ريبو GitHub الجديدة ، سيؤدي ذلك إلى تهيئة مستودع جديد ولن تكون رعايتي في سجل GIT الخاص بك)

(إذا لم تستخدم github ، يمكنك تنزيل أرشيف حزمة المثال)

حزمة ، اسم الوحدة النمطية

يستخدم الكثيرون نفس الحزمة والوحدة ، يمكنك بالتأكيد القيام بذلك. لكن حزمة المثال هذه وأسماء الوحدة النمطية مختلفة: example_pypi_package و examplepy .

افتح المجلد example_pypi_package مع رمز Visual Studio أو Ctrl + Shift + F (Windows / Linux) أو CMD + Shift + F (MacOS) للعثور على جميع أحداث كلا الاسمين واستبدالها بأسماء الحزمة والوحدة النمطية. تذكر أيضًا تغيير اسم المجلد src/examplepy .

ببساطة وبشكل تقريبًا ، يتم استخدام اسم الحزمة في pip install <PACKAGENAME> ويستخدم اسم الوحدة النمطية في import <MODULENAME> . يجب أن يتكون كلا الاسمين من الحروف الأساسية الصغيرة (AZ). قد يكون لديهم سطحي ( _ ) إذا كنت بحاجة إليها حقًا. لا ينبغي استخدام الواصلة ( - ).

ستحتاج أيضًا إلى التأكد من أن عنوان URL "https://pypi.org/project/example-pypi-package/" (استبدل example-pypi-package باسم الحزمة ، مع كل _ - ) غير مشغل.

تفاصيل حول اتفاقية التسمية (انقر لإظهار/إخفاء)

يمكن استخدام السطح السفلي ( _ ) ولكن هذا الاستخدام يتم تثبيته. يمكن استخدام الأرقام إذا لم يبدأ الاسم برقم ، ولكن يتم تثبيط هذا الاستخدام أيضًا.

لا ينبغي استخدام الاسم الذي يبدأ برقم و/أو يحتوي على الواصلة ( - ): على الرغم من قانوني تقنيًا ، فإن هذا الاسم يسبب الكثير من المتاعب - يجب على المستخدمين استخدام importlib لاستيراده.

لا تنخدع بواسطة عنوان URL "pypi.org/project/example-pypi-package/" و "example-pypi-package" على pypi.org. يقوم نظام pypi.org و pip بتحويل جميع _ - واستخدام الأخير على موقع الويب / في أمر pip ، ولكن لا يزال الاسم الحقيقي مع _ ، والذي يجب على المستخدمين استخدامه عند استيراد الحزمة.

هناك أيضًا مساحة اسم للاستخدام إذا كنت بحاجة إلى حزم فرعية.

تغييرات أخرى

إجراء تغييرات ضرورية في الإعداد .

رقم إصدار الحزمة __version__ في SRC/examplepy/__ init__.py . قد ترغب في تغيير ذلك.

تم تصميم حزمة المثال لتكون متوافقة مع Python 3.6 ، 3.7 ، 3.8 ، 3.9 ، وسيتم اختبارها مقابل هذه الإصدارات. إذا كنت بحاجة إلى تغيير نطاق الإصدار ، فيجب عليك التغيير:

  • classifiers ، python_requires في setup.py
  • envlist في tox.ini
  • matrix: python: في .github/سير العمل/test.yml

إذا كنت تخطط للتحميل إلى TestPypi الذي يعد ملعبًا لـ PYPI لغرض الاختبار ، قم بتغيير twine upload --repository pypi dist/* to twine upload --repository testpypi dist/* في الملف .github/سير العمل/الإصدار .

تطوير

pip

PIP هو مدير حزمة بيثون. لديك بالفعل PIP إذا كنت تستخدم Python 3.4 والإصدار اللاحق الذي يتضمنه افتراضيًا. اقرأ هذا لمعرفة كيفية التحقق مما إذا تم تثبيت PIP. اقرأ هذا إذا كنت بحاجة إلى تثبيته.

استخدم VS Code

Visual Studio Code هو محرر الرمز الأكثر شعبية اليوم ، يتم تكوين حزمة المثال لدينا للعمل مع VS Code.

قم بتثبيت امتداد رمز "Python".

"Python" VS Code Extension سيقترح عليك تثبيت Pylint. أيضًا ، تم تكوين حزمة المثال لاستخدام Pytest مع امتدادات VS Code + Python ، لذلك ، قم بتثبيت Pylint و Pytest: 

pip install pylint pytest

(من المحتمل أن تتم مطالبتك بتثبيتها ، إذا كان هذا هو الحال ، فأنت لا تحتاج إلى كتابة الأمر وتنفيذ الأمر)

محتوى VScode.env هو الآن PYTHONPATH=/;src/;${PYTHONPATH} وهو أمر جيد لنظام التشغيل Windows. إذا كنت تستخدم Linux أو MacOS ، فأنت بحاجة إلى تغييره إلى PYTHONPATH=/:src/:${PYTHONPATH} (استبدال ; مع : . إذا لم يتم تعيين المسار بشكل صحيح ، فسترى أخطاء في ملفات الاختبار ولن تتمكن pytest من إجراء اختبارات/اختبار _*. ملفات PY بشكل صحيح.

أغلق وإعادة فتح الكود. يمكنك الآن النقر فوق أيقونة Lab Flask في القائمة اليسرى وتشغيل جميع الاختبارات هناك ، مع Pytest. يبدو Pytest أفضل من الإطار القياسي غير المعتاد ، وهو يدعم unittest وبالتالي يمكنك الاستمرار في استخدام import unittest في ملفات الاختبار الخاصة بك.

تحتوي حزمة المثال أيضًا على ملف .editorConfig . يمكنك تثبيت ملحق VS Code "EditorConfig لـ VS Code" الذي يستخدم الملف. مع التكوين الحالي ، يمكن لأداة EditorConfig استخدام المساحات تلقائيًا (4 مسافات لـ .py ، 2 للآخرين) للمسافة البادئة ، تعيين UTF-8 الترميز ، نهاية LF للخطوط ، تقليم المساحات البيضاء الزائدة في الملفات غير المميزة ، إلخ ، إلخ.

في VS Code ، يمكنك الانتقال إلى الملف -> التفضيلات -> الإعدادات ، واكتب "مزود تنسيق Python" في مربع البحث ، واختر أحد أدوات تنسيق رمز Python الثلاثة (Autopep8 ، Black و YAPF) ، ستتم مطالبتك بتثبيته. اختصارات تنسيق ملف رمز هي Shift + Alt + F (Windows) ؛ Shift + Option (alt) + f (macOS) ؛ Ctrl + Shift + I (Linux).

اكتب الحزمة الخاصة بك

في src/ examplepy/ ( examplepy يجب استبداله باسم الوحدة النمطية) ، إعادة تسمية module1.py واكتب الكود الخاص بك فيه. أضف المزيد من ملفات .py إذا كنت بحاجة إلى ذلك.

اكتب اختباراتك

في الاختبارات/ المجلد ، أعد تسمية Test_Module1.py (للاختبار _* . أضف المزيد من الاختبار _*. ملفات PY إذا كنت بحاجة إلى ذلك.

سيتم استخدام أداة الاختبار `tox` في الأتمتة مع إجراءات github ci/cd. إذا كنت ترغب في استخدام "Tox` محليًا ، فانقر لقراءة قسم" استخدام Tox Localio "

استخدام توكس محليا

قم بتثبيت Tox وقم بتشغيله: 

pip install tox
tox

في تكويننا ، يقوم Tox بتشغيل فحص لتوزيع المصدر باستخدام Check-Manifest (والذي يتطلب أن يكون Repo الخاص بك git-initialized ( git init ) وإضافته ( git add . ) على الأقل) ، والتحقق من setuptools ، واختبارات الوحدة باستخدام pytest. لا تحتاج إلى تثبيت Check-Manifest و Pytest ، سيقوم Tox بتثبيتها في بيئة منفصلة.

يتم إجراء الاختبارات الآلية مقابل العديد من إصدارات Python ، ولكن على جهازك ، قد تستخدم إصدارًا واحدًا فقط من Python ، إذا كان هذا هو Python 3.9 ، ثم قم بتشغيله: 

tox -e py39

إذا قمت بإضافة المزيد من الملفات إلى دليل الجذر ( example_pypi_package/ ) ، فستحتاج إلى إضافة ملفك check-manifest --ignore في tox.ini .

بفضل العملية الآلية لـ GitHub Actions ، لا تحتاج إلى إنشاء ملفات توزيع محليًا. ولكن إذا أصرت ، انقر لقراءة قسم "إنشاء ملفات التوزيع"

إنشاء ملفات التوزيع

تثبيت الأدوات

تثبيت أو ترقية setuptools wheel : 

python -m pip install --user --upgrade setuptools wheel

(إذا كان python3 هو الأمر الموجود على جهازك ، فقم بتغيير python إلى python3 في الأمر أعلاه ، أو إضافة سطر alias python=python3 إلى ~/.bashrc أو ~/.bash_aliasies إذا كنت تستخدم bash على linux)

توليد dist

من دليل example_pypi_package ، قم بتشغيل الأمر التالي ، من أجل إنشاء إصدار الإنتاج لتوزيع المصدر (SDIST) في مجلد dist : 

python setup.py sdist bdist_wheel

تثبيت محليا

اختياريا ، يمكنك تثبيت إصدار DIST من الحزمة الخاصة بك محليًا قبل التحميل إلى PYPI أو TestPypi: 

pip install dist/example_pypi_package-0.1.0.tar.gz

(قد تحتاج إلى إلغاء تثبيت الحزمة الحالية أولاً: 

pip uninstall example_pypi_package

قد يكون هناك العديد من الحزم المثبتة بنفس الاسم ، لذا قم بتشغيل قم pip uninstall عدة مرات حتى لا تقول حزمة مزيد من الإزالة.)

تحميل إلى PYPI

سجل على PYPI واحصل على الرمز المميز

قم بتسجيل حساب على PYPI ، انتقل إلى إعدادات الحساب § رموز API ، "إضافة رمز API". يظهر رمز PYPI مرة واحدة فقط ، ونسخه في مكان ما. إذا فاتتك ذلك ، احذف القديم وأضف رمزًا جديدًا.

(سجل حساب TestPypi إذا كنت تقوم بتحميل إلى TestPypi)

تعيين سر في جيثب ريبو

في صفحة REPO التي تم إنشاؤها حديثًا أو حاليًا ، انقر فوق الإعدادات -> أسرار -> سر مستودع جديد ، يجب أن يكون الاسم PYPI_API_TOKEN وينبغي أن تكون القيمة الرمز المميز لـ pypi (الذي يبدأ بـ pypi- ).

دفع أو إطلاق

تحتوي حزمة المثال على اختبارات وتحميل (نشر) تم إعدادها بالفعل مع إجراءات GitHub:

  • في كل مرة يتم تقديم git push أو طلب سحب على الفرع master أو الفرع main ، يتم اختبار الحزمة تلقائيًا مقابل إصدارات Python المطلوبة مع إجراءات GitHub.
  • في كل مرة يتم إنشاء إصدار جديد (إما الإصدار الأولي أو إصدار محدث) ، يتم تحميل أحدث إصدار من الحزمة تلقائيًا إلى PYPI مع إجراءات GitHub.

عرضه على pypi.org

بعد نشر الحزمة الخاصة بك على PYPI ، انتقل إلى https://pypi.org/project/example-pakage/ ( _ - ). انسخ الأمر على الصفحة ، وقم بتنفيذه لتنزيل الحزمة الخاصة بك من PYPI وتثبيتها. (أو test.pypi.org إذا كنت تستخدم ذلك)

إذا كنت ترغب في تعديل الوصف / ReadMe من الحزمة الخاصة بك على pypi.org ، فيجب عليك نشر إصدار جديد.

إذا قمت بنشر الحزمة الخاصة بك إلى PYPI يدويًا ، فانقر للقراءة

تثبيت خيوط

قم بتثبيت أو ترقية خيوط: 

python -m pip install --user --upgrade twine

قم بإنشاء ملف .pypirc في دليل $ home ( ~ ) ، يجب أن يكون محتواه: 

 [pypi]
username = __token__
password = <PyPI token>

(استخدم [testpypi] بدلاً من [pypi] إذا كنت تقوم بتحميل إلى testpypi)

استبدل <PyPI token> برمز PYPI الحقيقي الخاص بك (الذي يبدأ بـ pypi- ).

(إذا لم تقم بإنشاء $ home/.pypirc يدويًا ، فسيتم مطالبتك بالاسم المستخدم (الذي يجب أن يكون __token__ ) وكلمة المرور (التي يجب أن تكون رمز Pypi الخاص بك) عند تشغيل خيوط)

رفع

قم بتشغيل Twine لتحميل جميع المحفوظات تحت مجلد Dist : 

python -m twine upload --repository pypi dist/ *

(استخدم testpypi بدلاً من pypi إذا كنت تقوم بتحميل إلى TestPypi)

تحديث

عند الانتهاء من تطوير إصدار أحدث من الحزمة الخاصة بك ، قم بالأشياء التالية.

قم بتعديل رقم الإصدار __version__ في src exampleminit __. py .

حذف جميع الإصدارات القديمة في dist .

قم بتشغيل الأمر التالي مرة أخرى لتجديد Dist : 

python setup.py sdist bdist_wheel

قم بتشغيل الأمر التالي مرة أخرى لتحميل DIST : 

python -m twine upload --repository pypi dist/ *

(استخدم testpypi بدلاً من pypi إذا لزم الأمر)

مراجع

  • مشروع عينة التغليف Python (PYPA)
  • دليل مستخدم التغليف Python Python's Python
  • أسئلة وأجوبة stackoverflow
  • أدلة الإجراءات github: بناء واختبار Python

راجع للشغل ، إذا كنت ترغب في نشر حزمة TypeScript (JavaScript) إلى سجل NPM ، انتقل إلى مثال حزمة TypeScript جاهزة لنشرها على NPM لعام 2021.

يوسع
معلومات إضافية
تطبيقات ذات صلة
نوصي لك
أخبار ذات صلة الكل