Skip to main content

A Python package to create XForms for ODK Collect.

Project description

circleci appveyor codecov black

pyxform is a Python library that makes writing forms for ODK Collect and Enketo easy by converting XLSForms (Excel spreadsheets) into ODK XForms. The XLSForms format is used in a number of tools.

XLS(X) documents used as input must follow to the XLSForm standard and the resulting output follows the ODK XForms standard.

pyxform is a major rewrite of xls2xform.

Running the latest release of pyxform

For those who want to convert forms at the command line, the latest official release of pyxform can be installed using pip:

pip install pyxform

The xls2xform command can then be used:

xls2xform path_to_XLSForm [output_path]

pyxform can be run with either Python 2 or Python 3. Continuous integration runs tests on both Python generations to ensure continued compatibility.

Running pyxform from local source

Note that you must uninstall any globally installed pyxform instance in order to use local modules. Please install java 8 or newer version.

From the command line:

python setup.py develop
python pyxform/xls2xform.py path_to_XLSForm [output_path]

Consider using a virtualenv and virtualenvwrapper to make dependency management easier and keep your global site-packages directory clean:

pip install virtualenv
pip install virtualenvwrapper
mkvirtualenv local_pyxform                     # or whatever you want to name it
(local_pyxform)$ python setup.py develop       # install the local files
(local_pyxform)$ python pyxform/xls2xform.py --help
(local_pyxform)$ xls2xform --help              # same effect as previous line
(local_pyxform)$ which xls2xform.              # ~/.virtualenvs/local_pyxform/bin/xls2xform

To leave and return to the virtual environment:

(local_pyxform)$ deactivate                    # leave the virtualenv
$ xls2xform --help
# -bash: xls2xform: command not found
$ workon local_pyxform                         # reactivate the virtualenv
(local_pyxform)$ which xls2xform               # & we can access the scripts once again
~/.virtualenvs/local_pyxform/bin/xls2xform

Installing pyxform from remote source

pip can install from any GitHub repository:

pip install git+https://github.com/XLSForm/pyxform.git@master#egg=pyxform

You can then run xls2xform from the commandline:

xls2xform path_to_XLSForm [output_path]

Development

To set up for development/contributing:

pip install -r requirements.pip

python setup.py develop

cd your-virtual-env-dir/src/pyxform

You can run tests with:

nosetests

Before committing, make sure to format your code using black:

black pyxform

If you are using a copy of black outside your virtualenv, make sure it is the same version as listed in requirements.pip.

Writing tests

Make sure to include tests for the changes you’re working on. When writing new tests you should add them in pyxform/test_v1 instead of in pyxform/test (which contains tests using an older style). Generally, the easiest way to write tests is to extend PyxformTestCase which will let you compile example XLSForm and make assertions on the resulting XForm.

Documentation

To check out the documentation for pyxform do the following:

pip install Sphinx==1.0.7

cd your-virtual-env-dir/src/pyxform/docs

make html

Change Log

Changelog

Releasing pyxform

  1. Make sure the version of ODK Validate in the repo is up-to-date:

    pyxform_validator_update odk update ODK-Validate-vx.x.x.jar
  2. Run all tests through Validate by setting the default for run_odk_validate to kwargs.get("run_odk_validate", True) in pyxform/tests_v1/pyxform_test_case.py.

  3. Draft a new GitHub release with the list of merged PRs. Follow the title and description pattern of the previous release.

  4. Checkout a release branch from latest upstream master.

  5. Update CHANGES.txt with the text of the draft release.

  6. Update README.rst, setup.py, pyxform/__init__.py with the new release version number.

  7. Commit, push the branch, and initiate a pull request. Wait for tests to pass, then merge the PR.

  8. In a clean new release only directory, checkout master.

  9. Create a new virtualenv in this directory to ensure a clean Python environment:

    mkvirtualenv pyxform-release
  10. Install the development and release requirements:

    pip install -r requirements.pip
    pip install wheel twine
  11. Cleanup build and dist folders:

    rm -rf build dist pyxform.egg-info
  12. Prepare sdist and bdist_wheel distributions:

    python setup.py sdist bdist_wheel
  13. Publish release to PyPI with twine:

    twine upload dist/pyxform-*-py2.py3-none-any.whl dist/pyxform-*.tar.gz
  14. Tag the GitHub release and publish it.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pyxform-1.5.0.tar.gz (2.0 MB view hashes)

Uploaded Source

Built Distribution

pyxform-1.5.0-py2.py3-none-any.whl (2.1 MB view hashes)

Uploaded Python 2 Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page