นี่คือการใช้งานต้นแบบของยูทิลิตีการลงนามคำขอเพื่อใช้กับ 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]'
สร้างพื้นฐานสำหรับความลับใดๆ (ที่อยู่อีเมล รหัสผ่าน คีย์ API ฯลฯ) ในพื้นที่เก็บข้อมูล:
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
จากนั้น กำหนดค่า hooks pre-commit :
pre-commit install pre-commit install -t pre-push pre-commit install -t prepare-commit-msg pre-commit install -t commit-msg
hooks เหล่านี้จะตรวจสอบการคอมมิตในอนาคตที่อาจมีความลับ นอกจากนี้ยังตรวจสอบการจัดรูปแบบโค้ด การปฏิบัติตาม PEP8 คำแนะนำประเภท ฯลฯ
- หมายเหตุ: จำเป็นต้องมีการตั้งค่าครั้งเดียวเพื่อรองรับ detect-secrets และในการกำหนดค่า Git ส่วนกลางของคุณ ดูรายการวิกิเกี่ยวกับความลับเพื่อเรียนรู้วิธีการ
หากต้องการแยกและสร้างสภาพแวดล้อมใหม่สำหรับแพ็คเกจนี้ คุณควรใช้ Python Virtual Environment โดยเรียกใช้:
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 ด้วย:
ชื่อของโมดูลของคุณ
ใบอนุญาต, Apache เริ่มต้น, อัปเดตหากจำเป็น
คำอธิบาย
ดาวน์โหลด url เมื่อคุณปล่อยแพ็คเกจของคุณบน github ให้เพิ่ม url ที่นี่
คำหลัก
ตัวแยกประเภท
install_requires เพิ่มการขึ้นต่อกันของแพ็คเกจของคุณ
extras_require เพิ่มการพึ่งพาการพัฒนาของแพ็คเกจของคุณ
entry_points เมื่อแพ็คเกจของคุณสามารถเรียกในบรรทัดคำสั่งได้ สิ่งนี้จะช่วยปรับใช้จุดเข้าบรรทัดคำสั่งที่ชี้ไปที่สคริปต์ในแพ็คเกจของคุณ
สำหรับรายละเอียดบรรจุภัณฑ์ โปรดดู 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 เพื่อวัตถุประสงค์ในการบันทึกข้อมูลเกี่ยวกับการเรียกใช้โค้ดของคุณ ขึ้นอยู่กับว่าโค้ดทำงานที่ใดข้อมูลเหล่านี้สามารถเปลี่ยนเส้นทางไปยังไฟล์บันทึกเฉพาะได้
เพื่อให้ได้ผล ให้เริ่มไฟล์ Python แต่ละไฟล์ด้วย:
"""โมดูลของฉัน"""นำเข้า logginglogger = logging.getLogger(__name__)
หากต้องการบันทึกข้อความ:
logger.info("my message") ในกิจวัตร main ของคุณ ให้รวมถึง:
logging.basicConfig(level=logging.INFO)
เพื่อกำหนดค่าระบบบันทึกพื้นฐาน
dev extras_require ที่รวมอยู่ใน repo เทมเพลตจะติดตั้ง black , flake8 (รวมถึงปลั๊กอินบางตัว) และ mypy พร้อมกับการกำหนดค่าเริ่มต้นสำหรับทั้งหมด คุณสามารถเรียกใช้สิ่งเหล่านี้ (และอีกมากมาย!) ด้วย:
tox -e lint
เพื่อให้โค้ดของคุณสามารถอ่านได้ คุณควรปฏิบัติตามคำแนะนำสไตล์ PEP8 รูปแบบโค้ดของเราถูกบังคับใช้โดยอัตโนมัติผ่าน black และ flake8 ดูส่วนเครื่องมือสำหรับข้อมูลเกี่ยวกับการเรียกใช้ไปป์ไลน์ขุย
❗หมายเหตุสำคัญสำหรับผู้ใช้เทมเพลต❗ ไฟล์การกำหนดค่าล่วงหน้าที่รวมไว้จะเรียกใช้งาน 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
Python มีไลบรารี่ที่หลากหลาย ในขอบเขต PDS สำหรับการใช้งานล่าสุดเราควรใช้:
| ห้องสมุด | การใช้งาน |
|---|---|
| configparser | จัดการและแยกวิเคราะห์ไฟล์การกำหนดค่า |
| การแยกวิเคราะห์ | เอกสารอาร์กิวเมนต์บรรทัดคำสั่งและการแยกวิเคราะห์ |
| คำขอ | โต้ตอบกับเว็บ API |
| lxml | อ่าน/เขียนไฟล์ XML |
| json.json | อ่าน/เขียนไฟล์ JSON |
| ไพยัมล์ | อ่าน/เขียนไฟล์ YAML |
| พิสตาเช่ | สร้างไฟล์จากเทมเพลต |
สิ่งเหล่านี้บางส่วนถูกสร้างขึ้นใน Python 3; ส่วนอื่นๆ เป็นส่วนเสริมแบบโอเพ่นซอร์สที่คุณสามารถรวมไว้ใน requirements.txt ของคุณได้
ส่วนนี้อธิบายการทดสอบแพ็คเกจของคุณ
"บิลด์" ที่สมบูรณ์ รวมถึงการดำเนินการทดสอบ, linting ( 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
โครงการของคุณควรใช้ Sphinx เพื่อสร้างเอกสารประกอบ เทมเพลตเอกสารของ PDS ได้รับการกำหนดค่าเป็นส่วนหนึ่งของบิลด์เริ่มต้นแล้ว คุณสามารถสร้างเอกสารโครงการของคุณด้วย:
python setup.py build_sphinx
คุณสามารถเข้าถึงไฟล์บิลด์ในไดเร็กทอรีต่อไปนี้ที่เกี่ยวข้องกับรูทโปรเจ็กต์:
build/sphinx/html/
pip install wheel python setup.py sdist bdist_wheel
แพ็คเกจ NASA PDS สามารถเผยแพร่โดยอัตโนมัติโดยใช้ Roundup Action ซึ่งใช้ประโยชน์จาก GitHub Actions เพื่อดำเนินการบูรณาการอย่างต่อเนื่องแบบอัตโนมัติและการส่งมอบอย่างต่อเนื่อง เวิร์กโฟลว์เริ่มต้นที่มี Roundup มีอยู่ในไฟล์ . .github/workflows/unstable-cicd.yaml (ไม่เสถียรในที่นี้หมายถึงการเปิดตัวชั่วคราว)
สร้างแพ็คเกจ:
python setup.py bdist_wheel
เผยแพร่เป็นรุ่น Github
เผยแพร่บน 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 สำหรับข้อมูลเฉพาะ)
