fix readme, add lint params

14 files changed, 171 insertions, 89 deletions

diff --git a/.gitattributes b/.gitattributes
index 86c9df4..966b570 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -1 +1 @@
-virtualenv_embedded/*.bat text eol=crlf
\ No newline at end of file
+virtualenv_embedded/*.bat text eol=crlf
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
new file mode 100644
index 0000000..ff6b256
--- /dev/null
+++ b/.pre-commit-config.yaml
@@ -0,0 +1,40 @@
+repos:
+-   repo: https://github.com/ambv/black
+    rev: 18.9b0
+    hooks:
+    -   id: black
+        args: [--safe]
+        language_version: python3.7
+-   repo: https://github.com/asottile/blacken-docs
+    rev: v0.3.0
+    hooks:
+    -   id: blacken-docs
+        additional_dependencies: [black==18.9b0]
+        language_version: python3.7
+-   repo: https://github.com/asottile/seed-isort-config
+    rev: v1.2.0
+    hooks:
+    -   id: seed-isort-config
+        args: [--application-directories, "src:."]
+-   repo: https://github.com/pre-commit/mirrors-isort
+    rev: v4.3.4
+    hooks:
+    -   id: isort
+-   repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v2.0.0
+    hooks:
+    -   id: trailing-whitespace
+    -   id: end-of-file-fixer
+    -   id: check-yaml
+    -   id: debug-statements
+    -   id: flake8
+        additional_dependencies: ["flake8-bugbear == 18.2.0"]
+        language_version: python3.7
+-   repo: https://github.com/asottile/pyupgrade
+    rev: v1.9.1
+    hooks:
+    -   id: pyupgrade
+-   repo: https://github.com/pre-commit/pygrep-hooks
+    rev: v1.1.0
+    hooks:
+    -   id: rst-backticks
diff --git a/AUTHORS.txt b/AUTHORS.txt
index 2724941..aa077b2 100644
--- a/AUTHORS.txt
+++ b/AUTHORS.txt
@@ -88,4 +88,4 @@ Thomas Aglassinger
 Vinay Sajip
 Vitaly Babiy
 Vladimir Rutsky
-Wang Xuerui
\ No newline at end of file
+Wang Xuerui
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index a45bc4e..b0815ca 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -10,7 +10,7 @@ Contributor notes
   Use Python 3 print-function syntax, and always ``use sys.exc_info()[1]``
   inside the ``except`` block to get at exception objects.
 
-* Pull requests should be made against `master` branch, which is also our
+* Pull requests should be made against ``master`` branch, which is also our
   latest stable version.
 
 * All changes to files inside virtualenv_embedded should be integrated to
diff --git a/README.rst b/README.rst
index 6be1ddc..19cd47b 100644
--- a/README.rst
+++ b/README.rst
@@ -3,11 +3,24 @@ virtualenv
 
 A tool for creating isolated 'virtual' python environments.
 
+.. image:: https://badge.fury.io/py/virtualenv.svg
+  :target: https://badge.fury.io/py/virtualenv
+  :alt: Latest version on PyPi
+.. image:: https://img.shields.io/pypi/pyversions/virtualenv.svg
+  :target: https://pypi.org/project/virtualenv/
+  :alt: Supported Python versions
+.. image:: https://dev.azure.com/pypa/virtualenv/_apis/build/status/pypa.virtualenv
+  :target: https://dev.azure.com/pypa/virtualenv/_apis/build/status/pypa.virtualenv?branchName=master
+  :alt: Azure Pipelines build status
+.. image:: https://readthedocs.org/projects/virtualenv/badge/?version=latest&style=flat-square
+  :target: https://virtualenv.readthedocs.io/en/latest/?badge=latest
+  :alt: Documentation status
+.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
+  :target: https://github.com/ambv/black
+  :alt: Code style: black
 .. image:: https://img.shields.io/pypi/v/virtualenv.svg
-        :target: https://pypi.org/project/virtualenv
+   :target: https://pypi.org/project/virtualenv
 
-.. image:: https://img.shields.io/travis/pypa/virtualenv/develop.svg
-   :target: http://travis-ci.org/pypa/virtualenv
 
 * `Installation <https://virtualenv.pypa.io/en/latest/installation.html>`_
 * `Documentation <https://virtualenv.pypa.io/>`_
diff --git a/azure-pipelines.yml b/azure-pipelines.yml
index 36db607..07deb07 100644
--- a/azure-pipelines.yml
+++ b/azure-pipelines.yml
@@ -21,6 +21,8 @@ trigger:
 
 jobs:
 - template: azure-run-tox-env.yml
+  parameters: {tox: fix_lint, python: 3.7}
+- template: azure-run-tox-env.yml
   parameters: {tox: embed, python: 3.7}
 - template: azure-run-tox-env.yml
   parameters: {tox: docs, python: 3.7}
@@ -117,4 +119,4 @@ jobs:
       codeCoverageTool: 'cobertura'
       summaryFileLocation: '$(System.DefaultWorkingDirectory)/.tox/coverage.xml'
       reportDirectory: '$(System.DefaultWorkingDirectory)/.tox/htmlcov'
-      failIfCoverageEmpty: true
\ No newline at end of file
+      failIfCoverageEmpty: true
diff --git a/bin/rebuild-script.py b/bin/rebuild-script.py
index 7066bb6..5361210 100755
--- a/bin/rebuild-script.py
+++ b/bin/rebuild-script.py
@@ -4,80 +4,77 @@ Helper script to rebuild virtualenv.py from virtualenv_support
 """
 from __future__ import print_function
 
+import codecs
 import os
 import re
-import codecs
 from zlib import crc32 as _crc32
 
 
 def crc32(data):
     """Python version idempotent"""
-    return _crc32(data) & 0xffffffff
+    return _crc32(data) & 0xFFFFFFFF
 
 
 here = os.path.dirname(__file__)
-script = os.path.join(here, '..', 'src', 'virtualenv.py')
+script = os.path.join(here, "..", "src", "virtualenv.py")
 
-gzip = codecs.lookup('zlib')
-b64 = codecs.lookup('base64')
+gzip = codecs.lookup("zlib")
+b64 = codecs.lookup("base64")
 
-file_regex = re.compile(
-    br'##file (.*?)\n([a-zA-Z][a-zA-Z0-9_]+)\s*=\s*convert\("""\n(.*?)"""\)',
-    re.S)
-file_template = b'##file %(filename)s\n%(varname)s = convert("""\n%(data)s""")'
+file_regex = re.compile(br'# file (.*?)\n([a-zA-Z][a-zA-Z0-9_]+) = convert\(\n    """\n(.*?)"""\n\)', re.S)
+file_template = b'# file %(filename)s\n%(variable)s = convert(\n    """\n%(data)s"""\n)'
 
 
 def rebuild(script_path):
     exit_code = 0
-    with open(script_path, 'rb') as f:
+    with open(script_path, "rb") as f:
         script_content = f.read()
     parts = []
     last_pos = 0
     match = None
-    for match in file_regex.finditer(script_content):
-        parts += [script_content[last_pos:match.start()]]
+    _count = 0
+    for _count, match in enumerate(file_regex.finditer(script_content)):
+        parts += [script_content[last_pos : match.start()]]
         last_pos = match.end()
         filename, fn_decoded = match.group(1), match.group(1).decode()
-        varname = match.group(2)
+        variable = match.group(2)
         data = match.group(3)
 
-        print('Found file %s' % fn_decoded)
-        pathname = os.path.join(here, '..', 'virtualenv_embedded', fn_decoded)
+        print("Found file %s" % fn_decoded)
+        pathname = os.path.join(here, "..", "virtualenv_embedded", fn_decoded)
 
-        with open(pathname, 'rb') as f:
+        with open(pathname, "rb") as f:
             embedded = f.read()
         new_crc = crc32(embedded)
         new_data = b64.encode(gzip.encode(embedded)[0])[0]
 
         if new_data == data:
-            print('  File up to date (crc: %08x)' % new_crc)
+            print("  File up to date (crc: %08x)" % new_crc)
             parts += [match.group(0)]
             continue
         exit_code = 1
         # Else: content has changed
         crc = crc32(gzip.decode(b64.decode(data)[0])[0])
-        print('  Content changed (crc: %08x -> %08x)' %
-              (crc, new_crc))
-        new_match = file_template % {
-            b'filename': filename,
-            b'varname': varname,
-            b'data': new_data
-        }
+        print("  Content changed (crc: {:08x} -> {:08x})".format(crc, new_crc))
+        new_match = file_template % {b"filename": filename, b"variable": variable, b"data": new_data}
         parts += [new_match]
 
     parts += [script_content[last_pos:]]
-    new_content = b''.join(parts)
+    new_content = b"".join(parts)
 
     if new_content != script_content:
-        print('Content updated; overwriting... ', end='')
-        with open(script_path, 'wb') as f:
+        print("Content updated; overwriting... ", end="")
+        with open(script_path, "wb") as f:
             f.write(new_content)
-        print('done.')
+        print("done.")
     else:
-        print('No changes in content')
+        print("No changes in content")
     if match is None:
-        print('No variables were matched/found')
+        print("No variables were matched/found")
+    if not _count:
+        exit_code = 1
     raise SystemExit(exit_code)
 
-if __name__ == '__main__':
+
+if __name__ == "__main__":
     rebuild(script)
diff --git a/docs/changes.rst b/docs/changes.rst
index 5b5bb4e..6b0bc00 100644
--- a/docs/changes.rst
+++ b/docs/changes.rst
@@ -75,7 +75,7 @@ Release History
 15.0.0 (2016-03-05)
 -------------------
 
-* Remove the `virtualenv-N.N` script from the package; this can no longer be
+* Remove the ``virtualenv-N.N`` script from the package; this can no longer be
   correctly created from a wheel installation.
   Resolves :issue:`851`, :issue:`692`
 
@@ -124,7 +124,7 @@ Release History
 
 * Upgrade setuptools to 19.6
 
-* Supress any errors from `unset` on different shells (:pull:`843`)
+* Suppress any errors from ``unset`` on different shells (:pull:`843`)
 
 * Normalize letter case for prefix path checking. Fixes :issue:`837`
 
@@ -485,7 +485,7 @@ Release History
 1.8.1 (2012-09-03)
 ------------------
 
-* Fixed distribute version used with `--never-download`. Thanks michr for
+* Fixed distribute version used with ``--never-download``. Thanks michr for
   report and patch.
 
 * Fix creating Python 3.3 based virtualenvs by unsetting the
@@ -498,7 +498,7 @@ Release History
 * **Dropped support for Python 2.4** The minimum supported Python version is
   now Python 2.5.
 
-* Fix `--relocatable` on systems that use lib64. Fixes #78. Thanks Branden
+* Fix ``--relocatable`` on systems that use lib64. Fixes #78. Thanks Branden
   Rolston.
 
 * Symlink some additional modules under Python 3. Fixes #194. Thanks Vinay
@@ -556,7 +556,7 @@ Release History
 1.7.1.2 (2012-02-17)
 --------------------
 
-* Fixed minor issue in `--relocatable`. Thanks, Cap Petschulat.
+* Fixed minor issue in ``--relocatable``. Thanks, Cap Petschulat.
 
 
 1.7.1.1 (2012-02-16)
@@ -572,7 +572,7 @@ Release History
 
 * Update embedded pip to version 1.1.
 
-* Fix `--relocatable` under Python 3. Thanks Doug Hellmann.
+* Fix ``--relocatable`` under Python 3. Thanks Doug Hellmann.
 
 * Added environ PATH modification to activate_this.py. Thanks Doug
   Napoleone. Fixes #14.
@@ -592,8 +592,8 @@ Release History
   Napoleone for testing and confirmation. Fixes #87.
 
 * Fixed creation of virtualenvs using -p in installs where some modules
-  that ought to be in the standard library (e.g. `readline`) are actually
-  installed in `site-packages` next to `virtualenv.py`. Thanks Greg Haskins
+  that ought to be in the standard library (e.g. ``readline``) are actually
+  installed in ``site-packages`` next to ``virtualenv.py``. Thanks Greg Haskins
   for report and fix. Fixes #167.
 
 * Added activation script for Powershell (signed by Jannis Leidel). Many
diff --git a/docs/conf.py b/docs/conf.py
index 9332aa1..36cf58a 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -14,7 +14,7 @@
 import os
 import sys
 
-on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
+on_rtd = os.environ.get("READTHEDOCS", None) == "True"
 
 # If your extensions are in another directory, add it here.
 sys.path.insert(0, os.path.abspath(os.pardir))
@@ -24,58 +24,59 @@ sys.path.insert(0, os.path.abspath(os.pardir))
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.extlinks']
+extensions = ["sphinx.ext.autodoc", "sphinx.ext.extlinks"]
 
 # Add any paths that contain templates here, relative to this directory.
-#templates_path = ['_templates']
+# templates_path = ['_templates']
 
 # The suffix of source filenames.
-source_suffix = '.rst'
+source_suffix = ".rst"
 
 # The master toctree document.
-master_doc = 'index'
+master_doc = "index"
 
 # General substitutions.
-project = 'virtualenv'
-copyright = '2007-2014, Ian Bicking, The Open Planning Project, PyPA'
+project = "virtualenv"
+copyright = "2007-2014, Ian Bicking, The Open Planning Project, PyPA"
 
 # The default replacements for |version| and |release|, also used in various
 # other places throughout the built documents.
 try:
     from virtualenv import __version__
+
     # The short X.Y version.
-    version = '.'.join(__version__.split('.')[:2])
+    version = ".".join(__version__.split(".")[:2])
     # The full version, including alpha/beta/rc tags.
     release = __version__
 except ImportError:
-    version = release = 'dev'
+    version = release = "dev"
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
-#today = ''
+# today = ''
 # Else, today_fmt is used as the format for a strftime call.
-today_fmt = '%B %d, %Y'
+today_fmt = "%B %d, %Y"
 
 # List of documents that shouldn't be included in the build.
 unused_docs = []
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
-#add_function_parentheses = True
+# add_function_parentheses = True
 
 # If true, the current module name will be prepended to all description
 # unit titles (such as .. function::).
-#add_module_names = True
+# add_module_names = True
 
 # If true, sectionauthor and moduleauthor directives will be shown in the
 # output. They are ignored by default.
-#show_authors = False
+# show_authors = False
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
+pygments_style = "sphinx"
 
 extlinks = {
-    'issue': ('https://github.com/pypa/virtualenv/issues/%s', '#'),
-    'pull': ('https://github.com/pypa/virtualenv/pull/%s', 'PR #'),
+    "issue": ("https://github.com/pypa/virtualenv/issues/%s", "#"),
+    "pull": ("https://github.com/pypa/virtualenv/pull/%s", "PR #"),
 }
 
 
@@ -85,13 +86,14 @@ extlinks = {
 # The style sheet to use for HTML and HTML Help pages. A file of that name
 # must exist either in Sphinx' static/ path, or in one of the custom paths
 # given in html_static_path.
-#html_style = 'default.css'
+# html_style = 'default.css'
 
-html_theme = 'default'
+html_theme = "default"
 if not on_rtd:
     try:
         import sphinx_rtd_theme
-        html_theme = 'sphinx_rtd_theme'
+
+        html_theme = "sphinx_rtd_theme"
         html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
     except ImportError:
         pass
@@ -104,50 +106,50 @@ if not on_rtd:
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
-html_last_updated_fmt = '%b %d, %Y'
+html_last_updated_fmt = "%b %d, %Y"
 
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.
-#html_use_smartypants = True
+# html_use_smartypants = True
 
 # Content template for the index page.
-#html_index = ''
+# html_index = ''
 
 # Custom sidebar templates, maps document names to template names.
-#html_sidebars = {}
+# html_sidebars = {}
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.
-#html_additional_pages = {}
+# html_additional_pages = {}
 
 # If false, no module index is generated.
-#html_use_modindex = True
+# html_use_modindex = True
 
 # If true, the reST sources are included in the HTML build as _sources/<name>.
-#html_copy_source = True
+# html_copy_source = True
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'Pastedoc'
+htmlhelp_basename = "Pastedoc"
 
 
 # Options for LaTeX output
 # ------------------------
 
 # The paper size ('letter' or 'a4').
-#latex_paper_size = 'letter'
+# latex_paper_size = 'letter'
 
 # The font size ('10pt', '11pt' or '12pt').
-#latex_font_size = '10pt'
+# latex_font_size = '10pt'
 
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, document class [howto/manual]).
-#latex_documents = []
+# latex_documents = []
 
 # Additional stuff for the LaTeX preamble.
-#latex_preamble = ''
+# latex_preamble = ''
 
 # Documents to append as an appendix to all manuals.
-#latex_appendices = []
+# latex_appendices = []
 
 # If false, no module index is generated.
-#latex_use_modindex = True
+# latex_use_modindex = True
diff --git a/docs/development.rst b/docs/development.rst
index d60f5a8..ea216ea 100644
--- a/docs/development.rst
+++ b/docs/development.rst
@@ -12,11 +12,11 @@ Virtualenv's release schedule is tied to pip's -- each time there's a new pip
 release, there will be a new virtualenv release that bundles the new version of
 pip.
 
-Files in the `virtualenv_embedded/` subdirectory are embedded into
-`virtualenv.py` itself as base64-encoded strings (in order to support
-single-file use of `virtualenv.py` without installing it). If your patch
-changes any file in `virtualenv_embedded/`, run `bin/rebuild-script.py` to
-update the embedded version of that file in `virtualenv.py`; commit that and
+Files in the ``virtualenv_embedded/`` subdirectory are embedded into
+``virtualenv.py`` itself as base64-encoded strings (in order to support
+single-file use of ``virtualenv.py`` without installing it). If your patch
+changes any file in ``virtualenv_embedded/``, run ``bin/rebuild-script.py`` to
+update the embedded version of that file in ``virtualenv.py``; commit that and
 submit it as part of your patch / pull request.
 
 .. _pip development: https://pip.pypa.io/en/latest/development/
diff --git a/docs/installation.rst b/docs/installation.rst
index a99ff5a..7e6a97d 100644
--- a/docs/installation.rst
+++ b/docs/installation.rst
@@ -17,7 +17,7 @@ Installation
     setuptools < 0.9.7, because easy_install didn't download from PyPI over SSL
     and was broken in some subtle ways.
 
-To install globally with `pip` (if you have pip 1.3 or greater installed globally):
+To install globally with ``pip`` (if you have pip 1.3 or greater installed globally):
 
 ::
 
diff --git a/docs/userguide.rst b/docs/userguide.rst
index dc594d3..ca761d2 100644
--- a/docs/userguide.rst
+++ b/docs/userguide.rst
@@ -65,7 +65,7 @@ To undo these changes to your path (and prompt), just run::
 
     $ deactivate
 
-On Windows, the equivalent `activate` script is in the ``Scripts`` folder::
+On Windows, the equivalent ``activate`` script is in the ``Scripts`` folder::
 
     > \path\to\env\Scripts\activate
 
@@ -255,4 +255,3 @@ As well as the extra directories, the search order includes:
 #. The ``virtualenv_support`` directory relative to virtualenv.py
 #. The directory where virtualenv.py is located.
 #. The current directory.
-
diff --git a/pyproject.toml b/pyproject.toml
index c70af8c..211cf02 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,3 +4,6 @@ requires = [
     "wheel >= 0.29.0",
 ]
 build-backend = 'setuptools.build_meta'
+
+[tool.black]
+line-length = 120
diff --git a/tox.ini b/tox.ini
index a7d92d9..e01a404 100644
--- a/tox.ini
+++ b/tox.ini
@@ -1,6 +1,6 @@
 [tox]
 minversion = 3.3.0
-envlist = embed, py{27,34,35,36,37}, pypy{,3}, cross_python{2,3}, docs, package_readme
+envlist = fix_lint, embed, py{27,34,35,36,37}, pypy{,3}, cross_python{2,3}, docs, package_readme
 isolated_build = true
 skip_missing_interpreters = true
 
@@ -91,3 +91,29 @@ skip_install = true
 deps =
 commands = python {toxinidir}/bin/rebuild-script.py
 
+[testenv:fix_lint]
+description = format the code base to adhere to our styles, and complain about what we cannot do automatically
+basepython = python3.7
+passenv = HOMEPATH
+          PROGRAMDATA
+deps = pre-commit == 1.12.0
+skip_install = True
+commands = pre-commit run --all-files --show-diff-on-failure
+           python -c 'import pathlib; print("hint: run \{\} install to add checks as pre-commit hook".format(pathlib.Path(r"{envdir}") / "bin" / "pre-commit"))'
+
+[isort]
+multi_line_output = 3
+include_trailing_comma = True
+force_grid_wrap = 0
+line_length = 120
+known_first_party = tox,tests
+known_third_party = __builtin__,_winreg,mock,pytest,sets,setuptools,sitecustomize,sphinx_rtd_theme,urlparse,usercustomize,winreg
+
+[flake8]
+max-complexity = 22
+max-line-length = 120
+ignore = E203, W503, C901, E402
+exclude = virtualenv_embedded/site.py
+
+[pep8]
+max-line-length = 120