Package: centralpy
A Python client for ODK CentralODK Central has anAPI, and this Python package interacts with it. The use cases in this package were written to support PMA data management purposes, but the package can be extended for other use cases as well.InstallationFirst, make sure Python3 (at least version 3.6) is installed.Usepipto install this package withpython3 -m pip install centralpyFrom here, the program runs by using either the installed script, e.g.centralpy --helpor, by invoking the module withpython3 -m centralpy --helpUpgradeUpgrade this package withpython3 -m pip install --upgrade centralpyInstallation from Githubpython3 -m pip install --upgrade https://github.com/pmaengineering/centralpy/zipball/masterUsageThe main commandcentralpydoes not do anything by itself. It has its own options to configure the program and then delegate to its subcommands.The options for the main commandcentralpyareOptionDescription-u, --url TEXTThe URL for the ODK Central server-e, --email TEXTAn ODK Central user email-p, --password TEXTThe password for the account-l, --log-file FILEWhere to save logs.  (default: ./centralpy.log)-v, --verboseDisplay logging messages to console. This cannot be enabled from a config file.-c, --config-file FILENAMEA configuration file with KEY=VALUE defined (one per line). Keys should be formatted asCENTRALPY_***.--helpShow this message and exit.There are then nine subcommands.pullcsvpushcheckdownload-attachmentsupload-attachmentscheck-server-auditsrepair-server-auditsconfigversionSubcommand: pullcsvThis subcommand downloads the CSV zip file and extracts data CSVs. The zip file is saved with a timestamp in the filename in order to assist in deleting old zip files (see the--keepoption).An easy way to get the project ID (a number) and the XForm ID is to navigate to the form on ODK Central, and then examine the URL.The options forpullcsvareOptionDescription-p, --project INTEGERThe numeric ID of the project. ODK Central assigns this ID when the project is created.  (required)-f, --form-id TEXTThe form ID (a string), usually defined in the XLSForm settings. This is a unique identifier for an ODK form. (required)-c, --csv-dir DIRECTORYThe directory to export CSV files to  (default: ./)-z, --zip-dir DIRECTORYThe directory to save the downloaded zip to  (default: ./)-A, --no-attachmentsIf this flag is supplied, then the CSV zip will be downloaded without attachments.-P, --no-progress-barDo not show progress bar for download.-k, --keep INTEGERThe number of zip files to keep in the zip directory, keeping the most recent. The number must be 1 or larger for anything to happen.--helpShow this message and exit.Subcommand: pushThis subcommand crawls through a local directory looking for XML files to upload. The form ID is autodetected from the XML.NOTECentralpy expects there to be no more than one XML file per subfolder, which is how instances are saved on the phone by ODK Collect.The options forpushareOptionDescription-p, --project INTEGERThe numeric ID of the project  (required)-l, --local-dir DIRECTORYThe directory to push uploads from  (default: ./)--helpShow this message and exit.Subcommand: checkCheck the connection, configuration, and parameters for centralpy.These checks are performed in order, checking that centralpy canConnect to the serverVerify the server is an ODK Central serverAuthenticate the provided credentialsCheck existence and access to the project, if providedCheck existence and access to the form ID within the project, if providedCheck existence of the instance ID within the form, if providedIf any of the checks fail, then the remaining checks are not performed.TIP:If a project is not provided, but the credentials are valid, then centralpy will show which projects are accessible for the user. Likewise, if there are valid credentials and a valid project, then centralpy will show which form IDs are accessible for the user.OptionDescription-p, --project INTEGERThe numeric ID of the project. ODK Central assigns this ID when the project is created.-f, --form-id TEXTThe form ID (a string), usually defined in the XLSForm settings. This is a unique identifier for an ODK form.-i, --instance-id TEXTAn instance ID, found in the metadata for a submission. This is a unique identifier for an ODK submission to a form.--helpShow this message and exit.Subcommand: download-attachmentsDownload attachments for the given submission.To download all attachments, do not specify -a. To specify multiple
attachments, use -a multiple times.Use the check sub-command to see what attachments are available.OptionDescription-p, --project INTEGERThe numeric ID of the project. ODK Central assigns this ID when the project is created. (required)-f, --form-id TEXTThe form ID (a string), usually defined in the XLSForm settings. This is a unique identifier for an ODK form.  (required)-i, --instance-id TEXTAn instance ID, found in the metadata for a submission. This is a unique identifier for an ODK submission to a form.  (required)-a, --attachment TEXTThe attachment file to download for the instance ID. If not given, then download all attachments.-d, --download-dir DIRECTORYThe directory to save audit files to. Default is a safe version of the instance ID as the directory.--helpShow this message and exit.Subcommand: upload-attachmentsUpload one or more attachments for the given submission.To pass multiple attachments, use -a multiple times.OptionDescription-p, --project INTEGERThe numeric ID of the project. ODK Central assigns this ID when the project is created.-f, --form-id TEXTThe form ID (a string), usually defined in the XLSForm settings. This is a unique identifier for an ODK form.-i, --instance-id TEXTAn instance ID, found in the metadata for a submission. This is a unique identifier for an ODK submission to a form.-a, --attachment FILENAMEThe attachment file to upload for the instance ID.--helpShow this message and exit.Subcommand: check-server-auditsCheck audit files on ODK Central for correctness.This command saves bad audits to disk so they can be corrected. After
correcting them, use repair-server-audits to upload back to ODK Central.OptionDescription-p, --project INTEGERThe numeric ID of the project. ODK Central assigns this ID when the project is created.  (required)-f, --form-id TEXTThe form ID (a string), usually defined in the XLSForm settings. This is a unique identifier for an ODK form.  (required)-r, --report-file FILEWhere to save results from checking audits in JSON format. This file is meant to be reused from check to check.  (required)-a, --audit-dir DIRECTORYThe directory to save audit files to  (required)-t, --time TEXTA relative time string, formatted as #h or #d with # is a number. Use "h" for hours and "d" for days. Check submissions in the last #h or #d.-s, --since-prevCheck submissions received after the last check (from --report-file). If no --time option is given, then the code tries to filter by previous report time.--helpShow this message and exit.Subcommand: repair-server-auditsRepair audit files on ODK Central by uploading corrected audits.This is meant to be used after running check-server-audits.OptionDescription-r, --report-file FILEThe JSON file saved from check-server-audits. This file contains metadata about where to find instances.  (required)--helpShow this message and exit.Subcommand: configThis subcommand prints out the configuration that the main command,centralpyusesSubcommand: versionThis subcommand prints out centralpy's version.NOTE:The logs generated fromcli.pyalso include the version number.Example usageHow toPull CSV dataSave CSV data and zip files to different directoriesKeep the most recent 7 zip files# First on one line
centralpy --url "https://central.example.com" --email "manager@example.com" --password "password1234" --verbose pullcsv --project 1 --form-id MY_FORM_ID --csv-dir /path/to/csv/dir --zip-dir /path/to/zip/dir --keep 7
# Then the same command on multiple lines
centralpy \
--url "https://central.example.com" \
--email "manager@example.com" \
--password "password1234" \
--verbose \
pullcsv \
--project 1 \
--form-id MY_FORM_ID \
--csv-dir /path/to/csv/dir \
--zip-dir /path/to/zip/dir \
--keep 7How toDo the same as the above using a log file# First on one line
centralpy --config-file /path/to/config.txt --verbose pullcsv --project 1 --form-id MY_FORM_ID --csv-dir /path/to/csv/dir --zip-dir /path/to/zip/dir --keep 7
# Then the same command on multiple lines
centralpy \
--config-file /path/to/config.txt \
--verbose \
pullcsv \
--project 1 \
--form-id MY_FORM_ID \
--csv-dir /path/to/csv/dir \
--zip-dir /path/to/zip/dir \
--keep 7How toPush XML files to ODK Central# First on one line
centralpy --url "https://odkcentral.example.com" --email "manager@example.com" --password "password1234" push --project 1 --local-dir /path/to/dir
# Then the same command on multiple lines
centralpy \
--url "https://odkcentral.example.com" \
--email "manager@example.com" \
--password "password1234" \
push \
--project 1 \
--local-dir /path/to/dirAn example config fileA config file can be specified for the main command,centralpy. The following demonstrates the contents of an example config file:CENTRALPY_URL=https://odkcentral.example.com
CENTRALPY_EMAIL=manager@example.com
CENTRALPY_PASSWORD=password1234
CENTRALPY_LOG_FILE=centralpy.logUsage: check-auditsFind audit files with incorrect number of fields in a record.ODK Central expects audit files to have the correct number of fields per record.
The correct length is established by the header row.
An record is usually a line. However, using quoting, a CSV field can span multiple lines.OptionDescription-r, --record TEXTWhich records to look at. Give a range or a single number. Default is all records.-l, --log-file FILEWhere to save logs.  (default: ./centralpy.log)-v, --verboseDisplay logging messages to console. This cannot be enabled from a config file.--helpShow this message and exit.The commandcheck-audits(not prefixed bycentralpy) orpython3 -m centralpy.check_auditscan be used to check localaudit.csvfiles for correct record length. ODK Central tends to get into a bad state if these files are downloaded as attachments.check-audits /path/to/storageDevelopCreate a virtual environmentpython3 -m venv env/ --prompt centralpyActivate itsource env/bin/activateInstallpip-toolswithpython3 -m pip install pip-toolsClone this repositoryDownload all developer packages:pip-sync requirements.txt requirements-dev.txtFYI: this package's dependencies arerequestsfor communicating with ODK Centralclick>=8.0.0 for composing the command-line interfacetqdm>= 4.62.0 for progress bar feedbackwerkzeug>= 2.0.2 for secure filenamesBugsSubmit bug reports on the Github repository's issue tracker athttps://github.com/pmaengineering/centralpy/issues. Or, email the maintainer atjpringleBEAR@jhu.edu(minus the BEAR).Un client Python pour ODK CentralODK Central a uneAPI, et ce package Python interagit avec elle. Les cas d'utilisation de ce package ont été écrits pour prendre en charge les objectifs de gestion des données PMA, mais le package peut également être étendu à d'autres cas d'utilisation.InstallationTout d'abord, assurez-vous que Python3 (au moins la version 3.6) est installé.Utilisezpippour installer ce package avecpython3 -m pip install centralpyÀ partir de là, le programme s'exécute en utilisant soit le script installé, par exemplecentralpy --helpou, en invoquant le module avecpython3 -m centralpy --helpAméliorerMettez à niveau ce package avecpython3 -m pip install --upgrade centralpyInstallation depuis Githubpython3 -m pip install --upgrade https://github.com/pmaengineering/centralpy/zipball/masterUsageLa commande principalecentralpyne fait rien par elle-même. Il a ses propres options pour configurer le programme et ensuite déléguer à ses sous-commandes.Les options de la commande principalecentralpysontOptionDescription-u, --url TEXTL'URL du serveur ODK Central-e, --email TEXTUn e-mail d'utilisateur ODK Central-p, --password TEXTLe mot de passe du compte-l, --log-file FILEOù enregistrer les journaux. (par défaut: ./centralpy.log)-v, --verboseAfficher les messages de journalisation sur la console. Cela ne peut pas être activé à partir d'un fichier de configuration.-c, --config-file FILENAMEUn fichier de configuration avec KEY = VALUE défini (un par ligne). Les clés doivent être au formatCENTRALPY_***.--helpAffichez ce message et quittez.Il y a alors neuf sous-commandes.pullcsvpushcheckdownload-attachmentsupload-attachmentscheck-server-auditsrepair-server-auditsconfigversionSous-commande: pullcsvCette sous-commande télécharge le fichier zip CSV et extrait les données CSV. Le fichier zip est enregistré avec un horodatage dans le nom du fichier afin d'aider à supprimer les anciens fichiers zip (voir l'option--keep).Un moyen simple d'obtenir l'ID de projet (un nombre) et l'ID XForm consiste à accéder au formulaire sur ODK Central, puis à examiner l'URL.Les options pourpullcsvsontOptionDescription-p, --project INTEGERL'ID numérique du projet. ODK Central attribue cet ID lors de la création du projet. (obligatoire)-f, --form-id TEXTL'ID du formulaire (une chaîne), généralement défini dans les paramètres XLSForm. Il s'agit d'un identifiant unique pour un formulaire ODK. (obligatoire)-c, --csv-dir DIRECTORYLe répertoire vers lequel exporter les fichiers CSV (par défaut: ./)-z, --zip-dir DIRECTORYLe répertoire dans lequel enregistrer le zip téléchargé (par défaut: ./)-A, --no-attachmentsSi cet indicateur est fourni, le zip CSV sera téléchargé sans pièces jointes.-P, --no-progress-barNe pas afficher la barre de progression pour le téléchargement.-k, --keep INTEGERLe nombre de fichiers zip à conserver dans le répertoire zip, en conservant les plus récents. Le nombre doit être 1 ou plus pour que quoi que ce soit se passe.--helpAffichez ce message et quittez.Sous-commande: pushCette sous-commande parcourt un répertoire local à la recherche de fichiers XML à télécharger. L'ID de formulaire est détecté automatiquement à partir du XML.REMARQUECentralpy s'attend à ce qu'il n'y ait pas plus d'un fichier XML par sous-dossier, c'est ainsi que les instances sont enregistrées sur le téléphone par ODK Collect.Les options pourpushsontOptionDescription-p, --project INTEGERL'ID numérique du projet (obligatoire)-l, --local-dir DIRECTORYLe répertoire à partir duquel envoyer les téléchargements (par défaut: ./)--helpAffichez ce message et quittez.Sous-commande: checkVérifiez la connexion, la configuration et les paramètres de centralpy.Ces contrôles sont effectués dans l'ordre, en vérifiant que centralpy peutConnectez-vous au serveurVérifiez que le serveur est un serveur ODK CentralAuthentifiez les informations d'identification fourniesVérifier l'existence et l'accès au projet, le cas échéantVérifier l'existence et l'accès à l'ID de formulaire dans le projet, s'il est fourniSi l'une des vérifications échoue, les vérifications restantes ne sont pas effectuées.CONSEIL:Si un projet n'est pas fourni, mais que les informations d'identification sont valides, alors centralpy montrera quels projets sont accessibles à l'utilisateur. De même, s'il existe des informations d'identification valides et un projet valide, alors centralpy affiche les ID de formulaire accessibles à l'utilisateur.OptionDescription-p, --project INTEGERL'ID numérique du projet. ODK Central attribue cet ID lors de la création du projet.-f, --form-id TEXTL'ID du formulaire (une chaîne), généralement défini dans les paramètres XLSForm. Il s'agit d'un identifiant unique pour un formulaire ODK.-i, --instance-id TEXTEUn identifiant d'instance, trouvé dans les métadonnées d'un soumission. Il s'agit d'un identifiant unique pour un ODK soumission à un formulaire.--helpAffichez ce message et quittez.Sous-commande: download-attachmentsTéléchargez les pièces jointes pour la soumission donnée.Pour télécharger toutes les pièces jointes, ne spécifiez pas -a. Pour spécifier plusieurs
pièces jointes, utilisez -a plusieurs fois.Utilisez la sous-commande check pour voir quelles pièces jointes sont disponibles.OptionDescription-p, --project ENTIERL'ID numérique du projet. ODK Central attribue cet ID lors de la création du projet. (obligatoire)-f, --form-id TEXTEL'ID du formulaire (une chaîne), généralement défini dans les paramètres XLSForm. Il s'agit d'un identifiant unique pour un formulaire ODK. (obligatoire)-i, --instance-id TEXTEUn ID d'instance, trouvé dans les métadonnées d'une soumission. Il s'agit d'un identifiant unique pour une soumission ODK à un formulaire. (obligatoire)-a, --attachement TEXTELe fichier de pièce jointe à télécharger pour l'ID d'instance. Sinon, téléchargez toutes les pièces jointes.-d, --download-dir RÉPERTOIRERépertoire dans lequel enregistrer les fichiers d'audit. La valeur par défaut est une version sécurisée de l'ID d'instance en tant que répertoire.--helpAffichez ce message et quittez.Sous-commande: upload-attachmentsMettez à jour une ou plusieurs pièces jointes pour la soumission donnée.Pour transmettre plusieurs pièces jointes, utilisez -a plusieurs fois.OptionsDescription-p, --project INTEGERL'ID numérique du projet. ODK Central attribue cet ID lors de la création du projet.-f, --form-id TEXTL'ID du formulaire (une chaîne), généralement défini dans le Paramètres XLSForm. Il s'agit d'un identifiant unique pour un formulaire ODK.-i, --instance-id TEXTEUn identifiant d'instance, trouvé dans les métadonnées d'un soumission. Il s'agit d'un identifiant unique pour un Soumission ODK à un formulaire.-a, --attachment FILENAMELe fichier de pièce jointe à mettre à jour pour l'instance IDENTIFIANT.--helpAffiche ce message et quitte.Sous-commande: check-server-auditsVérifiez l'exactitude des fichiers d'audit sur ODK Central.Cette commande enregistre les mauvais audits sur le disque afin qu'ils puissent être corrigés. Après
les corriger, utilisez repair-server-audits pour les télécharger à nouveau vers ODK Central.OptionDescription-p, --project ENTIERL'ID numérique du projet. ODK Central attribue cet ID lors de la création du projet. (obligatoire)-f, --form-id TEXTEL'ID du formulaire (une chaîne), généralement défini dans les paramètres XLSForm. Il s'agit d'un identifiant unique pour un formulaire ODK. (obligatoire)-r, --report-file FICHIEROù enregistrer les résultats de la vérification des audits au format JSON. Ce fichier est destiné à être réutilisé de chèque en chèque. (obligatoire)-a, --audit-dir RÉPERTOIRELe répertoire dans lequel enregistrer les fichiers d'audit (obligatoire)-t, --time TEXTEUne chaîne d'heure relative, au format #h ou #d avec # est un nombre. Utilisez "h" pour les heures et "d" pour les jours. Vérifiez les soumissions dans le dernier #h ou #d.-s, --since-prevVérifiez les soumissions reçues après la dernière vérification (depuis --report-file). Si aucune option --time n'est donnée, le code essaie de filtrer par heure du rapport précédent.--helpAffichez ce message et quittez.Sous-commande: repair-server-auditsRéparez les fichiers d'audit sur ODK Central en téléchargeant les audits corrigés.Ceci est destiné à être utilisé après avoir exécuté check-server-audits.OptionDescription-r, --report-file FICHIERLe fichier JSON enregistré à partir de check-server-audits. Ce fichier contient des métadonnées indiquant où trouver les instances. (obligatoire)--helpAffichez ce message et quittez.Sous-commande: configCette sous-commande imprime la configuration utilisée par la commande principale,centralpySous-commande: versionCette sous-commande imprime la version de centralpy.REMARQUE:Les journaux générés à partir decli.pyincluent également le numéro de version.Exemple d'utilisationCommentExtraire les données CSVEnregistrer les données CSV et les fichiers zip dans différents répertoiresConservez les 7 fichiers zip les plus récents# Premier sur une ligne
centralpy --url "https://central.example.com" --email "manager@example.com" --password "password1234" --verbose pullcsv --project 1 --form-id MY_FORM_ID --csv-dir /path/to/csv/dir --zip-dir /path/to/zip/dir --keep 7
# Puis la même commande sur plusieurs lignes
centralpy \
--url "https://central.example.com" \
--email "manager@example.com" \
--password "password1234" \
--verbose \
pullcsv \
--project 1 \
--form-id MY_FORM_ID \
--csv-dir /path/to/csv/dir \
--zip-dir /path/to/zip/dir \
--keep 7CommentFaites la même chose que ci-dessus en utilisant un fichier journal# Premier sur une ligne
centralpy --config-file /path/to/config.txt --verbose pullcsv --project 1 --form-id MY_FORM_ID --csv-dir /path/to/csv/dir --zip-dir /path/to/zip/dir --keep 7
# Puis la même commande sur plusieurs lignes
centralpy \
--config-file /path/to/config.txt \
--verbose \
pullcsv \
--project 1 \
--form-id MY_FORM_ID \
--csv-dir /path/to/csv/dir \
--zip-dir /path/to/zip/dir \
--keep 7CommentPoussez les fichiers XML vers ODK Central# Premier sur une ligne
centralpy --url "https://odkcentral.example.com" --email "manager@example.com" --password "password1234" push --project 1 --local-dir /path/to/dir
# Puis la même commande sur plusieurs lignes
centralpy \
--url "https://odkcentral.example.com" \
--email "manager@example.com" \
--password "password1234" \
push \
--project 1 \
--local-dir /path/to/dirUn exemple de fichier de configurationUn fichier de configuration peut être spécifié pour la commande principale,centralpy. Ce qui suit montre le contenu d'un exemple de fichier de configuration:CENTRALPY_URL=https://odkcentral.example.com
CENTRALPY_EMAIL=manager@example.com
CENTRALPY_PASSWORD=password1234
CENTRALPY_LOG_FILE=centralpy.logUtilisation : check-auditsTrouver des fichiers d'audit avec un nombre incorrect de champs dans un enregistrement.ODK Central s'attend à ce que les fichiers d'audit aient le nombre correct de champs par enregistrement.
La longueur correcte est établie par la ligne d'en-tête.
Un enregistrement est généralement une ligne. Cependant, en utilisant les guillemets, un champ CSV peut s'étendre sur plusieurs lignes.OptionDescription-r, --record TEXTEQuels enregistrements consulter. Donnez une plage ou un nombre unique. La valeur par défaut est tous les enregistrements.-l, --log-file FICHIEROù enregistrer les journaux. (par défaut : ./centralpy.log)-v, --verboseAfficher les messages de journalisation sur la console. Cela ne peut pas être activé à partir d'un fichier de configuration.--helpAffichez ce message et quittez.La commandecheck-audits(non préfixée parcentralpy) oupython3 -m centralpy.check_auditspeut être utilisée pour vérifier la longueur d'enregistrement correcte des fichiersaudit.csvlocaux. ODK Central a tendance à se détériorer si ces fichiers sont téléchargés en tant que pièces jointes.check-audits /chemin/vers/stockageDévelopperCréer un environnement virtuelpython3 -m venv env/ --prompt centralpyActivez-lesource env/bin/activateInstallezpip-toolsavecpython3 -m pip install pip-toolsCloner ce référentielTéléchargez tous les packages de développement:pip-sync requirements.txt requirements-dev.txtPour info: les dépendances de ce package sontrequestspour communiquer avec ODK Centralclick>=8.0.0 pour composer l'interface de ligne de commandetqdm>= 4.62.0 pour les commentaires de la barre de progressionwerkzeug>= 2.0.2 pour les noms de fichiers sécurisésInsectesSoumettez des rapports de bogue sur le suivi des problèmes du référentiel Github à l'adressehttps://github.com/pmaengineering/centralpy/issues. Ou, envoyez un e-mail au responsable àjpringleOURS@jhu.edu(moins l'OURS).Dernière mise à jour de la traduction française 10/21/2021