| OLD | NEW |
| 1 # python-abp | 1 # python-abp |
| 2 | 2 |
| 3 This repository contains a library for working with Adblock Plus filter lists | 3 This repository contains a library for working with Adblock Plus filter lists |
| 4 and the script that is used for building Adblock Plus filter lists from the | 4 and the script that is used for building Adblock Plus filter lists from the |
| 5 form in which they are authored into the format suitable for consumption by the | 5 form in which they are authored into the format suitable for consumption by the |
| 6 adblocking software. | 6 adblocking software. |
| 7 | 7 |
| 8 ## Installation | 8 ## Installation |
| 9 | 9 |
| 10 Prerequisites: | 10 Prerequisites: |
| (...skipping 10 matching lines...) Expand all Loading... |
| 21 | 21 |
| 22 The filter lists are originally authored in relatively smaller parts focused | 22 The filter lists are originally authored in relatively smaller parts focused |
| 23 on a particular type of filters, related to a specific topic or relevant | 23 on a particular type of filters, related to a specific topic or relevant |
| 24 for particular geographical area. | 24 for particular geographical area. |
| 25 We call these parts _filter list fragments_ (or just _fragments_) | 25 We call these parts _filter list fragments_ (or just _fragments_) |
| 26 to distinguish them from full filter lists that are | 26 to distinguish them from full filter lists that are |
| 27 consumed by the adblocking software such as Adblock Plus. | 27 consumed by the adblocking software such as Adblock Plus. |
| 28 | 28 |
| 29 Rendering is a process that combines filter list fragments into a filter list. | 29 Rendering is a process that combines filter list fragments into a filter list. |
| 30 It starts with one fragment that can include other ones and so forth. | 30 It starts with one fragment that can include other ones and so forth. |
| 31 The produced filter list is marked with a version, a timestamp and | 31 The produced filter list is marked with a [version and a timestamp][1]. |
| 32 a [checksum][1]. | |
| 33 | 32 |
| 34 Python-abp contains a script that can do this called `flrender`: | 33 Python-abp contains a script that can do this called `flrender`: |
| 35 | 34 |
| 36 $ flrender fragment.txt filterlist.txt | 35 $ flrender fragment.txt filterlist.txt |
| 37 | 36 |
| 38 This will take the top level fragment in `fragment.txt`, render it and save into | 37 This will take the top level fragment in `fragment.txt`, render it and save into |
| 39 `filterlist.txt`. | 38 `filterlist.txt`. |
| 40 | 39 |
| 41 The `flrender` script can also be used by only specifying `fragment.txt`: | 40 The `flrender` script can also be used by only specifying `fragment.txt`: |
| 42 | 41 |
| (...skipping 79 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 122 lines of a filter list: `parse_line`. It returns a parsed line object just like | 121 lines of a filter list: `parse_line`. It returns a parsed line object just like |
| 123 the items in the iterator returned by `parse_filterlist`. | 122 the items in the iterator returned by `parse_filterlist`. |
| 124 | 123 |
| 125 For further information on the library API use `help()` on `abp.filters` and | 124 For further information on the library API use `help()` on `abp.filters` and |
| 126 its contents in interactive Python session, read the docstrings or look at the | 125 its contents in interactive Python session, read the docstrings or look at the |
| 127 tests for some usage examples. | 126 tests for some usage examples. |
| 128 | 127 |
| 129 ## Testing | 128 ## Testing |
| 130 | 129 |
| 131 Unit tests for `python-abp` are located in the `/tests` directory. | 130 Unit tests for `python-abp` are located in the `/tests` directory. |
| 132 [Pytest][3] is used for quickly running the tests | 131 [Pytest][2] is used for quickly running the tests |
| 133 during development. | 132 during development. |
| 134 [Tox][4] is used for testing in different | 133 [Tox][3] is used for testing in different |
| 135 environments (Python 2.7, Python 3.5+ and PyPy) and code quality | 134 environments (Python 2.7, Python 3.5+ and PyPy) and code quality |
| 136 reporting. | 135 reporting. |
| 137 | 136 |
| 138 In order to execute the tests, first create and activate development | 137 In order to execute the tests, first create and activate development |
| 139 virtualenv: | 138 virtualenv: |
| 140 | 139 |
| 141 $ python setup.py devenv | 140 $ python setup.py devenv |
| 142 $ . devenv/bin/activate | 141 $ . devenv/bin/activate |
| 143 | 142 |
| 144 With the development virtualenv activated use pytest for a quick test run: | 143 With the development virtualenv activated use pytest for a quick test run: |
| 145 | 144 |
| 146 (devenv) $ pytest tests | 145 (devenv) $ pytest tests |
| 147 | 146 |
| 148 and tox for a comprehensive report: | 147 and tox for a comprehensive report: |
| 149 | 148 |
| 150 (devenv) $ tox | 149 (devenv) $ tox |
| 151 | 150 |
| 152 ## Development | 151 ## Development |
| 153 | 152 |
| 154 When adding new functionality, add tests for it (preferably first). Code | 153 When adding new functionality, add tests for it (preferably first). Code |
| 155 coverage (as measured by `tox -e qa`) should not decrease and the tests | 154 coverage (as measured by `tox -e qa`) should not decrease and the tests |
| 156 should pass in all Tox environments. | 155 should pass in all Tox environments. |
| 157 | 156 |
| 158 All public functions, classes and methods should have docstrings compliant with | 157 All public functions, classes and methods should have docstrings compliant with |
| 159 [NumPy/SciPy documentation guide][5]. One exception is the constructors of | 158 [NumPy/SciPy documentation guide][4]. One exception is the constructors of |
| 160 classes that the user is not expected to instantiate (such as exceptions). | 159 classes that the user is not expected to instantiate (such as exceptions). |
| 161 | 160 |
| 162 [1]: https://adblockplus.org/filters#special-comments | 161 [1]: https://adblockplus.org/filters#special-comments |
| 163 [2]: https://adblockplus.org/filters#options | 162 [2]: http://pytest.org/ |
| 164 [3]: http://pytest.org/ | 163 [3]: https://tox.readthedocs.org/ |
| 165 [4]: https://tox.readthedocs.org/ | 164 [4]: https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt |
| 166 [5]: https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt | |
| OLD | NEW |