/ta-lib-python-wheel

Primary LanguageShellMIT LicenseMIT

English:

TA-Lib Pre-built Wheels (Windows & Linux x64)

Project Overview

This project provides a GitHub Actions workflow to automatically build Python wheels (.whl files) for the TA-Lib (Technical Analysis Library) across various Python versions for Windows (32-bit and 64-bit) and Linux (64-bit) platforms.

TA-Lib is a widely used library for financial market technical analysis. However, installing the original TA-Lib Python package can be challenging, especially on Windows, as it requires a pre-compiled C library. The pre-built wheels generated by this project allow users to install TA-Lib easily via pip without needing to compile the C library manually.

Features

  • Builds wheels for multiple Python versions (currently 3.8 - 3.12).
  • Supports Windows 32-bit (x86, win32) and 64-bit (AMD64, win_amd64) architectures.
  • Supports Linux 64-bit (x86_64, manylinux_x86_64).
    • Note: Linux 32-bit (i686) and musllinux builds are explicitly skipped.
  • Uses specific versions of the TA-Lib C library (e.g., 0.6.4) and the Python bindings (e.g., 0.6.3). (Check env section in the workflow file for exact versions).
  • Automated testing of the built wheels using pytest.
  • Easy customization of build parameters (versions, skipped builds, etc.) via environment variables in the workflow file.

Workflow

The project utilizes a GitHub Actions workflow defined in .github/workflows/build.yml to automate the build process. The main steps include:

  1. Checkout Code: Gets the latest code from the repository.
  2. Setup Environment: Sets up the correct Python version and architecture for the build matrix job. Installs necessary build dependencies (like MSVC tools on Windows, or build-essential, autoconf, etc., on Linux).
  3. Build TA-Lib C Library:
    • On Windows: Executes build.cmd to compile the C library using CMake/NMake.
    • On Linux: Executes build.sh to compile the C library using Autotools (configure, make).
  4. Build Wheels: Uses cibuildwheel to build the Python wheels for the target Python version and architecture within an isolated environment (Docker container on Linux).
  5. Test Wheels: Runs the test suite defined by CIBW_TEST_COMMAND against the built wheels.
  6. Upload Artifacts: Uploads the successfully built wheels for each job as build artifacts.
  7. Create Release (on Tag Push): When a tag matching v*.*.* is pushed, a GitHub Release is automatically created, and all built wheels are downloaded from the artifacts and attached to the release.

Usage

Getting Pre-built Wheels

Option 1: From GitHub Releases (Recommended for stable versions)

  1. Go to the Releases page of this repository (replace YOUR_USERNAME/YOUR_REPO with the actual URL).
  2. Find the release corresponding to the version you need (e.g., based on the tag).
  3. Download the appropriate .whl file for your Python version and operating system/architecture directly from the release assets.

Option 2: From GitHub Actions Artifacts (For latest builds or testing)

  1. Go to the Actions tab of this repository (replace YOUR_USERNAME/YOUR_REPO).
  2. Select the most recent successful run of the "Build TA-Lib Wheels" workflow.
  3. Scroll down to the "Artifacts" section at the bottom of the run summary page.
  4. Download the artifact corresponding to your OS, architecture, and Python version (e.g., talib-0.6.3-windows-latest-py3.11-win_amd64.whl). The artifacts might be zipped; if so, unzip the downloaded file to get the .whl file.

Installing the Wheel

Once you have downloaded the correct .whl file, open your terminal or command prompt, navigate to the directory containing the file, and install it using pip:

pip install TA_Lib-x.y.z-cp3xx-cp3xx-os_arch.whl

Replace TA_Lib-x.y.z-cp3xx-cp3xx-os_arch.whl with the actual filename you downloaded.

Example:

# Example for Windows 64-bit, Python 3.11
pip install TA_Lib-0.6.3-cp311-cp311-win_amd64.whl

# Example for Linux 64-bit, Python 3.10
pip install TA_Lib-0.6.3-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Customization

You can modify the build process by editing the workflow file .github/workflows/build.yml. Key environment variables include:

  • TALIB_C_VER: Version of the TA-Lib C library to build.
  • TALIB_PY_VER: Version of the TA-Lib Python wrapper to build.
  • python-version (in matrix): List of Python versions to build for.
  • CIBW_SKIP: Patterns for Python versions/platforms to skip during the build.

License

Please refer to the LICENSE file in this repository and the licenses of TA-Lib C and TA-Lib Python themselves.

中文 (Chinese):

TA-Lib 预编译 Wheels (Windows & Linux x64)

项目简介

本项目提供了一个 GitHub Actions 工作流程，用于为 Windows (32位 和 64位) 以及 Linux (64位) 平台上的多种 Python 版本自动构建 TA-Lib (Technical Analysis Library) 的 Python wheel (.whl) 文件。

TA-Lib 是一个广泛用于金融市场技术分析的库。然而，安装原始的 TA-Lib Python 包通常比较困难，尤其是在 Windows 上，因为它需要预先编译好的 C 语言库。本项目生成的预编译 wheel 文件允许用户通过 pip 轻松安装 TA-Lib，无需手动编译 C 库。

特性

  • 为多个 Python 版本构建 wheel 文件 (当前支持 3.8 - 3.12)。
  • 支持 Windows 32位 (x86, win32) 和 64位 (AMD64, win_amd64) 架构。
  • 支持 Linux 64位 (x86_64, manylinux_x86_64) 架构。
    • 注意：明确跳过了 Linux 32位 (i686) 和 musllinux 的构建。
  • 使用特定版本的 TA-Lib C 库 (例如 0.6.4) 和 Python 绑定 (例如 0.6.3)。
  • 通过 pytest 自动测试构建好的 wheel 文件。
  • 可通过 workflow 文件中的环境变量轻松自定义构建参数（如版本、跳过的构建等）。

工作流程

本项目使用定义在 .github/workflows/build.yml 中的 GitHub Actions 工作流程来自动化构建过程。主要步骤包括：

  1. 检出代码: 获取仓库的最新代码。
  2. 设置环境: 为构建矩阵中的任务设置正确的 Python 版本和架构。安装必要的构建依赖（例如 Windows 上的 MSVC 工具，或 Linux 上的 build-essential, autoconf 等）。
  3. 构建 TA-Lib C 库:
    • 在 Windows 上: 执行 build.cmd 脚本，使用 CMake/NMake 编译 C 库。
    • 在 Linux 上: 执行 build.sh 脚本，使用 Autotools (configure, make) 编译 C 库。
  4. 构建 Wheels: 使用 cibuildwheel 在隔离的环境中（Linux 上是 Docker 容器）为目标 Python 版本和架构构建 Python wheel 文件。
  5. 测试 Wheels: 运行由 CIBW_TEST_COMMAND 定义的测试套件，以验证构建好的 wheel 文件。
  6. 上传构建产物: 将每个任务成功构建的 wheel 文件作为构建产物 (artifacts) 上传。
  7. 创建 Release (当推送标签时): 当一个匹配 v*.*.* 格式的标签被推送到仓库时，会自动创建一个 GitHub Release，并将所有构建好的 wheel 文件从构建产物中下载并附加到该 Release。

使用方法

获取预编译的 Wheel 文件

方式一：从 GitHub Releases 获取 (推荐，用于稳定版本)

  1. 访问本仓库的 Releases 页面 (请将 YOUR_USERNAME/YOUR_REPO 替换为实际的 URL)。
  2. 找到你需要的版本对应的 Release (例如，根据标签名称)。
  3. 直接从 Release 的 Assets (附件) 中下载适用于你的 Python 版本和操作系统/架构的 .whl 文件。

方式二：从 GitHub Actions 构建产物获取 (用于最新构建或测试)

  1. 访问本仓库的 Actions 标签页 (请将 YOUR_USERNAME/YOUR_REPO 替换为实际的 URL)。
  2. 选择最近一次成功的 "Build TA-Lib Wheels" 工作流程运行记录。
  3. 在运行记录摘要页面的底部找到 "Artifacts" (构建产物) 部分。
  4. 下载与你的操作系统、架构和 Python 版本对应的构建产物 (例如 talib-0.6.3-windows-latest-py3.11-win_amd64.whl)。构建产物可能是 zip 压缩文件，如果是，请先解压以获取 .whl 文件。

安装 Wheel 文件

下载到正确的 .whl 文件后，打开你的终端或命令提示符，切换到包含该文件的目录，然后使用 pip 进行安装：

pip install TA_Lib-x.y.z-cp3xx-cp3xx-os_arch.whl

请将 TA_Lib-x.y.z-cp3xx-cp3xx-os_arch.whl 替换为你实际下载的文件名。

示例:

# Windows 64位, Python 3.11 示例
pip install TA_Lib-0.6.3-cp311-cp311-win_amd64.whl

# Linux 64位, Python 3.10 示例
pip install TA_Lib-0.6.3-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

自定义

你可以通过编辑工作流程文件 .github/workflows/build.yml 来修改构建过程。关键的环境变量包括：

  • TALIB_C_VER: 要构建的 TA-Lib C 库的版本。
  • TALIB_PY_VER: 要构建的 TA-Lib Python 包装器的版本。
  • python-version (在 matrix 中): 要为其构建 wheel 的 Python 版本列表。
  • CIBW_SKIP: 用于在构建过程中跳过某些 Python 版本/平台的模式。

许可证

请参考本仓库中的 LICENSE 文件，以及 TA-Lib C 库和 TA-Lib Python 包本身的许可证。