From 2668958ae6039abb6c2ef496f228c6a30c866d04 Mon Sep 17 00:00:00 2001 From: Adriane Boyd Date: Thu, 10 Dec 2020 15:34:34 +0100 Subject: [PATCH] Docs and extras updates for v2.3.5 * Update install instructions for updated packages * Add `cuda110` and `cuda111` extras, remove upper `cupy` pins (only compatible with `thinc>=7.4.4`) --- README.md | 42 ++++++++++--- setup.cfg | 20 +++--- website/docs/usage/index.md | 75 ++++++++++++++++++----- website/src/widgets/quickstart-install.js | 19 +++--- 4 files changed, 112 insertions(+), 44 deletions(-) diff --git a/README.md b/README.md index 0698cc848..6723e9626 100644 --- a/README.md +++ b/README.md @@ -106,12 +106,22 @@ For detailed installation instructions, see the ### pip Using pip, spaCy releases are available as source packages and binary wheels (as -of `v2.0.13`). +of `v2.0.13`). Before you install spaCy and its dependencies, make sure that +`pip`, `setuptools` and `wheel` are up to date. ```bash +pip install -U pip setuptools wheel pip install spacy ``` +For installation on python 2.7 or 3.5 where binary wheels are not provided for +the most recent versions of the dependencies, you can prefer older binary +wheels over newer source packages with `--prefer-binary`: + +```bash +pip install spacy --prefer-binary +``` + To install additional data tables for lemmatization and normalization in **spaCy v2.2+** you can run `pip install spacy[lookups]` or install [`spacy-lookups-data`](https://github.com/explosion/spacy-lookups-data) @@ -126,6 +136,7 @@ environment to avoid modifying system state: ```bash python -m venv .env source .env/bin/activate +pip install -U pip setuptools wheel pip install spacy ``` @@ -224,16 +235,28 @@ do that depends on your system. See notes on Ubuntu, OS X and Windows for details. ```bash -# make sure you are using the latest pip -python -m pip install -U pip git clone https://github.com/explosion/spaCy cd spaCy python -m venv .env source .env/bin/activate -export PYTHONPATH=`pwd` + +# make sure you are using the latest pip +python -m pip install -U pip setuptools wheel + +pip install . +``` + +To install with extras: + +```bash +pip install .[lookups,cuda102] +``` + +To install all dependencies required for development: + +```bash pip install -r requirements.txt -python setup.py build_ext --inplace ``` Compared to regular install via pip, [requirements.txt](requirements.txt) @@ -273,14 +296,13 @@ tests, you'll usually want to clone the repository and build spaCy from source. This will also install the required development dependencies and test utilities defined in the `requirements.txt`. -Alternatively, you can find out where spaCy is installed and run `pytest` on -that directory. Don't forget to also install the test utilities via spaCy's +Alternatively, you can run `pytest` on the tests from within the installed +`spacy` package. Don't forget to also install the test utilities via spaCy's `requirements.txt`: ```bash -python -c "import os; import spacy; print(os.path.dirname(spacy.__file__))" -pip install -r path/to/requirements.txt -python -m pytest +pip install -r requirements.txt +python -m pytest --pyargs spacy ``` See [the documentation](https://spacy.io/usage#tests) for more details and diff --git a/setup.cfg b/setup.cfg index e556ba19c..48772bb4e 100644 --- a/setup.cfg +++ b/setup.cfg @@ -61,21 +61,25 @@ install_requires = lookups = spacy_lookups_data>=0.3.2,<0.4.0 cuda = - cupy>=5.0.0b4,<9.0.0 + cupy>=5.0.0b4 cuda80 = - cupy-cuda80>=5.0.0b4,<9.0.0 + cupy-cuda80>=5.0.0b4 cuda90 = - cupy-cuda90>=5.0.0b4,<9.0.0 + cupy-cuda90>=5.0.0b4 cuda91 = - cupy-cuda91>=5.0.0b4,<9.0.0 + cupy-cuda91>=5.0.0b4 cuda92 = - cupy-cuda92>=5.0.0b4,<9.0.0 + cupy-cuda92>=5.0.0b4 cuda100 = - cupy-cuda100>=5.0.0b4,<9.0.0 + cupy-cuda100>=5.0.0b4 cuda101 = - cupy-cuda101>=5.0.0b4,<9.0.0 + cupy-cuda101>=5.0.0b4 cuda102 = - cupy-cuda102>=5.0.0b4,<9.0.0 + cupy-cuda102>=5.0.0b4 +cuda110 = + cupy-cuda110>=5.0.0b4 +cuda111 = + cupy-cuda111>=5.0.0b4 # Language tokenizers with external dependencies ja = sudachipy>=0.4.5 diff --git a/website/docs/usage/index.md b/website/docs/usage/index.md index d0172104b..e5a37ad6c 100644 --- a/website/docs/usage/index.md +++ b/website/docs/usage/index.md @@ -31,9 +31,10 @@ import QuickstartInstall from 'widgets/quickstart-install.js' ### pip {#pip} Using pip, spaCy releases are available as source packages and binary wheels (as -of v2.0.13). +of v2.0.13). For the most recent releases, pip 19.3 or newer is recommended. ```bash +$ pip install -U pip setuptools wheel $ pip install -U spacy ``` @@ -66,6 +67,7 @@ environment to avoid modifying system state: ```bash python -m venv .env source .env/bin/activate +pip install -U pip setuptools wheel pip install spacy ``` @@ -122,10 +124,11 @@ support, we've been grateful to use the work of Chainer's interface for GPU arrays. spaCy can be installed on GPU by specifying `spacy[cuda]`, `spacy[cuda90]`, -`spacy[cuda91]`, `spacy[cuda92]`, `spacy[cuda100]`, `spacy[cuda101]` or -`spacy[cuda102]`. If you know your cuda version, using the more explicit -specifier allows cupy to be installed via wheel, saving some compilation time. -The specifiers should install [`cupy`](https://cupy.chainer.org). +`spacy[cuda91]`, `spacy[cuda92]`, `spacy[cuda100]`, `spacy[cuda101]`, +`spacy[cuda102]`, `spacy[cuda110]` or `spacy[cuda111]`. If you know your cuda +version, using the more explicit specifier allows cupy to be installed via +wheel, saving some compilation time. The specifiers should install +[`cupy`](https://cupy.chainer.org). ```bash $ pip install -U spacy[cuda92] @@ -158,15 +161,25 @@ system. See notes on [Ubuntu](#source-ubuntu), [macOS / OS X](#source-osx) and [Windows](#source-windows) for details. ```bash -python -m pip install -U pip # update pip git clone https://github.com/explosion/spaCy # clone spaCy cd spaCy # navigate into directory python -m venv .env # create environment in .env source .env/bin/activate # activate virtual environment -\export PYTHONPATH=`pwd` # set Python path to spaCy directory -pip install -r requirements.txt # install all requirements -python setup.py build_ext --inplace # compile spaCy +python -m pip install -U pip setuptools wheel # update build tools +pip install . # compile and install spaCy +``` + +To install with extras: + +```bash +pip install .[lookups,cuda102] # install spaCy with extras +``` + +To install all dependencies required for development: + +```bash +pip install -r requirements.txt ``` Compared to regular install via pip, the @@ -204,6 +217,36 @@ official distributions these are: | Python 3.4 | Visual Studio 2010 | | Python 3.5+ | Visual Studio 2015 | +#### Additional options for developers {#source-developers} + +Some additional options may be useful for spaCy developers who are editing the +source code and recompiling frequently. + +- Install in editable mode. Changes to `.py` files will be reflected as soon as + the files are saved, but edits to Cython files (`.pxd`, `.pyx`) will require + the `pip install` or `python setup.py build_ext` command below to be run + again. Before installing in editable mode, be sure you have removed any + previous installs with `pip uninstall spacy`, which you may need to run + multiple times to remove all traces of earlier installs. + + ```diff + pip install -U pip setuptools wheel + - pip install . + + pip install -r requirements.txt + + pip install --no-build-isolation --editable . + ``` + +- Build in parallel using `N` CPUs to speed up compilation and then install in + editable mode: + + ```diff + pip install -U pip setuptools wheel + - pip install . + + pip install -r requirements.txt + + python setup.py build_ext --inplace -j N + + python setup.py develop + ``` + ### Run tests {#run-tests} spaCy comes with an @@ -213,14 +256,12 @@ In order to run the tests, you'll usually want to clone the [build spaCy from source](#source). This will also install the required development dependencies and test utilities defined in the `requirements.txt`. -Alternatively, you can find out where spaCy is installed and run `pytest` on -that directory. Don't forget to also install the test utilities via spaCy's -[`requirements.txt`](https://github.com/explosion/spaCy/tree/master/requirements.txt): +Alternatively, you can run `pytest` on the tests packaged with the install +`spacy package. Don't forget to also install the test utilities via spaCy's [`requirements.txt`](https://github.com/explosion/spaCy/tree/master/requirements.txt): ```bash -python -c "import os; import spacy; print(os.path.dirname(spacy.__file__))" -pip install -r path/to/requirements.txt -python -m pytest [spacy directory] +pip install -r requirements.txt +python -m pytest --pyargs spacy ``` Calling `pytest` on the spaCy directory will run only the basic tests. The flag @@ -230,8 +271,8 @@ Calling `pytest` on the spaCy directory will run only the basic tests. The flag # make sure you are using recent pytest version python -m pip install -U pytest -python -m pytest [spacy directory] # basic tests -python -m pytest [spacy directory] --slow # basic and slow tests +python -m pytest --pyargs spacy # basic tests +python -m pytest --pyargs spacy --slow # basic and slow tests ``` ## Troubleshooting guide {#troubleshooting} diff --git a/website/src/widgets/quickstart-install.js b/website/src/widgets/quickstart-install.js index d32062627..e2da49f7e 100644 --- a/website/src/widgets/quickstart-install.js +++ b/website/src/widgets/quickstart-install.js @@ -88,17 +88,15 @@ const QuickstartInstall = ({ id, title }) => ( .env\Scripts\activate - pip install -U spacy + + pip install -U pip setuptools wheel + + + pip install -U spacy + conda install -c conda-forge spacy git clone https://github.com/{repo} cd spaCy - - export PYTHONPATH=`pwd` - - - set PYTHONPATH=/path/to/spaCy - - pip install -r requirements.txt pip install -U spacy-lookups-data @@ -108,7 +106,10 @@ const QuickstartInstall = ({ id, title }) => ( conda install -c conda-forge spacy-lookups-data - python setup.py build_ext --inplace + + pip install -U pip setuptools wheel + + pip install . {models.map(({ code, models: modelOptions }) => ( python -m spacy download {modelOptions[0]}