PythonCodingGuidelines
1.0.0
إرشادات برمجة Python هي مجموعة من الإرشادات والقواعد وأفضل الممارسات المجربة والصحيحة حول البرمجة في Python.
الهدف من الإرشادات هو مساعدة المطورين على استخدام بايثون بشكل فعال وتوفير أسلوب بايثون حديث أكثر قابلية للقراءة. رمز يمكن صيانته بسهولة وقابل للتطوير. وأيضًا وضع معيار تطوير يجب اتباعه عند تطوير التطبيقات أو المكتبات في لغة بايثون.
آمل أن يساعدك هذا المستند أيضًا في البدء باستخدام Python. إذا كنت قادمًا من لغة برمجة نصية أخرى مثل JavaScript، فستجد أن Python متشابهة جدًا وأن هذا المستند هو وسيلة للانتقال إلى Python.
تركز الإرشادات على جميع الموارد التي توفرها لغة Python المحددة عادةً في معيار PEP8. يتم استخدام PEP8 PEP8 هنا كقاعدة لمقترح إرشادات الترميز هذا. أريد الترويج لأسلوب بايثون الأكثر قابلية للقراءة والحداثة.
قد تجد أن بعض القواعد الواردة في هذا الدليل الإرشادي تتعارض مع توقعاتك أو حتى تتعارض مع تجربتك.
إذا لم أقترح عليك تغيير أسلوب الترميز الخاص بك بأي شكل من الأشكال، فقد فشلت!
يرجى محاولة التحقق من قواعد هذا الدليل الإرشادي أو دحضها. على وجه الخصوص، أود حقًا أن يتم دعم بعض القواعد المقترحة بقياسات وأمثلة أفضل.
هي قاعدة عامة لتطوير البرمجيات لصياغة تطبيقات قابلة للقراءة، وقابلة للصيانة، وقابلة للتطوير. هذه ليست الحقيقة دائمًا، لكننا نهدف إلى تحقيق هذا الهدف.
معايير الكود هي أدوات تساعد في بناء التطبيقات باستخدام المبادئ الثلاثية المذكورة أعلاه. فيما يلي بعض الفوائد التي يتم توفيرها من خلال إنشاء معيار تطوير ثابت:
️ تحذير: هذه وثيقة حية تخضع للتحسين المستمر. التعليقات والاقتراحات للتحسينات هي موضع ترحيب كبير. أخطط لتعديل وتوسيع هذه الوثيقة مع تحسن فهمنا وتطور اللغة التي تستخدمها مجموعة المكتبات المتاحة.
| اسم | مؤتمر | مثال الكود |
|---|---|---|
| اسم متغير واحد | Snake_case | age: int = 100 |
| اسم المتغير المركب | Snake_case | first_name: str = "Akira" |
| اسم ثابت | ثابت | CPU: number = 8 |
| اسم ثابت مركب | ثابت | MAX_NUMBER: number = 100 |
| اسم التعداد | باسكال كيس | class Color(Enum): RED = 1 GREEN = 2 |
| اسم الوظيفة | Snake_case | def main() |
| وظيفة مع المعلمات | Snake_case | def calculate(n1: int, n2: int) |
| وظيفة مع نوع الإرجاع | Snake_case | def calculate(n1: int, n2: int) -> int: |
| اسم الدالة المركبة | Snake_case | def add_two_numbers(n1: int, n2: int) -> int: |
| اسم الفصل | باسكال كيس | class Base |
| اسم الفئة المركبة | باسكال كيس | class MyClass |
| واجهات | باسكال كيس | class IUser(ABC) |
| صب | تقصير | age: int = int(100) |
| قائمة | com.camelCase | myList: list[int] = [1,2,3] |
| مترابطة بيانية | com.camelCase | myTuple: tuple[int] = (1,2,3) |
| تعيين | Snake_case | my_set: set[int] = {1,2,3} |
| قاموس | Snake_case | my_dictionary: dict = {"name": "John", "age": 100} |
| تلميحات متعددة النوع | Snake_case | var_a: Union[int, str] |
اقترحنا استخدام Google Doc Style لتوثيق Python لأنه الأسهل في القراءة والفهم. يحظى دليل Google Style أيضًا بشعبية كبيرة ويستخدم على نطاق واسع في مجتمع Python.
def add_binary ( a : int , b : int ) -> int :
"""
Returns the sum of two decimal numbers in binary format.
Parameters:
a (int): First number to add
b (int): Second number to add
Returns:
binary (int): Binary int of the sum of a and b
"""
binary_sum = bin ( a + b )[ 2 :]
return int ( binary_sum )تعد تلميحات الكتابة حلاً رسميًا للإشارة بشكل ثابت إلى نوع القيمة.
مثال:
def addBinary(a: int, b: int)-> int:
...
في هذه الدالة أعلاه، من الواضح أن الدالة تنتظر قيمة int في المتغيرين a و b ، وترجع قيمة int .
تحقق من هذا الرابط: كتابة بايثون الوثائق الرسمية
لكن أليست لغة بايثون لغة غير مكتوبة؟ نعم، ليس كذلك. إذا قمت بتمرير أي قيمة مختلفة عن int ، فسيعمل.
كيفية التحقق من نوع الضرب في بايثون؟
يجب عليك استخدام مكتبة mypy .
Mypy هو مدقق اختياري للنوع الثابت لـ Python يهدف إلى الجمع بين فوائد الكتابة الديناميكية (أو "البطة") والكتابة الثابتة. (المصدر: الوثائق الرسمية)
pip install mypy
mypy mycode.py
فكرة استخدام linter لـ python هي تطبيق إرشادات الترميز المقترحة في هذا المستند. سأستخدم الالتزام المسبق.
pip install pre-commit
التكوين الأساسي:
.pre-commit-config.yml لحفظ تكوينات الالتزام المسبقفي هذا المثال أدناه، سيقوم البرنامج النصي بتنفيذ الخطوات التالية:
مثال:
repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v2.3.0
hooks:
- id: check-yaml
- id: end-of-file-fixer
- id: trailing-whitespace
- id: check-json
- id: detect-private-key
- repo: https://github.com/PyCQA/isort
rev: 5.12.0
hooks:
- id: isort
- repo: https://github.com/psf/black
rev: 22.12.0
hooks:
- id: black
language_version: python3.10
- repo: https://github.com/charliermarsh/ruff-pre-commit
rev: 'v0.0.260'
hooks:
- id: ruff
pyproject.toml لحفظ تكوينات المتسابقين المسبقينمثال:
[tool.black]
line-length = 80
target-version = ['py310']
include = '.pyi?$'
[tool.isort]
line_length = 79
multi_line_output = 3
include_trailing_comma = true
force_grid_wrap = 0
use_parentheses = true
ensure_newline_before_comments = true
بعد هذه التكوينات، في كل مرة تقوم فيها بإجراء التزام، سيتم تشغيل الالتزام المسبق
التوثيق الرسمي المسبق
الإطار المقترح للاختبار هو pytest. وهو أيضًا إطار اختبار شائع جدًا لـ Python.
tests : pytest
pytest --cov . 
لمزيد من أوامر pytest، اتبع الوثائق الرسمية هنا pytest
فيما يلي مثال لتعريف الوظيفة للاختبار:
بعد إنشاء وظيفتك كما هو موضح في المثال أدناه: 
يمكنك إنشاء اختبار الوحدة الخاص بك باتباع الخطوات التالية:
test_ في اسم الوظيفة.
لبدء مشروع جديد يمكنك استنساخ المشروع باستخدام الأمر التالي:
git clone https://github.com/rsaz/python-project-templateفيما يلي الهيكل الافتراضي للمشروع المقترح.
يعتمد هيكل المشروع على ما يلي:
| المجلد / الملف | وصف |
|---|---|
| utils | البرامج النصية PowerShell التي تسمح لك بإنشاء البيئات وتنشيطها وإلغاء تنشيطها وحذفها، بالإضافة إلى تحديث وإنشاء التبعيات |
| .vscode | تكوين محدد للمحرر |
| src | المجلد المصدر الرئيسي للمشروع |
| امتحان | المجلد الذي يحتوي على كافة اختبارات وحدة التطبيق |
| venv | بيئة بايثون الافتراضية |
| .pylintrc | ملف التكوين لمحلل الكود الثابت pylint لـ Python |
| pytest.ini | ملف التكوين لـ pytest |
| LICENSE.txt | شروط ترخيص المشروع |
| التمهيدي.md | تفاصيل المشروع |
| المتطلبات.txt | تبعيات المشروع |
| setup.cfg وsetup.py | التكوين الأولي للمشروع |
