From 73f5c9cf31f4a8ae1611077a4a77f18c71d874d4 Mon Sep 17 00:00:00 2001 From: Petr Muller Date: Fri, 20 Jul 2018 16:10:20 +0200 Subject: [PATCH] Update the README.md --- README.md | 94 ++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 58 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index 74f26d5..e53516c 100644 --- a/README.md +++ b/README.md @@ -1,62 +1,84 @@ # pyff: Python Diff -The purpose of Python Diff (`pyff`) is to compare two versions of a Python module -and detect syntactical and semantical differences between them. Currently `pyff` -is a very early-stage, experimental toy project, so please do not expect miracles. +Python Diff compares two versions of Python code (modules, packages, +directories containing Python modules and/or packages) and detects syntactical +and semantical differences between them. [![Build Status](https://travis-ci.org/petr-muller/pyff.svg?branch=master)](https://travis-ci.org/petr-muller/pyff) [![Maintainability](https://api.codeclimate.com/v1/badges/bb1aa4b86fed8097aa0f/maintainability)](https://codeclimate.com/github/petr-muller/pyff/maintainability) [![Codacy Badge](https://api.codacy.com/project/badge/Grade/b970a7c6c6314ab3b28bddaeab523457)](https://www.codacy.com/app/afri/pyff?utm_source=github.com&utm_medium=referral&utm_content=petr-muller/pyff&utm_campaign=Badge_Grade) [![Coverage Status](https://coveralls.io/repos/github/petr-muller/pyff/badge.svg?branch=master)](https://coveralls.io/github/petr-muller/pyff?branch=master) +## Installation + +You can install pyff from [Python Package Index](https://pypi.org/) as +`pythodiff` (unfortunately, a name `pyff` was taken already): + +``` +$ pip install pythondiff +``` + ## Usage -You can install `pyff`, preferably to a virtual environment, using the `setup.py` -file. +You can run `pyff` to compare two Python modules: ``` -$ python -m venv venv -$ . venv/bin/activate -$ pip install -r requirements.txt -$ python setup.py install -(...) +$ pyff old.py new.py ``` -This installs the `pyff` executable that accepts two Python files as positional -arguments: +For comparing Python packages, there is the `pyff-package` executable: ``` -$ pyff tests/examples/01-run.old tests/examples/01-run.new -Added import of new names ArgumentParser, Action from new package argparse -New class ParsePlayerAction with 0 public methods -Function main changed implementation, newly uses external names ArgumentParser +$ pyff-package old_package new_package ``` -Programmatical interface in the form of `pyff.api` or something similar is on -the roadmap. +You can also compare directories using the `pyff-dir` executable. In this case, +`pyff` finds all Python content in both directories (recurively) and compares +everything it finds: + +``` +$ pyff-dir old_directory new_directory +``` + +Finally, `pyff-git` can compare Python content between two revisions in a given +Git repository: + +``` +$ pyff-git https://github.com/petr-muller/pyff.git master^ master +``` ## Development -Currently, `pyff` is quite trivial, but one of my goals while working on it was -to try use various Python development support tools, sometimes quite -excessively: [pytest](https://pytest.org) is used for testing (along with few -plugins) and [Pylint](https://www.pylint.org/) for static analysis. The code of -`pyff` is annotated with Python type hints and [mypy](http://mypy-lang.org/) is -used to check them. There are shell helpers in `helpers/helpers.sh` that make -executing all checks easier: +The development of `pyff` is far from complete: most of the basic features (code +elements being removed, changed or added) are there but not all of them. Some +Python code can also confuse `pyff` or even make it crash. PRs or issue reports +are happily accepted. + +`pyff` is written using a modern (3.5+) Python version and has both unit and +integration tests. The unit test coverage goal is 100% but it is OK to not cover +some elementary (or really hard to unit-test) code, provided the code is marked +with a `# pragma: no cover` comment. [pytest](https://pytest.org) is used as a +unit test driver. All code is statically checked with +[Pylint](https://www.pylint.org/) and also annotated with Python type hints. The +[mypy](http://mypy-lang.org/) checker is used to check them. You can install all +necessary test requirements using pip: ``` $ pip install -r requirements-tests.txt +``` + +There are shell helpers in `helpers/helpers.sh` that make +executing all checks easier: + +``` $ . helpers/helpers.sh -$ ft # Fast Test: run all tests without coverage, pylint and mypy check -$ st # Slow Test: run all tests with coverage, pylint and mypy +$ ft # Fast Test: run just unit tests, without pylint and mypy checks +$ st # Slow Test: run all (unit and integration) tests, pylint and mypy ``` -## Future +The integration tests are executed using an excellent +[clitest](https://github.com/aureliojargas/clitest) tool. -Currently, the high-level roadmap looks somewhat like this: +## Future -1. Finish the `pyff` command and provide basic set of smart comparisons. -2. Provide programmatical API (allow `import pyff.api`) providing - machine-readable difference artifact. -3. Build a Git-aware comparison tools that will be able to compare Git revisions - (instead of single files) -4. Build a PR-commenting GitHub bot that should provide human readable, natural - language "summaries" to submitted Python project PRs. +`pyff` is a pre-1.0.0 version: basically a toy project of mine. A brief list of +TODOs for me to consider doing a 1.0.0 version is in [#19](#19). My idea is to +bring `pyff` to a small GitHub PR-commenting bot that would comment PRs to +Python repositories with a nice, human-readable summary of changes.