Ini adalah implementasi prototipe dari utilitas penandatanganan permintaan untuk digunakan dengan OpenSearch tanpa server (AOSS). Ini (saat ini) dimaksudkan untuk menyediakan antarmuka seperti ikal untuk menanyakan instans AOSS PDS Registry menggunakan identitas pengguna Cognito.
Fungsionalitas tambahan mungkin akan dikembangkan di masa mendatang.
Kredensial pengguna/pass pribadi untuk pengguna Cognito yang diotorisasi untuk Registry AOSS
Python >=3.9
Variabel lingkungan (hubungi pengembang untuk mengetahui nilai)
ekspor REQUEST_SIGNER_AWS_ACCOUNT='' ekspor REQUEST_SIGNER_AWS_REGION='' ekspor REQUEST_SIGNER_CLIENT_ID='' ekspor REQUEST_SIGNER_USER_POOL_ID='' ekspor REQUEST_SIGNER_IDENTITY_POOL_ID='' ekspor REQUEST_SIGNER_AOSS_ENDPOINT='' ekspor REQUEST_SIGNER_COGNITO_USER='' ekspor REQUEST_SIGNER_COGNITO_PASSWORD=''
Kloning repositori
git clone https://github.com/NASA-PDS/registry-client.git cd registry-client
Ciptakan lingkungan virtual
python -m venv venv source ./venv/bin/activate
Instal alat ke lingkungan virtual
pip install --editable .[dev]
Jalankan alat secara langsung
registry-client --help
Semua pengguna dan pengembang perangkat lunak NASA-PDS diharapkan mematuhi Kode Etik kita. Harap baca ini untuk memastikan Anda memahami harapan komunitas kami.
Untuk mengembangkan proyek ini, gunakan editor teks favorit Anda, atau lingkungan pengembangan terintegrasi dengan dukungan Python, seperti PyCharm.
Untuk informasi tentang cara berkontribusi pada basis kode NASA-PDS, silakan lihat pedoman Berkontribusi kami.
Instal dalam mode yang dapat diedit dan dengan ketergantungan pengembang tambahan ke dalam lingkungan virtual pilihan Anda:
pip install --editable '.[dev]'
Buatlah garis dasar untuk rahasia apa pun (alamat email, kata sandi, kunci API, dll.) di repositori:
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
Tinjau rahasia untuk menentukan mana yang diperbolehkan dan mana yang positif palsu:
detect-secrets audit .secrets.baseline
Harap hapus rahasia apa pun yang tidak boleh dilihat oleh publik. Anda kemudian dapat menambahkan file dasar ke komit:
git add .secrets.baseline
Kemudian, konfigurasikan hook pre-commit :
pre-commit install pre-commit install -t pre-push pre-commit install -t prepare-commit-msg pre-commit install -t commit-msg
Kait ini kemudian akan memeriksa komitmen apa pun di masa mendatang yang mungkin berisi rahasia. Mereka juga memeriksa pemformatan kode, kepatuhan PEP8, petunjuk jenis, dll.
? Catatan: Penyiapan satu kali diperlukan untuk mendukung detect-secrets dan konfigurasi Git global Anda. Lihat entri wiki di Rahasia untuk mempelajari caranya.
Untuk mengisolasi dan dapat memproduksi ulang lingkungan untuk paket ini, Anda harus menggunakan Lingkungan Virtual Python. Untuk melakukannya, jalankan:
python -m venv venv
Kemudian gunakan secara eksklusif venv/bin/python , venv/bin/pip , dll.
Jika Anda telah menginstal tox dan ingin membuat lingkungan Anda sendiri dan menginstal dependensi untuk Anda jalankan:
tox --devenv <name you'd like for env> -e dev
Dependensi untuk pengembangan ditentukan sebagai dev extras_require di setup.cfg ; mereka diinstal ke dalam lingkungan virtual sebagai berikut:
pip install --editable '.[dev]'
Semua kode sumber ada di subdirektori di bawah src .
Anda harus memperbarui file setup.cfg dengan:
nama modul Anda
lisensi, apache default, perbarui jika diperlukan
keterangan
unduh url, ketika Anda merilis paket Anda di github tambahkan url di sini
kata kunci
pengklasifikasi
install_requires, tambahkan dependensi paket Anda
extras_require, tambahkan Dependensi pengembangan paket Anda
entry_points, ketika paket Anda dapat dipanggil di baris perintah, ini membantu menyebarkan titik masuk baris perintah yang menunjuk ke skrip dalam paket Anda
Untuk detail pengemasan, lihat https://packaging.python.org/tutorials/packaging-projects/ sebagai referensi.
Lebih mudah menggunakan paket ConfigParser untuk mengelola konfigurasi. Ini memungkinkan konfigurasi default yang dapat ditimpa oleh pengguna dalam file tertentu di lingkungan mereka. Lihat https://pymotw.com/2/ConfigParser/
Misalnya:
candidates = ['my_pds_module.ini', 'my_pds_module.ini.default'] found = parser.read(candidates)
Anda tidak boleh menggunakan print() vin tujuan mencatat informasi tentang eksekusi kode Anda. Tergantung di mana kode dijalankan, informasi ini dapat dialihkan ke file log tertentu.
Untuk membuatnya berfungsi, mulai setiap file Python dengan:
"""Modul saya."""import logginglogger = logging.getLogger(__name__)
Untuk mencatat pesan:
logger.info("my message") Dalam rutinitas main Anda, sertakan:
logging.basicConfig(level=logging.INFO)
untuk mengkonfigurasi sistem logging dasar.
dev extras_require yang disertakan dalam repo template menginstal black , flake8 (ditambah beberapa plugin), dan mypy bersama dengan konfigurasi default untuk semuanya. Anda dapat menjalankan semua ini (dan lebih banyak lagi!) dengan:
tox -e lint
Agar kode Anda dapat dibaca, Anda harus mematuhi panduan gaya PEP8. Gaya kode kami secara otomatis diterapkan melalui black dan flake8. Lihat bagian Peralatan untuk informasi tentang cara memanggil pipeline linting.
❗Catatan penting untuk pengguna template❗ File konfigurasi pra-komit yang disertakan mengeksekusi flake8 (bersama dengan mypy ) di seluruh folder src dan tidak hanya pada file yang diubah. Jika Anda mengonversi basis kode yang sudah ada sebelumnya ke templat ini, hal itu mungkin mengakibatkan banyak kesalahan yang belum siap Anda atasi.
Sebagai gantinya, Anda dapat mengeksekusi flake8 hanya pada perbedaan perubahan yang sedang dilakukan dengan memodifikasi baris entry pre-commit :
entry: git diff -u | flake8 --diff
Atau Anda dapat mengubah konfigurasi pre-commit sehingga flake8 hanya dipanggil pada file yang diubah yang cocok dengan kriteria pemfilteran tertentu:
- repo: local hooks: - id: flake8 name: flake8 entry: flake8 files: ^src/|tests/ language: system
Python menawarkan berbagai macam perpustakaan. Dalam lingkup PDS, untuk penggunaan terkini kita harus menggunakan:
| Perpustakaan | Penggunaan |
|---|---|
| configparser | mengelola dan mengurai file konfigurasi |
| argparse | dokumentasi dan penguraian argumen baris perintah |
| permintaan | berinteraksi dengan API web |
| lxml | membaca/menulis file XML |
| json | membaca/menulis file JSON |
| pyyaml | membaca/menulis file YAML |
| sakit kepala | menghasilkan file dari templat |
Beberapa di antaranya dibangun dalam Python 3; lainnya adalah add-on sumber terbuka yang dapat Anda sertakan dalam requirements.txt Anda.
Bagian ini menjelaskan pengujian untuk paket Anda.
Sebuah "build" lengkap termasuk eksekusi pengujian, linting ( mypy , black , flake8 , dll.), dan build dokumentasi dijalankan melalui:
tox
Proyek Anda harus memiliki pengujian unit bawaan, pengujian fungsional, validasi, penerimaan, dll.
Untuk pengujian unit, lihat modul unittest, yang dibangun dalam Python 3.
Objek pengujian harus berada dalam modul test paket atau sebaiknya di direktori 'tes' proyek yang mencerminkan struktur paket proyek.
Tes unit kami diluncurkan dengan perintah:
pytest
Jika Anda ingin pengujian Anda berjalan secara otomatis saat Anda melakukan perubahan, mulailah pytest dalam mode tontonan dengan:
ptw
Seseorang harus menggunakan behave package dan mendorong hasil tes ke "testrail".
Lihat contohnya di https://github.com/NASA-PDS/pds-doi-service#behavioral-testing-for-integration--testing
Proyek Anda harus menggunakan Sphinx untuk membuat dokumentasinya. Templat dokumentasi PDS sudah dikonfigurasikan sebagai bagian dari build default. Anda dapat membuat dokumen proyek Anda dengan:
python setup.py build_sphinx
Anda dapat mengakses file build di direktori berikut yang berhubungan dengan root proyek:
build/sphinx/html/
pip install wheel python setup.py sdist bdist_wheel
Paket PDS NASA dapat dipublikasikan secara otomatis menggunakan Roundup Action, yang memanfaatkan GitHub Actions untuk melakukan integrasi berkelanjutan otomatis dan pengiriman berkelanjutan. Alur kerja default yang menyertakan Roundup disediakan di file .github/workflows/unstable-cicd.yaml . (Tidak stabil di sini berarti rilis sementara.)
Buat paket:
python setup.py bdist_wheel
Publikasikan sebagai rilis Github.
Publikasikan di PyPI (Anda memerlukan akun PyPI dan mengonfigurasi $HOME/.pypirc ):
pip install twine twine upload dist/*
Atau publikasikan di Test PyPI (Anda memerlukan akun Test PyPI dan konfigurasikan $HOME/.pypirc ):
pip install twine twine upload --repository testpypi dist/*
Repositori templat dilengkapi dengan dua alur kerja CI/CD "standar" kami, stable-cicd dan unstable-cicd . Build yang tidak stabil berjalan dengan dorongan apa pun ke main (± mengabaikan perubahan pada file tertentu) dan build stabil berjalan dengan menekan cabang rilis dalam bentuk release/<release version> . Keduanya menggunakan langkah pembuatan tindakan GitHub kami, Roundup. unstable-cicd akan menghasilkan (dan terus memperbarui) rilis SNAPSHOT. Jika Anda belum melakukan rilis perangkat lunak formal, Anda akan mendapatkan rilis v0.0.0-SNAPSHOT (lihat NASA-PDS/roundup-action#56 untuk lebih spesifik).
