Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
f983eef
commit 73f5c9c
Showing
1 changed file
with
58 additions
and
36 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. |