[ENH] handle dependencies by pypi pyfar-gallery package

[ahms5]

I would suggest to define the dependencies in the pyproject.toml similar to other packages. Then we could just publish this as an pypi package with versions, and pypi can handle the dependencies for us.

The required requirements.txt for bilder could just include pyfar-gallery and the dependency hint at the beginning of each notebook would just be pip install pyfar-gallery.

an alternative name would be pyfar-examples, pyfar-gallery could be better as it is the same name used for readthedocs.

[project]
name = "pyfar-gallery"
version = "0.1.0"
description = "Dependencies for the pyfar example gallery."
readme = "README.md"
license = {file = "LICENSE"}
requires-python = ">=3.11"
authors = [
    { name = "The pyfar developers", email = "info@pyfar.org" },
]
dependencies = [
    "numpy>=1.23.0",
    "scipy>=1.5.0",
    "matplotlib",
    "pyfar>=0.8.0",
    "sofar>=1.2.0",
    "spharpy>=1.0.0",
    "pyrato>=1.0.0",
    "urllib3",
    "soundfile>=0.11.0",
    "sounddevice",
    "deepdiff",
    "ipykernel",
    "ipympl",
    "pooch",
    "watermark",
    "pytz",
]

[project.optional-dependencies]
deploy = [
    "bump-my-version",
    "wheel",
    "twine",
    ]
tests = [
    "watchdog",
    "pytest<8.1.0",
    "pytest-runner",
    "pytest-cov",
    "coverage",
    "flake8",
    "nbmake>=0.7.0",
    "pre-commit",
]
docs = [
    "Sphinx",
    "pydata-sphinx-theme",
    "autodocsumm>=0.2.14",
    "nbsphinx",
    "nbsphinx-link",
    "sphinx-gallery",
    "sphinx-design",
    "sphinx-favicon",
    "sphinx-copybutton",
]
dev = ["pyfar-gallery[deploy,tests,docs]"]

This is just an inital draft, we could also think of other usefull optional-dependencies.

This would solve the problem of double dependency handling discussed in #136
related to #101

If we decide to do that, I would like to implement it.

[ahms5]

This would solve the problem of maintaining double dependencies, of

• the notebook itself: as comments or pip install commands.
  • this would be also very difficult to test automatically, as you would need to deinstall and install the requirements for each notebook
• in the requirements.txt: required for ci testing and binder.

The proposed option would have the following advantages:

• one ci tested definition of dependencies
• dependencies can be versioned, each notebook could state e.g. pip install pyfar-galery==0.1.0, this could be updated from bump-my-version on release.
• very easy to maintain
• users can run one install command and dont need to think about dependencies.

An other option, which was discussed is to have optional dependencies for each notebook, this would prevent to have more installs as needed, but on the other hand, ci testing and maintaining would be a nightmare.

[sikersten]

Thank you for this suggestion! I'd like to add the point that it would be nice to make the dependencies easily trackable by the users to answer the question "What do I need to have installed in my environment to use the functionality presented in the notebook?".

Otherwise, the easy way to go for a unexperienced user (who we try to help with making the requirements transparent) would be to simply pip install pyfar-gallery all the time when using any pyfar package. However, then more dependencies than necessary are installed. For example, the Getting Started notebooks simply require pyfar (plus ipykernel), but not sofar, spharpy, pyrato ... With an emerging pyfar ecosystem, this will lead to increased amounts of dependencies in the future due to the various requirements of these packages.

One solution would be to let the users know the individual requirements from the imports. However, this ignores cross-dependencies, e.g. pip install pyfar automatically installs correct versions of numpy and matplotlib.

Therefore I think it is worth considering the two solutions you already mentioned, which could also be combined:

• Define dependencies per notebook or groups of notebooks in pyproject.toml. For example, pip install pyfar-gallery[getting_started] would only install pyfar to execute the Getting Started notebooks, pip install pyfar-gallery[sofar] for the sofar and SOFA notebook ...
• Add a short explanation at the beginning of each notebook with the individual requirements, e.g., "Please ensure that pyfar and ipykernel are installed in your environment by running pip install pyfar ipykernel (or pip install pyfar-gallery[getting_started] when combined with the first solution)".

Both of these solutions require tracking of the individual requirements per notebook. While this may be a bit more effort for the existing notebooks (not too complex, usually low number of packages is required), it is easy to implement for new notebooks. I agree, this would increase maintenance efforts, but does not seem like a nightmare to me. Testing could still be done with collecting the requirements for all notebooks.

[ahms5]

One solution would be to let the users know the individual requirements from the imports. However, this ignores cross-dependencies, e.g. pip install pyfar automatically installs correct versions of numpy and matplotlib.

I think good practice is to install all packages which are imported by the notebook, e.g. if we use numpy directly, we should also add it to the install command, even pyfar would also install it. It might be the case that pyfar will drop this dependency at some point and than it would not work anymore.

Testing could still be done with collecting the requirements for all notebooks.

This would test the notebooks functionality, but not whether the dependecies per notebook are correct.
The proposes solution would solve this issue, with the drawback that the user has to install all requirements for a single notebook.

• One point from my side would also be that the purpose of the notebooks is to teach how to use pyfar therefore we need to provide the dependencies somehow and not to teach about dependencies itself. If we want to teach about dependencies, we could introduce a notebook, which explains it.