How to activate Python env in the local directory and run pdoc with pre-commit?

Question

I have recently created a GitHub Actions workflow to lint/reformat the code of my repo and create documentation HTML pages using pdoc . The last step is problematic, because pdoc runs the.py files to create the documentation. For one of the files (file.py) the ServiceNow ODBC driver needs to be set up and it's unfeasible to do on every workflow. That is why I decided to try using pdoc with pre-commit. Locally the pdoc command only works if pdoc is in the same directory as file.py, that is why a virtual env has to be activated before running the command

My configuration is Windows 10 and Python 3.9. These are the commands:

.\env\Scripts\activate
pdoc ./file.py -o ./docs

This is the.pre-commit-config.yaml I tried:

repos:
-   repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.4.0
    hooks:
    -   id: check-yaml

-   repo: local
    hooks:
    - id: env
      name: Activate env
      language: system
      entry: .\env\Scripts\activate

-   repo: local
    hooks:
    - id: pdoc
      name: Run pdoc
      language: system
      entry: pdoc ./file.py -o ./docs


# Output:

check yaml...............................................................Passed
Activate env.............................................................Failed
- hook id: env
- exit code: 1
Executable `.envScriptsactivate` not found
Run pdoc.................................................................Failed
- hook id: pdoc
- exit code: 1
Executable `pdoc` not found

This may not be intuitive use of pre-commit, but I need a way to run the pdoc commands before every commit. This is intended for use inside the same organization, so the set up will be the same on every device.

Edit 1: I tried one of the suggestions from anthony sottile , but there are still some errors because of unexpected arguments.

repos:
-   repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.4.0
    hooks:
    -   id: check-yaml

-   repo: local
    hooks:
    - id: env
      name: Activate env
      language: system
      entry: ./env/Scripts/pdoc.exe file.py -o ./packages

# Output:

check yaml...............................................................Passed
Activate env.............................................................Failed
- hook id: env
- exit code: 2
usage: pdoc.exe [-o DIR] [-d {markdown,google,numpy,restructuredtext}]
                [-e module=url] [--favicon URL] [--footer-text TEXT]
                [--logo URL] [--logo-link URL] [--math | --no-math]
                [--search | --no-search] [--show-source | --no-show-source]
                [-t DIR] [-h HOST] [-p PORT] [-n] [--help] [--version]
                [module ...]
pdoc.exe: error: unrecognized arguments: .idea/misc.xml .idea/inspectionProfiles/profiles_settings.xml .pre-commit-config.yaml file.py

Answer 1

"activating" a virtualenv is simply prepending PATH (and VIRTUAL_ENV , though this usually doesn't do anything)

the activate script isn't something you execute, it's something you source as it has to modify the shell environment

fortunately, you don't need to actually source it -- you can just run the executable as normal

you've got a couple options -- the first is to access the executable directly:

        entry: venv\Scripts\pdoc -o docs

this is kind of a bad idea though as it's non-portable -- Scripts is only a thing on windows

a better option would be to assume it's already on the PATH and put nothing in your pre-commit configuration:

        entry: pdoc -o docs

and then add to the PATH in your github actions steps:

    - run: echo "$PWD/venv/Scripts" >> "$GITHUB_PATH"
      shell: bash

even this isn't great because it means you always need to have pdoc on the PATH when working locally (meaning you can't commit without your virtualenv activated). this kind of goes against the design of pre-commit where it manages your tools so you don't have to. you may be able to use additional_dependencies to install pdoc such that you don't need to depend on the state of things that are installed -- but I suspect pdoc needs the rest of your dependencies to properly generate its output -- this usually is an indicator that what you're trying to do isn't a good fit for pre-commit in the first place

---

disclaimer: I wrote pre-commit

Answer 2

With the suggestions of anthony sottile the following changes to the.pre-commit-config.yaml worked for me:

repos:
-   repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.4.0
    hooks:
    -   id: check-yaml

-   repo: local
    hooks:
    - id: env
      name: Activate env
      language: system
      pass_filenames: false
      entry: ./env/Scripts/pdoc.exe ./file.py -o ./packages