Issue 3754 - Initial setup of the python-abp repo.

setup.py

+# This file is part of Adblock Plus <https://adblockplus.org/>,
+# Copyright (C) 2006-2016 Eyeo GmbH
+#
+# Adblock Plus is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License version 3 as
+# published by the Free Software Foundation.
+#
+# Adblock Plus is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Adblock Plus.  If not, see <http://www.gnu.org/licenses/>.
+
+"""A library for working with Adblock Plus filterlists."""

[Sebastian Noack, 2016/03/15 12:18:07]

This doc string seems to be misleading, as this file isn't the library mentioned
but it's setup script.

[Vasily Kuznetsov, 2016/03/15 13:14:36]

It's here to be used in the long_description later, but yeah, misleading indeed.
I'll move the content of the docstring there directly instead.

+
+from __future__ import print_function

[Sebastian Noack, 2016/03/15 12:18:07]

It seems you don't use any print statements in here.

[Vasily Kuznetsov, 2016/03/15 13:14:35]

Acknowledged.

+
+import os
+import shutil
+import subprocess
+from os import path
+from setuptools import setup, Command
+
+
+PACKAGE = 'python-abp'
+DEVENV = 'devenv'
+MODULE = 'abp'
+TESTS = 'tests'
+
+PYTHON = path.join(DEVENV, 'bin', 'python')
+PIP = path.join(DEVENV, 'bin', 'pip')
+PYTEST = path.join(DEVENV, 'bin', 'py.test')
+TOX = path.join(DEVENV, 'bin', 'tox')
+FLAKE8 = path.join(DEVENV, 'bin', 'flake8')
+AUTOPEP8 = path.join(DEVENV, 'bin', 'autopep8')
+
+DEV_DEPENDENCIES = ['pytest', 'pytest-cov', 'tox', 'flake8', 'autopep8']
+PYCS = sum([[path.join(dirname, fn) for fn in files if fn.endswith('.pyc')]
+            for dirname, _, files in os.walk('.')], [])
+GARBAGE = [
+    DEVENV, '.cache', '.coverage', '.tox', 'htmlcov', 'build',
+    PACKAGE.replace('-', '_') + '.egg-info', 'dist'
+] + PYCS
+
+
+def make_command(func):
+    """Converting function to a command suitable for use with setup."""
+
+    class CmdClass(Command):
+
+        description = func.__doc__[0].lower() + func.__doc__[1:-1]
+        user_options = []
+
+        def initialize_options(self):
+            pass
+
+        def finalize_options(self):
+            pass
+
+        def run(self):
+            func()
+
+    return CmdClass
+
+
+def devclean():
+    """Delete development artifacts."""
+    for item in GARBAGE:
+        if path.isdir(item):
+            shutil.rmtree(item, ignore_errors=True)
+        elif path.isfile(item):
+            os.remove(item)
+
+
+def devenv():
+    """Create development virtualenv."""
+    if not path.isdir(DEVENV):
+        subprocess.check_call(['virtualenv', DEVENV])
+        subprocess.check_call([PIP, 'install'] + DEV_DEPENDENCIES)
+
+
+def syntaxcheck():
+    """Find PEP8 violations and common errors with flake8."""
+    devenv()
+    subprocess.call([FLAKE8, MODULE, TESTS])
+
+
+def diffpep8():
+    """Produce a diff of PEP8 fixes proposed by autopep8."""
+    devenv()
+    subprocess.check_call([AUTOPEP8, '--diff', '-r', '-aaa', MODULE, TESTS])
+
+
+def test():
+    """Run tests with py.test."""
+    devenv()
+    subprocess.call([PYTEST, TESTS])
+
+
+def testall():
+    """Run tests with all supported python versions using tox."""
+    devenv()
+    subprocess.call([TOX])
+
+
+def testcov():
+    """Produce test coverage report."""
+    devenv()
+    subprocess.call([PYTEST, '--cov=' + MODULE, TESTS])
+
+
+def htmlcov():
+    """Produce test coverage report in HTML."""
+    devenv()
+    subprocess.call([PYTEST, '--cov-report=html', '--cov=' + MODULE, TESTS])
+
+
+setup(
+    name=PACKAGE,
+    version='0.0.1',
+    description='ABP python tools',
+    long_description=__doc__,
+    author='Vasily Kuznetsov',
+    author_email='vasily@adblockplus.org',
+    url='https://hg.adblockplus.org/python-abp/',
+    packages=['abp', 'abp.filters'],
+    cmdclass={
+        'devenv': make_command(devenv),

[Sebastian Noack, 2016/03/15 12:18:07]

As I said before, most of the commands you added in here seem superfluous to me,
e.g. running "python setup.py testall" cetrtainly isn't any more convenient than
simply running "tox". 

And in particular the "devclean" command requires quite some complexity and
hard-coded information, while somebody could simply run |hg clean --all| or |git
clean -x| instead.

While the logic for most other commands isn't even specific to this project. So
do you copy that boilerplate into every single Python project? That kind of
cargo cult programming is something we generally don't do.

IMO, the "devenv" command would be the only one that might be justified.

[Vasily Kuznetsov, 2016/03/15 13:14:35]

Pretty much none of the commands are really specific to this project. The idea
is that anybody who hacks on this code can run the build, tests, coverage
reports etc. the same way and get hopefully the same results. I don't think
there's any cargo cult in this.

I would probably agree that things like diffpep8 and htmlcov are going a bit too
far, but things like syntaxcheck and testcov are generally useful, and they in a
way define a coding standard for the project.

About devclean -- you're right.

So how about I remove diffpep8, htmlcov and devclean and keep the rest?

[Sebastian Noack, 2016/03/15 16:33:01]

IMO, the tox script should run py.test --cov anyway. And if you want to use
flake8, it should probably be called from tox as well. So people working on that
code would only have to run tox.

That's not only even more convenient than those custom commands, but also makes
sure that people run the whole suite on all supported Python versions.

+        'devclean': make_command(devclean),
+        'diffpep8': make_command(diffpep8),
+        'syntaxcheck': make_command(syntaxcheck),
+        'test': make_command(test),
+        'testall': make_command(testall),
+        'testcov': make_command(testcov),
+        'htmlcov': make_command(htmlcov)
+    },
+    include_package_data=True,
+    license='GPLv3',
+    zip_safe=False,
+    keywords='filterlist adblockplus ABP',
+    classifiers=[
+        'Development Status :: 2 - Pre-Alpha',
+        'Intended Audience :: Developers',
+        'License :: OSI Approved :: GNU General Public License v3 (GPLv3)',
+        'Natural Language :: English',
+        'Programming Language :: Python :: 2',
+        'Programming Language :: Python :: 2.7',
+        'Programming Language :: Python :: 3',
+        'Programming Language :: Python :: 3.3',

[Sebastian Noack, 2016/03/15 12:18:07]

If you list Python 3.3 and 3.4 you might want to also list them in tox.ini

[Vasily Kuznetsov, 2016/03/15 13:14:35]

Good point. I'd actually rather remove them from here. I don't think there's a
good reason to use Python 3.3 or 3.4 at this moment. What do you think?

[Sebastian Noack, 2016/03/15 16:33:00]

So far we didn't care about supporting outdated Python versions, since we have
Python 2.7 anyway wherever we run our code, and testing additional versions
would have been a hassle. However, in the case here, on the other hand, with
py.test and tox, testing a set of Python versions wouldn't be a big deal. And
since we have to support Python 2 and 3, we cannot use any new features added
after Python 3.3 without a fallback, anyway. But then again, if there is nobody
using that code on Python 3.3 or 3.4 it doesn't really matter. I leave it up to
you.

+        'Programming Language :: Python :: 3.4',
+        'Programming Language :: Python :: 3.5',
+    ]
+)