Создание среды разработки#

Чтобы протестировать изменения кода, вам потребуется собрать pandas из исходного кода, что требует компилятора C/C++ и среды Python. Если вы вносите изменения в документацию, вы можете перейти к внесение вклада в документацию но если вы пропустите создание среды разработки, вы не сможете собрать документацию локально перед отправкой изменений. Рекомендуется также установить хуки pre-commit.

Шаг 1: установите компилятор C#

Как это сделать, зависит от вашей платформы. Если вы решите использовать Docker или GitPod на следующем шаге, тогда вы можете пропустить этот шаг.

Windows

Вам потребуется Средства сборки для Visual Studio 2022.

Примечание

Вам НЕ нужно устанавливать Visual Studio 2022. Вам нужны только "Build Tools for Visual Studio 2022", которые можно найти, прокрутив вниз до "All downloads" -> "Tools for Visual Studio". В установщике выберите рабочую нагрузку "Desktop development with C++".

В качестве альтернативы, вы можете установить необходимые компоненты в командной строке, используя vs_BuildTools.exe

В качестве альтернативы вы можете использовать WSL и обратитесь к Linux инструкции ниже.

macOS

Чтобы использовать mamba-based компиляторов, вам потребуется установить Инструменты разработчика с помощью xcode-select --install.

Если вы предпочитаете использовать другой компилятор, общая информация доступна здесь: https://devguide.python.org/setup/#macos

Linux

Для Linux-систем mamba установках, вам не придется устанавливать какие-либо дополнительные компоненты вне среды mamba. Инструкции ниже нужны только если ваша настройка не основана на средах mamba.

Некоторые дистрибутивы Linux поставляются с предустановленным компилятором C. Чтобы узнать, какие компиляторы (и версии) установлены в вашей системе:

# for Debian/Ubuntu:
dpkg --list | grep compiler
# for Red Hat/RHEL/CentOS/Fedora:
yum list installed | grep -i --color compiler

GCC (GNU Compiler Collection), является широко используемым компилятором, который поддерживает C и ряд других языков. Если GCC указан как установленный компилятор, больше ничего не требуется.

Если компилятор C не установлен, или вы хотите обновить, или вы используете другой дистрибутив Linux, обратитесь к любимой поисковой системе за инструкциями по установке/обновлению компилятора.

Сообщите нам о любых трудностях, создав issue или связавшись с нашим сообществом контрибьюторов Slack.

Шаг 2: создание изолированной среды#

Прежде чем мы начнем, пожалуйста:

  • Убедитесь, что у вас есть клонировал репозиторий

  • cd в каталог исходного кода pandas, который вы только что создали командой клонирования

Вариант 2: использование pip#

Вам потребуется иметь как минимум минимальная версия Python которые поддерживает pandas. Вам также необходимо иметь setuptools 51.0.0 или более поздней для сборки pandas.

Unix/macOS с virtualenv

# Create a virtual environment
# Use an ENV_DIR of your choice. We'll use ~/virtualenvs/pandas-dev
# Any parent directories should already exist
python3 -m venv ~/virtualenvs/pandas-dev

# Activate the virtualenv
. ~/virtualenvs/pandas-dev/bin/activate

# Install the build dependencies
python -m pip install -r requirements-dev.txt

Unix/macOS с pyenv

Обратитесь к документации по настройке pyenv здесь.

# Create a virtual environment
# Use an ENV_DIR of your choice. We'll use ~/Users//.pyenv/versions/pandas-dev
pyenv virtualenv  

# For instance:
pyenv virtualenv 3.9.10 pandas-dev

# Activate the virtualenv
pyenv activate pandas-dev

# Now install the build dependencies in the cloned pandas repo
python -m pip install -r requirements-dev.txt

Windows

Ниже приведён краткий обзор, как настроить виртуальное окружение с Powershell в Windows. Подробности см. в официальное руководство пользователя virtualenv.

Используйте ENV_DIR по вашему выбору. Мы будем использовать ~\\virtualenvs\\pandas-dev где ~ это папка, на которую указывает либо $env:USERPROFILE (Powershell) или %USERPROFILE% (cmd.exe) переменная окружения. Все родительские каталоги должны уже существовать.

# Create a virtual environment
python -m venv $env:USERPROFILE\virtualenvs\pandas-dev

# Activate the virtualenv. Use activate.bat for cmd.exe
~\virtualenvs\pandas-dev\Scripts\Activate.ps1

# Install the build dependencies
python -m pip install -r requirements-dev.txt

Вариант 3: использование Docker#

pandas предоставляет DockerFile в корневом каталоге для создания образа Docker с полной средой разработки pandas.

Команды Docker

Собрать образ Docker:

# Build the image
docker build -t pandas-dev .

Запустить контейнер:

# Run a container and bind your local repo to the container
# This command assumes you are running from your local repo
# but if not alter ${PWD} to match your local repo path
docker run -it --rm -v ${PWD}:/home/pandas pandas-dev

Ещё проще, вы можете интегрировать Docker со следующими IDE:

Visual Studio Code

Вы можете использовать DockerFile для запуска удаленной сессии с Visual Studio Code, популярной бесплатной IDE, используя .devcontainer.json файл. См. https://code.visualstudio.com/docs/remote/containers подробности.

PyCharm (Professional)

Включить поддержку Docker и использовать окно инструментов Services для сборки и управления образами, а также запуска и взаимодействия с контейнерами. См. https://www.jetbrains.com/help/pycharm/docker.html подробности.

Вариант 4: использование Gitpod#

Gitpod — это платформа с открытым исходным кодом, которая автоматически создаёт правильную среду разработки прямо в браузере, уменьшая необходимость установки локальных сред разработки и борьбы с несовместимыми зависимостями.

Если вы пользователь Windows, не знакомый с использованием командной строки или впервые собирающий pandas, часто быстрее собрать с помощью Gitpod. Вот подробные инструкции для сборка pandas с GitPod.

Шаг 3: сборка и установка pandas#

В настоящее время существует два поддерживаемых способа сборки pandas: pip/meson и setuptools(setup.py). Исторически pandas поддерживал только использование setuptools для сборки. Однако этот метод требует много запутанного кода в setup.py и также имеет множество проблем при компиляции pandas параллельно из-за ограничений в setuptools.

Новая система сборки, вызывает бэкенд meson через pip (через PEP 517 сборка). Он автоматически использует все доступные ядра вашего процессора, а также избегает необходимости ручных пересборок, автоматически пересобирая при каждом импорте pandas (с редактируемой установкой).

По этим причинам следует компилировать pandas с помощью meson. Поскольку система сборки meson новее, вы можете обнаружить ошибки/незначительные проблемы по мере её развития. Вы можете сообщать об этих ошибках здесь.

Для компиляции pandas с meson выполните:

# Build and install pandas
# By default, this will print verbose output
# showing the "rebuild" taking place on import (see section below for explanation)
# If you do not want to see this, omit everything after --no-build-isolation
python -m pip install -ve . --no-build-isolation --config-settings editable-verbose=true

Примечание

Номер версии извлекается из последнего тега репозитория. Убедитесь, что вы получили последние теги из вышестоящего репозитория перед сборкой:

# set the upstream repository, if not done already, and fetch the latest tags
git remote add upstream https://github.com/pandas-dev/pandas.git
git fetch upstream --tags

Параметры сборки

Можно передать опции из интерфейса pip в бэкенд meson, если вы хотите настроить свою установку. Иногда это может понадобиться для настройки каталога сборки и/или переключения уровней отладки/оптимизации.

Вы можете передать каталог сборки в pandas, добавив --config-settings builddir="your builddir here" в вашу команду pip. Эта опция позволяет настроить, где meson хранит скомпилированные C-расширения, и обеспечивает быструю пересборку.

Иногда может быть полезно скомпилировать pandas с отладочными символами при отладке C-расширений. Добавление --config-settings setup-args="-Ddebug=true" сработает.

С помощью pip можно объединять несколько настроек конфигурации (например, указание каталога сборки и сборка с отладочными символами будет выглядеть как --config-settings builddir="your builddir here" --config-settings=setup-args="-Dbuildtype=debug".

Компиляция pandas с помощью setup.py

Примечание

Этот метод компиляции pandas будет устаревшим и удалён в ближайшее время, по мере развития бэкенда meson.

Для компиляции pandas с setuptools выполните:

python setup.py develop

Примечание

Если pandas уже установлен (через meson), сначала необходимо его удалить:

python -m pip uninstall pandas

Это происходит потому, что python setup.py develop не удалит скрипт загрузчика, который meson-python использует для импорта расширения из папки сборки, что может вызывать ошибки, такие как FileNotFoundError будет вызвано.

Примечание

Вам нужно будет повторять этот шаг каждый раз при изменении C-расширений, например, если вы изменили любой файл в pandas/_libs или если вы выполнили fetch и merge из upstream/main.

Проверка сборки

На этом этапе вы должны иметь возможность импортировать pandas из локально собранной версии:

$ python
>>> import pandas
>>> print(pandas.__version__)  # note: the exact output may differ
2.0.0.dev0+880.g2b9e661fbb.dirty

На этом этапе вы можете попробовать запуск набора тестов.

Поддержание актуальности с последней сборкой

При сборке pandas с помощью meson импорт pandas автоматически запустит пересборку, даже если файлы C/Cython изменены. По умолчанию при этой пересборке не будет выводиться никакой информации (импорт просто займёт больше времени). Если вы хотите видеть вывод meson при импорте pandas, вы можете установить переменную окружения MESONPY_EDTIABLE_VERBOSE. Например, это будет:

# On Linux/macOS
MESONPY_EDITABLE_VERBOSE=1 python

# Windows
set MESONPY_EDITABLE_VERBOSE=1 # Only need to set this once per session
python

Если вы хотите видеть этот подробный вывод каждый раз, вы можете установить editable-verbose настройку конфигурации для true вот так:

python -m pip install -ve . --config-settings editable-verbose=true

Совет

Если вы когда-нибудь задумываетесь, использовался ли setuptools или meson для сборки вашего pandas, вы можете проверить значение pandas._built_with_meson, что будет истинным, если meson использовался для компиляции pandas.