Make hocr-tools a proper module

[kba]

The README currently states:

Each command line program is self contained; if you have Python 2.7 with the required packages installed, it should just work. (Unfortunately, that means some code duplication; we may revisit this issue in later revisions.)

I would like to revisit this issue 😄

The advantages of striving to make the programs self-contained is that there is no need to install the whole project to run an individual script, provided the requirements were installed by some other means (e.g. apt-get). For simple scripts like hocr-check this is really neat.

The disadvantages of self-contained commands are IMHO:

• Code redundancy (assoc, get_text etc.). These are small functions but it's considerable boilerplate and keeping them consistent is a hassle. This also makes it hard to spot that e.g. get_text has not been needed for a while.
• Embedding resources in the source code, such as the invisible font in hocr-pdf, makes it hard to add changes.
• It makes it harder to keep consistent interfaces. Some commands use optparse, others parse CLI arguments themselves, some read from STDIN on no args, some show the help page on no args, some exit with an error etc. A shared hocrlib module could help reduce boilerplate, though a consistent use of one of argparse could also remedy this situation.

In summary, I would argue for an approach with a shared library, resources in the file system and require users to properly (setup.py) install the tools.

What do you think?

In particular, is anyone relying on the scripts being self-contained?

[stweil]

We could also write modular code and provide a way to build self contained command files.

[zuphilip]

I agree that the advantages of a shared library, resources are larger and we can also require that people are running a setup script (maybe add more options there). Personally, I always run the setup.py-script to make the command known system-wide.

Would it still be possible to go the PyPI way with that?

We could also write modular code and provide a way to build self contained command files.

Yes, we could maybe build them also for every release as a separate zip (resp. check if we can automate that). Alternatively, it could also be an option for the setup script to build independent python commands.

[kba]

Would it still be possible to go the PyPI way with that?

Yes, all this can be handled by setuptools in setup.py.

We could also write modular code and provide a way to build self contained command files.

Not sure if I understand. The commands cannot be truly self-contained, they still have external dependencies, e.g. hocr-pdf requires reportlab to be installed.

Creating special versions of the scripts at build time, e.g. "baking in" the invisible font is possible but very finicky.

But we can use setuptools to create egg distributions, Windows installers and such. And of course users should still be able to just git clone the repository and run the scripts directly.