From 188b160e221684431bc73491685ad3fa591cbe1b Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Sat, 20 Jul 2019 15:25:45 -0700 Subject: [PATCH 01/18] Add note on navigation and prose edits --- source/index.rst | 48 +++++++++++++++++++++++++++++++++++++----------- 1 file changed, 37 insertions(+), 11 deletions(-) diff --git a/source/index.rst b/source/index.rst index db8bcf1c1..4633efe4d 100644 --- a/source/index.rst +++ b/source/index.rst @@ -11,6 +11,7 @@ Python Packaging User Guide :hidden: overview + basics tutorials/index guides/index discussions/index @@ -32,26 +33,51 @@ happily accept any :doc:`contributions and feedback `. 😊 .. _Python Packaging Authority: https://pypa.io +.. note:: **Navigating the User Guide** + + The *Python Packaging User Guide* is divided into several sections: + + - **Tutorials** introduce packaging concepts through opinionated, + step-by-step guides, such as *Installing Packages* and *Packaging Projects*. + - **Guides** focus on accomplishing a specific task, such as *Making a + PyPI friendly README* and *Installing Scientific Packages*. + - **Discussions** provide comprehensive information about a specific topic + such as *install_requires vs requirements files* and *Wheel vs Egg*. + - **Specifications** document interoperability and standards, such as + *Entry points specification* and *Platform compatibility tags*. + + The :doc:`glossary` also helps the reader understand any unfamiliar terms or + jargon. + + Get started =========== -Essential tools and concepts for working within the Python -development ecosystem are covered in our :doc:`tutorials/index` section: +Many readers will find the :doc:`tutorials/index` section a good starting place +to learn more about Python packaging. It provides step-by-step information about +the essential tools and concepts of installing and packaging Python projects: + +* :doc:`tutorial on installing packages ` +* :doc:`tutorial on managing application dependencies ` + in a version controlled project +* :doc:`tutorial on packaging and distributing ` + your projects + +The :doc:`Basics of Installation ` discusses the methods of +installing a Python package for different use cases, such as web, scientific +applications, devops, and more. New developers are encouraged to read this +section before the :doc:`tutorial on installing packages `. -* to learn how to install packages, see the - :doc:`tutorial on installing packages `. -* to learn how to manage dependencies in a version controlled project, see the - :doc:`tutorial on managing application dependencies `. -* to learn how to package and distribute your projects, see the - :doc:`tutorial on packaging and distributing ` -* to get an overview of packaging options for Python libraries and - applications, see the :doc:`Overview of Python Packaging `. +Intermediate to advanced Python developers interested in creating a Python +package will benefit from reviewing the :doc:`Overview of Python Packaging ` +and its guidance on planning development for packaging. Learn more ========== -Beyond our :doc:`tutorials/index`, this guide has several other resources: +Beyond our :doc:`tutorials/index`, this User Guide has several resource +sections with topical and in-depth information: * the :doc:`guides/index` section for walk throughs, such as :doc:`guides/installing-using-linux-tools` or :doc:`guides/packaging-binary-extensions` From 00a717490956da46034c2d2c852ad811aaf06457 Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Sat, 20 Jul 2019 15:26:04 -0700 Subject: [PATCH 02/18] simplify section title --- source/overview.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/overview.rst b/source/overview.rst index 6a11f2c00..ca4b78310 100644 --- a/source/overview.rst +++ b/source/overview.rst @@ -1,6 +1,6 @@ -=================================== -An Overview of Packaging for Python -=================================== +================================ +Overview of Packaging for Python +================================ .. Editors, see notes at the bottom of the document for maintenance info. From 2fb27be541c786bf6ab93d3f9f01bb0ecca85c46 Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Sat, 20 Jul 2019 15:26:37 -0700 Subject: [PATCH 03/18] add basics of installation --- source/basics.rst | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 source/basics.rst diff --git a/source/basics.rst b/source/basics.rst new file mode 100644 index 000000000..cbd73d8f8 --- /dev/null +++ b/source/basics.rst @@ -0,0 +1,3 @@ +====================== +Basics of Installation +====================== \ No newline at end of file From 41a47a2326b0bd69fb211a322cc8a5c467b525db Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Sat, 20 Jul 2019 15:28:44 -0700 Subject: [PATCH 04/18] move creating documentation from tutorials to guides --- source/{tutorials => guides}/creating-documentation.rst | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename source/{tutorials => guides}/creating-documentation.rst (100%) diff --git a/source/tutorials/creating-documentation.rst b/source/guides/creating-documentation.rst similarity index 100% rename from source/tutorials/creating-documentation.rst rename to source/guides/creating-documentation.rst From c3abe087f84d273d8c2cb7818166d92d24defee8 Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Sat, 20 Jul 2019 15:31:05 -0700 Subject: [PATCH 05/18] update local table of contents --- source/guides/index.rst | 1 + source/tutorials/index.rst | 1 - 2 files changed, 1 insertion(+), 1 deletion(-) diff --git a/source/guides/index.rst b/source/guides/index.rst index b8d25d499..c50d1a27a 100644 --- a/source/guides/index.rst +++ b/source/guides/index.rst @@ -28,4 +28,5 @@ introduction to packaging, see :doc:`/tutorials/index`. hosting-your-own-index migrating-to-pypi-org using-testpypi + creating-documentation making-a-pypi-friendly-readme diff --git a/source/tutorials/index.rst b/source/tutorials/index.rst index 40b0620f3..33ab4f98a 100644 --- a/source/tutorials/index.rst +++ b/source/tutorials/index.rst @@ -11,4 +11,3 @@ topics, see :doc:`/guides/index`. installing-packages managing-dependencies packaging-projects - creating-documentation From 07434ee7638a8fbb49999b52d3ba2640f25e711a Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Sat, 20 Jul 2019 15:48:09 -0700 Subject: [PATCH 06/18] Refine note box links and headings --- source/index.rst | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/source/index.rst b/source/index.rst index 4633efe4d..af026d371 100644 --- a/source/index.rst +++ b/source/index.rst @@ -35,16 +35,18 @@ happily accept any :doc:`contributions and feedback `. 😊 .. note:: **Navigating the User Guide** - The *Python Packaging User Guide* is divided into several sections: + The *Python Packaging User Guide* is organized into several sections: - - **Tutorials** introduce packaging concepts through opinionated, + - :doc:`tutorials/index` introduce packaging concepts through opinionated, step-by-step guides, such as *Installing Packages* and *Packaging Projects*. - - **Guides** focus on accomplishing a specific task, such as *Making a + - :doc:`guides/index` focus on accomplishing a specific task, such as *Making a PyPI friendly README* and *Installing Scientific Packages*. - - **Discussions** provide comprehensive information about a specific topic + - :doc:`discussions/index` provide comprehensive information about a specific topic such as *install_requires vs requirements files* and *Wheel vs Egg*. - - **Specifications** document interoperability and standards, such as + - :doc:`specifications/index` document interoperability and standards, such as *Entry points specification* and *Platform compatibility tags*. + - :doc:`key_projects` highlights PyPA maintained projects and mentions notable + third-party maintained projects. The :doc:`glossary` also helps the reader understand any unfamiliar terms or jargon. @@ -57,16 +59,16 @@ Many readers will find the :doc:`tutorials/index` section a good starting place to learn more about Python packaging. It provides step-by-step information about the essential tools and concepts of installing and packaging Python projects: -* :doc:`tutorial on installing packages ` -* :doc:`tutorial on managing application dependencies ` +* :doc:`tutorial on Installing Packages ` +* :doc:`tutorial on Managing Application Dependencies ` in a version controlled project -* :doc:`tutorial on packaging and distributing ` +* :doc:`tutorial on Packaging and Distributing ` your projects The :doc:`Basics of Installation ` discusses the methods of installing a Python package for different use cases, such as web, scientific applications, devops, and more. New developers are encouraged to read this -section before the :doc:`tutorial on installing packages `. +section before the :doc:`tutorial on Installing Packages `. Intermediate to advanced Python developers interested in creating a Python package will benefit from reviewing the :doc:`Overview of Python Packaging ` From 5794b4cc1c2f96c484913191bd7f0024ebcd8df7 Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Sat, 20 Jul 2019 16:04:42 -0700 Subject: [PATCH 07/18] add skeleton for basics of installation --- source/basics.rst | 48 ++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 47 insertions(+), 1 deletion(-) diff --git a/source/basics.rst b/source/basics.rst index cbd73d8f8..b0a7c5408 100644 --- a/source/basics.rst +++ b/source/basics.rst @@ -1,3 +1,49 @@ ====================== Basics of Installation -====================== \ No newline at end of file +====================== + +.. Editors, see notes at the bottom of the document for maintenance info. + +.. contents:: Contents + :local: + +Jargon +------ + +- System Python +- Selected Python +- Environments (None, virtual, conda) +- Package manager/tool (pipenv, pip, conda, others) +- Advanced installation cases + +Installation using PyPA Tools +----------------------------- + + +Third Party Installation Tools +------------------------------ + +Best Practices Checklist +------------------------ + +- Review the installation documentation for the package +- Install the package by following the installation documentation +- Most packages will be installed with pipenv or pip. +- [Science and Data Science Packages] The installation instructions may include + references to conda and conda-forge. Follow those instructions. + +Wrap up +------- + + + +.. Editing notes: + + This document targets at an intermediate audience, + lower-mid-level to early-advanced Python developers. It's expected + that most developers finding this document will have already + encountered several packaging technologies, through package + managers, app stores, pip, and so forth. They may have even + shipped a few packages of their own. They are smart enough to have + built something to ship, and experienced (or frustrated) enough to + know to search for prior art. From 56d4e4f1ff1f54587c4e60da5241ce0c6de19234 Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Sat, 20 Jul 2019 16:04:58 -0700 Subject: [PATCH 08/18] add name to authors --- authors.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/authors.txt b/authors.txt index 087255916..44d4626a6 100644 --- a/authors.txt +++ b/authors.txt @@ -2,6 +2,7 @@ Alex J. Burke Brett Cannon C\. Titus Brown Carl Meyer +Carol Willing Daniel Holth Kevin Teague Jean-Paul Calderone From c9c54dc9f3810edcaf531803de3fdfcb8a7ad913 Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Sat, 20 Jul 2019 16:19:33 -0700 Subject: [PATCH 09/18] add sections to basic doc --- source/basics.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/basics.rst b/source/basics.rst index b0a7c5408..d650c873a 100644 --- a/source/basics.rst +++ b/source/basics.rst @@ -13,7 +13,7 @@ Jargon - System Python - Selected Python - Environments (None, virtual, conda) -- Package manager/tool (pipenv, pip, conda, others) +- Package manager/tool (pipenv, pip, conda, miniconda, others) - Advanced installation cases Installation using PyPA Tools From 2d921df177a8a25a2348b7e5649c1a52d636727c Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Sat, 20 Jul 2019 16:23:15 -0700 Subject: [PATCH 10/18] add note for target audience of basics document --- source/basics.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/source/basics.rst b/source/basics.rst index d650c873a..7683d389c 100644 --- a/source/basics.rst +++ b/source/basics.rst @@ -39,11 +39,11 @@ Wrap up .. Editing notes: - This document targets at an intermediate audience, - lower-mid-level to early-advanced Python developers. It's expected - that most developers finding this document will have already - encountered several packaging technologies, through package - managers, app stores, pip, and so forth. They may have even - shipped a few packages of their own. They are smart enough to have - built something to ship, and experienced (or frustrated) enough to - know to search for prior art. + This document targets at a novice audience especially scientists who may + not have a computer development background. It's expected + that most developers finding this document will have experience installing + applications and apps, but may not have installed a Python package before + or be familiar with the command line. + + For specific how-to information refer to the documentation of the desired + package for installation. From 94ad36ed271563b17805c3c671781d204d747862 Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Sat, 20 Jul 2019 16:24:22 -0700 Subject: [PATCH 11/18] fix typo --- source/basics.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/basics.rst b/source/basics.rst index 7683d389c..cbec4d64c 100644 --- a/source/basics.rst +++ b/source/basics.rst @@ -39,7 +39,7 @@ Wrap up .. Editing notes: - This document targets at a novice audience especially scientists who may + This document targets a novice audience especially scientists who may not have a computer development background. It's expected that most developers finding this document will have experience installing applications and apps, but may not have installed a Python package before From bb8db4ddf7fcbceaea8310f3516727ed9246f889 Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Sun, 21 Jul 2019 14:11:50 -0700 Subject: [PATCH 12/18] add todo comment --- source/tutorials/packaging-projects.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/source/tutorials/packaging-projects.rst b/source/tutorials/packaging-projects.rst index a2455205a..f2da4430e 100644 --- a/source/tutorials/packaging-projects.rst +++ b/source/tutorials/packaging-projects.rst @@ -201,6 +201,9 @@ Now run this command from the same directory where :file:`setup.py` is located: python3 setup.py sdist bdist_wheel +.. TODO where to document setup.py sdist / bdist_wheel -> python -m pep517.build -s -b + probably in a guide re: scientific python + This command should output a lot of text and once completed should generate two files in the :file:`dist` directory: From 1495f1adead18c12fe179b3c9b045a77c3b326b2 Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Sun, 21 Jul 2019 14:12:16 -0700 Subject: [PATCH 13/18] edit prose to simplify for user reading --- source/tutorials/installing-packages.rst | 29 ++++++++++++++---------- 1 file changed, 17 insertions(+), 12 deletions(-) diff --git a/source/tutorials/installing-packages.rst b/source/tutorials/installing-packages.rst index 8e20d6a41..b412917f2 100644 --- a/source/tutorials/installing-packages.rst +++ b/source/tutorials/installing-packages.rst @@ -33,8 +33,8 @@ packages. Ensure you can run Python from the command line ----------------------------------------------- -Before you go any further, make sure you have Python and that the expected -version is available from your command line. You can check this by running: +Before you go any further, make sure you have Python and the expected +version available from your command line. You can check this by running: .. code-block:: bash @@ -44,7 +44,8 @@ You should get some output like ``Python 3.6.3``. If you do not have Python, please install the latest 3.x version from `python.org`_ or refer to the `Installing Python`_ section of the Hitchhiker's Guide to Python. -.. Note:: If you're a newcomer and you get an error like this: +.. Note:: If you are new to Python or the command line and the system returns + an error like this: .. code-block:: python @@ -53,26 +54,30 @@ please install the latest 3.x version from `python.org`_ or refer to the File "", line 1, in NameError: name 'python' is not defined - It's because this command and other suggested commands in this tutorial - are intended to be run in a *shell* (also called a *terminal* or + It is due to running ``python --version`` in the Python REPL + instead of a *shell*, like bash. This command and others in this + tutorial should be run in a *shell* (also called a *terminal* or *console*). See the Python for Beginners `getting started tutorial`_ for an introduction to using your operating system's shell and interacting with Python. .. Note:: If you're using an enhanced shell like IPython or the Jupyter - notebook, you can run system commands like those in this tutorial by - prefacing them with a ``!`` character: + notebook, you can run system commands, like those in this tutorial, by + prefacing the command with a ``!`` character: :: In [1]: import sys - !{sys.executable} --version + + In [2]: !{sys.executable} --version + Python 3.6.3 - It's recommended to write ``{sys.executable}`` rather than plain ``python`` in - order to ensure that commands are run in the Python installation matching - the currently running notebook (which may not be the same Python - installation that the ``python`` command refers to). + It's recommended to substitute ``{sys.executable}`` for ``python``. This + helps to ensure that commands are run in the same Python installation as + the currently running notebook. Running ``python`` as a command in the + notebook may execute in the same Python installation that the + notebook is running which will cause confusion or unexpected results. .. Note:: Due to the way most Linux distributions are handling the Python 3 migration, Linux users using the system Python without creating a virtual From cbc3c6133225a14bcd247c09281bae4b2ea4f66b Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Sun, 21 Jul 2019 14:49:28 -0700 Subject: [PATCH 14/18] Rename discussions to concepts for better discovery --- source/discussions/index.rst | 21 ++++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) diff --git a/source/discussions/index.rst b/source/discussions/index.rst index ab35c93e1..caecd810a 100644 --- a/source/discussions/index.rst +++ b/source/discussions/index.rst @@ -1,14 +1,21 @@ -Discussions -########### +Concepts +######## -**Discussions** are focused on providing comprehensive information about a -specific topic. If you're just trying to get stuff done, see -:doc:`/guides/index`. +The **Concepts** section discusses fundamental information about specific +topics. + +The goals of this section include providing background information, describing +important technical concepts, and highlighting usage tradeoffs. + +Contents include: .. toctree:: :maxdepth: 1 - deploying-python-applications - pip-vs-easy-install install-requires-vs-requirements + pip-vs-easy-install wheel-vs-egg + deploying-python-applications + +Alternatively, if you're trying to get a specific task done, see +:doc:`/guides/index`. \ No newline at end of file From d52a8b39e1b23261637a665060a185c36b9d4f95 Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Sun, 21 Jul 2019 15:24:25 -0700 Subject: [PATCH 15/18] rename guides to tasks --- source/guides/index.rst | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/source/guides/index.rst b/source/guides/index.rst index c50d1a27a..8f5cdea19 100644 --- a/source/guides/index.rst +++ b/source/guides/index.rst @@ -1,9 +1,10 @@ -Guides -###### +Tasks +##### -**Guides** are focused on accomplishing a specific task and assume that you are -already familiar with the basics of Python packaging. If you're looking for an -introduction to packaging, see :doc:`/tutorials/index`. +**Tasks** guides focus on accomplishing specific tasks. + +The guides in this Tasks section assume that you are already familiar with the +basics of Python packaging. Contents include: .. toctree:: :maxdepth: 1 @@ -30,3 +31,5 @@ introduction to packaging, see :doc:`/tutorials/index`. using-testpypi creating-documentation making-a-pypi-friendly-readme + +If you're looking for an introduction to packaging, see :doc:`/tutorials/index`. \ No newline at end of file From e272fed6f8b6c0259225ff8a9553f2e505f461ff Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Sun, 21 Jul 2019 15:24:43 -0700 Subject: [PATCH 16/18] replace box with a table --- source/index.rst | 45 ++++++++++++++++++++++++++++----------------- 1 file changed, 28 insertions(+), 17 deletions(-) diff --git a/source/index.rst b/source/index.rst index af026d371..193460ca4 100644 --- a/source/index.rst +++ b/source/index.rst @@ -33,23 +33,34 @@ happily accept any :doc:`contributions and feedback `. 😊 .. _Python Packaging Authority: https://pypa.io -.. note:: **Navigating the User Guide** - - The *Python Packaging User Guide* is organized into several sections: - - - :doc:`tutorials/index` introduce packaging concepts through opinionated, - step-by-step guides, such as *Installing Packages* and *Packaging Projects*. - - :doc:`guides/index` focus on accomplishing a specific task, such as *Making a - PyPI friendly README* and *Installing Scientific Packages*. - - :doc:`discussions/index` provide comprehensive information about a specific topic - such as *install_requires vs requirements files* and *Wheel vs Egg*. - - :doc:`specifications/index` document interoperability and standards, such as - *Entry points specification* and *Platform compatibility tags*. - - :doc:`key_projects` highlights PyPA maintained projects and mentions notable - third-party maintained projects. - - The :doc:`glossary` also helps the reader understand any unfamiliar terms or - jargon. +Navigating the User Guide +========================= + +The *Python Packaging User Guide* is organized into several sections: + ++------------------------------+----------------------------------------------------------+ +| Section | Description | ++------------------------------+----------------------------------------------------------+ +| :doc:`tutorials/index` | Introduce packaging concepts through opinionated, | +| | step-by-step guides, such as *Installing Packages* | +| | and *Packaging Projects*. | ++------------------------------+----------------------------------------------------------+ +| :doc:`guides/index` | Focus on accomplishing a specific task, such as | +| | *Making a PyPI friendly README* and *Installing* | +| | *Scientific Packages*. | ++------------------------------+----------------------------------------------------------+ +| :doc:`discussions/index` | Provide comprehensive information about a specific topic | +| | such as *install_requires vs requirements files* and | +| | *Wheel vs Egg*. | ++------------------------------+----------------------------------------------------------+ +| :doc:`specifications/index` | Document interoperability and standards, such as | +| | *Entry points specification* | ++------------------------------+----------------------------------------------------------+ +| :doc:`key_projects` | Highlights PyPA maintained projects and mentions notable | +| | third-party maintained projects. | ++------------------------------+----------------------------------------------------------+ +| :doc:`glossary` | Define unfamiliar terms or jargon | ++------------------------------+----------------------------------------------------------+ Get started From cdae51c5138d51f9823c2afe84bd3fac256629fa Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Sun, 21 Jul 2019 15:45:29 -0700 Subject: [PATCH 17/18] add overview and prereqs to sci pkg doc --- .../guides/installing-scientific-packages.rst | 20 +++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/source/guides/installing-scientific-packages.rst b/source/guides/installing-scientific-packages.rst index 8133ba07c..7ab84c078 100644 --- a/source/guides/installing-scientific-packages.rst +++ b/source/guides/installing-scientific-packages.rst @@ -7,12 +7,24 @@ Installing scientific packages .. contents:: Contents :local: +Overview +-------- Scientific software tends to have more complex dependencies than most, and it will often have multiple build options to take advantage of different kinds of hardware, or to interoperate with different pieces of external software. +Prerequisites +------------- + +A basic understanding of the Scientific Python stack as well as installation +of packages using tools such as pip or conda and using hosting repositories +like PyPI and conda-forge. + +Complexity, NumPy, and SciPy +---------------------------- + In particular, `NumPy `__, which provides the basis for most of the software in the `scientific Python stack `__ can be configured @@ -105,8 +117,12 @@ end users in an easy to use and update format. Some of these distributions may not be compatible with the standard ``pip`` and ``virtualenv`` based toolchain. +Third-party package managers +---------------------------- + Spack ------- +~~~~~ + `Spack `_ is a flexible package manager designed to support multiple versions, configurations, platforms, and compilers. It was built to support the needs of large supercomputing centers and scientific @@ -125,7 +141,7 @@ be loaded and unloaded from the user's environment. The conda cross-platform package manager ----------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ `Anaconda `_ is a Python distribution published by Anaconda, Inc. It is a stable collection of Open Source From 71dad940feb57892c084c936c599af6eb21d613e Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Sun, 21 Jul 2019 16:05:21 -0700 Subject: [PATCH 18/18] add section headings and content to science doc --- .../guides/installing-scientific-packages.rst | 86 +++++++++++++------ 1 file changed, 62 insertions(+), 24 deletions(-) diff --git a/source/guides/installing-scientific-packages.rst b/source/guides/installing-scientific-packages.rst index 7ab84c078..119662f3d 100644 --- a/source/guides/installing-scientific-packages.rst +++ b/source/guides/installing-scientific-packages.rst @@ -43,8 +43,8 @@ libraries (or any other Python libraries that require a compilation environment to install from source and don't provide pre-built wheel files on PyPI). -Building from source --------------------- +Building and installing from source +----------------------------------- The same complexity which makes it difficult to distribute NumPy (and many of the projects that depend on it) as wheel files also make them difficult @@ -52,9 +52,16 @@ to build from source yourself. However, for intrepid folks that are willing to spend the time wrangling compilers and linkers for both C and FORTRAN, building from source is always an option. +Installation options by operating system +---------------------------------------- + +Scientific packages may use multiple programming languages. In addition, +the use of different operating systems increases the complexity of installation. +Therefore, the selection of installation tool and method will often depend on +several factors including those already mentioned. Linux distribution packages ---------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~ For Linux users, the system package manager will often have pre-compiled versions of various pieces of scientific software, including NumPy and @@ -66,7 +73,7 @@ installed into the system Python when using virtual environments). Windows installers ------------------- +~~~~~~~~~~~~~~~~~~ Many Python projects that don't (or can't) currently publish wheel files at least publish Windows installers, either on PyPI or on their project @@ -95,7 +102,7 @@ convert a Windows `bdist_wininst` installer to a wheel. .. _mac-os-x-installers-and-package-managers: macOS installers and package managers -------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Similar to the situation on Windows, many projects (including NumPy) publish macOS installers that are compatible with the macOS CPython binaries @@ -120,25 +127,8 @@ and ``virtualenv`` based toolchain. Third-party package managers ---------------------------- -Spack -~~~~~ - -`Spack `_ is a flexible package manager -designed to support multiple versions, configurations, platforms, and compilers. -It was built to support the needs of large supercomputing centers and scientific -application teams, who must often build software many different ways. -Spack is not limited to Python; it can install packages for ``C``, ``C++``, -``Fortran``, ``R``, and other languages. It is non-destructive; installing -a new version of one package does not break existing installations, so many -configurations can coexist on the same system. - -Spack offers a simple but powerful syntax that allows users to specify -versions and configuration options concisely. Package files are written in -pure Python, and they are templated so that it is easy to swap compilers, -dependency implementations (like MPI), versions, and build options with a single -package file. Spack also generates *module* files so that packages can -be loaded and unloaded from the user's environment. - +Often a third-party package manager, maintained by groups other than PyPA, may +be an expedient solution for installing scientific and data science packages. The conda cross-platform package manager ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -161,3 +151,51 @@ written in Python, but is Python-agnostic. Conda manages Python itself as a package, so that `conda update python` is possible, in contrast to pip, which only manages Python packages. Conda is available in Anaconda and Miniconda (an easy-to-install download with just Python and conda). + +Miniconda +~~~~~~~~~ + +A lighter-weight option for conda installs and often using conda-forge as the +preferred channel. + +Spack +~~~~~ + +`Spack `_ is a flexible package manager +designed to support multiple versions, configurations, platforms, and compilers. +It was built to support the needs of large supercomputing centers and scientific +application teams, who must often build software many different ways. +Spack is not limited to Python; it can install packages for ``C``, ``C++``, +``Fortran``, ``R``, and other languages. It is non-destructive; installing +a new version of one package does not break existing installations, so many +configurations can coexist on the same system. + +Spack offers a simple but powerful syntax that allows users to specify +versions and configuration options concisely. Package files are written in +pure Python, and they are templated so that it is easy to swap compilers, +dependency implementations (like MPI), versions, and build options with a single +package file. Spack also generates *module* files so that packages can +be loaded and unloaded from the user's environment. + +Conda-forge +----------- + +Maintained and tested scientific packages by the conda-forge community. A +good source for finding up-to-date builds for package installation. + +DockerHub +--------- + +Docker and other container technologies are used within the sciences to spin +up a predetermined container of packages. This often can be an aid to +reproducibility of results. + +What's next +----------- + +A wise recommendation for installing Scientific packages would be to follow +the installation recommendations provided in the package's documentation. +Another practical next step for users who are new to installing Python Scientific +packages would be to consult a recent tutorial or talk from a prior PyCon, +SciPy, or PyData conference which describes the current state of installing +scientific packages and tools. \ No newline at end of file