هذا هو تطبيق نموذج أولي لأداة مساعدة لتوقيع الطلب للاستخدام مع OpenSearch بدون خادم (AOSS). الغرض منه (حاليًا) هو توفير واجهة تشبه الضفيرة للاستعلام عن مثيل AOSS الخاص بـ PDS Registry باستخدام هوية مستخدم Cognito.
قد يتم إنشاء وظائف إضافية في المستقبل.
بيانات اعتماد المستخدم/المرور الشخصية لمستخدم Cognito المعتمد لـ Registry AOSS
بايثون >=3.9
متغيرات البيئة (اتصل بالمطور للحصول على القيم)
تصدير REQUEST_SIGNER_AWS_ACCOUNT='' تصدير REQUEST_SIGNER_AWS_REGION='' تصدير REQUEST_SIGNER_CLIENT_ID='' تصدير REQUEST_SIGNER_USER_POOL_ID='' تصدير REQUEST_SIGNER_IDENTITY_POOL_ID='' تصدير REQUEST_SIGNER_AOSS_ENDPOINT='' تصدير REQUEST_SIGNER_COGNITO_USER='' تصدير REQUEST_SIGNER_COGNITO_PASSWORD=''
استنساخ المستودع
git clone https://github.com/NASA-PDS/registry-client.git cd registry-client
إنشاء بيئة افتراضية
python -m venv venv source ./venv/bin/activate
قم بتثبيت الأداة على البيئة الافتراضية
pip install --editable .[dev]
قم بتشغيل الأداة مباشرة
registry-client --help
من المتوقع أن يلتزم جميع مستخدمي ومطوري برنامج NASA-PDS بقواعد السلوك الخاصة بنا. يرجى قراءة هذا للتأكد من أنك تفهم توقعات مجتمعنا.
لتطوير هذا المشروع، استخدم محرر النصوص المفضل لديك، أو بيئة تطوير متكاملة تدعم لغة Python، مثل PyCharm.
للحصول على معلومات حول كيفية المساهمة في قواعد بيانات NASA-PDS، يرجى إلقاء نظرة على إرشادات المساهمة الخاصة بنا.
التثبيت في الوضع القابل للتحرير ومع تبعيات المطور الإضافية في البيئة الافتراضية التي تختارها:
pip install --editable '.[dev]'
قم بإنشاء خط أساس لأي أسرار (عناوين البريد الإلكتروني وكلمات المرور ومفاتيح واجهة برمجة التطبيقات وما إلى ذلك) في المستودع:
detect-secrets scan . --all-files --disable-plugin AbsolutePathDetectorExperimental --exclude-files '.secrets..*' --exclude-files '.git.*' --exclude-files '.mypy_cache' --exclude-files '.pytest_cache' --exclude-files '.tox' --exclude-files '.venv' --exclude-files 'venv' --exclude-files 'dist' --exclude-files 'build' --exclude-files '.*.egg-info' > .secrets.baseline
قم بمراجعة الأسرار لتحديد ما يجب السماح به وأيها إيجابيات كاذبة:
detect-secrets audit .secrets.baseline
يرجى إزالة أي أسرار لا ينبغي أن يراها الجمهور. يمكنك بعد ذلك إضافة الملف الأساسي إلى الالتزام:
git add .secrets.baseline
بعد ذلك، قم بتكوين خطافات pre-commit :
pre-commit install pre-commit install -t pre-push pre-commit install -t prepare-commit-msg pre-commit install -t commit-msg
ستقوم هذه الخطافات بعد ذلك بالتحقق من أي التزامات مستقبلية قد تحتوي على أسرار. كما يقومون أيضًا بالتحقق من تنسيق التعليمات البرمجية، والامتثال لـ PEP8، وتلميحات الكتابة، وما إلى ذلك.
؟ ملاحظة: يلزم الإعداد لمرة واحدة لدعم detect-secrets وفي تكوين Git العام. راجع إدخال الويكي الخاص بالأسرار لمعرفة كيفية القيام بذلك.
لعزل البيئة لهذه الحزمة والقدرة على إعادة إنتاجها، يجب عليك استخدام بيئة Python الافتراضية. للقيام بذلك، قم بتشغيل:
python -m venv venv
ثم استخدم حصريًا venv/bin/python و venv/bin/pip وما إلى ذلك.
إذا كان لديك tox مثبتًا وترغب في إنشاء بيئتك وتثبيت التبعيات لتشغيله:
tox --devenv <name you'd like for env> -e dev
تم تحديد تبعيات التطوير على أنها dev extras_require في setup.cfg ؛ يتم تثبيتها في البيئة الافتراضية على النحو التالي:
pip install --editable '.[dev]'
كل التعليمات البرمجية المصدر موجودة في دليل فرعي ضمن src .
يجب عليك تحديث ملف setup.cfg بما يلي:
اسم الوحدة الخاصة بك
الترخيص، أباتشي الافتراضي، التحديث إذا لزم الأمر
وصف
عنوان url للتنزيل، عندما تقوم بإصدار الحزمة الخاصة بك على github أضف عنوان url هنا
الكلمات الرئيسية
المصنفات
install_requires، قم بإضافة تبعيات الحزمة الخاصة بك
extras_require، قم بإضافة تبعيات التطوير لحزمتك
نقاط الإدخال، عندما يمكن استدعاء الحزمة الخاصة بك في سطر الأوامر، فهذا يساعد على نشر نقاط إدخال سطر الأوامر التي تشير إلى البرامج النصية في الحزمة الخاصة بك
للحصول على تفاصيل التغليف، راجع https://packaging.python.org/tutorials/packaging-projects/ كمرجع.
من السهل استخدام حزمة ConfigParser لإدارة التكوين. فهو يسمح بالتكوين الافتراضي الذي يمكن للمستخدم الكتابة فوقه في ملف معين في بيئته. راجع https://pymotw.com/2/ConfigParser/
على سبيل المثال:
candidates = ['my_pds_module.ini', 'my_pds_module.ini.default'] found = parser.read(candidates)
يجب ألا تستخدم print() vin لغرض تسجيل المعلومات حول تنفيذ التعليمات البرمجية الخاصة بك. اعتمادًا على مكان تشغيل التعليمات البرمجية، يمكن إعادة توجيه هذه المعلومات إلى ملفات سجل محددة.
لإنجاز هذا العمل، ابدأ كل ملف بايثون باستخدام:
"""الوحدة النمطية الخاصة بي."""استيراد logginglogger = logging.getLogger(__name__)
لتسجيل رسالة:
logger.info("my message") في روتينك main ، قم بتضمين:
logging.basicConfig(level=logging.INFO)
لتكوين نظام التسجيل الأساسي.
تقوم dev extras_require المضمنة في نموذج الريبو بتثبيت black و flake8 (بالإضافة إلى بعض المكونات الإضافية) و mypy بالإضافة إلى التكوين الافتراضي لهم جميعًا. يمكنك تشغيل كل هذه الأمور (وأكثر!) باستخدام:
tox -e lint
لكي تكون التعليمات البرمجية الخاصة بك قابلة للقراءة، يجب عليك الالتزام بدليل نمط PEP8. يتم فرض نمط الكود الخاص بنا تلقائيًا عبر الأسود والرقائق8. راجع قسم الأدوات للحصول على معلومات حول استدعاء خط أنابيب الفحص.
❗ملاحظة مهمة لمستخدمي القالب❗ ينفذ ملف التكوين المسبق المضمن flake8 (جنبًا إلى جنب مع mypy ) عبر مجلد src بأكمله وليس فقط على الملفات التي تم تغييرها. إذا كنت تقوم بتحويل قاعدة تعليمات برمجية موجودة مسبقًا إلى هذا القالب، فقد يؤدي ذلك إلى حدوث الكثير من الأخطاء التي لست مستعدًا للتعامل معها.
يمكنك بدلاً من ذلك تنفيذ flake8 فقط عبر اختلاف في التغييرات الحالية التي يتم إجراؤها عن طريق تعديل سطر entry pre-commit :
entry: git diff -u | flake8 --diff
أو يمكنك تغيير تكوين pre-commit بحيث يتم استدعاء flake8 فقط على الملفات التي تم تغييرها والتي تتوافق مع معايير تصفية معينة:
- repo: local hooks: - id: flake8 name: flake8 entry: flake8 files: ^src/|tests/ language: system
تقدم بايثون مجموعة كبيرة ومتنوعة من المكتبات. في نطاق PDS، للاستخدام الحالي يجب أن نستخدم:
| مكتبة | الاستخدام |
|---|---|
| configparser | إدارة وتحليل ملفات التكوين |
| argparse | توثيق وسيطة سطر الأوامر وتحليلها |
| طلبات | التفاعل مع واجهات برمجة تطبيقات الويب |
| com.lxml | قراءة/كتابة ملفات XML |
| json | قراءة/كتابة ملفات JSON |
| pyyaml | قراءة/كتابة ملفات YAML |
| pystache | توليد الملفات من القوالب |
بعض هذه العناصر مدمجة في Python 3؛ البعض الآخر عبارة عن وظائف إضافية مفتوحة المصدر يمكنك تضمينها في requirements.txt الخاص بك.
يصف هذا القسم اختبار الحزمة الخاصة بك.
يتم تنفيذ "البناء" الكامل بما في ذلك تنفيذ الاختبار والفحص ( mypy و black و flake8 وما إلى ذلك) وبناء الوثائق عبر:
tox
يجب أن يحتوي مشروعك على اختبارات وحدة مدمجة، واختبارات وظيفية، واختبارات التحقق من الصحة، والقبول، وما إلى ذلك.
لاختبار الوحدة، تحقق من وحدة Unittest، المضمنة في Python 3.
يجب أن تكون كائنات الاختبارات في وحدات test الحزم أو يفضل أن تكون في دليل "اختبارات" المشروع الذي يعكس بنية حزمة المشروع.
يتم إطلاق اختبارات وحدتنا بالأمر:
pytest
إذا كنت تريد تشغيل اختباراتك تلقائيًا أثناء إجراء التغييرات، فابدأ تشغيل pytest في وضع المراقبة باستخدام:
ptw
يجب على المرء استخدام behave package ودفع نتائج الاختبار إلى "testrail".
راجع مثالاً في https://github.com/NASA-PDS/pds-doi-service#behavioral-testing-for-integration--testing
يجب أن يستخدم مشروعك أبو الهول لبناء وثائقه. تم بالفعل تكوين قالب وثائق PDS كجزء من البناء الافتراضي. يمكنك إنشاء مستندات مشاريعك باستخدام:
python setup.py build_sphinx
يمكنك الوصول إلى ملفات البناء في الدليل التالي بالنسبة إلى جذر المشروع:
build/sphinx/html/
pip install wheel python setup.py sdist bdist_wheel
يمكن لحزم NASA PDS النشر تلقائيًا باستخدام Roundup Action، الذي يعزز إجراءات GitHub لإجراء تكامل مستمر آلي وتسليم مستمر. يتم توفير سير العمل الافتراضي الذي يتضمن Roundup في ملف .github/workflows/unstable-cicd.yaml . (غير المستقر هنا يعني إصدارًا مؤقتًا.)
إنشاء الحزمة:
python setup.py bdist_wheel
نشره كإصدار جيثب.
النشر على PyPI (تحتاج إلى حساب PyPI وتكوين $HOME/.pypirc ):
pip install twine twine upload dist/*
أو انشر على Test PyPI (تحتاج إلى حساب Test PyPI وقم بتكوين $HOME/.pypirc ):
pip install twine twine upload --repository testpypi dist/*
يأتي مستودع القوالب مزودًا بسيرتي عمل CI/CD "القياسيتين"، stable-cicd و unstable-cicd . يتم تشغيل البناء غير المستقر عند أي دفع إلى main (± تجاهل التغييرات في ملفات محددة) ويتم تشغيل البناء المستقر عند دفع فرع إصدار النموذج release/<release version> . كلاهما يستفيد من خطوة بناء إجراءات GitHub، Roundup. سيقوم unstable-cicd بإنشاء (وتحديثه باستمرار) إصدار SNAPSHOT. إذا لم تكن قد قمت بإصدار برنامج رسمي، فسينتهي بك الأمر بإصدار v0.0.0-SNAPSHOT (راجع NASA-PDS/roundup-action#56 للحصول على التفاصيل).
