diff --git a/docs/index.md b/docs/index.md index 0e9fca2e..8a372594 100644 --- a/docs/index.md +++ b/docs/index.md @@ -40,13 +40,12 @@ are a good place to start. ### Traffic lights -Each item has an (opinionated) traffic light. The meaning of these is: +Each item has an (opinionated) traffic light label. The meaning of these is: -- 🟒 At least one person in ARC uses this. We actively recommend using it above +- Best: At least one person in ARC uses this. We actively recommend using it above other tools. It is the single recommended tool for a given purpose. -- 🟠 We don't discourage using this, but it may duplicate functionality of a - green tool. -- πŸ”΄ We actively discourage using this. This could be because it's no longer +- Good: We don't discourage using this, but it may duplicate functionality of the Best tool. +- Avoid: We actively discourage using this. This could be because it's no longer maintained, not open source, or difficult to use. Consider moving to alternatives if you're currently using something that's red. A reason for not using this is given. diff --git a/docs/pages/benchmarking-profiling.md b/docs/pages/benchmarking-profiling.md index dd2521ee..ea741bc1 100644 --- a/docs/pages/benchmarking-profiling.md +++ b/docs/pages/benchmarking-profiling.md @@ -5,29 +5,29 @@ layout: default ## Benchmarking -| Name | Short description | 🚦 | -| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-: | -| [asv](https://asv.readthedocs.io/en/stable/) | A tool for benchmarking Python packages over their lifetime. Allows you to write benchmarks and then run them against every commit in the repository, to identify where performance increased or decreased. Comparative benchmarks can also be run, which can be useful for [running them in CI using GitHub runners](https://labs.quansight.org/blog/2021/08/github-actions-benchmarks). | 🟒 | +| Name | Short description | 🚦 | +| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-----------------------------------------: | +| [asv](https://asv.readthedocs.io/en/stable/) | A tool for benchmarking Python packages over their lifetime. Allows you to write benchmarks and then run them against every commit in the repository, to identify where performance increased or decreased. Comparative benchmarks can also be run, which can be useful for [running them in CI using GitHub runners](https://labs.quansight.org/blog/2021/08/github-actions-benchmarks). | Best | ## Profiling ### Time -| Name | Short description | 🚦 | -| ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | :-: | -| [pyinstrument](https://pyinstrument.readthedocs.io/en/stable) | Python profiler. Tells you how long individual lines of code take to run, so you can focus on the slowest part of your program to speed it up. | 🟒 | -| [line_profiler](https://pypi.org/project/line-profiler/) | A tool for line-by-line profiling of functions. | 🟠 | +| Name | Short description | 🚦 | +| ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------: | +| [pyinstrument](https://pyinstrument.readthedocs.io/en/stable) | Python profiler. Tells you how long individual lines of code take to run, so you can focus on the slowest part of your program to speed it up. | Best | +| [line_profiler](https://pypi.org/project/line-profiler/) | A tool for line-by-line profiling of functions. | Good | ### Memory -| Name | Short description | 🚦 | -| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-: | -| [memray](https://bloomberg.github.io/memray/) | Tracks and reports memory allocations, both in Python code and in compiled extension modules. It also has a [plugin](https://pytest-memray.readthedocs.io/en/latest/) for easy integration with pytest. Only works on Linux and macOS. | 🟠 | -| [memory_profiler](https://pypi.org/project/memory-profiler/) | No longer actively maintained. A Python module for monitoring memory consumption of a process alongside line-by-line analysis of memory consumption. Might be a useful alternative to memray if you need to do memory profiling on Windows. | 🟠 | +| Name | Short description | 🚦 | +| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------: | +| [memray](https://bloomberg.github.io/memray/) | Tracks and reports memory allocations, both in Python code and in compiled extension modules. It also has a [plugin](https://pytest-memray.readthedocs.io/en/latest/) for easy integration with pytest. Only works on Linux and macOS. | Good | +| [memory_profiler](https://pypi.org/project/memory-profiler/) | No longer actively maintained. A Python module for monitoring memory consumption of a process alongside line-by-line analysis of memory consumption. Might be a useful alternative to memray if you need to do memory profiling on Windows. | Good | ### General/other tools -| Name | Short description | 🚦 | -| -------------------------------------------------- | ------------------------------------------------------------------------------------------------- | :-: | -| [psutil](https://psutil.readthedocs.io/en/latest/) | System monitoring, profiling, limiting process resources and the management of running processes. | 🟒 | -| [snakeviz](https://jiffyclub.github.io/snakeviz/) | Browser based graphical viewer for the output of Python’s cProfile module. | 🟒 | +| Name | Short description | 🚦 | +| -------------------------------------------------- | ------------------------------------------------------------------------------------------------- | :-----------------------------------------: | +| [psutil](https://psutil.readthedocs.io/en/latest/) | System monitoring, profiling, limiting process resources and the management of running processes. | Best | +| [snakeviz](https://jiffyclub.github.io/snakeviz/) | Browser based graphical viewer for the output of Python’s cProfile module. | Best | diff --git a/docs/pages/ci.md b/docs/pages/ci.md index 68c8d0dd..523fb7aa 100644 --- a/docs/pages/ci.md +++ b/docs/pages/ci.md @@ -5,15 +5,15 @@ layout: default ## Continuous integration (CI) -| Name | Short description | 🚦 | -| ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | :-: | -| [GitHub Actions](https://docs.github.com/en/actions) | Continuous integration and continuous delivery platform (integrated with GitHub). | 🟒 | -| [AppVeyor](https://www.appveyor.com/docs/) | Continuous integration and continuous delivery platform. | 🟠 | -| [Bamboo](https://confluence.atlassian.com/bamboo/bamboo-documentation-289276551.html) | Atlassian continuous integration and continuous delivery platform. | 🟠 | -| [Travis CI](https://docs.travis-ci.com/) | Continuous integration and continuous delivery platform. | 🟠 | -| [pre-commit.ci](https://pre-commit.ci/) | A bot that adds a pre-commit job to your GitHub Actions CI, and can automatically fix most trivial linting failures. Free for open-source projects. | 🟒 | +| Name | Short description | 🚦 | +| ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------: | +| [GitHub Actions](https://docs.github.com/en/actions) | Continuous integration and continuous delivery platform (integrated with GitHub). | Best | +| [AppVeyor](https://www.appveyor.com/docs/) | Continuous integration and continuous delivery platform. | Good | +| [Bamboo](https://confluence.atlassian.com/bamboo/bamboo-documentation-289276551.html) | Atlassian continuous integration and continuous delivery platform. | Good | +| [Travis CI](https://docs.travis-ci.com/) | Continuous integration and continuous delivery platform. | Good | +| [pre-commit.ci](https://pre-commit.ci/) | A bot that adds a pre-commit job to your GitHub Actions CI, and can automatically fix most trivial linting failures. Free for open-source projects. | Best | -
🟒 explanation +
Best explanation We have many projects using GitHub CI and, it has good integration with GitHub itself, and is free for public repositories (with limited free monthly minutes for private repositories).
@@ -24,11 +24,11 @@ code with highlighting to show which lines are not executed by tests. See [testing](testing) for our recommendations on packages to generate code coverage during tests. -| Name | Short description | 🚦 | -| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-: | -| [Codecov](https://docs.codecov.com/docs) | Hosted service to report code coverage metrics. Occasionally slow to update after a report is updated, can be configured to add extra CI checks. This service is probably more widely used and is [free for both open-source and private projects](https://about.codecov.io/pricing/). | 🟒 | -| [Coveralls](https://docs.coveralls.io/) | Hosted service to report code coverage metrics. Very similar to codecov and we don't strongly recommend one over the other. This service is only [free for open-source projects](https://coveralls.io/pricing). | 🟒 | +| Name | Short description | 🚦 | +| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-----------------------------------------: | +| [Codecov](https://docs.codecov.com/docs) | Hosted service to report code coverage metrics. Occasionally slow to update after a report is updated, can be configured to add extra CI checks. This service is probably more widely used and is [free for both open-source and private projects](https://about.codecov.io/pricing/). | Best | +| [Coveralls](https://docs.coveralls.io/) | Hosted service to report code coverage metrics. Very similar to codecov and we don't strongly recommend one over the other. This service is only [free for open-source projects](https://coveralls.io/pricing). | Best | -
🟒 explanation -Both services are similar, so both 🟒. +
Best explanation +Both services are similar, so both Best.
diff --git a/docs/pages/community.md b/docs/pages/community.md index 01cb7292..a7d931de 100644 --- a/docs/pages/community.md +++ b/docs/pages/community.md @@ -11,11 +11,11 @@ space, you should consider joining an existing community space. Common topics discussed in these communities can be developers meetings, ideas for new directions, and general help and support for users. -| Name | Short description | 🚦 | -| ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-: | -| [Slack](https://slack.com/intl/en-gb/) | Instant messaging platform. For projects with UCL, any University of London, and UCL-ARC collaborators we have the [Research Programming Hub](ucl-programming-hub.slack.com) Slack channel. Any member of ARC can create a project channel. Note, however, the limitation for external collaborators. | 🟒 | -| [Discord](https://discord.com/) | An instant messaging and VoIP platform built around virtual communities called servers. It has options for private channels, moderation tools and custom member access. It also has voice channels, which can be created in a server and users can pop in to have a multi-user voice or video call. | 🟠 | -| [Discourse](https://discourse.org/) | Discussion forum. | 🟠 | -| [GitHub discussions](https://docs.github.com/en/discussions) | Discussion forum built into GitHub repositories. | 🟠 | -| [Gitter](https://gitter.im/) | Open-source instant messaging platform. Links directly to GitLab or GitHub repositories. | 🟠 | -| [Zulip](https://zulip.com/) | Open source chat and collaborative software with topic-based threading. It has a public access option, with which anyone can browse an organization's public content with no account required. The free option also provides access to your organization's entire message history. | 🟠 | +| Name | Short description | 🚦 | +| ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------: | +| [Slack](https://slack.com/intl/en-gb/) | Instant messaging platform. For projects with UCL, any University of London, and UCL-ARC collaborators we have the [Research Programming Hub](ucl-programming-hub.slack.com) Slack channel. Any member of ARC can create a project channel. Note, however, the limitation for external collaborators. | Best | +| [Discord](https://discord.com/) | An instant messaging and VoIP platform built around virtual communities called servers. It has options for private channels, moderation tools and custom member access. It also has voice channels, which can be created in a server and users can pop in to have a multi-user voice or video call. | Good | +| [Discourse](https://discourse.org/) | Discussion forum. | Good | +| [GitHub discussions](https://docs.github.com/en/discussions) | Discussion forum built into GitHub repositories. | Good | +| [Gitter](https://gitter.im/) | Open-source instant messaging platform. Links directly to GitLab or GitHub repositories. | Good | +| [Zulip](https://zulip.com/) | Open source chat and collaborative software with topic-based threading. It has a public access option, with which anyone can browse an organization's public content with no account required. The free option also provides access to your organization's entire message history. | Good | diff --git a/docs/pages/docs.md b/docs/pages/docs.md index 7315af7a..c80b5bce 100644 --- a/docs/pages/docs.md +++ b/docs/pages/docs.md @@ -25,12 +25,12 @@ If you're using GitHub, one option is to host your docs on [GitHub pages]. ### Documentation build tools -| Name | Short description | 🚦 | -| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-: | -| [MkDocs] | Generates documentation from Markdown files, with a plugin to generate API documentation. A good plugin ecosystem and balance of usability and customisability. | 🟒 | -| [Sphinx] | Generates documentation from reStructuredText or Markdown files, long been the de-facto standard and very widely used. Mature plugin ecosystem. | 🟠 | -| [gitbook] | General documentation builder; integrates with GitHub. | 🟠 | -| [pdoc] | Auto-generates API documentation from docstrings, beginner friendly but with less of a plugin ecosystem than others. | 🟠 | +| Name | Short description | 🚦 | +| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------: | +| [MkDocs] | Generates documentation from Markdown files, with a plugin to generate API documentation. A good plugin ecosystem and balance of usability and customisability. | Best | +| [Sphinx] | Generates documentation from reStructuredText or Markdown files, long been the de-facto standard and very widely used. Mature plugin ecosystem. | Good | +| [gitbook] | General documentation builder; integrates with GitHub. | Good | +| [pdoc] | Auto-generates API documentation from docstrings, beginner friendly but with less of a plugin ecosystem than others. | Good |
More details about Sphinx @@ -61,13 +61,13 @@ community that heavily uses [Sphinx] then we recommend you use that instead. ### MkDocs plugins -| Name | Short description | 🚦 | -| ------------------------------------------------------------- | -------------------------------------------- | :-: | -| [mkdocstrings-python](https://mkdocstrings.github.io/python/) | Automatically generates API reference pages. | 🟒 | +| Name | Short description | 🚦 | +| ------------------------------------------------------------- | -------------------------------------------- | :-----------------------------------------: | +| [mkdocstrings-python](https://mkdocstrings.github.io/python/) | Automatically generates API reference pages. | Best | ### Sphinx extensions -| Name | Short description | 🚦 | -| -------------------------------------------------------------------- | ---------------------------------------------------------------- | :-: | -| [sphinx-gallery](https://sphinx-gallery.github.io/stable/index.html) | Builds an HTML gallery of examples from a set of Python scripts. | 🟒 | -| [sphinx-autoapi](https://sphinx-autoapi.readthedocs.io/en/stable/) | Automatically generates API reference pages. | 🟒 | +| Name | Short description | 🚦 | +| -------------------------------------------------------------------- | ---------------------------------------------------------------- | :-----------------------------------------: | +| [sphinx-gallery](https://sphinx-gallery.github.io/stable/index.html) | Builds an HTML gallery of examples from a set of Python scripts. | Best | +| [sphinx-autoapi](https://sphinx-autoapi.readthedocs.io/en/stable/) | Automatically generates API reference pages. | Best | diff --git a/docs/pages/libraries/bindings.md b/docs/pages/libraries/bindings.md index 05839831..047875e4 100644 --- a/docs/pages/libraries/bindings.md +++ b/docs/pages/libraries/bindings.md @@ -8,20 +8,20 @@ parent: Recommended libraries ### C/C++ -| Name | Short description | 🚦 | -| --------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | :-: | -| [Cython](https://cython.readthedocs.io/en/latest/src/userguide/wrapping_CPlusPlus.html) | C/C++ binding library with numpy array integration | 🟒 | -| [ctypes](https://docs.python.org/3.8/library/ctypes.html) | Native python method for calling functions in shared C libraries | 🟠 | -| [pybind11](https://github.com/pybind/pybind11) | Bindings to C++ with a steep learning curve | 🟠 | +| Name | Short description | 🚦 | +| --------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | :------------------------------------------: | +| [Cython](https://cython.readthedocs.io/en/latest/src/userguide/wrapping_CPlusPlus.html) | C/C++ binding library with numpy array integration | Best | +| [ctypes](https://docs.python.org/3.8/library/ctypes.html) | Native python method for calling functions in shared C libraries | Good | +| [pybind11](https://github.com/pybind/pybind11) | Bindings to C++ with a steep learning curve | Good | ### Rust -| Name | Short description | 🚦 | -| ------------------------------------ | ---------------------------------------------------------------------------------------------- | :-: | -| [pyO3](https://github.com/PyO3/pyo3) | Straightforward bindings to rust with support for [packaging](https://github.com/PyO3/maturin) | 🟒 | +| Name | Short description | 🚦 | +| ------------------------------------ | ---------------------------------------------------------------------------------------------- | :-----------------------------------------: | +| [pyO3](https://github.com/PyO3/pyo3) | Straightforward bindings to rust with support for [packaging](https://github.com/PyO3/maturin) | Best | ### Fortran -| Name | Short description | 🚦 | -| ---------------------------------------------------------------- | -------------------------------------- | :-: | -| [f2py](https://numpy.org/devdocs/f2py/f2py.getting-started.html) | Bindings to Fortran developed by numpy | 🟠 | +| Name | Short description | 🚦 | +| ---------------------------------------------------------------- | -------------------------------------- | :------------------------------------------: | +| [f2py](https://numpy.org/devdocs/f2py/f2py.getting-started.html) | Bindings to Fortran developed by numpy | Good | diff --git a/docs/pages/libraries/clis.md b/docs/pages/libraries/clis.md index 87305914..aa3002a3 100644 --- a/docs/pages/libraries/clis.md +++ b/docs/pages/libraries/clis.md @@ -6,16 +6,16 @@ parent: Recommended libraries ## Command-line interfaces -| Name | Short description | 🚦 | -| ----------------------------------------------------------- | ------------------------------------------------------------------------------ | :-: | -| [typer](https://typer.tiangolo.com/) | A user-friendly and intuitive CLI system. Built on click. | 🟒 | -| [click](https://click.palletsprojects.com/) | Makes nice-looking CLIs, and more configurable than argparse. Uses decorators. | 🟠 | -| [argparse](https://docs.python.org/3/library/argparse.html) | Python's builtin CLI system uses object configuration. | 🟠 | -| [optparse](https://docs.python.org/3/library/optparse.html) | A now-deprecated CLI system built into Python. | πŸ”΄ | +| Name | Short description | 🚦 | +| ----------------------------------------------------------- | ------------------------------------------------------------------------------ | :------------------------------------------: | +| [typer](https://typer.tiangolo.com/) | A user-friendly and intuitive CLI system. Built on click. | Best | +| [click](https://click.palletsprojects.com/) | Makes nice-looking CLIs, and more configurable than argparse. Uses decorators. | Good | +| [argparse](https://docs.python.org/3/library/argparse.html) | Python's builtin CLI system uses object configuration. | Good | +| [optparse](https://docs.python.org/3/library/optparse.html) | A now-deprecated CLI system built into Python. | Avoid | ### Other useful tools for CLIs -| Name | Short description | 🚦 | -| ----------------------------------------------------- | -------------------------------------------------------------- | :-: | -| [tqdm](https://tqdm.github.io/) | Progress bar for loops. | 🟒 | -| [inquirer](https://github.com/magmax/python-inquirer) | Collection of common interactive command line user interfaces. | 🟒 | +| Name | Short description | 🚦 | +| ----------------------------------------------------- | -------------------------------------------------------------- | :-----------------------------------------: | +| [tqdm](https://tqdm.github.io/) | Progress bar for loops. | Best | +| [inquirer](https://github.com/magmax/python-inquirer) | Collection of common interactive command line user interfaces. | Best | diff --git a/docs/pages/libraries/guis.md b/docs/pages/libraries/guis.md index d68b8049..499fdcd7 100644 --- a/docs/pages/libraries/guis.md +++ b/docs/pages/libraries/guis.md @@ -6,12 +6,12 @@ parent: Recommended libraries ## Graphical user interface toolkits -| Name | Short description | 🚦 | -| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-: | -| [QtPy] | A Python interface to the [Qt] GUI system. Recommended if you need to be binding-independent. | 🟒 | -| [PySlide] | A Python binding to the [Qt] GUI system. Recommended if you're developing an app that you'll build and distribute as an executable. In which case you don't need to be binding-independent. | 🟒 | -| [PyQt] | A Python binding to the [Qt] GUI system. A specific binding but with a more restrictive license. | 🟠 | -| [tkinter] | A Python interface to the Tcl/Tk GUI toolkit. Built into the Python standard library. | 🟠 | +| Name | Short description | 🚦 | +| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------: | +| [QtPy] | A Python interface to the [Qt] GUI system. Recommended if you need to be binding-independent. | Best | +| [PySlide] | A Python binding to the [Qt] GUI system. Recommended if you're developing an app that you'll build and distribute as an executable. In which case you don't need to be binding-independent. | Best | +| [PyQt] | A Python binding to the [Qt] GUI system. A specific binding but with a more restrictive license. | Good | +| [tkinter] | A Python interface to the Tcl/Tk GUI toolkit. Built into the Python standard library. | Good | diff --git a/docs/pages/libraries/jupyter-notebooks.md b/docs/pages/libraries/jupyter-notebooks.md index ffb78563..5fb8eb8e 100644 --- a/docs/pages/libraries/jupyter-notebooks.md +++ b/docs/pages/libraries/jupyter-notebooks.md @@ -14,11 +14,11 @@ running and recording the results of numerical experiments for example. ### Live executable environments -| Name | Short description | 🚦 | -| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-: | -| [binder](https://mybinder.org/) | Turns a Git repository into a collection of interactive notebooks | 🟒 | -| [Google Colab](https://colab.google/) | Colab is a hosted Jupyter Notebook service that requires no setup to use and provides free access to computing resources, including GPUs and TPUs. | 🟒 | -| [GitHub codespaces with JupyterLab](https://docs.github.com/en/codespaces/developing-in-a-codespace/getting-started-with-github-codespaces-for-machine-learning#opening-your-codespace-in-jupyterlab) | A codespace is a development environment that is hosted in the cloud and can run [Python and Jupyter notebooks](https://github.com/github/codespaces-jupyter) | 🟠 | +| Name | Short description | 🚦 | +| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------: | +| [binder](https://mybinder.org/) | Turns a Git repository into a collection of interactive notebooks | Best | +| [Google Colab](https://colab.google/) | Colab is a hosted Jupyter Notebook service that requires no setup to use and provides free access to computing resources, including GPUs and TPUs. | Best | +| [GitHub codespaces with JupyterLab](https://docs.github.com/en/codespaces/developing-in-a-codespace/getting-started-with-github-codespaces-for-machine-learning#opening-your-codespace-in-jupyterlab) | A codespace is a development environment that is hosted in the cloud and can run [Python and Jupyter notebooks](https://github.com/github/codespaces-jupyter) | Good | ### Linting @@ -29,18 +29,18 @@ tool that can be used to run our recommended linters over notebooks. There is one exception: we've found that [black]'s own Jupyter extension works more reliably than [black] via [nbQA]. -| Name | Short description | 🚦 | -| ---------------- | -------------------------------------------------------------------------------- | :-: | -| `black[jupyter]` | (also `black-jupyter`) [black] with the optional Jupyter extension. | 🟒 | -| [nbQA] | Recommended for all other linters ([ruff], [isort]) and [mypy]. | 🟒 | -| [pre-commit] | Has cell output cleanup hooks (if desired). Also found to work well with [nbQA]. | 🟒 | -| `nbqa black` | [black] via [nbQA]. | 🟠 | +| Name | Short description | 🚦 | +| ---------------- | -------------------------------------------------------------------------------- | :------------------------------------------: | +| `black[jupyter]` | (also `black-jupyter`) [black] with the optional Jupyter extension. | Best | +| [nbQA] | Recommended for all other linters ([ruff], [isort]) and [mypy]. | Best | +| [pre-commit] | Has cell output cleanup hooks (if desired). Also found to work well with [nbQA]. | Best | +| `nbqa black` | [black] via [nbQA]. | Good | ### Other -| Name | Short description | 🚦 | -| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | :-: | -| [jupytext] | Automatically convert notebooks to/from a plain text format that is more human readable and better for version control than the standard notebook format. | 🟒 | +| Name | Short description | 🚦 | +| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | :-----------------------------------------: | +| [jupytext] | Automatically convert notebooks to/from a plain text format that is more human readable and better for version control than the standard notebook format. | Best | diff --git a/docs/pages/libraries/logging.md b/docs/pages/libraries/logging.md index 586b595e..84a7dacc 100644 --- a/docs/pages/libraries/logging.md +++ b/docs/pages/libraries/logging.md @@ -6,7 +6,7 @@ parent: Recommended libraries ## Logging -| Name | Short description | 🚦 | -| --------------------------------------------------------- | -------------------------------------------------------------------- | :-: | -| [loguru](https://loguru.readthedocs.io/) | Simple and user-friendly with many nice features enabled by default. | 🟒 | -| [logging](https://docs.python.org/3/library/logging.html) | Python's builtin logging framework. Needs some configuration. | 🟠 | +| Name | Short description | 🚦 | +| --------------------------------------------------------- | -------------------------------------------------------------------- | :------------------------------------------: | +| [loguru](https://loguru.readthedocs.io/) | Simple and user-friendly with many nice features enabled by default. | Best | +| [logging](https://docs.python.org/3/library/logging.html) | Python's builtin logging framework. Needs some configuration. | Good | diff --git a/docs/pages/libraries/parallel-async.md b/docs/pages/libraries/parallel-async.md index fe47f3cc..6af45f56 100644 --- a/docs/pages/libraries/parallel-async.md +++ b/docs/pages/libraries/parallel-async.md @@ -15,36 +15,36 @@ tools which run the tasks to be parallelised outside of the Python interpreter, using for example Python wrappers around external code which uses thread-based parallelism. -🟠 tools in the following should be chosen, if there are external reasons to use +Good tools in the following should be chosen, if there are external reasons to use a specific interface or parallelisation scheme. Possibly due to the nature of the research problem, the high-performance computing resources available or simply due to pre-existing code using a library like [pandas]. ### Process-based (and thread-based) parallelism -| Name | Short description | 🚦 | -| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-: | -| [multiprocess] | A fork of [multiprocessing] which uses `dill` instead of `pickle` to allow serializing wider range of object types including nested / anonymous functions. We've found this easier to use than `multiprocessing`. | 🟒 | -| [concurrent.futures] | [See the table below](#asynchronous-processing). | 🟠 | -| [dask] | Aims to make scaling existing code in familiar libraries (`numpy`, [pandas], `scikit-learn`, ...) easy. | 🟠 | -| [multiprocessing] | The standard library module for distributing tasks across multiple processes. | 🟠 | -| [mpi4py] | Support for MPI based parallelism. | 🟠 | -| [threading] | The standard library module for multi-threading. Due to the _global interpreter lock_ [currently][PEP703] only one thread can execute Python code at a time. | πŸ”΄ | +| Name | Short description | 🚦 | +| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------: | +| [multiprocess] | A fork of [multiprocessing] which uses `dill` instead of `pickle` to allow serializing wider range of object types including nested / anonymous functions. We've found this easier to use than `multiprocessing`. | Best | +| [concurrent.futures] | [See the table below](#asynchronous-processing). | Good | +| [dask] | Aims to make scaling existing code in familiar libraries (`numpy`, [pandas], `scikit-learn`, ...) easy. | Good | +| [multiprocessing] | The standard library module for distributing tasks across multiple processes. | Good | +| [mpi4py] | Support for MPI based parallelism. | Good | +| [threading] | The standard library module for multi-threading. Due to the _global interpreter lock_ [currently][PEP703] only one thread can execute Python code at a time. | Avoid | ### Compiler-based parallelism -| Name | Short description | 🚦 | -| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-: | -| [Cython] | Has [support for OpenMP based parallelism](https://cython.readthedocs.io/en/latest/src/userguide/parallelism.html) | 🟠 | -| [numba] | [Support for parallelism via `jit(parallel=True)`](https://numba.readthedocs.io/en/stable/user/parallel.html). | 🟠 | -| [jax] | [Support for parallelising NumPy / scientific computing like operations using functional transforms](https://jax.readthedocs.io/en/latest/jax-101/06-parallelism.html). | 🟠 | +| Name | Short description | 🚦 | +| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------: | +| [Cython] | Has [support for OpenMP based parallelism](https://cython.readthedocs.io/en/latest/src/userguide/parallelism.html) | Good | +| [numba] | [Support for parallelism via `jit(parallel=True)`](https://numba.readthedocs.io/en/stable/user/parallel.html). | Good | +| [jax] | [Support for parallelising NumPy / scientific computing like operations using functional transforms](https://jax.readthedocs.io/en/latest/jax-101/06-parallelism.html). | Good | ### Asynchronous processing -| Name | Short description | 🚦 | -| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-: | -| [asyncio] | Python standard library for asynchronous programming with tasks run in a single-threaded event loop. Used for [cooperative multitasking](https://en.wikipedia.org/wiki/Cooperative_multitasking). | 🟠 | -| [concurrent.futures] | Another Python standard library for asynchronous processing. Provides a common interface for thread and process based concurrency as an alternative to using `multiprocess(ing)` or `threading` directly. | 🟠 | +| Name | Short description | 🚦 | +| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------: | +| [asyncio] | Python standard library for asynchronous programming with tasks run in a single-threaded event loop. Used for [cooperative multitasking](https://en.wikipedia.org/wiki/Cooperative_multitasking). | Good | +| [concurrent.futures] | Another Python standard library for asynchronous processing. Provides a common interface for thread and process based concurrency as an alternative to using `multiprocess(ing)` or `threading` directly. | Good | ### See also diff --git a/docs/pages/linting.md b/docs/pages/linting.md index 576d7d0d..aaddd8a8 100644 --- a/docs/pages/linting.md +++ b/docs/pages/linting.md @@ -11,24 +11,24 @@ for some of these. ### Code formatting -| Name | Short description | 🚦 | -| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-: | -| [pre-commit](https://pre-commit.com/) | Universal tool which performs a git hook on commit, allows you to run linters/formatters on any code. A tool to automatically run many of the tools listed below. | 🟒 | -| [ruff-format](https://github.com/astral-sh/ruff) | A drop-in replacement for `black` (and also super fast). A nice "no-need to think" code formatter. If you have your own opinions about code style, you might not like this. | 🟒 | -| [ruff](https://github.com/astral-sh/ruff) | A fast linter which incorporates a range of other linters. Notably [isort](https://pycqa.github.io/isort/) can be included as a [ruff rule](https://docs.astral.sh/ruff/rules/) (which we recommend). | 🟒 | -| [toml-sort](https://github.com/pappasam/toml-sort) | Sorts TOML files which are now part of PEP 8. | 🟒 | -| [autopep8](https://github.com/hhatto/autopep8) | Formatter which conforms to PEP 8. | 🟠 | -| [black](https://black.readthedocs.io/en/stable/) | Opinionated formatter, defaults to 88 characters per line. Widely used, but we now recommend `ruff-format` in its place. | 🟠 | -| [isort](https://pycqa.github.io/isort/) | Sorts imports alphabetically, splits into first/third party, works on python & cython code. We recommend this, but it can be included in `ruff`, which is simpler. | 🟠 | -| [pycodestyle](https://pycodestyle.pycqa.org/en/latest/) | Linter which checks for errors. | 🟠 | -| [pyflakes](https://github.com/PyCQA/pyflakes) | Linter which checks for errors. | 🟠 | -| [pylint](https://pylint.readthedocs.io/en/latest/) | Linter which checks for errors. | 🟠 | -| [sourcery](https://sourcery.ai/) | An AI code reviewer which simplifies code, has a free version but can pay for fancier features. | 🟠 | -| [yapf](https://github.com/google/yapf) | Google formatter. | 🟠 | -| [flake8](https://flake8.pycqa.org/en/latest/) | Linter which complains if code doesn't follow a rule. Does not support modern `pyproject.toml` configuration. | πŸ”΄ | +| Name | Short description | 🚦 | +| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------: | +| [pre-commit](https://pre-commit.com/) | Universal tool which performs a git hook on commit, allows you to run linters/formatters on any code. A tool to automatically run many of the tools listed below. | Best | +| [ruff-format](https://github.com/astral-sh/ruff) | A drop-in replacement for `black` (and also super fast). A nice "no-need to think" code formatter. If you have your own opinions about code style, you might not like this. | Best | +| [ruff](https://github.com/astral-sh/ruff) | A fast linter which incorporates a range of other linters. Notably [isort](https://pycqa.github.io/isort/) can be included as a [ruff rule](https://docs.astral.sh/ruff/rules/) (which we recommend). | Best | +| [toml-sort](https://github.com/pappasam/toml-sort) | Sorts TOML files which are now part of PEP 8. | Best | +| [autopep8](https://github.com/hhatto/autopep8) | Formatter which conforms to PEP 8. | Good | +| [black](https://black.readthedocs.io/en/stable/) | Opinionated formatter, defaults to 88 characters per line. Widely used, but we now recommend `ruff-format` in its place. | Good | +| [isort](https://pycqa.github.io/isort/) | Sorts imports alphabetically, splits into first/third party, works on python & cython code. We recommend this, but it can be included in `ruff`, which is simpler. | Good | +| [pycodestyle](https://pycodestyle.pycqa.org/en/latest/) | Linter which checks for errors. | Good | +| [pyflakes](https://github.com/PyCQA/pyflakes) | Linter which checks for errors. | Good | +| [pylint](https://pylint.readthedocs.io/en/latest/) | Linter which checks for errors. | Good | +| [sourcery](https://sourcery.ai/) | An AI code reviewer which simplifies code, has a free version but can pay for fancier features. | Good | +| [yapf](https://github.com/google/yapf) | Google formatter. | Good | +| [flake8](https://flake8.pycqa.org/en/latest/) | Linter which complains if code doesn't follow a rule. Does not support modern `pyproject.toml` configuration. | Avoid | ### Type checking -| Name | Short description | 🚦 | -| ---------------------------------------------- | ----------------------------------------------------------------------------- | :-: | -| [mypy](https://mypy.readthedocs.io/en/stable/) | Static type checker, won't fail if no typing but will if typing is incorrect. | 🟒 | +| Name | Short description | 🚦 | +| ---------------------------------------------- | ----------------------------------------------------------------------------- | :-----------------------------------------: | +| [mypy](https://mypy.readthedocs.io/en/stable/) | Static type checker, won't fail if no typing but will if typing is incorrect. | Best | diff --git a/docs/pages/packaging.md b/docs/pages/packaging.md index 58c0714a..45f2df32 100644 --- a/docs/pages/packaging.md +++ b/docs/pages/packaging.md @@ -25,29 +25,29 @@ a higher-level package which is effectively the same, but much easier to reuse. ## Packaging tools -| Name | Short description | 🚦 | -| --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | --- | -| [setuptools](https://setuptools.pypa.io) | A widely used build backend, used to configure a Python package. | 🟒 | -| [setuptools-scm](https://github.com/pypa/setuptools_scm/) | Provides automatic versioning Python packages. Also automatically adds all files under source control to the sdist / wheel. | 🟒 | -| [poetry](https://github.com/python-poetry/poetry) | A tool that lets you build and package your project as well as managing dependencies | 🟠 | -| [twine](https://pypi.org/project/twine/) | Tool for publishing Python packages on PyPI. | 🟠 | -| [bump2version](https://pypi.org/project/bump2version/) | Tool for version-bumping your software. No longer maintained | πŸ”΄ | -| [bump-my-version](https://github.com/callowayproject/bump-my-version) | Tool for version-bumping your software. Superseded by setuptools_scm | πŸ”΄ | +| Name | Short description | 🚦 | +| --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | +| [setuptools](https://setuptools.pypa.io) | A widely used build backend, used to configure a Python package. | Best | +| [setuptools-scm](https://github.com/pypa/setuptools_scm/) | Provides automatic versioning Python packages. Also automatically adds all files under source control to the sdist / wheel. | Best | +| [poetry](https://github.com/python-poetry/poetry) | A tool that lets you build and package your project as well as managing dependencies | Good | +| [twine](https://pypi.org/project/twine/) | Tool for publishing Python packages on PyPI. | Good | +| [bump2version](https://pypi.org/project/bump2version/) | Tool for version-bumping your software. No longer maintained | Avoid | +| [bump-my-version](https://github.com/callowayproject/bump-my-version) | Tool for version-bumping your software. Superseded by setuptools_scm | Avoid | ## Building -| Name | Short description | 🚦 | -| ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | --- | -| [build](https://pypa-build.readthedocs.io/en/stable/) | Straightforward tool to build a Python package. | 🟒 | -| [cibuildwheel](https://cibuildwheel.readthedocs.io) | Builds python wheels for the main operating systems on continuous integration runs (e.g. GitHub actions). | 🟠 | +| Name | Short description | 🚦 | +| ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | -------------------------------------------- | +| [build](https://pypa-build.readthedocs.io/en/stable/) | Straightforward tool to build a Python package. | Best | +| [cibuildwheel](https://cibuildwheel.readthedocs.io) | Builds python wheels for the main operating systems on continuous integration runs (e.g. GitHub actions). | Good | ### Package configuration file -| Name | Short description | 🚦 | -| -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --- | -| [pyproject.toml](https://pip.pypa.io/en/stable/reference/build-system/pyproject-toml/) | Contains build system requirements and information, which are used by pip to build the package. It is becoming the accepted standard and we strongly recommend it. | 🟒 | -| [setup.py](https://packaging.python.org/en/latest/guides/distributing-packages-using-setuptools/) | Strongly coupled with setuptools and therefore not recommended. | 🟠 | -| [setup.cfg](https://packaging.python.org/en/latest/guides/distributing-packages-using-setuptools/) | An ini file that contains defaults for setup.py commands. | 🟠 | +| Name | Short description | 🚦 | +| -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------- | +| [pyproject.toml](https://pip.pypa.io/en/stable/reference/build-system/pyproject-toml/) | Contains build system requirements and information, which are used by pip to build the package. It is becoming the accepted standard and we strongly recommend it. | Best | +| [setup.py](https://packaging.python.org/en/latest/guides/distributing-packages-using-setuptools/) | Strongly coupled with setuptools and therefore not recommended. | Good | +| [setup.cfg](https://packaging.python.org/en/latest/guides/distributing-packages-using-setuptools/) | An ini file that contains defaults for setup.py commands. | Good | ### Conda @@ -55,6 +55,6 @@ These tools are helpful if you're looking to publish your package on [conda-forge](https://conda-forge.org/), so users can install it through the [Conda](https://docs.conda.io/projects/conda/en/stable/) package manager. -| Name | Short description | 🚦 | -| --------------------------------------------------------- | --------------------------------------------------------------------------- | :-: | -| [GraySkull](https://github.com/conda-incubator/grayskull) | A tool for automatic Conda recipe generation (aimed at conda-forge, above). | 🟒 | +| Name | Short description | 🚦 | +| --------------------------------------------------------- | --------------------------------------------------------------------------- | :-----------------------------------------: | +| [GraySkull](https://github.com/conda-incubator/grayskull) | A tool for automatic Conda recipe generation (aimed at conda-forge, above). | Best | diff --git a/docs/pages/refactoring.md b/docs/pages/refactoring.md index 9d381e05..8f6da92f 100644 --- a/docs/pages/refactoring.md +++ b/docs/pages/refactoring.md @@ -5,8 +5,8 @@ layout: default ## Refactoring Tools -| Name | Short description | 🚦 | -| ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | --- | -| [jedi](https://jedi.readthedocs.io/en/stable/) | Refactoring and autocompletion used in [IDEs](https://en.wikipedia.org/wiki/Integrated_development_environment). | 🟒 | -| [sourcery.ai](https://sourcery.ai) | Refactoring suggestions and code review. Free for open source. | 🟠 | -| [rope](https://rope.readthedocs.io/en/stable/overview.html) | Refactoring library. | 🟠 | +| Name | Short description | 🚦 | +| ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | +| [jedi](https://jedi.readthedocs.io/en/stable/) | Refactoring and autocompletion used in [IDEs](https://en.wikipedia.org/wiki/Integrated_development_environment). | Best | +| [sourcery.ai](https://sourcery.ai) | Refactoring suggestions and code review. Free for open source. | Good | +| [rope](https://rope.readthedocs.io/en/stable/overview.html) | Refactoring library. | Good | diff --git a/docs/pages/templates.md b/docs/pages/templates.md index 83da2e9b..a4e6bc04 100644 --- a/docs/pages/templates.md +++ b/docs/pages/templates.md @@ -35,10 +35,10 @@ their package template. Tools that can be used for creating your own package template. -| Name | Short description | 🚦 | -| ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | :-: | -| [Cookiecutter](https://github.com/cookiecutter/cookiecutter) | Widely-used tool for creating project templates | 🟒 | -| [Copier](https://github.com/copier-org/copier) | A tool to create project templates that are highly configurable. Project configuration can be kept in sync with the templae. | 🟠 | -| [Cruft](https://github.com/cruft/cruft) | Can be used to create projects from a cookiecutter template and to keep the project configuration in sync with the template. | 🟠 | -| [GitHub templates](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-template-repository) | GitHub repositories can be used as templates, but they are not configurable. | 🟠 | -| [Cookieninja](https://github.com/cookieninja-generator/cookieninja) | A fork of Cookiecutter that is not actively maintained. | πŸ”΄ | +| Name | Short description | 🚦 | +| ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------: | +| [Cookiecutter](https://github.com/cookiecutter/cookiecutter) | Widely-used tool for creating project templates | Best | +| [Copier](https://github.com/copier-org/copier) | A tool to create project templates that are highly configurable. Project configuration can be kept in sync with the templae. | Good | +| [Cruft](https://github.com/cruft/cruft) | Can be used to create projects from a cookiecutter template and to keep the project configuration in sync with the template. | Good | +| [GitHub templates](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-template-repository) | GitHub repositories can be used as templates, but they are not configurable. | Good | +| [Cookieninja](https://github.com/cookieninja-generator/cookieninja) | A fork of Cookiecutter that is not actively maintained. | Avoid | diff --git a/docs/pages/testing.md b/docs/pages/testing.md index 93dd827b..8428783c 100644 --- a/docs/pages/testing.md +++ b/docs/pages/testing.md @@ -7,22 +7,22 @@ layout: default ### Test runners -| Name | Short description | 🚦 | -| ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-: | -| [pytest](https://docs.pytest.org/en/stable/contents.html) | A framework for writing and running tests. We recommend `pytest` over `unittest` because `pytest` tends to encourage a cleaner style, there are also extensive plugins and it's in widespread use. | 🟒 | -| [tox](https://tox.wiki/en/latest/index.html) | A framework that allows running tests and packaging in different environments. | 🟒 | -| [unittest](https://docs.python.org/dev/library/unittest.html#module-unittest) | Python's built in framework for writing and running tests. Encourages use of classes as test fixtures. | 🟠 | +| Name | Short description | 🚦 | +| ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------: | +| [pytest](https://docs.pytest.org/en/stable/contents.html) | A framework for writing and running tests. We recommend `pytest` over `unittest` because `pytest` tends to encourage a cleaner style, there are also extensive plugins and it's in widespread use. | Best | +| [tox](https://tox.wiki/en/latest/index.html) | A framework that allows running tests and packaging in different environments. | Best | +| [unittest](https://docs.python.org/dev/library/unittest.html#module-unittest) | Python's built in framework for writing and running tests. Encourages use of classes as test fixtures. | Good | ### pytest plugins -| Name | Short description | 🚦 | -| ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-: | -| [pytest-cov](https://pytest-cov.readthedocs.io/en/latest/index.html) | A framework to generate coverage reports that plays nicely with `pytest`. | 🟒 | -| [pytest-mock](https://pytest-mock.readthedocs.io/en/latest/index.html) | A framework to mock/patch objects that plays nicely with `pytest`. | 🟒 | -| [pyfakefs](https://pytest-pyfakefs.readthedocs.io/en/latest/) | A plugin to create a full fake file system, for situations where you need something more complicated than the built in [`tmp_path` fixture](https://docs.pytest.org/en/stable/how-to/tmp_path.html#how-to-use-temporary-directories-and-files-in-tests). | 🟒 | +| Name | Short description | 🚦 | +| ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-----------------------------------------: | +| [pytest-cov](https://pytest-cov.readthedocs.io/en/latest/index.html) | A framework to generate coverage reports that plays nicely with `pytest`. | Best | +| [pytest-mock](https://pytest-mock.readthedocs.io/en/latest/index.html) | A framework to mock/patch objects that plays nicely with `pytest`. | Best | +| [pyfakefs](https://pytest-pyfakefs.readthedocs.io/en/latest/) | A plugin to create a full fake file system, for situations where you need something more complicated than the built in [`tmp_path` fixture](https://docs.pytest.org/en/stable/how-to/tmp_path.html#how-to-use-temporary-directories-and-files-in-tests). | Best | ## Property based testing -| Name | Short description | 🚦 | -| ------------------------------------------------------------------------- | ------------------------------------------------------------------------ | :-: | -| [Hypothesis](https://hypothesis.readthedocs.io/en/latest/quickstart.html) | Allows one to easily test multiple inputs for a given function with ease | 🟒 | +| Name | Short description | 🚦 | +| ------------------------------------------------------------------------- | ------------------------------------------------------------------------ | :-----------------------------------------: | +| [Hypothesis](https://hypothesis.readthedocs.io/en/latest/quickstart.html) | Allows one to easily test multiple inputs for a given function with ease | Best | diff --git a/docs/pages/virtual.md b/docs/pages/virtual.md index a0bd4a08..f0c5aaa8 100644 --- a/docs/pages/virtual.md +++ b/docs/pages/virtual.md @@ -5,16 +5,16 @@ layout: default ## Virtual environments -| Name | Short description | 🚦 | -| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-: | -| conda-forge [miniforge] | Installs, runs, and updates packages and their dependencies. Uses `conda`, but with community maintained packages from `conda-forge` channel instead of commercially maintained packages. | 🟒 | -| [uv] | Fast dependency (and project) management tool. A drop-in replacement for `venv`. This will probably become our 🟒 tool, but for now we are playing cautious as there are some open bugs and features. If you're comfortable using `venv` syntax we'd recommend this. | 🟠 | -| [pipenv] | Automatically creates and manages a virtualenv for your projects. | 🟠 | -| [pixi] | A fast drop-in replacement for `conda`. | 🟠 | -| [pyenv] | Lets you easily switch between multiple versions of Python. | 🟠 | -| [virtualenv] | Creates isolated Python environments, and offers more features than venv. | 🟠 | -| [venv] | Creates isolated Python environments. Fewer features than other tools, but very widely used and comes built into Python. | 🟠 | -| [anaconda] | Due to recent [licensing ambiguity][anaconda-problems], we recommend avoiding anaconda and many of the default channels. We recommend installing miniforge and sticking to the `conda-forge` channel. | πŸ”΄ | +| Name | Short description | 🚦 | +| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------: | +| conda-forge [miniforge] | Installs, runs, and updates packages and their dependencies. Uses `conda`, but with community maintained packages from `conda-forge` channel instead of commercially maintained packages. | Best | +| [uv] | Fast dependency (and project) management tool. A drop-in replacement for `venv`. This will probably become our Best tool, but for now we are playing cautious as there are some open bugs and features. If you're comfortable using `venv` syntax we'd recommend this. | Good | +| [pipenv] | Automatically creates and manages a virtualenv for your projects. | Good | +| [pixi] | A fast drop-in replacement for `conda`. | Good | +| [pyenv] | Lets you easily switch between multiple versions of Python. | Good | +| [virtualenv] | Creates isolated Python environments, and offers more features than venv. | Good | +| [venv] | Creates isolated Python environments. Fewer features than other tools, but very widely used and comes built into Python. | Good | +| [anaconda] | Due to recent [licensing ambiguity][anaconda-problems], we recommend avoiding anaconda and many of the default channels. We recommend installing miniforge and sticking to the `conda-forge` channel. | Avoid |