Development

Cutplace is open source software, so its source code is available for you to inspect, extend and play around with. This chapter describes where to get it, how to build it and how to contribute to the project.

If you are interested in using cutplace’s classes and functions, refer to the chapter about the Application programmer interface.

Obtain and build the source code

The source code for cutplace is available via a Git repository from https://github.com/roskakori/cutplace. Visit http://help.github.com/ to learn how to browse, download or fork the source code.

To build the source code, you need a few additional tools and Python packages.

First, you need to install poetry.

Then you can run the test cases. When run for the first time, this also installs all the dependencies, which might take a while:

$ poetry run pytest

To build the distribution archives:

$ poetry build

For everything else related to the build, use ant, a build tool popular in the Java world. To get an overview of the available ant targets, run:

$ ant -projecthelp

Using ant in a Python project might seem unusual, but there are good reasons for that:

  • ant is more robust and portable than using shell scripts for the same thing.

  • It is easier to write and maintain an ant target than adding a new setup.py command. This is particularly true for targets that just call a few command line tools and move around a couple of files.

To build the documentation:

$ ant docs

Project overview

The source code consists of:

  • build.xml is the project file for the build tool ant

  • cutplace/*.py are the Python modules for cutplace

  • tests/test_*.py are test cases for unittest

  • tests/data/* are test data used by the unittests; some of them are *.ods, *.xls or *.xlsx spread sheet you can edit using Calc from OpenOffice.org.

  • docs/* is the reStructuredText for the user guide

  • examples/* contains the example date used in the Tutorial and code examples on how to use the cutplace Python module in you own code.

Source code contributions

In case you fixed any bugs or added improvements to cutplace, feel free to contribute your changes by forking the repository and issuing a pull request as described at http://help.github.com/fork-a-repo/.

Developer cheat sheet

This section makes it easier for developers to remember how to perform certain common but rarely necessary tasks.

Build the distribution archives:

$ poetry build

Tag a release (simply replace 0.9.x with the current version number):

$ git tag -a -m "Tagged version 0.9.x." v0.9.x
$ git push --tags

Upload release to PyPI:

$ poetry run pytest
$ poetry publish