All changes since code review on squashed commit

Fixes from CR

Adds multi-argument replace

Documentation improvements

Improves setup for PyPI

Update to pyparsing 2.1.7

Adds two more examples

Author: evhub

.gitignore

@@ -5,8 +5,7 @@
 \#*\#
 .cache
 
-# Develoopment Environment
-virtualenv_run
+# Development Environment
 venv
 
 # Packages
@@ -25,15 +24,14 @@ lib
 lib64
 *.iml
 *.log
-/.venv.touch
-/virtualenv_run
+.venv.touch
 
 # Installer logs
 pip-log.txt
 
 # Unit test / coverage reports
 .coverage
-/coverage-html
+coverage-html
 .tox
 nosetests.xml
 

README.md

@@ -1,11 +1,9 @@
 # Undebt
 
-Undebt is a tool for automatically refactoring massive code bases, like the one we have [@Yelp](https://github.com/Yelp).
+Undebt is a fast, simple, reliable tool for performing massive, automated code refactoring used [@Yelp](https://github.com/Yelp). Undebt lets you define complex find-and-replace rules using simple, straightforward Python that can be applied quickly to an entire code base with a simple command.
 
-Every developer knows that [technical debt](https://en.wikipedia.org/wiki/Technical_debt) is bad. Like financial debt, it incurs interest payments over time in the form of long developer hours fixing the sins of the past. Worse, we write code by learning (and copy-and-pasting) from existing code. Thus, if the existing code is full of debt, the debt will only perpetuate itself.
-
-Nevertheless, technical debt keeps growing. Every developer has felt the drive to create and deliver new code quickly, and because of this we ignore the technical debt created in the process. We tell ourselves that we don't have time to refactor code, and should be focusing on building new things instead. In some sense, that's true—there's only so much time available to write code, and the more spent refactoring old code to get rid of debt, the less spent shipping new features—but that just means we need a solution that's fast.
-
-Undebt is the solution to the problem of technical debt. Undebt is a fast and reliable way to refactor your code. Undebt lets you define complex find-and-replace rules using simple, straightforward Python that can be applied quickly to an entire codebase with a simple command.
-
-To get started using Undebt, head over to our [documentation](http://undebt.readthedocs.io/en/latest/).
+To get started using Undebt, install with
+```
+python -m pip install undebt
+```
+then head over to our **[documentation](http://undebt.readthedocs.io/en/latest/)** for more information.

docs/source/cli.rst

@@ -11,7 +11,7 @@ Install it
 
     $ git clone https://github.com/Yelp/undebt.git
     $ cd undebt
-    $ pip install -e .
+    $ pip install .
 
 Read it
 -------

docs/source/conf.py

@@ -1,34 +1,18 @@
 # -*- coding: utf-8 -*-
-#
-# undebt documentation build configuration file
-#
-# This file is execfile()d with the current directory set to its containing dir.
-#
-# Note that not all possible configuration values are present in this
-# autogenerated file.
-#
-# All configuration values have a default; values that are commented out
-# serve to show the default.
-# 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
-# documentation root, use os.path.abspath to make it absolute, like shown here.
+from __future__ import absolute_import
+from __future__ import division
+from __future__ import print_function
+
 import undebt
 
-# -- General configuration -----------------------------------------------------
 
 # 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', 'sphinxcontrib.programoutput']
 
-# Add any paths that contain templates here, relative to this directory.
-# templates_path = ['_templates']
-
 # The suffix of source filenames.
 source_suffix = '.rst'
 
-# The encoding of source files.
-# source_encoding = 'utf-8'
-
 # The master toctree document.
 master_doc = 'index'
 
@@ -46,143 +30,12 @@
 # release = 'LATEST_RELEASE'
 version = undebt.__version__
 
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-# language = None
-
-# There are two options for replacing |today|: either, you set today to some
-# non-false value, then it is used:
-# today = ''
-# Else, today_fmt is used as the format for a strftime call.
-# today_fmt = '%B %d, %Y'
-
-# List of documents that shouldn't be included in the build.
-# unused_docs = []
-
-# List of directories, relative to source directory, that shouldn't be searched
-# for source files.
-exclude_trees = []
-
-# The reST default role (used for this markup: `text`) to use for all documents.
-# default_role = None
-
-# If true, '()' will be appended to :func: etc. cross-reference text.
-# 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
-
-# If true, sectionauthor and moduleauthor directives will be shown in the
-# output. They are ignored by default.
-# show_authors = False
-
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
-# A list of ignored prefixes for module index sorting.
-# modindex_common_prefix = []
-
-
-# -- Options for HTML output ---------------------------------------------------
-
 # The theme to use for HTML and HTML Help pages.  Major themes that come with
 # Sphinx are currently 'default' and 'sphinxdoc'.
 html_theme = 'alabaster'
 
-# Theme options are theme-specific and customize the look and feel of a theme
-# further.  For a list of options available for each theme, see the
-# documentation.
-# html_theme_options = {}
-
-# Add any paths that contain custom themes here, relative to this directory.
-# html_theme_path = []
-
-# The name for this set of Sphinx documents.  If None, it defaults to
-# "<project> v<release> documentation".
-# html_title = None
-
-# A shorter title for the navigation bar.  Default is the same as html_title.
-# html_short_title = None
-
-# The name of an image file (relative to this directory) to place at the top
-# of the sidebar.
-# html_logo = None
-
-# The name of an image file (within the static path) to use as favicon of the
-# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
-# pixels large.
-# html_favicon = None
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-# html_static_path = ['_static']
-
-# 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'
-
-# If true, SmartyPants will be used to convert quotes and dashes to
-# typographically correct entities.
-# html_use_smartypants = True
-
-# Custom sidebar templates, maps document names to template names.
-# html_sidebars = {}
-
-# Additional templates that should be rendered to pages, maps page names to
-# template names.
-# html_additional_pages = {}
-
-# If false, no module index is generated.
-# html_use_modindex = True
-
-# If false, no index is generated.
-# html_use_index = True
-
-# If true, the index is split into individual pages for each letter.
-# html_split_index = False
-
-# If true, links to the reST sources are added to the pages.
-# html_show_sourcelink = True
-
-# If true, an OpenSearch description file will be output, and all pages will
-# contain a <link> tag referring to it.  The value of this option must be the
-# base URL from which the finished HTML is served.
-# html_use_opensearch = ''
-
-# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
-# html_file_suffix = ''
-
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'undebtdoc'
-
-
-# -- Options for LaTeX output --------------------------------------------------
-
-# The paper size ('letter' or 'a4').
-# latex_paper_size = 'letter'
-
-# The font size ('10pt', '11pt' or '12pt').
-# latex_font_size = '10pt'
-
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title, author, documentclass [howto/manual]).
-# latex_documents = []
-
-# The name of an image file (relative to this directory) to place at the top of
-# the title page.
-# latex_logo = None
-
-# For "manual" documents, if this is true, then toplevel headings are parts,
-# not chapters.
-# latex_use_parts = False
-
-# Additional stuff for the LaTeX preamble.
-# latex_preamble = ''
-
-# Documents to append as an appendix to all manuals.
-# latex_appendices = []
-
-# If false, no module index is generated.
-# latex_use_modindex = True

docs/source/examples.rst

@@ -4,12 +4,15 @@ Undebt_: Examples
 .. _Undebt: index.html
 .. default-role:: code
 
-The `undebt.examples` package contains various example pattern files. These example patterns can either simply be used as they are to make use of the transformation they describe, or used as templates to `build your own pattern files`_.
+The `undebt.examples`_ package contains various example pattern files. These example patterns can either simply be used as they are to make use of the transformation they describe, or used as templates to `build your own pattern files`_.
 
+.. _`undebt.examples`: https://github.com/Yelp/undebt/tree/master/undebt/examples
 .. _`build your own pattern files`: patterns.html
 
 `undebt.examples.nl_at_eof`
 ---------------------------
+(`Source
+<https://github.com/Yelp/undebt/blob/master/undebt/examples/nl_at_eof.py>`_)
 
 A toy example to add a new line (`"\n"`) to the end of files that lack one.
 
@@ -22,6 +25,8 @@ Example of:
 
 `undebt.examples.dbl_quote_docstring`
 -------------------------------------
+(`Source
+<https://github.com/Yelp/undebt/blob/master/undebt/examples/dbl_quote_docstring.py>`_)
 
 Changes all `'''` strings that can be changed to `"""` strings.
 
@@ -32,6 +37,8 @@ Example of:
 
 `undebt.examples.class_inherit_object`
 --------------------------------------
+(`Source
+<https://github.com/Yelp/undebt/blob/master/undebt/examples/class_inherit_object.py>`_)
 
 Changes classes that inherit from nothing to inherit from `object`, which makes sure they behave as Python 3 new-style classes instead of Python 2 old-style classes.
 
@@ -45,6 +52,8 @@ Example of:
 
 `undebt.examples.hex_to_bitshift`
 ---------------------------------
+(`Source
+<https://github.com/Yelp/undebt/blob/master/undebt/examples/hex_to_bitshift.py>`_)
 
 Replaces hex flags with bitshift flags.
 
@@ -56,6 +65,8 @@ Example of:
 
 `undebt.examples.exec_function`
 -------------------------------
+(`Source
+<https://github.com/Yelp/undebt/blob/master/undebt/examples/exec_function.py>`_)
 
 Changes instances of the Python 2 style `exec code in globals, locals` exec statement to the universal Python style `exec(code, globals, locals)` (which will work on Python 2.7 and Python 3).
 
@@ -66,6 +77,8 @@ Example of:
 
 `undebt.examples.attribute_to_function`
 ---------------------------------------
+(`Source
+<https://github.com/Yelp/undebt/blob/master/undebt/examples/attribute_to_function.py>`_)
 
 Transforms uses of `.attribute` into calls to `function`, and adds `from function_lives_here import function` whenever an instance of `function` is added.
 
@@ -79,11 +92,15 @@ Example of:
 
 `undebt.examples.method_to_function`
 ------------------------------------
+(`Source
+<https://github.com/Yelp/undebt/blob/master/undebt/examples/method_to_function.py>`_)
 
 Slightly more complicated version of `attribute_to_function` that finds a method call instead of an attribute access, and makes sure that method call is not on `self`.
 
 `undebt.examples.sqla_count`
 ----------------------------
+(`Source
+<https://github.com/Yelp/undebt/blob/master/undebt/examples/sqla_count.py>`_)
 
 Transforms inefficient SQL alchemy `.count()` queries into more efficient `.scalar()` queries that don't create a sub query.
 
@@ -93,8 +110,22 @@ Example of:
 - grammar element function calling to label tokens in the resulting `tokens_as_dict` dictionary
 - using `leading_whitespace` and `trailing_whitespace` to extract whitespace in a `replace` function
 
+`undebt.examples.remove_unused_import`
+--------------------------------------
+(`Source
+<https://github.com/Yelp/undebt/blob/master/undebt/examples/remove_unused_import.py>`_)
+
+Removes `from function_lives_here import function` if `function` does not appear anywhere else in the file.
+
+Example of:
+
+- using a multi-argument `replace` function
+- using `HEADER` to analyze the header of a Python file
+
 `undebt.examples.contextlib_nested`
 -----------------------------------
+(`Source
+<https://github.com/Yelp/undebt/blob/master/undebt/examples/contextlib_nested.py>`_)
 
 Transforms uses of `contextlib.nested` into multiple clauses in a `with` statement. Respects usage with `as` and without `as`.
 
@@ -103,3 +134,16 @@ Example of:
 - using `tokens_as_dict` to assert multiple possible dictionary keys
 - `EXPR` to match a Python expression
 - `COMMA_IND, LPAREN_IND, IND_RPAREN` to match optional indentation at particular points
+
+`undebt.examples.remove_needless_u_specifier`
+---------------------------------------------
+(`Source
+<https://github.com/Yelp/undebt/blob/master/undebt/examples/remove_needless_u_specifier.py>`_)
+
+In files where `from __future__ import unicode_literals` appears, removes unnecessary `u` before strings.
+
+Example of:
+
+- an advanced style pattern file making use of multi-pass parsing
+- `originalTextFor` to get make a grammar parse to the original text that matched it
+- `STRING` to match any valid string

docs/source/index.rst

@@ -3,7 +3,7 @@ Undebt
 
 .. default-role:: code
 
-This is the documentation for Undebt. For more information, check out our GitHub_.
+This is the documentation for Undebt_. See below for a list of all of the articles hosted here.
 
 .. toctree::
    :maxdepth: 3
@@ -14,4 +14,4 @@ This is the documentation for Undebt. For more information, check out our GitHub
    util
    pyparsing
 
-.. _GitHub: https://github.com/Yelp/undebt
+.. _Undebt: https://github.com/Yelp/undebt