From 2684dfac35a829a123983b1c5877a7849e2900af Mon Sep 17 00:00:00 2001 From: Felix Oesterle Date: Mon, 5 May 2025 12:47:20 +0200 Subject: [PATCH 1/2] chore(release): switch to pixi and hatchling build backend; fixes #1122 - Introduce `__about__.py` for runtime version access. - Update `setup.py` to use hatchling. - Add pixi configuration for dependency and environment management. - chore(pyproject): update dependencies and Python version requirements - docs(installation): update installation instructions with pixi information - docs(developinstallwin): update Windows installation guide for AvaFrame Clarify installation steps for Windows users by: - Removing outdated information regarding Python 3.13 - Streamlining conda environment setup instructions - Adding note about potential Powershell access issues - Emphasizing the command to run for setting execution policy chore(pyproject): update versioning options and add osx support --- docs/developinstall.rst | 34 +++++++-------- docs/developinstallwin.rst | 33 ++++++++------- docs/gettingstarted.rst | 3 +- pyproject.toml | 84 +++++++++++++++++++++++++++++++++++++- setup.py | 79 ++--------------------------------- 5 files changed, 117 insertions(+), 116 deletions(-) diff --git a/docs/developinstall.rst b/docs/developinstall.rst index 5d0f0fbd5..6b86aaf23 100644 --- a/docs/developinstall.rst +++ b/docs/developinstall.rst @@ -10,10 +10,7 @@ guide is described for **Linux**. For *Windows*, see :ref:`developinstallwin:Adv Requirements ^^^^^^^^^^^^ -Install `git `_ and python, we -suggest to work with miniconda/anaconda. For installation see `miniconda -`_ or -`anaconda `_. +Install `git `_, python and `pixi `_. Some operating systems might require the python headers (e.g python-dev on ubuntu) or other supporting libraries/packages (e.g. Visual Studio on Windows needs the c++ compiler components). @@ -21,20 +18,17 @@ libraries/packages (e.g. Visual Studio on Windows needs the c++ compiler compone Setup AvaFrame ^^^^^^^^^^^^^^ -Create a new `conda environment -`_ -for AvaFrame, activate it and install pip, numpy and cython in this environment:: - - conda create --name avaframe_env - conda activate avaframe_env - conda install pip numpy cython - Clone the AvaFrame repository (in a directory of your choice: [YOURDIR]) and change into it:: cd [YOURDIR] git clone https://github.com/avaframe/AvaFrame.git cd AvaFrame + +Run pixi:: + + pixi shell + Compile the cython com1DFA part. You might also have to install a c-compiler (gcc or similar) through your systems package manager:: @@ -44,18 +38,18 @@ package manager:: You will have to do this compilation every time something changes in the cython code. We also suggest to do this everytime updates from the repositories are pulled. -Install avaframe and its requirements by **either** doing:: - - pip install -e . - -or if this fails (see `github issue 986 `_), do:: +All this installs avaframe in editable mode, so every time you import avaframe the +current (local) version will be used. - python setup.py develop +If you want to have the lastet stable release instead, run:: -This installs avaframe in editable mode, so every time you import avaframe the -current (local) version will be used. + pixi shell --environment prod Test it by starting ``python`` and do an ``import avaframe``. If no error comes up, you are good to go. +To see the current version, you can use:: + + pixi list avaframe + Head over to :ref:`gettingstarted:First run` for the next steps. \ No newline at end of file diff --git a/docs/developinstallwin.rst b/docs/developinstallwin.rst index 9954853cd..0e4202195 100644 --- a/docs/developinstallwin.rst +++ b/docs/developinstallwin.rst @@ -3,17 +3,14 @@ Advanced Installation (Windows) This is a quick guide on how to install AvaFrame and the required dependencies on your machine. AvaFrame is developed on **Linux -machines** (Ubuntu/Manjaro/Arch) with recent Python versions > 3.8. Caution: currently unavailable for Version 3.13 +machines** (Ubuntu/Manjaro/Arch) with recent Python versions > 3.8. These instructions assume you are familiar with working in a terminal. This guide is described for **Windows**. For *Linux*, see :ref:`developinstall:Advanced Installation (Linux)`. Requirements ^^^^^^^^^^^^ -Install `git `_ and python, we -suggest to work with miniconda/anaconda. For installation see `miniconda -`_ or -`anaconda `_. +Install `git `_ Install `Microsoft C++ compiler `_. Follow the installation steps for the version corresponding to the installed python version. @@ -21,13 +18,7 @@ Follow the installation steps for the version corresponding to the installed pyt Setup AvaFrame ^^^^^^^^^^^^^^ -Open conda shell and create a new `conda environment -`_ -for AvaFrame, activate it and install pip, numpy and cython in this environment:: - - conda create --name avaframe_env - conda activate avaframe_env - conda install pip numpy cython +Might be needed: Clone the AvaFrame repository (in a directory of your choice: [YOURDIR]) and change into it:: @@ -35,6 +26,17 @@ Clone the AvaFrame repository (in a directory of your choice: [YOURDIR]) and cha git clone https://github.com/avaframe/AvaFrame.git cd AvaFrame + + +Run pixi:: + + pixi shell + +.. Note:: + If you get some access denied error in Powershell, you might need to run the command + + ``Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope CurrentUser`` + Compile the cython com1DFA part:: python setup.py build_ext --inplace @@ -46,13 +48,10 @@ Compile the cython com1DFA part:: **Before** compilation in Windows, make sure to delete ``AvaFrame/build`` directory, in addition to any .pyd, .c, and .pycache files in ``AvaFrame/avaframe/com1DFA`` -Install avaframe and its requirements by **either** doing:: - - pip install -e . +If you want to have the lastet stable release instead, run:: -or if this fails (see `github issue 986 `_), do:: + pixi shell --environment prod - python setup.py develop This installs avaframe in editable mode, so every time you import avaframe the current (local) version will be used. diff --git a/docs/gettingstarted.rst b/docs/gettingstarted.rst index f4787a81a..8eceaf62f 100644 --- a/docs/gettingstarted.rst +++ b/docs/gettingstarted.rst @@ -11,7 +11,8 @@ First run --------- -Follow these steps to run your first simulation: +Follow these steps to run your first simulation (assuming you finished the advanced installation steps; if you come +back later, make sure to run ``pixi shell`` again to activate the environment): * change into your ``AvaFrame`` directory (replace [YOURDIR] with your path from the installation steps):: diff --git a/pyproject.toml b/pyproject.toml index 9e5826345..37476a871 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,8 +1,53 @@ [build-system] # Cython dependency is optional, see setup.py for details. # For the package (run-time) dependencies, see setup.cfg. -requires = ["setuptools", "wheel", "numpy", "Cython"] -build-backend = "setuptools.build_meta" +#requires = ["setuptools", "wheel", "numpy", "Cython"] +#build-backend = "setuptools.build_meta" +requires = ["hatchling", "hatch-vcs"] +build-backend = "hatchling.build" + +[project] +name = "avaframe" +description = "The Open Avalanche Framework" +readme = "README.md" +dynamic = ["version"] +license = { text = "EUPL" } +authors = [ + { name = "AvaFrame Contributors", email = "felix@avaframe.org" } +] +urls = { Homepage = "http://avaframe.org" } +classifiers = [ + "Development Status :: 5 - Production/Stable", + "Intended Audience :: Science/Research", + "License :: OSI Approved :: European Union Public Licence 1.2 (EUPL 1.2)", + "Programming Language :: Python :: 3.8", + "Programming Language :: Python :: 3.9", + "Programming Language :: Python :: 3.10", + "Programming Language :: Python :: 3.11", + "Programming Language :: Python :: 3.12", + "Programming Language :: Python :: 3.13" +] +requires-python = ">=3.8" +dependencies = [ + "numpy", + "matplotlib", + "pyshp", + "scipy", + "cmcrameri", + "seaborn", + "cython", + "pandas", + "shapely", + "configUpdater", + "tabulate", + "deepdiff", + "deepmerge", + "psutil", + "rasterio", + "contextily", + "geopandas", + "fiona" +] [tool.flake8] max-line-length = 109 @@ -11,3 +56,38 @@ extend-ignore = ['E203', 'E501'] [tool.black] line-length = 109 + +[tool.hatch.version] +source = "vcs" + +[tool.hatch.version.raw-options] +version_scheme = "no-guess-dev" +local_scheme = "node-and-date" + +[tool.pixi.workspace] +channels = ["conda-forge/label/qgis_ltr", "https://prefix.dev/conda-forge"] +platforms = ["linux-64", "win-64", "osx-64"] + +[tool.pixi.dependencies] +pytest = "*" +setuptools = "*" + +[tool.pixi.pypi-dependencies] +#avaframe = { path = "./", editable = true } +# avaframe = "==1.11" + +[tool.pixi.feature.dev.pypi-dependencies] +avaframe = { path = "./", editable = true } + +[tool.pixi.feature.prod.pypi-dependencies] +avaframe = "*" + +[tool.pixi.feature.qgis.dependencies] +qgis = "*" + +[tool.pixi.environments] +default = { features = ["dev"], solve-group = "default" } +dev = ["dev"] +prod = ["prod"] +qgis = ["qgis", "dev"] + diff --git a/setup.py b/setup.py index 060e712dd..d62057dc7 100644 --- a/setup.py +++ b/setup.py @@ -21,81 +21,28 @@ import sys import numpy sys.path.append(str(Path(__file__).parent)) -from avaframe.version import getVersion from Cython.Build import cythonize -DISTNAME = "avaframe" -LICENSE = "EUPL" -AUTHOR = "AvaFrame Contributors" -AUTHOR_EMAIL = "felix@avaframe.org" -URL = "http://avaframe.org" -CLASSIFIERS = [ - # How mature is this project? Common values are - # 3 - Alpha 4 - Beta 5 - Production/Stable - "Development Status :: 5 - Production/Stable", - # Indicate who your project is intended for - "Intended Audience :: Science/Research", - "License :: OSI Approved :: European Union Public Licence 1.2 (EUPL 1.2)", - "Programming Language :: Python :: 3.7", - "Programming Language :: Python :: 3.8", - "Programming Language :: Python :: 3.9", - "Programming Language :: Python :: 3.10", - "Programming Language :: Python :: 3.11", - "Programming Language :: Python :: 3.12", -] - -DESCRIPTION = "The Open Avalanche Framework" - -req_packages = [ - "numpy", - "matplotlib", - "pyshp", - "scipy", - "cmcrameri", - "seaborn", - "cython", - "pandas", - "shapely", - "configUpdater", - "tabulate", - "deepdiff", - "deepmerge", - "psutil", - # Next ones are for geotiff: - "rasterio", - "contextily", - "geopandas", - # For geopackage, TODO might not be needed - "fiona", -] - - -# read the contents of your README file -this_directory = Path(__file__).parent -long_description = (this_directory / "README.md").read_text() - # Cython part setup_options = {} print("Package is built with cythonization.") setup_options = {"build_ext": {"inplace": True}} -ext = ".pyx" - extensions = [ Extension( "avaframe.com1DFA.DFAfunctionsCython", - ["avaframe/com1DFA/DFAfunctionsCython" + ext], + ["avaframe/com1DFA/DFAfunctionsCython.pyx"], include_dirs=[numpy.get_include()], ), Extension( "avaframe.com1DFA.damCom1DFA", - ["avaframe/com1DFA/damCom1DFA" + ext], + ["avaframe/com1DFA/damCom1DFA.pyx"], include_dirs=[numpy.get_include()], ), Extension( "avaframe.com1DFA.DFAToolsCython", - ["avaframe/com1DFA/DFAToolsCython" + ext], + ["avaframe/com1DFA/DFAToolsCython.pyx"], include_dirs=[numpy.get_include()], ), ] @@ -103,31 +50,11 @@ extensions = cythonize(extensions, compiler_directives={"linetrace": True}, language_level=3) setup( - # Project info - name=DISTNAME, - description=DESCRIPTION, - long_description=long_description, - long_description_content_type="text/markdown", - version=getVersion(), - - # The project's main homepage. - url=URL, - # Author details - author=AUTHOR, - author_email=AUTHOR_EMAIL, - # License - license=LICENSE, - classifiers=CLASSIFIERS, - # We are a python 3 only shop - python_requires=">=3.7", # Find packages automatically packages=find_packages(exclude=["docs"]), # Include package data include_package_data=True, # Install dependencies - install_requires=req_packages, - # additional groups of dependencies here (e.g. development dependencies). - extras_require={}, # Run build_ext options=setup_options, # Executable scripts From f9c36ab7d744948698ddf16405f19a2374c4e3ec Mon Sep 17 00:00:00 2001 From: Felix Oesterle Date: Thu, 8 May 2025 12:03:09 +0200 Subject: [PATCH 2/2] docs(developinstallwin): update installation instructions --- .gitignore | 1 + docs/developinstallwin.rst | 73 ++++++-------------------------------- docs/moduleCom4FlowPy.rst | 29 +++------------ 3 files changed, 16 insertions(+), 87 deletions(-) diff --git a/.gitignore b/.gitignore index a54e6ccc6..b324957fb 100644 --- a/.gitignore +++ b/.gitignore @@ -37,3 +37,4 @@ avaframe/**/**/Inputs/remeshedRasters avaframe/com1DFA/*.c avaframe/com1DFA/*.so +/pixi.lock diff --git a/docs/developinstallwin.rst b/docs/developinstallwin.rst index 0e4202195..c3f5c95fc 100644 --- a/docs/developinstallwin.rst +++ b/docs/developinstallwin.rst @@ -10,7 +10,7 @@ guide is described for **Windows**. For *Linux*, see :ref:`developinstall:Advanc Requirements ^^^^^^^^^^^^ -Install `git `_ +Install `git `_, python and `pixi `_. Install `Microsoft C++ compiler `_. Follow the installation steps for the version corresponding to the installed python version. @@ -18,8 +18,6 @@ Follow the installation steps for the version corresponding to the installed pyt Setup AvaFrame ^^^^^^^^^^^^^^ -Might be needed: - Clone the AvaFrame repository (in a directory of your choice: [YOURDIR]) and change into it:: cd [YOURDIR] @@ -48,81 +46,32 @@ Compile the cython com1DFA part:: **Before** compilation in Windows, make sure to delete ``AvaFrame/build`` directory, in addition to any .pyd, .c, and .pycache files in ``AvaFrame/avaframe/com1DFA`` +This installs avaframe in editable mode, so every time you import avaframe the +current (local) version will be used. + If you want to have the lastet stable release instead, run:: pixi shell --environment prod -This installs avaframe in editable mode, so every time you import avaframe the -current (local) version will be used. - Test it by starting ``python`` and do an ``import avaframe``. If no error comes up, you are good to go. -If wanted: Integrate conda environment into editor of your choice (i.e. PyCharm, Spyder or any other) - Head over to :ref:`gettingstarted:First run` for the next steps. -Using QGIS from Conda +Using QGIS from with an advanced installation ^^^^^^^^^^^^^^ -It is possible to have the script installation and the plugin installed on your machine at the same time. -However, be aware: Depending on your mode of QGis installation (direct installer, conda, OSGeo4W...) your script AvaFrame installation might be overruled. - -The steps below install QGis and the Connector plugin in a separate *conda* environment. If the steps above have been followed, this method will result in two script installations where one will be used by QGis and the other can be worked on separately, preventing any overlap. - -If you have another QGis installation somewhere, make sure that the AvaFrame plugin is not installed. -To create and activate a new environment, which will contain your installation of QGis open your conda terminal and run:: - - conda create -n qgis_latest - conda activate qgis_latest - -To **install the latest QGIS version**, use:: - - conda install qgis --channel conda-forge - -.. Note:: - Conda will always try to install the latest version. If you want to use another version, you need to specify it, e.g.: - - ``conda install qgis=3.34.11 --channel conda-forge`` -Now install the avaframe requirements:: +Assuming you followed the steps above, you should get a working QGis installation by running (it will take a while):: - conda install pip numpy cython + pixi shell --environment qgis -Now find the directory where your environment is located. The path should be something like: -``C:\Users\USER\miniconda3\envs\qgis_latest``. Change into it:: - cd \miniconda3\envs\qgis_latest - -Clone the AvaFrame repository and change into it:: - - git clone https://github.com/avaframe/AvaFrame.git - cd AvaFrame - -.. Note:: - This will pull the latest developer version of AvaFrame, if you want the current release version for the plugin, - you need to specify the version, e.g.: - - ``https://github.com/avaframe/AvaFrame/tree/1.8.3`` - -Compile the cython com1DFA part and create an editable avaframe version in your environment:: - - python setup.py build_ext --inplace - pip install -e . - -Run QGIS:: +An to run QGIS:: qgis -Now you can **install the AvaFrameConnector plugin** via QGIS as per usual (:ref:`installation:Operational Installation`). - -AvaFrame should now be installed, and both installations should work and be editable separately. To display the installed version and installation location, use -``pip show avaframe`` in the respective environment, or use the *getVersion* function in the plugin. Note that the script -versions are separate, and changes in one installation will not affect the other. - -**Updating QGIS** - -To update QGIS to the most recent version, you need to run the following command with the respective environment active:: - - conda update qgis -c conda-forge +Depending on your mode of QGis installation (direct installer, conda, OSGeo4W...) your script AvaFrame installation +might be overruled... +Now you can **install the AvaFrameConnector plugin** via QGIS as per usual (:ref:`installation:Operational Installation`). diff --git a/docs/moduleCom4FlowPy.rst b/docs/moduleCom4FlowPy.rst index a5497d214..d310ab253 100644 --- a/docs/moduleCom4FlowPy.rst +++ b/docs/moduleCom4FlowPy.rst @@ -30,33 +30,12 @@ The motivational background and concepts behind the model, as well as a list of :ref:`theoryCom4FlowPy:com4FlowPy theory`. -Additional installation requirements and running the code +Running the code ---------------- -In order to run :py:mod:`com4FlowPy` you need to separately install the ``rasterio`` package, which is not included in the general AvaFrame requirements. -On Linux distributions inside the ``avaframe_env`` `conda environment -`_ it should usually work with: - - :: - - pip install rasterio - - -Running ``pip install rasterio`` inside the newly created ``avaframe_env`` `conda environment -`_ -is now (status: December 2024) also the recommended way to install ``rasterio`` on Windows. - -If this does not work, alternatively you can try installing ``rasterio`` via ``conda`` from the ``conda-forge`` channel. - -Additional (albeit not straight-forward) information can be found on: - - https://rasterio.readthedocs.io/en/stable/installation.html - - https://github.com/conda-forge/rasterio-feedstock - -Once the rasterio package is installed you can test :py:mod:`com4FlowPy` by: - 1. setting ``avalancheDir = data/avaFlowPy`` inside ``local_avaframeCfg.ini`` in the ``avaframe`` directory (if you don't already hava a ``local_avaFrameCfg.ini`` create it by copying and renaming the ``avaframeCfg.ini`` -- also see :ref:`moduleCom4FlowPy:Configuration`.) - 2. running within the ``avaframe`` directory: - - :: +Generate an environment as described in :ref:`developinstall:Advanced Installation (Linux)` or +:ref:`developinstallwin:Advanced Installation (Windows)`. Once you have a working ``pixi shell``, you can run the +model via:: python runCom4FlowPy.py