Dies ist eine Prototyp-Implementierung eines Anforderungssignierungsdienstprogramms zur Verwendung mit serverlosem OpenSearch (AOSS). Es soll (derzeit) eine Curl-ähnliche Schnittstelle zum Abfragen der AOSS-Instanz von PDS Registry mithilfe einer Cognito-Benutzeridentität bereitstellen.
Möglicherweise werden in Zukunft noch weitere Funktionen entwickelt.
Persönliche Benutzer-/Pass-Anmeldeinformationen für einen Cognito-Benutzer, der für Registry AOSS autorisiert ist
Python >=3.9
Umgebungsvariablen (für Werte kontaktieren Sie den Entwickler)
export REQUEST_SIGNER_AWS_ACCOUNT='' export REQUEST_SIGNER_AWS_REGION='' export REQUEST_SIGNER_CLIENT_ID='' export REQUEST_SIGNER_USER_POOL_ID='' export REQUEST_SIGNER_IDENTITY_POOL_ID='' export REQUEST_SIGNER_AOSS_ENDPOINT='' export REQUEST_SIGNER_COGNITO_USER='' exportieren REQUEST_SIGNER_COGNITO_PASSWORD=''
Klonen Sie das Repository
git clone https://github.com/NASA-PDS/registry-client.git cd registry-client
Erstellen Sie eine virtuelle Umgebung
python -m venv venv source ./venv/bin/activate
Installieren Sie das Tool in der virtuellen Umgebung
pip install --editable .[dev]
Führen Sie das Tool direkt aus
registry-client --help
Von allen Benutzern und Entwicklern der NASA-PDS-Software wird erwartet, dass sie sich an unseren Verhaltenskodex halten. Bitte lesen Sie dies, um sicherzustellen, dass Sie die Erwartungen unserer Community verstehen.
Um dieses Projekt zu entwickeln, verwenden Sie Ihren bevorzugten Texteditor oder eine integrierte Entwicklungsumgebung mit Python-Unterstützung, wie z. B. PyCharm.
Informationen darüber, wie Sie zu NASA-PDS-Codebasen beitragen können, finden Sie in unseren Beitragsrichtlinien.
Installieren Sie es im bearbeitbaren Modus und mit zusätzlichen Entwicklerabhängigkeiten in der virtuellen Umgebung Ihrer Wahl:
pip install --editable '.[dev]'
Erstellen Sie eine Basis für alle Geheimnisse (E-Mail-Adressen, Passwörter, API-Schlüssel usw.) im Repository:
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
Überprüfen Sie die Geheimnisse, um festzustellen, welche zulässig sein sollten und welche falsch positiv sind:
detect-secrets audit .secrets.baseline
Bitte entfernen Sie alle Geheimnisse, die nicht für die Öffentlichkeit sichtbar sein sollten. Anschließend können Sie die Baseline-Datei zum Commit hinzufügen:
git add .secrets.baseline
Konfigurieren Sie dann die pre-commit -Hooks:
pre-commit install pre-commit install -t pre-push pre-commit install -t prepare-commit-msg pre-commit install -t commit-msg
Diese Hooks prüfen dann, ob zukünftige Commits Geheimnisse enthalten. Sie überprüfen auch Codeformatierung, PEP8-Konformität, Typhinweise usw.
? Hinweis: Eine einmalige Einrichtung ist sowohl zur Unterstützung detect-secrets als auch in Ihrer globalen Git-Konfiguration erforderlich. Weitere Informationen dazu finden Sie im Wiki-Eintrag zu Secrets.
Um die Umgebung für dieses Paket zu isolieren und neu erstellen zu können, sollten Sie eine virtuelle Python-Umgebung verwenden. Führen Sie dazu Folgendes aus:
python -m venv venv
Dann verwenden Sie ausschließlich venv/bin/python , venv/bin/pip usw.
Wenn Sie tox installiert haben und möchten, dass es Ihre Umgebung erstellt und Abhängigkeiten für Sie installiert, führen Sie Folgendes aus:
tox --devenv <name you'd like for env> -e dev
Abhängigkeiten für die Entwicklung werden als dev extras_require in setup.cfg angegeben; Sie werden wie folgt in der virtuellen Umgebung installiert:
pip install --editable '.[dev]'
Der gesamte Quellcode befindet sich in einem Unterverzeichnis unter src .
Sie sollten die Datei setup.cfg aktualisieren mit:
Name Ihres Moduls
Lizenz, Standard-Apache, bei Bedarf aktualisieren
Beschreibung
Laden Sie die URL herunter. Wenn Sie Ihr Paket auf Github veröffentlichen, fügen Sie die URL hier hinzu
Schlüsselwörter
Klassifikatoren
install_requires, fügen Sie die Abhängigkeiten Ihres Pakets hinzu
extras_require, fügen Sie die Entwicklungsabhängigkeiten Ihres Pakets hinzu
Entry_points: Wenn Ihr Paket über die Befehlszeile aufgerufen werden kann, hilft dies bei der Bereitstellung von Befehlszeilen-Einstiegspunkten, die auf Skripte in Ihrem Paket verweisen
Die Verpackungsdetails finden Sie als Referenz unter https://packaging.python.org/tutorials/packaging-projects/.
Es ist praktisch, das ConfigParser-Paket zum Verwalten der Konfiguration zu verwenden. Es ermöglicht eine Standardkonfiguration, die vom Benutzer in einer bestimmten Datei in seiner Umgebung überschrieben werden kann. Siehe https://pymotw.com/2/ConfigParser/
Zum Beispiel:
candidates = ['my_pds_module.ini', 'my_pds_module.ini.default'] found = parser.read(candidates)
Sie sollten print() nicht dazu verwenden, Informationen über die Ausführung Ihres Codes zu protokollieren. Je nachdem, wo der Code ausgeführt wird, können diese Informationen in bestimmte Protokolldateien umgeleitet werden.
Damit das funktioniert, starten Sie jede Python-Datei mit:
"""Mein Modul."""import logginglogger = logging.getLogger(__name__)
So protokollieren Sie eine Nachricht:
logger.info("my message") Zu Ihrer main gehören:
logging.basicConfig(level=logging.INFO)
um ein grundlegendes Protokollierungssystem zu konfigurieren.
Der im Vorlagen-Repo enthaltene dev extras_require installiert black , flake8 (plus einige Plugins) und mypy zusammen mit der Standardkonfiguration für alle. Sie können all dies (und noch mehr!) ausführen mit:
tox -e lint
Damit Ihr Code lesbar ist, sollten Sie sich an den PEP8-Styleguide halten. Unser Codestil wird automatisch über Black und Flake8 erzwungen. Informationen zum Aufrufen der Linting-Pipeline finden Sie im Abschnitt „Tools“.
❗Wichtiger Hinweis für Vorlagenbenutzer❗ Die enthaltene Pre-Commit-Konfigurationsdatei führt flake8 (zusammen mit mypy ) im gesamten src Ordner aus und nicht nur für geänderte Dateien. Wenn Sie eine bereits vorhandene Codebasis in diese Vorlage konvertieren, kann dies zu vielen Fehlern führen, mit denen Sie nicht umgehen können.
Stattdessen können Sie flake8 nur über einen Unterschied der aktuell vorgenommenen Änderungen ausführen, indem Sie die entry pre-commit ändern:
entry: git diff -u | flake8 --diff
Oder Sie können die pre-commit Konfiguration ändern, sodass flake8 nur für geänderte Dateien aufgerufen wird, die einem bestimmten Filterkriterium entsprechen:
- repo: local hooks: - id: flake8 name: flake8 entry: flake8 files: ^src/|tests/ language: system
Python bietet eine große Auswahl an Bibliotheken. Im PDS-Bereich sollten wir für die aktuellste Verwendung Folgendes verwenden:
| Bibliothek | Verwendung |
|---|---|
| configparser | Konfigurationsdateien verwalten und analysieren |
| argparse | Dokumentation und Analyse von Befehlszeilenargumenten |
| Anfragen | mit Web-APIs interagieren |
| lxml | XML-Dateien lesen/schreiben |
| json | JSON-Dateien lesen/schreiben |
| pyyaml | YAML-Dateien lesen/schreiben |
| Pystache | Generieren Sie Dateien aus Vorlagen |
Einige davon sind in Python 3 integriert; Bei anderen handelt es sich um Open-Source-Add-ons, die Sie in Ihre requirements.txt einbinden können.
In diesem Abschnitt werden Tests für Ihr Paket beschrieben.
Ein vollständiger „Build“, einschließlich Testausführung, Linting ( mypy , black , flake8 usw.) und Dokumentationsbuild, wird ausgeführt über:
tox
Ihr Projekt sollte über integrierte Komponententests, Funktions-, Validierungs-, Akzeptanztests usw. verfügen.
Schauen Sie sich für Unit-Tests das in Python 3 integrierte Unittest-Modul an.
Testobjekte sollten sich in test oder vorzugsweise im Projektverzeichnis „tests“ befinden, das die Projektpaketstruktur widerspiegelt.
Unsere Unit-Tests werden mit folgendem Befehl gestartet:
pytest
Wenn Sie möchten, dass Ihre Tests automatisch ausgeführt werden, während Sie Änderungen vornehmen, starten Sie pytest im Überwachungsmodus mit:
ptw
Man sollte das behave package verwenden und die Testergebnisse auf „testrail“ übertragen.
Ein Beispiel finden Sie unter https://github.com/NASA-PDS/pds-doi-service#behavioral-testing-for-integration--testing
Ihr Projekt sollte Sphinx zum Erstellen seiner Dokumentation verwenden. Die Dokumentationsvorlage von PDS ist bereits als Teil des Standardbuilds konfiguriert. Sie können Ihre Projektdokumente erstellen mit:
python setup.py build_sphinx
Sie können auf die Build-Dateien im folgenden Verzeichnis relativ zum Projektstamm zugreifen:
build/sphinx/html/
pip install wheel python setup.py sdist bdist_wheel
NASA PDS-Pakete können automatisch mithilfe der Roundup-Aktion veröffentlicht werden, die GitHub-Aktionen nutzt, um eine automatisierte kontinuierliche Integration und kontinuierliche Bereitstellung durchzuführen. Ein Standardworkflow, der das Roundup enthält, wird in der Datei .github/workflows/unstable-cicd.yaml bereitgestellt. (Instabil bedeutet hier eine vorläufige Veröffentlichung.)
Erstellen Sie das Paket:
python setup.py bdist_wheel
Veröffentlichen Sie es als Github-Release.
Auf PyPI veröffentlichen (Sie benötigen ein PyPI-Konto und konfigurieren $HOME/.pypirc ):
pip install twine twine upload dist/*
Oder veröffentlichen Sie es auf dem Test-PyPI (Sie benötigen ein Test-PyPI-Konto und konfigurieren $HOME/.pypirc ):
pip install twine twine upload --repository testpypi dist/*
Das Vorlagen-Repository enthält unsere beiden „Standard“-CI/CD-Workflows stable-cicd und unstable-cicd . Der instabile Build wird bei jedem Push auf main ausgeführt (Änderungen an bestimmten Dateien werden ignoriert) und der stabile Build wird bei jedem Push eines Release-Zweigs der Form release/<release version> ausgeführt. Beide nutzen unseren GitHub-Aktions-Build-Schritt Roundup. Der unstable-cicd generiert (und aktualisiert ständig) eine SNAPSHOT-Version. Wenn Sie kein formelles Software-Release durchgeführt haben, erhalten Sie am Ende ein v0.0.0-SNAPSHOT Release (Einzelheiten finden Sie unter NASA-PDS/roundup-action#56).
