How to replace the default python syntax in Neovim without a plugin manager?

Question

As the title, I would like to replace the default python syntax with the more modern one in https://github.com/vim-python/python-syntax.

I managed to do this in Neovim 0.9.4 with the vim-plug plugin manager, but I did not manage to replace the syntax manually.

I placed the syntax file in ~/.local/share/nvim/site/plugin/python-syntax/syntax/python.vim and I can see from :scriptnames that the file is imported:

/usr/local/share/nvim/runtime/ftplugin.vim
/usr/local/share/nvim/runtime/indent.vim
~/.config/nvim/init.vim
~/.vimrc
/usr/local/share/nvim/runtime/filetype.lua
/usr/local/share/nvim/runtime/syntax/syntax.vim
/usr/local/share/nvim/runtime/syntax/synload.vim
~/.local/share/nvim/site/plugin/python-syntax/syntax/python.vim   # <--- custom syntax
/usr/local/share/nvim/runtime/plugin/gzip.vim
/usr/local/share/nvim/runtime/plugin/health.vim
/usr/local/share/nvim/runtime/plugin/matchit.vim
/usr/local/share/nvim/runtime/pack/dist/opt/matchit/plugin/matchit.vim
/usr/local/share/nvim/runtime/plugin/matchparen.vim
/usr/local/share/nvim/runtime/plugin/netrwPlugin.vim
/usr/local/share/nvim/runtime/plugin/rplugin.vim
/usr/local/share/nvim/runtime/plugin/shada.vim
/usr/local/share/nvim/runtime/plugin/spellfile.vim
/usr/local/share/nvim/runtime/plugin/tarPlugin.vim
/usr/local/share/nvim/runtime/plugin/tohtml.vim
/usr/local/share/nvim/runtime/plugin/tutor.vim
/usr/local/share/nvim/runtime/plugin/zipPlugin.vim
/usr/local/share/nvim/runtime/plugin/editorconfig.lua
/usr/local/share/nvim/runtime/plugin/man.lua
/usr/local/share/nvim/runtime/plugin/nvim.lua
/usr/local/share/nvim/runtime/ftplugin/python.vim
/usr/local/share/nvim/runtime/autoload/provider/python3.vim
/usr/local/share/nvim/runtime/autoload/provider/pythonx.vim
/usr/local/share/nvim/runtime/autoload/remote/host.vim
/usr/local/share/nvim/runtime/indent/python.vim
/usr/local/share/nvim/runtime/syntax/python.vim   # <--- default syntax

The problem is that the syntax is overridden by the default one in /usr/local/share/nvim/runtime/syntax/python.vim: so the highlighting does not change and remains the default one.

I tried to debug this issue but I can see that both the files are sourced and the first one (the custom syntax) should win: the last line of the custom syntax (sourced first) is

let b:current_syntax = 'python'

and the first line of the default syntax (sourced after the custom one) is

if exists("b:current_syntax")
  finish
endif

so the second one should not be executed and finish right away. However the default syntax is still executed because at that point the buffer variable b:current_syntax is false again, even if it was set to true in the custom syntax.

So something between the sourcing of the two files resets the syntax and removes the custom syntax sourced at the beginning.

If I manually call finish from the default syntax the result is that the file is not highlighted at all. If I manually replace the default syntax file with the custom one, then the custom syntax is correctly sourced and applied.

I am willing to share more details if it can be beneficial.

As an aside, this is the result of :scriptnames on the neovim instance with the syntax enabled via the plugin manager:

/usr/local/share/nvim/runtime/ftplugin.vim
/usr/local/share/nvim/runtime/indent.vim
~/.config/nvim/init.vim
~/.vimrc
/usr/local/share/nvim/runtime/filetype.lua
~/.local/share/nvim/site/autoload/plug.vim
/usr/local/share/nvim/runtime/ftoff.vim
/usr/local/share/nvim/runtime/syntax/syntax.vim
/usr/local/share/nvim/runtime/syntax/synload.vim
/usr/local/share/nvim/runtime/plugin/gzip.vim
/usr/local/share/nvim/runtime/plugin/health.vim
/usr/local/share/nvim/runtime/plugin/matchit.vim
/usr/local/share/nvim/runtime/pack/dist/opt/matchit/plugin/matchit.vim
/usr/local/share/nvim/runtime/plugin/matchparen.vim
/usr/local/share/nvim/runtime/plugin/netrwPlugin.vim
/usr/local/share/nvim/runtime/plugin/rplugin.vim
/usr/local/share/nvim/runtime/plugin/shada.vim
/usr/local/share/nvim/runtime/plugin/spellfile.vim
/usr/local/share/nvim/runtime/plugin/tarPlugin.vim
/usr/local/share/nvim/runtime/plugin/tohtml.vim
/usr/local/share/nvim/runtime/plugin/tutor.vim
/usr/local/share/nvim/runtime/plugin/zipPlugin.vim
/usr/local/share/nvim/runtime/plugin/editorconfig.lua
/usr/local/share/nvim/runtime/plugin/man.lua
/usr/local/share/nvim/runtime/plugin/nvim.lua
/usr/local/share/nvim/runtime/ftplugin/python.vim
/usr/local/share/nvim/runtime/autoload/provider/python3.vim
/usr/local/share/nvim/runtime/autoload/provider/pythonx.vim
/usr/local/share/nvim/runtime/autoload/remote/host.vim
/usr/local/share/nvim/runtime/indent/python.vim
~/.vim/plugged/python-syntax/syntax/python.vim   # <--- custom syntax
/usr/local/share/nvim/runtime/syntax/python.vim   # <--- default syntax

Answer 1

"plugins" subdirectory is meant for the scripts sourced upon Vim startup. You should not put all that random stuff there.

Instead, buffer-specific scripts must be put under appropriately named subdirectories, such as "syntax", "ftplugin" etc. (Yes, that's because they are supposed to be sourced multiple times).

In fact, this implies that in order to merge your plugin with "nvim/site" you need to drop upper level dir "python-syntax" and copy the stuff below it.

As such merging is often inconvenient, you can instead create an extra runtimepath node named "python-syntax" and copy all the stuff there. This is actually what the plugin manager was doing. But it's not a problem to go without manager. The relevant steps are described in the built-in help page under :h packages topic.