Add full docker based test setup

diraol · diraol · commit 22aed090564d · 2025-07-12T12:21:24.000-03:00
diff --git a/Dockerfile b/Dockerfile
@@ -0,0 +1,42 @@
+ARG PYTHON_VERSION_SHORT
+ARG PYTHON_VERSION
+ARG REPO_OWNER=python-mode
+FROM ghcr.io/${REPO_OWNER}/python-mode-base:${PYTHON_VERSION_SHORT}-latest
+
+ENV PYTHON_VERSION=${PYTHON_VERSION}
+ENV PYTHONUNBUFFERED=1
+ENV PYMODE_DIR="/workspace/python-mode"
+
+# Set up working directory
+WORKDIR /workspace
+
+# Copy the python-mode plugin
+COPY . /workspace/python-mode
+
+# Set up python-mode in the test environment
+RUN mkdir -p /root/.vim/pack/foo/start/ && \
+    ln -s ${PYMODE_DIR} /root/.vim/pack/foo/start/python-mode && \
+    cp ${PYMODE_DIR}/tests/utils/pymoderc /root/.pymoderc && \
+    cp ${PYMODE_DIR}/tests/utils/vimrc /root/.vimrc && \
+    touch /root/.vimrc.before /root/.vimrc.after
+
+# Initialize git submodules
+WORKDIR /workspace/python-mode
+
+# Create a script to run tests
+RUN echo '#!/bin/bash\n\
+# export PYENV_ROOT="/opt/pyenv"\n\
+# export PATH="${PYENV_ROOT}/bin:${PYENV_ROOT}/shims:${PATH}"\n\
+eval "$(pyenv init -)"\n\
+eval "$(pyenv init --path)"\n\
+# Use specified Python version\n\
+pyenv shell ${PYTHON_VERSION}\n\
+cd /workspace/python-mode\n\
+echo "Using Python: $(python --version)"\n\
+bash ./tests/test.sh\n\
+rm -f tests/.swo tests/.swp 2>&1 >/dev/null \n\
+' > /usr/local/bin/run-tests && \
+    chmod +x /usr/local/bin/run-tests
+
+# Default command
+CMD ["/usr/local/bin/run-tests"]
diff --git a/README-Docker.md b/README-Docker.md
@@ -0,0 +1,132 @@
+# Docker Test Environment for python-mode
+
+This directory contains Docker configuration to run python-mode tests in a containerized environment that matches the GitHub Actions CI environment.
+
+## Prerequisites
+
+- Docker
+- Docker Compose
+
+## Quick Start
+
+### Run Tests
+
+To run all tests in Docker (default version 3.13.0):
+
+```bash
+# Using the convenience script
+./scripts/run-tests-docker.sh
+
+# Or manually with docker-compose
+docker compose run --rm python-mode-tests
+```
+
+### Interactive Development
+
+To start an interactive shell for development:
+
+```bash
+docker compose run --rm python-mode-dev
+```
+
+## What's Included
+
+The Docker environment includes:
+
+- **Ubuntu 24.04** base image
+- **pyenv** for Python version management
+- **Multiple Python versions**: 3.10.13, 3.11.9, 3.12.4, 3.13.0
+- **Python 3.13.0** as default
+- **Vim built from source** with Python support for each Python version
+- All required system dependencies:
+  - GUI libraries (GTK, X11, etc.)
+  - Lua 5.2
+  - Perl
+  - Build tools
+  - Python build dependencies
+- **python-mode plugin** properly installed and configured
+- **Git submodules** initialized
+- **Test environment** matching the CI setup
+
+## Environment Details
+
+The container replicates the GitHub Actions environment:
+
+- Vim is built with `--enable-python3interp=yes` for each Python version
+- pyenv is installed at `/opt/pyenv`
+- Python versions are managed by pyenv:
+  - 3.10.13
+  - 3.11.9
+  - 3.12.4
+  - 3.13.0 (default)
+- Each Python version has its own Vim binary: `vim-3.10.13`, `vim-3.11.9`, etc.
+- Python config directory is automatically detected using `python-config --configdir`
+- python-mode is installed in `/root/.vim/pack/foo/start/python-mode`
+- Test configuration files are copied to the appropriate locations
+- All required environment variables are set
+
+## Test Execution
+
+Tests are run using the same `tests/test.sh` script as in CI:
+
+1. **test_autopep8.sh** - Tests automatic code formatting
+2. **test_autocommands.sh** - Tests Vim autocommands
+3. **test_folding.sh** - Tests code folding functionality
+4. **test_textobject.sh** - Tests text object operations
+
+## Testing with Different Python Versions
+
+You can test python-mode with different Python versions:
+
+```bash
+# Test with Python 3.11.9
+./scripts/run-tests-docker.sh 3.11
+
+# Test with Python 3.12.4
+./scripts/run-tests-docker.sh 3.12
+
+# Test with Python 3.13.0
+./scripts/run-tests-docker.sh 3.13
+```
+
+Available Python versions: 3.10.13, 3.11.9, 3.12.4, 3.13.0
+
+Note: Use the major.minor format (e.g., 3.11) when specifying versions.
+
+## Troubleshooting
+
+### Python Config Directory Issues
+
+The Dockerfile uses `python-config --configdir` to automatically detect the correct Python config directory. If you encounter issues:
+
+1. Check that pyenv is properly initialized
+2. Verify that the requested Python version is available
+3. Ensure all environment variables are set correctly
+
+### Build Failures
+
+If the Docker build fails:
+
+1. Check that all required packages are available in Ubuntu 24.04
+2. Verify that pyenv can download and install Python versions
+3. Ensure the Vim source code is accessible
+4. Check that pyenv is properly initialized in the shell
+
+### Test Failures
+
+If tests fail in Docker but pass locally:
+
+1. Check that the Vim build includes Python support for the correct version
+2. Verify that all git submodules are properly initialized
+3. Ensure the test environment variables are correctly set
+4. Confirm that the correct Python version is active
+5. Verify that pyenv is properly initialized
+
+## Adding More Python Versions
+
+To add support for additional Python versions:
+
+1. Add the new version to the `pyenv install` commands in the Dockerfile.base
+2. Update the test scripts to include the new version
+4. Test that the new version works with the python-mode plugin
+5. Update this documentation with the new version information 
diff --git a/doc/pymode.txt b/doc/pymode.txt
@@ -54,7 +54,7 @@ Python-mode contains all you need to develop python applications in Vim.
 
 Features:                                                       *pymode-features*
 
-- Support Python version 2.6+ and 3.2+
+- Support Python version 3.10.13, 3.11.9, 3.12.4, 3.13.0
 - Syntax highlighting
 - Virtualenv support
 - Run python code (``<leader>r``)
@@ -161,6 +161,11 @@ python-features of **pymode** will be disabled.
 Set value to `python3` if you are working with python3 projects. You could use
 |exrc|
 
++ Currently supported Python versions: 3.10.13, 3.11.9, 3.12.4, 3.13.0
++ 
++ For testing with different Python versions, see the Docker testing environment
++ described in the Development section.
+
 -------------------------------------------------------------------------------
 2.2 Python indentation ~
                                                                   *pymode-indent*
@@ -862,6 +867,22 @@ newly added file (2). This latter file should invoke vim which in turn sources
 file (3). File (3) may then read (4) as a first part of its assertion
 structure and then execute the remaning of the instructions/assertions.
 
+6. Testing Environment: The project uses Docker for consistent testing across
+different Python versions. See `README-Docker.md` for detailed information about
+the Docker testing environment.
+
+7. CI/CD: The project uses GitHub Actions for continuous integration, building
+Docker images for each supported Python version and running tests automatically.
+
+8. Supported Python Versions: The project currently supports Python 3.10.13,
+3.11.9, 3.12.4, and 3.13.0. All tests are run against these versions in the
+CI environment.
+
+9. Docker Testing: To run tests locally with Docker:
+    - Use `./scripts/run-tests-docker.sh` to run tests with the default Python version
+    - Use `./scripts/run-tests-docker.sh 3.11` to test with Python 3.11.9
+    - Use `./scripts/test-all-python-versions.sh` to test with all supported versions
+
 ===============================================================================
 8. Credits ~
                                                                  *pymode-credits*
diff --git a/docker-compose.yml b/docker-compose.yml
@@ -0,0 +1,42 @@
+services:
+  python-mode-tests:
+    build:
+      context: .
+      dockerfile: Dockerfile
+      args:
+        - PYTHON_VERSION_SHORT
+        - PYTHON_VERSION
+    volumes:
+      # Mount the current directory to allow for development and testing
+      - .:/workspace/python-mode
+    environment:
+      - PYTHON_CONFIGURE_OPTS=--enable-shared
+      - PYMODE_DIR=/workspace/python-mode
+      - PYENV_ROOT=/opt/pyenv
+      - PATH=/usr/local/bin:/opt/pyenv/bin:/opt/pyenv/shims:$PATH
+      # Optional: Set PYTHON_VERSION to test with a specific Python version
+      # - PYTHON_VERSION=3.11.9
+    # Run tests by default
+    command: ["/usr/local/bin/run-tests"]
+
+  # Alternative service for interactive development
+  python-mode-dev:
+    build:
+      context: .
+      dockerfile: Dockerfile
+      args:
+        - PYTHON_VERSION_SHORT
+        - PYTHON_VERSION
+    volumes:
+      - .:/workspace/python-mode
+    environment:
+      - PYTHON_CONFIGURE_OPTS=--enable-shared
+      - PYMODE_DIR=/workspace/python-mode
+      - PYENV_ROOT=/opt/pyenv
+      - PATH=/usr/local/bin:/opt/pyenv/bin:/opt/pyenv/shims:$PATH
+      # Optional: Set PYTHON_VERSION to test with a specific Python version
+      # - PYTHON_VERSION=3.11.9
+    # Start an interactive shell for development
+    command: ["/bin/bash"]
+    stdin_open: true
+    tty: true
diff --git a/readme.md b/readme.md
@@ -56,7 +56,7 @@ Why Python-mode?
 
 The plugin contains all you need to develop python applications in Vim.
 
-* Support Python and 3.6+
+* Support Python 3.10.13, 3.11.9, 3.12.4, 3.13.0
 * Syntax highlighting
 * Virtualenv support
 * Run python code (`<leader>r`)
@@ -143,6 +143,41 @@ Then rebuild **helptags** in vim:
 **filetype-plugin** (`:help filetype-plugin-on`) and **filetype-indent**
 (`:help filetype-indent-on`) must be enabled to use python-mode.
 
+# Docker Testing Environment
+
+For consistent testing across different Python versions, python-mode provides a
+Docker-based testing environment. This is especially useful for contributors
+and developers who want to test the plugin with different Python versions.
+
+## Quick Start
+
+```bash
+# Run tests with default Python version (3.13.0)
+./scripts/run-tests-docker.sh
+
+# Run tests with specific Python version
+./scripts/run-tests-docker.sh 3.11
+
+# Run tests with all supported Python versions
+./scripts/test-all-python-versions.sh
+```
+
+## Supported Python Versions
+
+The Docker environment supports the following Python versions:
+- 3.10.13
+- 3.11.9
+- 3.12.4
+- 3.13.0 (default)
+
+For detailed information about the Docker testing environment, see
+[README-Docker.md](README-Docker.md).
+
+## Prerequisites
+
+- Docker
+- Docker Compose
+
 # Troubleshooting/Debugging
 
 First read our short
@@ -188,6 +223,12 @@ Please, also provide more contextual information such as:
 * `git status` (under your _python-mode_ directory)
 * `tree <python-mode-directory>` or something similar (such as `ls -lR`)
 
+If you're using the Docker testing environment, also provide:
+* The output of `docker --version` and `docker compose version`
+* The Python version used in Docker (if testing with a specific version)
+* Any Docker-related error messages
+* The output of `./scripts/run-tests-docker.sh --help` (if available)
+
 # Frequent problems
 
 Read this section before opening an issue on the tracker.
@@ -207,12 +248,50 @@ is a good reference on how to build vim from source.
 help you that much. Look for our branch with python2-support (old version,
 not maintained anymore) (`last-py2-support`).
 
+## Python 3 Support
+
+`python-mode` supports only Python 3. The project has completely removed Python 2
+support since version 0.11.0. Currently supported Python versions are:
+3.10.13, 3.11.9, 3.12.4, and 3.13.0.
+
+If you need Python 2 support, you can use the legacy `last-py2-support` branch,
+but it is no longer maintained.
+
+## Vim Python Support
+
+Vim [has issues](https://github.com/vim/vim/issues/3585) when compiled with
+both Python 2 and Python 3 support. For best compatibility with python-mode,
+build Vim with only Python 3 support. See
+[this guide](https://github.com/ycm-core/YouCompleteMe/wiki/Building-Vim-from-source)
+for building Vim from source.
+
 ## Symlinks on Windows
 
 Users on Windows OS might need to add `-c core.symlinks=true` switch to
 correctly clone / pull repository. Example: `git clone --recurse-submodules
 https://github.com/python-mode/python-mode -c core.symlinks=true`
 
+## Docker Testing Issues
+
+If you encounter issues with the Docker testing environment:
+
+1. **Build Failures**: Ensure Docker and Docker Compose are properly installed
+   and up to date. The Dockerfile requires Ubuntu 24.04 packages.
+
+2. **Python Version Issues**: Verify that the requested Python version is
+   supported (3.10.13, 3.11.9, 3.12.4, 3.13.0). Use the major.minor format
+   (e.g., `3.11`) when specifying versions.
+
+3. **Vim Build Issues**: The Docker environment builds Vim from source with
+   Python support for each version. Ensure sufficient disk space and memory
+   for the build process.
+
+4. **Test Failures**: If tests fail in Docker but pass locally, check that
+   all git submodules are properly initialized and the correct Python version
+   is active.
+
+For detailed troubleshooting, see [README-Docker.md](README-Docker.md).
+
 ## Error updating the plugin
 
 If you are trying to update the plugin (using a plugin manager or manually) and
@@ -242,6 +321,19 @@ the issue tracker at:
 The contributing guidelines for this plugin are outlined at
 `:help pymode-development`.
 
+Before contributing, please:
+
+1. **Test with Docker**: Use the Docker testing environment to ensure your
+    changes work across all supported Python versions (3.10.13, 3.11.9, 3.12.4, 3.13.0)
+
+2. **Run Full Test Suite**: Use `./scripts/test-all-python-versions.sh` to test
+    with all supported Python versions
+
+3. **Check CI**: Ensure the GitHub Actions CI passes for your changes
+
+4. **Follow Development Guidelines**: See `:help pymode-development` for detailed
+    development guidelines
+
 * Author: Kirill Klenov (<https://github.com/klen>)
 * Maintainers:
     * Felipe Vieira (<https://github.com/fmv1992>)
diff --git a/scripts/run-tests-docker.sh b/scripts/run-tests-docker.sh
diff --git a/scripts/test-all-python-versions.sh b/scripts/test-all-python-versions.sh
