add version-strings into the module

The version string is in the module as __version__ available.
In the doc the version will be automatically parsed. The version comes
from the installed module if on read the docs or directly from
setuptools_scm if you are working locally.
The CLI will issue the version string if you call it with the option
'version'. The CLI does not accept commands like '--version', since this
would not be conform with the rest of the interface (and argparse).

The configuration for loading the version-string is adapted from
pimutils/vdirsyncer. It autogenerates a version string setuptools_scm at
install-time and then adds it to the __version__ member in __init__.py

I adapted the GitHub-template with a fitting comment and bumped the
changelog.

closes #141

.github/ISSUE_TEMPLATE.md

@@ -17,6 +17,8 @@ I have:
 <!-- Replace examples with your info -->
  **Printer:** Manufacturer Model XVI
 
+<!-- since version 2.0.1 you can type 'python-escpos version' in your shell.
+Alternatively you could use '__version__' in module escpos. -->
  **python-escpos version:** 0.0.0
 
  **python version:** 0.0

.gitignore

@@ -17,6 +17,7 @@ temp
 build/
 dist/
 .coverage
+src/escpos/version.py
 
 # testing temporary directories
 test/test-cli-output/

CHANGELOG.rst

@@ -10,6 +10,7 @@ changes
 - packaging: configured the coverage-analysis codecov.io
 - GitHub: improved issues-template
 - documentation: add troubleshooting tip to network-interface
+- the module, cli and documentation is now aware of the version of python-escpos
 
 contributors
 ^^^^^^^^^^^^

doc/conf.py

@@ -15,7 +15,10 @@
 import sys
 import os
 on_rtd = os.getenv('READTHEDOCS') == 'True'
-from setuptools_scm import get_version
+if on_rtd:
+    import escpos
+else:
+    from setuptools_scm import get_version
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -70,10 +73,14 @@ copyright = u'2016, Manuel F Martinez and others'
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
+if on_rtd:
+    # The full version, including alpha/beta/rc tags.
+    release = escpos.__version__
+else:
+    # locally setuptools_scm should work
+    release = get_version(root=root)
 # The short X.Y version.
-version = get_version(root=root)
+version = '.'.join(release.split('.')[:2])  # The short X.Y version.
-# The full version, including alpha/beta/rc tags.
-release = version
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

setup.py

@@ -45,9 +45,24 @@ class Tox(test_command):
         errno = tox.cmdline(args=args)
         sys.exit(errno)
 
+
+setuptools_scm_template = """\
+# coding: utf-8
+# file generated by setuptools_scm
+# don't change, don't track in version control
+from __future__ import unicode_literals
+
+version = '{version}'
+
+"""
+
+
 setup(
     name='python-escpos',
-    use_scm_version=True,
+    use_scm_version={
+        'write_to': 'src/escpos/version.py',
+        'write_to_template': setuptools_scm_template,
+    },
     url='https://github.com/python-escpos/python-escpos',
     download_url='https://github.com/python-escpos/python-escpos/archive/master.zip',
     description='Python library to manipulate ESC/POS Printers',

src/escpos/__init__.py

@@ -1 +1,19 @@
+# -*- coding: utf-8 -*-
+"""
+python-escpos enables you to manipulate escpos-printers
+"""
+from __future__ import absolute_import
+from __future__ import division
+from __future__ import print_function
+from __future__ import unicode_literals
+
 __all__ = ["constants", "escpos", "exceptions", "printer"]
+
+try:
+    from .version import version as __version__  # noqa
+except ImportError:  # pragma: no cover
+    raise ImportError(
+        'Failed to find (autogenerated) version.py. '
+        'This might be because you are installing from GitHub\'s tarballs, '
+        'use the PyPI ones.'
+    )

src/escpos/cli.py

@@ -17,6 +17,7 @@ import argparse
 import sys
 import six
 from . import config
+from . import version
 
 
 # Must be defined before it's used in DEMO_FUNCTIONS
@@ -448,7 +449,7 @@ def main():
     # Allow config file location to be passed
     parser.add_argument(
         '-c', '--config',
-        help='Altnerate path to the configuration file',
+        help='Alternate path to the configuration file',
     )
 
     # Everything interesting runs off of a subparser so we can use the format
@@ -491,6 +492,10 @@ def main():
         action='store_true',
     )
 
+    parser_command_version = command_subparsers.add_parser('version',
+                                                           help='Print the version of python-escpos')
+    parser_command_version.set_defaults(version=True)
+
     # Get only arguments actually passed
     args_dict = vars(parser.parse_args())
     if not args_dict:
@@ -498,6 +503,12 @@ def main():
         sys.exit()
     command_arguments = dict([k, v] for k, v in six.iteritems(args_dict) if v is not None)
 
+    # If version should be printed, do this, then exit
+    print_version = command_arguments.pop('version', None)
+    if print_version:
+        print(version.version)
+        sys.exit()
+
     # If there was a config path passed, grab it
     config_path = command_arguments.pop('config', None)
 

test/test_cli.py

@@ -11,6 +11,7 @@ import os
 import sys
 from scripttest import TestFileEnvironment
 from nose.tools import assert_equals
+import escpos
 
 TEST_DIR = os.path.abspath('test/test-cli-output')
 
@@ -29,7 +30,7 @@ printer:
 )
 
 
-class TestCLI:
+class TestCLI():
     """ Contains setups, teardowns, and tests for CLI
     """
 
@@ -60,8 +61,7 @@ class TestCLI:
         )
 
         self.default_args = (
-            sys.executable,
+            'python-escpos',
-            '-mescpos.cli',
             '-c',
             CONFIGFILE,
         )
@@ -79,10 +79,16 @@ class TestCLI:
 
     def test_cli_help(self):
         """ Test getting help from cli """
-        result = self.env.run(sys.executable, '-mescpos.cli', '-h')
+        result = self.env.run('python-escpos', '-h')
         assert not result.stderr
         assert 'usage' in result.stdout
 
+    def test_cli_version(self):
+        """ Test the version string """
+        result = self.env.run('python-escpos', 'version')
+        assert not result.stderr
+        assert_equals(escpos.__version__, result.stdout.strip())
+
     def test_cli_text(self):
         """ Make sure text returns what we sent it """
         test_text = 'this is some text'