example_pypi_package
v0.1.0
นี่เป็นตัวอย่างแพ็คเกจ PYPI (Python Package) ที่ตั้งค่าด้วยการทดสอบอัตโนมัติและเวิร์กโฟลว์การเผยแพร่แพ็คเกจโดยใช้ GitHub Actions CI/CD มันถูกสร้างขึ้นเป็นหลักสำหรับผู้ใช้ GitHub + VS (Windows / Mac / Linux) ผู้ใช้ที่กำลังจะเขียนและเผยแพร่แพ็คเกจ PYPI แรกของพวกเขา แพ็คเกจสามารถทำหน้าที่เป็นสตาร์ทเตอร์ / หม้อไอน้ำ / การสาธิตและการสอนอาจให้คำอธิบายที่รวดเร็วและรัดกุมเพื่อแก้ปัญหาเล็ก ๆ แต่น่ารำคาญที่คุณอาจพบเช่นแพ็คเกจ / ชื่อโมดูลสับสนและปัญหาการกำหนดค่าการทดสอบรหัส VS
แพ็คเกจตัวอย่างนี้ได้รับแรงบันดาลใจจาก / ตามตัวอย่างโครงการ PYPA / SampleProject อย่างเป็นทางการ แต่แพ็คเกจนี้:
master หรือสาขา main และเผยแพร่เมื่อสร้างการเปิดตัวPYTHONPATH เพื่อให้ไฟล์ทดสอบไม่มีข้อผิดพลาดเกี่ยวกับผ้าสำลีและอาจทำงานด้วย pytest ในรหัส VS(คลิกปุ่มด้านบนเพื่อใช้แพ็คเกจตัวอย่างนี้เป็นเทมเพลตสำหรับ repo 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 System จะแปลง _ ทั้งหมดเป็น - และใช้หลังบนเว็บไซต์ / ในคำสั่ง pip แต่ชื่อจริงยังคงอยู่กับ _ ซึ่งผู้ใช้ควรใช้เมื่อนำเข้าแพ็คเกจ
นอกจากนี้ยังมีเนมสเปซให้ใช้หากคุณต้องการแพคเกจย่อย
ทำการเปลี่ยนแปลงที่จำเป็นใน setup.py
หมายเลขเวอร์ชันของแพ็คเกจ __version__ อยู่ใน SRC/ExamplePy/__ init__.py คุณอาจต้องการเปลี่ยนสิ่งนั้น
แพ็คเกจตัวอย่างได้รับการออกแบบให้เข้ากันได้กับ Python 3.6, 3.7, 3.8, 3.9 และจะถูกทดสอบกับเวอร์ชันเหล่านี้ หากคุณต้องการเปลี่ยนช่วงเวอร์ชันคุณควรเปลี่ยน:
classifiers , python_requires ใน setup.pyenvlist ใน tox.inimatrix: python: ใน . github/workflows/test.yml หากคุณวางแผนที่จะอัปโหลดไปยัง TestPypi ซึ่งเป็นสนามเด็กเล่นของ PYPI เพื่อจุดประสงค์ในการทดสอบให้เปลี่ยน twine upload --repository pypi dist/* เพื่อ twine upload --repository testpypi dist/* ในไฟล์ . github/workflows/release.yml
PIP เป็นตัวจัดการแพ็คเกจ Python คุณมี PIP อยู่แล้วหากคุณใช้ Python 3.4 และรุ่นใหม่กว่าซึ่งรวมอยู่ในค่าเริ่มต้น อ่านสิ่งนี้เพื่อทราบวิธีการตรวจสอบว่าติดตั้ง PIP หรือไม่ อ่านสิ่งนี้หากคุณต้องการติดตั้ง
Visual Studio Code เป็นโปรแกรมแก้ไขรหัสที่ได้รับความนิยมมากที่สุดในปัจจุบันแพ็คเกจตัวอย่างของเราได้รับการกำหนดค่าให้ทำงานกับรหัส VS
ติดตั้ง VS Code Extension "Python"
"Python" VS Code Extension จะแนะนำให้คุณติดตั้ง Pylint นอกจากนี้แพ็คเกจตัวอย่างได้รับการกำหนดค่าให้ใช้ pytest กับส่วนขยาย VS + 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 Extension "EditorConfig สำหรับ VS Code" ที่ใช้ไฟล์ ด้วยการกำหนดค่าปัจจุบันเครื่องมือ editorConfig สามารถใช้ช่องว่างโดยอัตโนมัติ (4 ช่องว่างสำหรับ. py, 2 สำหรับอื่น ๆ ) สำหรับการเยื้อง, ตั้งค่าการเข้ารหัส UTF-8 , LF end ของบรรทัด, การตัดแต่งช่องว่างในไฟล์ที่ไม่ใช่การทำเครื่องหมาย ฯลฯ ฯลฯ
ในรหัส VS คุณสามารถไปที่ไฟล์ -> การตั้งค่า -> การตั้งค่าพิมพ์ "ผู้ให้บริการการจัดรูปแบบ Python" ในช่องค้นหาและเลือกหนึ่งในสามเครื่องมือการจัดรูปแบบรหัส Python (AutopeP8, Black และ Yapf) คุณจะได้รับแจ้งให้ติดตั้ง ทางลัดสำหรับการจัดรูปแบบไฟล์รหัสคือ Shift + Alt + F (Windows); ตัวเลือก Shift + (alt) + f (macOS); Ctrl + Shift + I (Linux)
ใน SRC/ ExamplePy/ ( examplepy ควรถูกแทนที่ด้วยชื่อโมดูลของคุณ) โฟลเดอร์ Rename Module1.py และเขียนรหัสของคุณในนั้น เพิ่มโมดูลเพิ่มเติมไฟล์. py หากคุณต้องการ
ใน การทดสอบ/ โฟลเดอร์เปลี่ยนชื่อ test_module1.py (เพื่อ ทดสอบ _*. py ) และเขียนรหัสทดสอบหน่วยของคุณ (ด้วย unittest) ในนั้น เพิ่ม การทดสอบเพิ่มเติม _*. ไฟล์ py หากคุณต้องการ
ติดตั้ง TOX และเรียกใช้:
pip install tox
tox ในการกำหนดค่าของเรา TOX เรียกใช้การตรวจสอบการกระจายแหล่งที่มาโดยใช้เช็ค-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
ติดตั้งหรืออัพเกรด setuptools และ wheel :
python -m pip install --user --upgrade setuptools wheel (ถ้า python3 เป็นคำสั่งบนเครื่องของคุณให้เปลี่ยน python เป็น python3 ในคำสั่งด้านบนหรือเพิ่มนามแฝง alias python=python3 เป็น ~/.bashrc หรือ ~/.bash_aliases หากคุณใช้ Bash on 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 ไปที่การตั้งค่าบัญชี§ Tokens API, "เพิ่ม API Token" โทเค็น PYPI ปรากฏขึ้นเพียงครั้งเดียวคัดลอกที่ไหนสักแห่ง หากคุณพลาดให้ลบเก่าและเพิ่มโทเค็นใหม่
(ลงทะเบียนบัญชี TestPypi หากคุณกำลังอัปโหลดไปยัง TestPypi)
ในหน้าของ GitHub Repo ที่สร้างขึ้นใหม่หรือที่มีอยู่ของคุณคลิก การตั้งค่า -> ความลับ -> ความลับที่เก็บใหม่ ชื่อ ควรเป็น PYPI_API_TOKEN และ ค่า ควรเป็นโทเค็น Pypi ของคุณ (ซึ่งเริ่มต้นด้วย pypi- )
แพ็คเกจตัวอย่างมีการทดสอบอัตโนมัติและอัปโหลด (การเผยแพร่) ตั้งค่าแล้วด้วยการกระทำของ GitHub:
git push หรือคำขอดึงจะถูกส่งไปยัง master หรือสาขา main ของคุณแพ็คเกจจะถูกทดสอบโดยอัตโนมัติกับรุ่น Python ที่ต้องการพร้อมการกระทำของ GitHub หลังจากที่แพ็คเกจของคุณถูกเผยแพร่บน PYPI ให้ไปที่ https://pypi.org/project/example-pypi-package/ ( _ กลายเป็น - ) คัดลอกคำสั่งในหน้าดำเนินการเพื่อดาวน์โหลดและติดตั้งแพ็คเกจของคุณจาก PYPI (หรือ test.pypi.org ถ้าคุณใช้สิ่งนั้น)
หากคุณต้องการแก้ไขคำอธิบาย / readme ของแพ็คเกจของคุณบน pypi.org คุณต้องเผยแพร่เวอร์ชันใหม่
ติดตั้งหรืออัพเกรด Twine:
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)
เรียกใช้ Twine เพื่ออัปโหลดคลังเก็บทั้งหมดภายใต้โฟลเดอร์ Dist :
python -m twine upload --repository pypi dist/ * (ใช้ testpypi แทน pypi หากคุณกำลังอัปโหลดไปยัง TestPypi)
เมื่อคุณพัฒนาแพ็คเกจรุ่นใหม่ของคุณเสร็จแล้วให้ทำสิ่งต่อไปนี้
แก้ไขหมายเลขเวอร์ชัน __version__ ใน Src ExamplePy__init __. Py
ลบเวอร์ชันเก่าทั้งหมดใน Dist
เรียกใช้คำสั่งต่อไปนี้อีกครั้งเพื่อสร้าง Dist :
python setup.py sdist bdist_wheelเรียกใช้คำสั่งต่อไปนี้อีกครั้งเพื่ออัปโหลด Dist :
python -m twine upload --repository pypi dist/ * (ใช้ testpypi แทน pypi ถ้าจำเป็น)
BTW หากคุณต้องการเผยแพร่แพ็คเกจ TypeScript (JavaScript) ไปยังรีจิสทรี NPM ให้ไปที่ตัวอย่างแพ็คเกจ TypeScript พร้อมที่จะเผยแพร่บน NPM สำหรับปี 2021
