pynblint

นักวิทยาศาสตร์ข้อมูลมืออาชีพหลายคนใช้สมุดบันทึก Jupyter เพื่อทำงานประจำวันให้สำเร็จตั้งแต่การสำรวจข้อมูลเบื้องต้นไปจนถึงการสร้างต้นแบบแบบจำลอง การโต้ตอบของโน้ตบุ๊กนั้นสะดวกโดยเฉพาะอย่างยิ่งสำหรับการเขียนโปรแกรมที่เน้นข้อมูลเป็นศูนย์กลางและลักษณะการจัดทำเอกสารด้วยตนเองของพวกเขาให้การสนับสนุนที่ยอดเยี่ยมสำหรับการสื่อสารของผลการวิเคราะห์

อย่างไรก็ตามสมุดบันทึก Jupyter มักถูกวิพากษ์วิจารณ์ว่าเป็นการกระตุ้นพฤติกรรมการเขียนโปรแกรมที่ไม่ดีและแนวทางปฏิบัติที่ดีที่สุดของวิศวกรรมซอฟต์แวร์ เพื่อให้ได้ประโยชน์จากสมุดบันทึกผู้ใช้ควรตระหนักถึงข้อผิดพลาดทั่วไปของพวกเขาและเรียนรู้วิธีป้องกันพวกเขา

ในงานก่อนหน้านี้ (ดู "แนวทางปฏิบัติที่ดีที่สุดสำหรับการทำงานร่วมกันกับสมุดบันทึกการคำนวณ" [1]) เราได้แนะนำแคตตาล็อกของแนวทางที่ได้รับการตรวจสอบความถูกต้องเชิงประจักษ์ 17 แนวทางสำหรับการใช้โน้ตบุ๊กร่วมกันในบริบทระดับมืออาชีพ

เพื่อส่งเสริมการใช้แนวทางปฏิบัติที่ดีที่สุดเหล่านี้เราได้สร้าง Pynblint ซึ่งเป็นเครื่องมือวิเคราะห์แบบคงที่สำหรับสมุดบันทึก Jupyter ที่เขียนใน Python Pynblint เปิดเผยข้อบกพร่องของสมุดบันทึกที่อาจเกิดขึ้นและแนะนำการดำเนินการแก้ไข สามารถใช้งานได้ว่าเป็นแอปพลิเคชัน CLI แบบสแตนด์อโลนหรือเป็นส่วนหนึ่งของท่อส่ง CI/CD

กฎผ้าสำลีหลักของ Pynblint นั้นได้รับมาจากการดำเนินงานของแนวทางปฏิบัติที่ดีที่สุดจากแคตตาล็อกของเรา อย่างไรก็ตามสถาปัตยกรรมปลั๊กอินของ Pynblint ช่วยให้ผู้ใช้สามารถขยายชุดการตรวจสอบหลักได้อย่างง่ายดายด้วยกฎผ้าสำลีของตนเอง

ความต้องการ

Python 3.7+

การติดตั้ง

Pynblint สามารถติดตั้งด้วย pip หรือ PYPI Package Manager อื่น:

pip install pynblint

หลังจากการติดตั้งเราขอแนะนำให้สำรวจอินเทอร์เฟซบรรทัดคำสั่งของเครื่องมือ:

pynblint --help

การใช้งาน

Pynblint สามารถใช้ในการวิเคราะห์:

• สมุดบันทึกแบบสแตนด์อโลน:

  pynblint path/to/the/notebook.ipynb

• ที่เก็บรหัสที่มีสมุดบันทึก:

  pynblint path/to/the/project/dir/

  • (อาจบีบอัดเป็น. charch .zip ):

    pynblint path/to/the/compressed/archive.zip

• พื้นที่เก็บข้อมูล สาธารณะ GitHub ที่มีสมุดบันทึก (สนับสนุนที่เก็บส่วนตัวอยู่บนแผนงานของเรา?):

  pynblint --from-github https://github.com/collab-uniba/pynblint

สำหรับข้อมูลเพิ่มเติมเกี่ยวกับตัวเลือกที่มีอยู่โปรดดูเอกสารประกอบโครงการ

แคตตาล็อกของแนวปฏิบัติที่ดีที่สุด

ปัจจุบัน Pynblint ใช้กฎผ้าสำลี 22 ฉบับ:

• 17 กฎที่ใช้บังคับกับสมุดบันทึกแบบสแตนด์อโลน
• 5 กฎที่ใช้บังคับกับที่เก็บวิทยาศาสตร์ข้อมูลทั้งหมด

กฎเหล่านี้มาจากแคตตาล็อกที่ครอบคลุมของเราเกี่ยวกับแนวปฏิบัติที่ดีที่สุดสำหรับการพัฒนาสมุดบันทึกความร่วมมือ [1] ด้านล่างนี้เป็นสถานะการใช้งานปัจจุบันของกฎการตัดหญ้าที่เกี่ยวข้องกับการปฏิบัติที่ดีที่สุดแต่ละครั้ง:

• ✅เสร็จสมบูรณ์: ดำเนินการอย่างเต็มที่
• - บางส่วน: ดำเนินการบางส่วนกับการปรับปรุงที่วางแผนไว้
• ⏳อยู่ระหว่างดำเนินการ: การดำเนินการตามแผนสำหรับการเผยแพร่ในอนาคต
• ไม่ได้วางแผนไว้: ไม่มีการวางแผนการดำเนินการ

แนวปฏิบัติที่ดีที่สุดจาก [1]	สถานะ	รายละเอียด
1. ใช้การควบคุมเวอร์ชัน	✅เสร็จสมบูรณ์	ดำเนินการอย่างเต็มที่
2. จัดการการพึ่งพาโครงการ	✅เสร็จสมบูรณ์	ดำเนินการอย่างเต็มที่
3. ใช้สภาพแวดล้อมที่มีอยู่ในตัวเอง	⏳กำลังดำเนินการ:	วางแผน : การตรวจจับของ - สภาพแวดล้อมเสมือนจริงของ Python (เช่นสร้างขึ้นด้วย venv , pyenv หรือ conda ) - สภาพแวดล้อมแบบคอนเทนเนอร์ (เช่น Docker)
4. ใส่การนำเข้าที่จุดเริ่มต้น	✅เสร็จสมบูรณ์	ดำเนินการอย่างเต็มที่
5. ตรวจสอบความสามารถในการตรวจสอบอีกครั้ง (โน้ตบุ๊กรันใหม่จากบนลงล่าง)	✅เสร็จสมบูรณ์	ดำเนินการอย่างเต็มที่
6. โมดูลรหัสของคุณ	- บางส่วน	ปัจจุบัน : การตรวจจับการสร้างแบบแยกส่วนในโน้ตบุ๊ก วางแผน : คำแนะนำ refactoring แบบแยกส่วนที่เน้นตามรูปแบบที่ตรวจพบ
7. ทดสอบรหัสของคุณ	- บางส่วน	ปัจจุบัน : การตรวจจับระดับที่เก็บข้อมูลความครอบคลุม วางแผน : การตรวจจับโมดูลการทดสอบ/ฟังก์ชั่นที่เป็นอิสระจากเครื่องมือครอบคลุม
8. ตั้งชื่อสมุดบันทึกของคุณอย่างสม่ำเสมอ	✅เสร็จสมบูรณ์	ดำเนินการอย่างเต็มที่
9. ติดกับมาตรฐานการเข้ารหัส	- บางส่วน	ปัจจุบัน : การตรวจจับเซลล์ที่มีไวยากรณ์งูหลามไม่ถูกต้อง วางแผน : การบูรณาการของ linters python เช่น pylint, flake8 และ ruff
10. ใช้เส้นทางสัมพัทธ์	⏳กำลังดำเนินการ:	วางแผน : การระบุอินสแตนซ์ของเส้นทางสัมบูรณ์ในสมุดบันทึกและคำแนะนำของเส้นทางสัมพัทธ์ที่สอดคล้องกัน
11. เอกสารการวิเคราะห์ของคุณ	✅เสร็จสมบูรณ์	ดำเนินการอย่างเต็มที่
12. เลเวอเรจหัวเรื่อง Markdown เพื่อจัดโครงสร้างสมุดบันทึกของคุณ	✅เสร็จสมบูรณ์	ดำเนินการอย่างเต็มที่
13. รักษาสมุดบันทึกของคุณให้สะอาด	✅เสร็จสมบูรณ์	ดำเนินการอย่างเต็มที่
14. เก็บสมุดบันทึกของคุณให้กระชับ	✅เสร็จสมบูรณ์	ดำเนินการอย่างเต็มที่
15. แยกแยะสิ่งประดิษฐ์การผลิตและการพัฒนา	ไม่ได้วางแผนไว้	การใช้งานถือว่าเป็นไปไม่ได้ (ดูหมายเหตุด้านล่าง)
16. ทำให้สมุดบันทึกของคุณพร้อมใช้งาน	⏳กำลังดำเนินการ:	วางแผน : Pynblint จะตรวจสอบให้แน่ใจว่าสมุดบันทึกที่ทำเครื่องหมายไว้ตามที่เผยแพร่ในการกำหนดค่ามีให้ทางออนไลน์
17. ทำให้ข้อมูลของคุณพร้อมใช้งาน	✅เสร็จสมบูรณ์	ดำเนินการอย่างเต็มที่

หมายเหตุ : แนวปฏิบัติที่ดีที่สุด #15 (แยกแยะสิ่งประดิษฐ์การผลิต/การพัฒนา) จะไม่ถูกนำไปใช้เนื่องจากไม่มีเกณฑ์วัตถุประสงค์สำหรับการพิจารณาความแตกต่างนี้ผ่านการวิเคราะห์แบบคงที่ของสมุดบันทึกหรือที่เก็บ

ใบอนุญาต

โครงการนี้ได้รับใบอนุญาตภายใต้ข้อกำหนดของใบอนุญาต MIT

การอ้างอิง

[1] Luigi Quaranta, Fabio Calefato และ Filippo Lanubile 2022. นำเสนอแนวทางปฏิบัติที่ดีที่สุดสำหรับการทำงานร่วมกันกับสมุดบันทึกการคำนวณ Proc. ACM HUM.-COMPUT มีปฏิสัมพันธ์. 6 , CSCW1, บทความ 87 (เมษายน 2022), 41 หน้า https://doi.org/10.1145/3512934