pip3 installation error

[rouson]

Thanks for contributing this filter! Below is the output from my attempt to install it. Any advice? My apologies if the solution seems obvious from the message below. I don't use Python often so the explanation below is not easy for me to follow. I did attempt the first couple of suggestions (e.g., git clone git@github.com:veneres/py-pandoc-include-code && python3 -m py-pandoc-include-code ./py-pandoc-include-code) but to no avail.

% pip3 install git+https://github.com/veneres/py-pandoc-include-code.git
error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try brew install
    xyz, where xyz is the package you are trying to
    install.
    
    If you wish to install a Python library that isn't in Homebrew,
    use a virtual environment:
    
    python3 -m venv path/to/venv
    source path/to/venv/bin/activate
    python3 -m pip install xyz
    
    If you wish to install a Python application that isn't in Homebrew,
    it may be easiest to use 'pipx install xyz', which will manage a
    virtual environment for you. You can install pipx with
    
    brew install pipx
    
    You may restore the old behavior of pip by passing
    the '--break-system-packages' flag to pip, or by adding
    'break-system-packages = true' to your pip.conf file. The latter
    will permanently disable this error.
    
    If you disable this error, we STRONGLY recommend that you additionally
    pass the '--user' flag to pip, or set 'user = true' in your pip.conf
    file. Failure to do this can result in a broken Homebrew installation.
    
    Read more about this behavior here: <https://peps.python.org/pep-0668/>

note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages.
hint: See PEP 668 for the detailed specification.

[veneres]

Hi @rouson, I think this issue is related to #1.
The problem is related to the fact that the installation script also installs a command system-wide (py-pandoc-include-code).
There are two possible solutions:

1. Use a virtual environment following this guide, or using conda, which I kindly suggest, following this guide.
2. Use pipx to install the program in an isolated environment without manually creating the virtualenv

Since you said you do not use Python often, I suggest using pipx, which I consider the simplest solution.

Thus, assuming that you are on macOS (guessed from your output shared), the commands to use are the following:

brew install pipx # or follow the instruction that better suits you to install pipx from https://github.com/pypa/pipx
pipx ensurepath # ensure that pipx is in your path
pipx install git+https://github.com/veneres/py-pandoc-include-code.git

I've just tried on my system and this works for me. Please tell me if it also works for you, because if it does, I will update the README.md of this repo.
Thanks!