Package: pyodk
pyODKAn API client for theODK Central API. Use it to interact with your data and automate common tasks from Python.This library aims to make common data analysis and workflow automation tasks as simple as possible by providing clear method names, types, and examples. It also provides convenient access to the full API usingHTTP verb methods.InstallThe currently supported Python version forpyodkis 3.8.From pippipinstallpyodkFrom source# Get a copy of the repository.mkdir-P~/repos/pyodkcd~/repos/pyodk
gitclonehttps://github.com/getodk/pyodk.gitrepo# Create and activate a virtual environment for the install./usr/local/bin/python3.8-mvenvvenvsourcevenv/bin/activate# Install pyodk and its production dependencies.cd~/repos/pyodk/repo
pipinstall-e.# Leave the virtualenv.deactivateConfigureThe configuration file uses the TOML format. The default file name is.pyodk_config.toml, and the default location is the user home directory. The file name and location can be customised by setting the environment variablePYODK_CONFIG_FILEto some other file path, or by passing the path at init withClient(config_path="my_config.toml"). The expected file structure is as follows:[central]base_url="https://www.example.com"username="my_user"password="my_password"default_project_id=123Custom configuration file pathsTheClientis specific to a configuration and cache file. These approximately correspond to the session which theClientrepresents; it also encourages segregating credentials. These paths can be set by:Setting environment variablesPYODK_CONFIG_FILEandPYODK_CACHE_FILEInit arguments:Client(config_path="my_config.toml", cache_path="my_cache.toml").Default projectTheClientis not specific to a project, but a defaultproject_idcan be set by:Adefault_project_idin the configuration file.An init argument:Client(project_id=1).A property on the client:client.project_id = 1.Session cache fileThe session cache file uses the TOML format. The default file name is.pyodk_cache.toml, and the default location is the user home directory. The file name and location can be customised by setting the environment variablePYODK_CACHE_FILEto some other file path, or by passing the path at init withClient(config_path="my_cache.toml"). This file should not be pre-created as it is used to store a session token after login.UseTo get started withpyODK, build aClient:frompyodk.clientimportClientclient=Client()Authentication is triggered by the first API call on theClient, or by explicitly usingClient.open().UseClient.close()to clean up a client session. Clean up is recommended for long-running scripts, e.g. web apps, etc.You can also use the Client as a context manager to manage authentication and clean up:withClient()asclient:print(client.projects.list())Learn morein the documentation.Examples👉 See detailed tutorials inthe documentation.frompyodk.clientimportClientclient=Client()projects=client.projects.list()forms=client.forms.list()submissions=client.submissions.list(form_id=next(forms).xmlFormId)form_data=client.submissions.get_table(form_id="birds",project_id=8)comments=client.submissions.list_comments(form_id=next(forms).xmlFormId,instance_id="uuid:...")client.forms.update(form_id="my_xlsform",definition="my_xlsform.xlsx",attachments=["fruits.csv","vegetables.png"],)client.close()Session customizationIf Session behaviour needs to be customised, for example to set alternative timeouts or retry strategies, etc., then subclass thepyodk.session.Sessionand provide an instance to theClientconstructor, e.g.Client(session=my_session).LoggingErrors raised by pyODK and other messages are logged using theloggingstandard library. The logger is in thepyodknamespace / hierarchy (e.gpyodk.config,pyodk.endpoints.auth, etc.). The logs can be manipulated from your script / app as follows.importlogging# Initialise an example basic logging config (writes to stdout/stderr).logging.basicConfig()logging.getLogger().setLevel(logging.DEBUG)# Get a reference to the pyodk logger.pyodk_log=logging.getLogger("pyodk")# Receive everything DEBUG level and higher.pyodk_log.setLevel(logging.DEBUG)pyodk_log.propagate=True# Ignore everything below FATAL level.pyodk_log.setLevel(logging.FATAL)pyodk_log.propagate=FalseErrors raised by pyODKError types raised by pyODK are found inerrors.py, which currently is only thePyODKError. In general this error is raised when:The pyODK configuration is invalid (missing file, missing fields, etc).The client method arguments are invalid (missing, wrong type, etc.).The response from ODK Central indicated and error (HTTP >=400, <600).The data returned from ODK Central does not have the expected fields or types.Note that pyODK does not attempt to wrap every possible error condition, so if needed, broader exception handling should be included in your script / app.ContributeSee issues for additions topyodkthat are under consideration. Please file new issues for any functionality you are missing.DevelopInstall the source files as described above, then:pipinstall-rdev_requirements.pipYou can run tests with:nosetestsOn Windows, use:nosetests-v-v--traverse-namespace./testsReleaseRun all linting and tests.Draft a new GitHub release with the list of merged PRs.Check out a release branch from latest upstream master.Updatepyodk/__version__.pywith the new release version number.Commit, push the branch, and initiate a pull request. Wait for tests to pass, then merge the PR.Tag the release and it will automatically be published (seerelease.ymlactions file).