action.yml

name: "Setup poetry and python"
description: "Setup python, install poetry, install dependencies, cache."

inputs:
  python-version:
    description: "The version of python to use (passed into `actions/setup-python` action)."
    required: true

  poetry-version:
    description: "Poetry version to use (passed to the official poetry install script). Leave blank for latest."
    required: true
    default: ""

  install-args:
    description: "A string placed after the `poetry install` command, which can contain extra options."
    required: true
    default: ""

  working-dir:
    description: "The directory to run the `poetry` commands in. By default, this will just be the root directory of the project."
    required: true
    default: "."

  cache-poetry-install:
    description: "Enable caching for poetry tool itself (not related to caching of the project's poetry dependencies)."
    required: true
    default: "true"

  cache-poetry-environment:
    description: "Enable caching for poetry environments (venvs that contain the project's poetry dependencies)."
    required: true
    default: "true"

  poetry-home:
    description: "Directory to install the poetry tool into. (passed into the official poetry installer as `POETRY_HOME` env variable)."
    required: true
    default: "~/.local/share/pypoetry"

outputs:
  poetry-version:
    description: "The version of poetry installed"
    value: ${{ steps.installed_poetry_version.outputs.poetry-version }}

  poetry-venv-path:
    description: "Path to the virtual environment created by poetry for the project."
    value: ${{ steps.poetry_environment.outputs.venv-path }}

  python-version:
    description: "The python version used (forwarded from `actions/setup-python` action)."
    value: ${{ steps.python_setup.outputs.python-version }}

  python-path:
    description: "Path to the python interpreter (forwarded from `actions/setup-python` action)."
    value: ${{ steps.python_setup.outputs.python-path }}

  cache-hit-poetry-install:
    description: "The was a cache hit for the poetry tool (installation) cache."
    value: ${{ steps.poetry_installation_cache.outputs.cache-hit }}

  cache-hit-poetry-environment:
    description: "There was a cache hit for the poetry environment (dependencies) cache."
    value: ${{ steps.poetry_dependencies_cache.outputs.cache-hit }}

runs:
  using: "composite"

  steps:
    - name: Setup python
      uses: actions/setup-python@v4
      id: python_setup
      with:
        python-version: ${{ inputs.python-version }}

    # We need to know what poetry version we'll be installing, so that we can construct
    # a unique cache key based on it, which we need before the installation (for restore).
    - name: Determine poetry version to be installed
      shell: bash
      id: installation_poetry_version
      run: |
        echo "::group::Determine poetry version to be installed"
        if [ "${{ inputs.poetry-version }}" = "" ]; then
          echo "Obtaining latest version from PyPI"

          # Obtain the latest non pre-release version of poetry from PyPI's API
          version="$(curl https://pypi.org/pypi/poetry/json |\
                   jq --raw-output ".releases | keys[]" |\
                   grep -E "^[0-9]+\.[0-9]+\.[0-9]+$" |\
                   tail -n 1)"
        else
          echo "Using user-defined version"
          version="${{ inputs.poetry-version }}"
        fi

        echo "version: $version"
        echo "poetry-version=$version" >> $GITHUB_OUTPUT
        echo "::endgroup::"

    # Poetry install arguments may contain some special symbols (most notably a comma), which can't be
    # present in cache keys. Compute a hash of the input arguments which we can safely use instead
    - name: Hash install arguments
      shell: bash
      id: install_args_hash
      run: |
        echo "::group::Hash poetry install arguments"
        echo "Passed install args: ${{ inputs.install-args }}"
        # Macos doesn't have sha256sum command, use openssl command
        function sha256sum() { openssl sha256 "$@" | awk '{print $2}'; }
        hashed_args=$(echo -n "${{ inputs.install-args }}" | sha256sum)
        echo "Resulting hash: $hashed_args"
        echo "install-args-hash=$hashed_args" >> $GITHUB_OUTPUT
        echo "::endgroup::"

    - name: Cache poetry installation
      # We're using the cache restore only action, rather than full actions/cache, as we then explicitly
      # save this cache later, to save installation cache even if the dependency install fails.
      uses: actions/cache/restore@v3
      if: ${{ inputs.cache-poetry-install == 'true' }}
      id: poetry_installation_cache
      with:
        path: |
          ${{ inputs.poetry-home }}
        key: "setup-poetry-v1.0.0--cache-installation--\
          os-${{ runner.os }}--\
          python-${{ steps.python_setup.outputs.python-version }}--\
          poetry-${{ steps.installation_poetry_version.outputs.poetry-version }}"

    - name: Install Poetry
      shell: bash
      # If cache was restored, the poetry install script will detect it, and will skip the installation
      # no need to add an if condition for running this step.
      run: |
        echo "::group::Install Poetry (version: ${{ steps.installation_poetry_version.outputs.poetry-version }})"
        curl -sSL "https://install.python-poetry.org" | python - --yes
        echo "::endgroup::"
      env:
        POETRY_HOME: ${{ inputs.poetry-home }}
        POETRY_VERSION: ${{ steps.installation_poetry_version.outputs.poetry-version }}

    # Windows is just a big pile of bugs...
    #
    # Poetry installation in windows symlinks ${{ inputs.poetry-home }}/bin/poetry.exe to
    # {{ inputs.poetry-version }}/venv/Scripts/poetry.exe, however in some cases, this just deosn't work properly
    # after a cache restore.
    #
    # Sometimes, the symlink seems to be present and point to the correct destination, however it actually doesn't work
    # and invoking poetry results in code 127 and message: D:\a\_temp\df65fdd4-e6e5-44b7-b05a-a7a312eae7ec.sh: line 16:
    #  /c/Users/runneradmin/.local/share/pypoetry/bin/poetry.exe: cannot execute: required file not found
    # This can be fixed by recreating the symlink, even though it has the exact same destination, it just magically starts
    # working for some reason.
    #
    # Other times, the file isn't even a symlink and is instead a full file, which however doesn't actually work, and
    # needs to be removed and replaced with a valid symlink.
    #
    # What I assume is going on is some mess up with cache restoration, as cache is stored in tar archives
    # and it seems that the restored link is no longer working, however it shows up correctly in `ls`, and
    # `readlink` works properly and is able to read it's destination, so I've no idea why this is needed.
    # To fix this, we dynamically obtain the destination of this link, and recreate it with that exact
    # obtained destination.
    - name: Fix symlinks for poetry executable on windows
      # Only run on windows, if we matched some cache key
      if: ${{ runner.os == 'Windows' && steps.poetry_installation_cache.outputs.cache-matched-key != '' }}
      shell: bash
      run: |
        echo "::group::Fix symlinks for poetry executable on windows"

        poetry_link_path="${{ inputs.poetry-home }}/bin/poetry.exe"
        poetry_link_path="${poetry_link_path/#\~/$HOME}"
        echo "Link path: $poetry_link_path"

        poetry_link_dest_path="$(readlink -f "$poetry_link_path")"
        echo "Destination path: $poetry_link_dest_path"

        if [ "$poetry_link_path" = "$poetry_link_dest_path" ]; then
          echo "Poetry executable not a link, replacing with one"

          poetry_link_dest_path="${{ inputs.poetry-home }}/venv/Scripts/poetry.exe"
          poetry_link_dest_path="${poetry_link_dest_path/#\~/$HOME}"
          echo "New destination path: $poetry_link_dest_path"

          rm "$poetry_link_path"
          ln -s "$poetry_link_dest_path" "$poetry_link_path"
        else
          echo "Poetry executable is a link, recreating because windows requires it"
          # Use the -f flag to force symlink creation, even though it already exists
          ln -sf "$poetry_link_dest_path" "$poetry_link_path"
        fi

        echo "::endgroup::"

    - name: Add poetry executable to $PATH
      shell: bash
      run: |
        echo "::group::Add poetry executable(s) to PATH"
        poetry_home="${{ inputs.poetry-home }}"
        absolute_poetry_home="${poetry_home/#\~/$HOME}"
        echo "Path to poetry binaries: ${absolute_poetry_home}/bin"
        echo "${absolute_poetry_home}/bin" >> $GITHUB_PATH
        echo "::endgroup::"

    - name: Obtain poetry version
      shell: bash
      id: installed_poetry_version
      run: |
        echo "::group::Obtain poetry version"
        version="$(poetry --version | awk '{print $3}' | sed 's/.$//')"
        echo "Detected installed poetry version: $version"
        echo "poetry-version=$version" >> $GITHUB_OUTPUT
        echo "::endgroup::"

    # Sometimes, poetry might get installed properly, while the dependency installation later fails.
    # If this happens, poetry installation cache is also ignored, which is not what we want. There's
    # no reason to throw away a completely working poetry installation here, so let's explicitly save
    # it, no matter what happens later.
    - name: Save poetry install cache early
      if: ${{ steps.poetry_installation_cache.outputs.cache-hit != 'true' }}
      uses: actions/cache/save@v3
      with:
        path: |
          ${{ inputs.poetry-home }}
        key: ${{ steps.poetry_installation_cache.outputs.cache-primary-key }}

    - name: Obtain poetry cache-dir
      id: poetry_cache_dir
      shell: bash
      run: |
        echo "::group::Obtain poetry cache-dir"
        cache_dir="$(poetry config cache-dir)"
        echo "Cache dir: $cache_dir"
        echo "cache-dir=$cache_dir" >> $GITHUB_OUTPUT
        echo "::endgroup::"

    - name: Cache poetry dependencies
      if: ${{ inputs.cache-poetry-environment == 'true' }}
      uses: actions/cache/restore@v3
      id: poetry_dependencies_cache
      with:
        # Cache poetry cache-dir, where virtual environments get created by default.
        # However in case we'd want the virtual environments created in-project, also cache the .venv folder
        path: |
          ${{ steps.poetry_cache_dir.outputs.cache-dir }}
          ${{ inputs.working-dir }}/.venv
        # If a cache key is the same, we can safely restore the cache knowing that it was the cache for this version.
        #
        # Otherwise, if we don't have any stored cache matching the exact cache key, it usually means that a new
        # dependency was added, updated or removed.
        #
        # For these cases, we can actually still perform a cache restore, even if the key doesn't match, as long as
        # that cache comes from a compatible version (ensured by a match on a restore-key). That way, poetry will just
        # have to install the missing packages, or update/remove some packages, but all other dependencies will still
        # be cached.
        #
        # After that, new cache will still get created, with an appropriate restore key, so next time when this same
        # config runs, we can have an exact match.
        #
        # See: https://github.com/actions/cache/blob/main/tips-and-workarounds.md#update-a-cache
        key: "setup-poetry-v1.0.0--cache-dependencies--\
          os-${{ runner.os }}--\
          python-${{ steps.python_setup.outputs.python-version }}--\
          poetry-${{ steps.installed_poetry_version.outputs.poetry-version }}--\
          args-${{ steps.install_args_hash.outputs.install-args-hash }}--\
          workdir-${{ inputs.working-dir }}--\
          filehash-${{ hashFiles(format('{0}/pyproject.toml', inputs.working-dir), format('{0}/poetry.lock', inputs.working-dir)) }}"
        restore-keys: "setup-poetry-v1.0.0--cache-dependencies--\
          os-${{ runner.os }}--\
          python-${{ steps.python_setup.outputs.python-version }}--\
          poetry-${{ steps.installed_poetry_version.outputs.poetry-version }}--\
          args-${{ steps.install_args_hash.outputs.install-args-hash }}--\
          workdir-${{ inputs.working-dir }}--"

    - name: Create poetry environment for the project
      id: poetry_environment
      shell: bash
      run: |
        echo "::group::Poetry environment"
        cd ${{ inputs.working-dir }}
        echo "Python path: ${{ steps.python_setup.outputs.python-path }}"
        poetry env use "${{ steps.python_setup.outputs.python-path }}"
        echo "venv-path=$(poetry env info --path)" >> $GITHUB_OUTPUT
        echo "::endgroup::"

    - name: Install dependencies with poetry
      shell: bash
      run: |
        echo "::group::Install Dependencies"
        cd ${{ inputs.working-dir }}
        poetry install --sync ${{ inputs.install-args }}
        echo "::endgroup::"

    - name: Save poetry dependencies cache early
      # Cache-hit is only true if the primary key was matched, not if there was a restore-key match.
      # That means we can use it to skip the save step if we know the primary key was matched, as
      # nothing has changed. But if one of the restore keys was matched, or there wasn't a hit at all,
      # we do want to save a new cache under the primary key.
      if: ${{ steps.poetry_dependencies_cache.outputs.cache-hit != 'true' }}
      uses: actions/cache/save@v3
      with:
        path: |
          ${{ steps.poetry_cache_dir.outputs.cache-dir }}
          ${{ inputs.working-dir }}/.venv
        key: ${{ steps.poetry_dependencies_cache.outputs.cache-primary-key }}

    - name: Add poetry venv binaries to path
      shell: bash
      run: |
        echo "::group::Add venv to PATH"
        cd ${{ inputs.working-dir }}
        echo "Adding $(poetry env info --path)/bin to path"
        echo "$(poetry env info --path)/bin" >> $GITHUB_PATH
        echo "::endgroup::"