From 23feaf2b87598c539b600d4fccb5a5828ce49d03 Mon Sep 17 00:00:00 2001 From: Toon Verstraelen Date: Tue, 4 Jun 2024 21:43:22 +0200 Subject: [PATCH] Update installation instructions These instructions are intended to work with the next prerelease: - I'm not preparing conda releases at this stage. (Not so useful anymore now that IOData is pure Python. Pip works in a conda env.) - I've updated NumPy and SciPy dependencies to the oldest ones that are not listed on the NIST national vulnerability database. It may be worth extending our CI to explicitly test with these verions. - The `--pre` option is no longer needed. - The number installation options has been reduced: - No conda releases. - We no longer have setup.py (because such setup scripts are no longer recommended). - The option `--user` is no longer needed. `pip` assumes it when there is no venv. --- README.rst | 31 ++------- doc/install.rst | 162 ++++++++++++++---------------------------------- pyproject.toml | 6 +- 3 files changed, 53 insertions(+), 146 deletions(-) diff --git a/README.rst b/README.rst index 82b393c9..f4682609 100644 --- a/README.rst +++ b/README.rst @@ -50,37 +50,14 @@ Please use the following citation in any publication using IOData library: Installation ------------ -.. - : To install IOData using the conda package management system, install - : `miniconda `__ or - : `anaconda `__ first, and then: - : - : .. code-block:: bash - : - : # Create a horton3 conda environment. (optional, recommended) - : conda create -n horton3 - : source activate horton3 - : - : # Install the stable release. - : conda install -c theochem iodata - : - : To install IOData with pip, you may want to create a `virtual environment`_, - : and then: - : - : .. code-block:: bash - : - : # Install the stable release. - : pip install qc-iodata - -In anticipation of the 1.0 release of IOData, install the latest git revision -as follows: +In anticipation of the 1.0 release of IOData, install the latest pre-release as follows: .. code-block:: bash - python -m pip install git+https://github.com/theochem/iodata.git + python -m pip install qc-iodata -Add the ``--user`` argument if you are not working in a virtual or conda -environment. Note that there may be API changes between subsequent revisions. +Note that there may still be a few API changes between the pre-release 1.0.0a3 +and the upcoming stable release 1.0.0. See https://iodata.readthedocs.io/en/latest/install.html for full details. diff --git a/doc/install.rst b/doc/install.rst index 79fbbdd5..7b363751 100644 --- a/doc/install.rst +++ b/doc/install.rst @@ -24,59 +24,20 @@ Installation ============ -Stable releases ---------------- - -.. warning:: - - We are preparing a 1.0 release. Until then, these instructions for - installing a stable release will not work yet. If you enjoy living on the - edge, try the development release as explained in the - ":ref:`install-latest-git-revision`" section below. +Latest PyPI version +------------------- -Python 3 (>=3.6) must be installed before you can install IOData. In addition, -IOData has the following dependencies: +Python 3 (>=3.9) must be installed before you can install IOData. +In addition, IOData has the following dependencies: -- numpy >= 1.0: https://numpy.org/ -- scipy: https://scipy.org/ -- attrs >= 20.1.0: https://www.attrs.org/en/stable/index.html -- importlib_resources [only for Python 3.6]: https://gitlab.com/python-devs/importlib_resources +- numpy >= 1.22: https://numpy.org/ +- scipy >= 1.8: https://scipy.org/ +- attrs >= 21.3.0: https://www.attrs.org/en/stable/index.html Normally, you don't need to install these dependencies manually. They will be installed automatically when you follow the instructions below. -Installation with Ana- or Miniconda -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -To install IOData using the conda package management system, install -`miniconda `__ or -`anaconda `__ first, and then: - -.. code-block:: bash - - # Activate your main conda environment if it is not loaded in your .bashrc. - # E.g. run the following if you have miniconda installed in e.g. ~/miniconda3 - source ~/miniconda3/bin/activate - - # Create a horton3 conda environment. (optional, recommended) - conda create -n horton3 - source activate horton3 - - # Install the stable release. - conda install -c theochem qc-iodata - - # Unstable releases - # (Only do this if you understand the implications.) - # Install the testing release. (beta) - conda install -c theochem/label/test qc-iodata - # Install the development release. (alpha) - conda install -c theochem/label/dev qc-iodata - - -Installation with Pip -^^^^^^^^^^^^^^^^^^^^^ - -1. You can work in a `virtual environment`_: +1. The cleanest option is to install IOData in a `virtual environment`_: .. code-block:: bash @@ -84,35 +45,36 @@ Installation with Pip # Feel free to change the path. python3 -m venv ~/horton3 - # Activate the virtual environemnt. + # Activate the virtual environment. source ~/horton3/bin/activate - # Install the stable release in the venv horton3. + # Install IOData in the venv horton3. pip3 install qc-iodata # alternative: python3 -m pip install qc-iodata - # For developers, install a pre-release (alpha or beta). - # (Only do this if you understand the implications.) - pip3 install --pre qc-iodata - # alternative: python3 -m pip install --pre qc-iodata + # For developers, install with developer dependencies + pip3 install qc-iodata[dev] + # alternative: python3 -m pip install qc-iodata[dev] -2. You can install into your ``${HOME}`` directory, without creating a virtual + The ``source`` command needs to be entered every time you open a new virtual terminal, + which can be inconvenient. + You may put this line in your `.bashrc` or `.bash_profile` to avoid that repetition. + You may also automatically load environments when entering specific directories + with tools like `direnv`_. + +2. You can install IOData into your ``${HOME}`` directory, without creating a virtual environment. .. code-block:: bash # Install the stable release in your home directory. - pip3 install qc-iodata --user - # alternative: python3 -m pip install qc-iodata --user - - # For developers, install a pre-release (alpha or beta). - # (Only do this if you understand the implications.) - pip3 install --pre qc-iodata --user - # alternative: python3 -m pip install --pre qc-iodata --user + pip3 install qc-iodata + # alternative: python3 -m pip install qc-iodata This is by far the simplest method, ideal to get started, but you have only one home directory. If the installation breaks due to some experimentation, - it is harder to make a clean start in comparison to the other options. + it is harder to make a clean start in comparison to the virtual environment, + which you can simply delete. In case the ``pip3`` executable is not found, pip may be installed in a directory which is not included in your ``${PATH}`` variable. This seems to be a @@ -127,7 +89,7 @@ only present in names of executables, not names of Python modules. .. _install-latest-git-revision: -Latest git revision +Latest Git revision ------------------- This section shows how one can install the latest revision of IOData from the @@ -137,25 +99,20 @@ installation instructions. There are two installation methods: -1. **Quick and dirty.** Of this method, there are four variants, depending on - the correctness of your ``PATH`` variable and the presence of a virtual or - conda environment. These different scenarios are explained in more detail in - the previous section. +1. **Quick and dirty.** Of this method, there are two variants, depending on + the correctness of your ``PATH`` variable. + These different scenarios are explained in more detail in the previous section. .. code-block:: bash - # with env, correct PATH + # correct PATH pip install git+https://github.com/theochem/iodata.git - # with env, broken PATH - python -m pip install git+https://github.com/theochem/iodata.git - # without env, correct PATH - pip install git+https://github.com/theochem/iodata.git --user - # without env, broken PATH - python -m pip install git+https://github.com/theochem/iodata.git --user - -2. **Slow and smart.** In addition to the four variations in the quick and dirty - method, the slow and smart can be used with ``pip`` or just with - ``setup.py``. You also have the options to use *SSH* or *HTTPS* protocols to + # broken PATH + python3 -m pip install git+https://github.com/theochem/iodata.git + +2. **Slow and smart.** In addition to the two variations in the quick and dirty + method, the slow and smart can be useful when you plan to tinker with the source code. + You also have the options to use *SSH* or *HTTPS* protocols to clone the git repository. Pick whichever works best for you. .. code-block:: bash @@ -166,55 +123,28 @@ There are two installation methods: git clone https://github.com/theochem/iodata.git # A2) ssh git clone git@github.com:theochem/iodata.git - # B) Optionally write the version string - pip install roberto # or any of the three other ways of running pip, see above. - rob write-version - # C) Actual install, 6 different methods. - # C1) setup.py, with env - python setup.py install - # C2) pip, with env, correct PATH - pip install . - # C3) pip, with env, broken PATH - python -m pip install . - # C4) setup.py, without env - python setup.py install --user - # C5) pip, without env, correct PATH - pip install . --user - # C6) pip, without env, broken PATH - python -m pip install . --user + # B) Actual install, 2 different methods. + # B1) correct PATH + pip3 install . + # B2) broken PATH + python3 -m pip install . Testing ------- -The tests are automatically run when we build packages with conda, but you may -try them again on your own machine after installation. - -With Ana- or Miniconda: +The tests are automatically run after each change in the main branch on GitHub, +but you may try them again on your own machine after installation. +For this to work, you also need to install the development dependencies, as shown below. .. code-block:: bash - # Install pytest in your conda env. - conda install pytest pytest-xdist - # Then run the tests. - pytest --pyargs iodata -n auto - - -With Pip: - -.. code-block:: bash - - # Install pytest in your conda env ... - pip install pytest pytest-xdist - # .. and refresh the virtual environment. - # This is a venv quirk. Without it, pytest may not find IOData. - deactivate && source ~/horton3/activate - - # Alternatively, install pytest in your home directory. - pip install pytest pytest-xdist --user + # Install pytest + pip3 install qc-iodata[dev] # Finally, run the tests. pytest --pyargs iodata -n auto .. _virtual environment: https://docs.python.org/3/tutorial/venv.html +.. _direnv: https://direnv.net/ diff --git a/pyproject.toml b/pyproject.toml index a7d1eccb..d9520cf8 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -21,9 +21,9 @@ classifiers = [ "Intended Audience :: Science/Research", ] dependencies = [ - "numpy>=1.0", - "scipy", - "attrs>=20.1.0", + "numpy>=1.22", + "scipy>=1.8", + "attrs>=21.3.0", ] dynamic = ["version"]