2016-10-17 17:00:14 +00:00
|
|
|
This directory contains the code for the Python `brotli` module,
|
|
|
|
|
`bro.py` tool, and roundtrip tests.
|
2016-02-23 15:06:31 +00:00
|
|
|
|
2017-08-28 09:31:29 +00:00
|
|
|
Only Python 2.7+ is supported.
|
|
|
|
|
|
2017-08-02 14:59:46 +00:00
|
|
|
We provide a `Makefile` to simplify common development commands.
|
|
|
|
|
|
2016-12-21 09:17:11 +00:00
|
|
|
### Installation
|
2016-02-23 15:06:31 +00:00
|
|
|
|
2017-08-02 14:59:46 +00:00
|
|
|
If you just want to install the latest release of the Python `brotli`
|
|
|
|
|
module, we recommend installing from [PyPI][]:
|
|
|
|
|
|
|
|
|
|
$ pip install brotli
|
|
|
|
|
|
|
|
|
|
Alternatively, you may install directly from source by running the
|
|
|
|
|
following command from this directory:
|
2016-12-21 09:17:11 +00:00
|
|
|
|
2017-08-02 14:59:46 +00:00
|
|
|
$ make install
|
2016-10-17 17:00:14 +00:00
|
|
|
|
2016-12-21 09:17:11 +00:00
|
|
|
### Development
|
2016-10-17 17:00:14 +00:00
|
|
|
|
disable buidling/deployment of python wheels (#583)
* [appveyor] remove 'deploy' stage; only test python 2.7 and 3.6
all the other python versions are being built and tested on
https://github.com/google/brotli-wheels/blob/d571d63/appveyor.yml
* remove terrify submodule as not needed any more
* [travis] just test py2.7 and 3.6 on linux; remove extra osx python builds
All the other python versions for OSX are being built/tested on:
https://github.com/google/brotli-wheels/blob/d571d63/.travis.yml
Also, there's no need to build and deploy wheels here, as that's done
in the separate repository.
* [setup.py] only rebuild if dependency are newer; fix typo in list of 'depends'
https://github.com/python/cpython/blob/v3.6.2/Lib/distutils/command/build_ext.py#L485-L500
* [ci] only run 'python setup.py test'
if we run 'python setup.py built test', the setuptools 'test' command will
forcibly re-run the build_ext subcommand because it wants to pass the --inplace
option (it ignores whether it's up to date, just re-runs it all the time).
with this we go from running built_ext twice, to running it only once per build
* [Makefile] run 'build_ext --inplace' instead of 'develop' as default target
The 'develop' command is like 'install' in the sense that it
modifies the user's python environment.
The default make target should be less intrusive, i.e. just building
the extension module in-place without modify anything in the user's
environment.
We don't need to tell make about the dependency between 'test' and
'build' target as that is baked in the `python setup.py test` command.
* [Makefile] add 'develop' target; remove unnecessary 'tests' target
`make test` is good enough
* [Makefile] `setup.py test` requires setuptools; run `python -m unittest`
This will work even if setuptools is not installed, which is unlikely
nowadays but still our `setup.py` works with plain distutils, so
we may well have our tests work without setuptools.
* [python/README.md] add ref to 'develop' target; remove 'tests', just 'make test'
* [setup.py] import modules as per nicksay's comment
https://github.com/google/brotli/pull/583#discussion_r131981049
* [Makefile] add 'develop' to .PHONY targets
remove 'tests' from .PHONY
* [appveyor] remove unused setup scripts
We don't need to install custom python versions, we are
using the pre-installed ones on Appveyor.
* [appveyor] remove unneeded setup code
2017-08-23 18:45:13 +00:00
|
|
|
You may run the following commands from this directory:
|
2016-10-17 17:00:14 +00:00
|
|
|
|
disable buidling/deployment of python wheels (#583)
* [appveyor] remove 'deploy' stage; only test python 2.7 and 3.6
all the other python versions are being built and tested on
https://github.com/google/brotli-wheels/blob/d571d63/appveyor.yml
* remove terrify submodule as not needed any more
* [travis] just test py2.7 and 3.6 on linux; remove extra osx python builds
All the other python versions for OSX are being built/tested on:
https://github.com/google/brotli-wheels/blob/d571d63/.travis.yml
Also, there's no need to build and deploy wheels here, as that's done
in the separate repository.
* [setup.py] only rebuild if dependency are newer; fix typo in list of 'depends'
https://github.com/python/cpython/blob/v3.6.2/Lib/distutils/command/build_ext.py#L485-L500
* [ci] only run 'python setup.py test'
if we run 'python setup.py built test', the setuptools 'test' command will
forcibly re-run the build_ext subcommand because it wants to pass the --inplace
option (it ignores whether it's up to date, just re-runs it all the time).
with this we go from running built_ext twice, to running it only once per build
* [Makefile] run 'build_ext --inplace' instead of 'develop' as default target
The 'develop' command is like 'install' in the sense that it
modifies the user's python environment.
The default make target should be less intrusive, i.e. just building
the extension module in-place without modify anything in the user's
environment.
We don't need to tell make about the dependency between 'test' and
'build' target as that is baked in the `python setup.py test` command.
* [Makefile] add 'develop' target; remove unnecessary 'tests' target
`make test` is good enough
* [Makefile] `setup.py test` requires setuptools; run `python -m unittest`
This will work even if setuptools is not installed, which is unlikely
nowadays but still our `setup.py` works with plain distutils, so
we may well have our tests work without setuptools.
* [python/README.md] add ref to 'develop' target; remove 'tests', just 'make test'
* [setup.py] import modules as per nicksay's comment
https://github.com/google/brotli/pull/583#discussion_r131981049
* [Makefile] add 'develop' to .PHONY targets
remove 'tests' from .PHONY
* [appveyor] remove unused setup scripts
We don't need to install custom python versions, we are
using the pre-installed ones on Appveyor.
* [appveyor] remove unneeded setup code
2017-08-23 18:45:13 +00:00
|
|
|
$ make # Build the module in-place
|
2016-12-21 09:17:11 +00:00
|
|
|
|
disable buidling/deployment of python wheels (#583)
* [appveyor] remove 'deploy' stage; only test python 2.7 and 3.6
all the other python versions are being built and tested on
https://github.com/google/brotli-wheels/blob/d571d63/appveyor.yml
* remove terrify submodule as not needed any more
* [travis] just test py2.7 and 3.6 on linux; remove extra osx python builds
All the other python versions for OSX are being built/tested on:
https://github.com/google/brotli-wheels/blob/d571d63/.travis.yml
Also, there's no need to build and deploy wheels here, as that's done
in the separate repository.
* [setup.py] only rebuild if dependency are newer; fix typo in list of 'depends'
https://github.com/python/cpython/blob/v3.6.2/Lib/distutils/command/build_ext.py#L485-L500
* [ci] only run 'python setup.py test'
if we run 'python setup.py built test', the setuptools 'test' command will
forcibly re-run the build_ext subcommand because it wants to pass the --inplace
option (it ignores whether it's up to date, just re-runs it all the time).
with this we go from running built_ext twice, to running it only once per build
* [Makefile] run 'build_ext --inplace' instead of 'develop' as default target
The 'develop' command is like 'install' in the sense that it
modifies the user's python environment.
The default make target should be less intrusive, i.e. just building
the extension module in-place without modify anything in the user's
environment.
We don't need to tell make about the dependency between 'test' and
'build' target as that is baked in the `python setup.py test` command.
* [Makefile] add 'develop' target; remove unnecessary 'tests' target
`make test` is good enough
* [Makefile] `setup.py test` requires setuptools; run `python -m unittest`
This will work even if setuptools is not installed, which is unlikely
nowadays but still our `setup.py` works with plain distutils, so
we may well have our tests work without setuptools.
* [python/README.md] add ref to 'develop' target; remove 'tests', just 'make test'
* [setup.py] import modules as per nicksay's comment
https://github.com/google/brotli/pull/583#discussion_r131981049
* [Makefile] add 'develop' to .PHONY targets
remove 'tests' from .PHONY
* [appveyor] remove unused setup scripts
We don't need to install custom python versions, we are
using the pre-installed ones on Appveyor.
* [appveyor] remove unneeded setup code
2017-08-23 18:45:13 +00:00
|
|
|
$ make test # Test the module
|
2016-10-17 17:00:14 +00:00
|
|
|
|
2016-12-21 09:17:11 +00:00
|
|
|
$ make clean # Remove all temporary files and build output
|
2016-10-17 17:00:14 +00:00
|
|
|
|
disable buidling/deployment of python wheels (#583)
* [appveyor] remove 'deploy' stage; only test python 2.7 and 3.6
all the other python versions are being built and tested on
https://github.com/google/brotli-wheels/blob/d571d63/appveyor.yml
* remove terrify submodule as not needed any more
* [travis] just test py2.7 and 3.6 on linux; remove extra osx python builds
All the other python versions for OSX are being built/tested on:
https://github.com/google/brotli-wheels/blob/d571d63/.travis.yml
Also, there's no need to build and deploy wheels here, as that's done
in the separate repository.
* [setup.py] only rebuild if dependency are newer; fix typo in list of 'depends'
https://github.com/python/cpython/blob/v3.6.2/Lib/distutils/command/build_ext.py#L485-L500
* [ci] only run 'python setup.py test'
if we run 'python setup.py built test', the setuptools 'test' command will
forcibly re-run the build_ext subcommand because it wants to pass the --inplace
option (it ignores whether it's up to date, just re-runs it all the time).
with this we go from running built_ext twice, to running it only once per build
* [Makefile] run 'build_ext --inplace' instead of 'develop' as default target
The 'develop' command is like 'install' in the sense that it
modifies the user's python environment.
The default make target should be less intrusive, i.e. just building
the extension module in-place without modify anything in the user's
environment.
We don't need to tell make about the dependency between 'test' and
'build' target as that is baked in the `python setup.py test` command.
* [Makefile] add 'develop' target; remove unnecessary 'tests' target
`make test` is good enough
* [Makefile] `setup.py test` requires setuptools; run `python -m unittest`
This will work even if setuptools is not installed, which is unlikely
nowadays but still our `setup.py` works with plain distutils, so
we may well have our tests work without setuptools.
* [python/README.md] add ref to 'develop' target; remove 'tests', just 'make test'
* [setup.py] import modules as per nicksay's comment
https://github.com/google/brotli/pull/583#discussion_r131981049
* [Makefile] add 'develop' to .PHONY targets
remove 'tests' from .PHONY
* [appveyor] remove unused setup scripts
We don't need to install custom python versions, we are
using the pre-installed ones on Appveyor.
* [appveyor] remove unneeded setup code
2017-08-23 18:45:13 +00:00
|
|
|
If you wish to make the module available while still being
|
|
|
|
|
able to edit the source files, you can use the `setuptools`
|
|
|
|
|
"[development mode][]":
|
|
|
|
|
|
|
|
|
|
$ make develop # Install the module in "development mode"
|
|
|
|
|
|
2016-10-17 17:00:14 +00:00
|
|
|
### Code Style
|
|
|
|
|
|
|
|
|
|
Brotli's code follows the [Google Python Style Guide][]. To
|
2016-12-21 09:17:11 +00:00
|
|
|
automatically format your code, first install [YAPF][]:
|
2016-10-17 17:00:14 +00:00
|
|
|
|
|
|
|
|
$ pip install yapf
|
|
|
|
|
|
2016-12-21 09:17:11 +00:00
|
|
|
Then, to format all files in the project, you can run:
|
2016-10-17 17:00:14 +00:00
|
|
|
|
2016-12-21 09:17:11 +00:00
|
|
|
$ make fix # Automatically format code
|
2016-10-17 17:00:14 +00:00
|
|
|
|
|
|
|
|
See the [YAPF usage][] documentation for more information.
|
|
|
|
|
|
|
|
|
|
|
2017-08-02 14:59:46 +00:00
|
|
|
[PyPI]: https://pypi.org/project/Brotli/
|
2016-12-21 09:17:11 +00:00
|
|
|
[development mode]: https://setuptools.readthedocs.io/en/latest/setuptools.html#development-mode
|
2016-10-17 17:00:14 +00:00
|
|
|
[Google Python Style Guide]: https://google.github.io/styleguide/pyguide.html
|
|
|
|
|
[YAPF]: https://github.com/google/yapf
|
|
|
|
|
[YAPF usage]: https://github.com/google/yapf#usage
|
