py-dem-bones 0.4.0__tar.gz

py_dem_bones-0.4.0/.coveragerc

@@ -0,0 +1,13 @@
+[run]
+branch = True
+source =
+
+[report]
+exclude_lines =
+    if self.debug:
+    pragma: no cover
+    raise NotImplementedError
+    if __name__ == .__main__.:
+ignore_errors = True
+omit =
+    tests/*

py_dem_bones-0.4.0/.dockerignore

@@ -0,0 +1,79 @@
+# Git
+.git
+.github
+.gitignore
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# C++ build artifacts
+*.o
+*.obj
+*.a
+*.lib
+*.dll
+*.so
+*.dylib
+*.exe
+CMakeFiles/
+CMakeCache.txt
+cmake_install.cmake
+Makefile
+*.cbp
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Sphinx documentation
+docs/_build/
+docs/generated/
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDE files
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store
+
+# CMake build directories
+_build/
+_skbuild/
+_cmake_build/

py_dem_bones-0.4.0/.flake8

@@ -0,0 +1,34 @@
+[flake8]
+ignore = BLK100
+
+# flake8-quotes:
+# Use double quotes as our default to comply with black, we like it and
+# don't want to use single quotes anymore.
+# We would love to configure this via our pyproject.toml but flake8-3.8 does
+# not support it yet.
+inline-quotes = double
+multiline-quotes = double
+docstring-quotes = double
+avoid-escape = True
+
+# flake8-docstrings
+# Use the Google Python Styleguide Docstring format.
+docstring-convention=google
+
+exclude =
+    # No need to traverse our git directory
+    .git,
+    # There's no value in checking cache directories
+    __pycache__,
+    # The conf file is mostly autogenerated, ignore it
+    docs/source/conf.py,
+    # The old directory contains Flake8 2.0
+    old,
+    # This contains our built documentation
+    build,
+    # This contains builds of flake8 that we don't want to check
+    dist,
+    venv,
+    docs
+
+max-line-length = 120

py_dem_bones-0.4.0/.github/CITATION.cff

@@ -0,0 +1,12 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+title: "py-dem-bones"
+abstract: "Python bindings for the Dem Bones library"
+authors:
+  - family-names: "Long"
+    given-names: "Hao"
+    email: "hal.long@outlook.com"
+version: 0.4.0
+date-released: 2024-03-05
+license: BSD-3-Clause
+repository-code: "https://github.com/loonghao/py-dem-bones"

py_dem_bones-0.4.0/.github/MACOS_OPTIMIZATION.md

@@ -0,0 +1,95 @@
+# macOS 环境 GitHub Actions 优化指南
+
+本文档总结了针对 py-dem-bones 项目在 macOS 环境下的 GitHub Actions 工作流优化策略。
+
+## 主要优化内容
+
+### 1. Homebrew 环境变量优化
+
+在所有使用 Homebrew 的步骤中添加以下环境变量，显著提高性能：
+
+```bash
+export HOMEBREW_NO_AUTO_UPDATE=1     # 禁止自动更新
+export HOMEBREW_NO_INSTALL_CLEANUP=1 # 禁止安装后清理
+export HOMEBREW_NO_ANALYTICS=1       # 禁止分析数据收集
+export HOMEBREW_NO_COLOR=1           # 禁止彩色输出
+```
+
+### 2. Eigen 库安装优化
+
+- 添加缓存检查，避免重复安装
+- 使用重试机制处理网络不稳定问题
+- 使用 `--quiet` 参数减少输出
+- 添加安装验证，确保安装成功
+
+### 3. 缓存策略优化
+
+- 添加 Homebrew 缓存，减少依赖下载时间
+- 优化 Eigen 库缓存，避免重复安装
+- 保留 pip 缓存，加速依赖安装
+
+### 4. 依赖安装优化
+
+- 使用清华大学镜像源加速依赖下载
+- 配置 pip 重试参数，提高网络稳定性
+- 使用 `--no-cache-dir` 参数避免缓存问题
+
+### 5. 重试机制实现
+
+- 创建 `retry_command.sh` 脚本，支持命令执行失败时自动重试
+- 实现指数退避策略，每次重试等待时间翻倍
+- 提供详细的日志输出，记录重试过程
+
+## 优化效果
+
+这些优化措施显著提高了 macOS 环境下的构建稳定性和性能：
+
+1. **构建速度提升**：通过缓存和优化的依赖安装，减少了构建时间
+2. **稳定性提高**：通过重试机制，降低了网络不稳定导致的构建失败
+3. **资源消耗降低**：通过跳过不必要的步骤，减少了资源消耗
+
+## 最佳实践建议
+
+1. **使用缓存**：尽可能使用缓存机制，避免重复下载和安装
+2. **添加重试机制**：对网络相关操作添加重试机制，提高稳定性
+3. **优化 Homebrew**：使用环境变量优化 Homebrew 性能
+4. **使用镜像源**：使用国内镜像源加速依赖下载
+5. **跳过不必要的步骤**：通过条件判断，跳过已完成的步骤
+
+## 后续优化方向
+
+1. **进一步减少构建矩阵**：考虑在 macOS 环境中只测试最新的 Python 版本
+2. **优化 Python 3.7 支持**：考虑在 macOS 环境中移除 Python 3.7 支持，或使用更高效的安装方式
+3. **并行构建优化**：探索更多并行构建的可能性，进一步提高构建速度
+
+## macOS 运行器资源优化
+
+GitHub Actions 中的 macOS 运行器资源通常比 Linux 运行器更为有限，可能导致构建任务长时间等待。以下是一些解决方案：
+
+### 1. 减少 macOS 构建矩阵
+
+- 仅在主分支和发布分支上运行完整的 macOS 测试矩阵
+- 在 Pull Request 中仅使用最新的 Python 版本进行 macOS 测试
+- 使用条件表达式控制何时运行 macOS 构建：
+  ```yaml
+  if: ${{ github.event_name != 'pull_request' || github.base_ref == 'main' }}
+  ```
+
+### 2. 使用自托管运行器
+
+如果有条件，可以考虑使用自托管的 macOS 运行器，这样可以：
+- 避免等待 GitHub 托管的 macOS 运行器
+- 自定义硬件配置，提高构建性能
+- 预装所需的依赖，减少安装时间
+
+### 3. 优化构建并发性
+
+- 使用 `concurrency` 配置限制同时运行的 macOS 作业数量
+- 优先处理关键分支的构建任务
+- 取消正在运行的冗余构建，例如当有新的提交推送到同一个 PR 时
+
+### 4. 使用缓存预热
+
+- 定期运行构建任务以预热缓存
+- 使用 `actions/cache` 的 `restore-keys` 功能利用部分匹配的缓存
+- 考虑使用 GitHub Packages 或其他制品存储来缓存预构建的依赖

py_dem_bones-0.4.0/.github/scripts/create_gh_pages_structure.sh

@@ -0,0 +1,77 @@
+#!/bin/bash
+# 创建 GitHub Pages 目录结构和重定向文件
+# 用法: ./create_gh_pages_structure.sh <docs_build_dir>
+
+set -ex
+
+# 获取当前目录的绝对路径
+CURRENT_DIR=$(pwd)
+DOCS_BUILD_DIR=${1:-"docs/_build/html"}
+ROOT_DIR="${CURRENT_DIR}/gh-pages-root"
+LATEST_DIR="${ROOT_DIR}/latest"
+
+echo "Creating GitHub Pages directory structure..."
+echo "Current directory: ${CURRENT_DIR}"
+echo "Docs build directory: ${DOCS_BUILD_DIR}"
+echo "Root directory: ${ROOT_DIR}"
+echo "Latest directory: ${LATEST_DIR}"
+
+# 1. 验证文档构建目录
+if [ ! -d "${DOCS_BUILD_DIR}" ]; then
+    echo "Warning: Docs build directory does not exist: ${DOCS_BUILD_DIR}"
+    echo "Available directories in docs:"
+    ls -la docs/
+    echo "Creating empty docs build directory."
+    mkdir -p "${DOCS_BUILD_DIR}"
+    echo "<html><body><h1>Placeholder Documentation</h1></body></html>" > "${DOCS_BUILD_DIR}/index.html"
+else
+    echo "Docs build directory exists."
+    ls -la "${DOCS_BUILD_DIR}"
+fi
+
+# 2. 创建目录结构
+mkdir -p "${ROOT_DIR}"
+mkdir -p "${LATEST_DIR}"
+
+echo "Directory structure created:"
+ls -la "${ROOT_DIR}"
+
+# 3. 创建根目录的 index.html (重定向到latest)
+cat > "${ROOT_DIR}/index.html" << EOF
+<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="utf-8">
+    <title>py-dem-bones Documentation</title>
+    <meta http-equiv="refresh" content="0; url=./latest/">
+    <link rel="canonical" href="./latest/">
+</head>
+<body>
+    <p>Redirecting to <a href="./latest/">latest documentation</a>...</p>
+    <script>window.location.href = "./latest/";</script>
+</body>
+</html>
+EOF
+
+# 4. 复制文档文件到latest目录
+echo "Copying documentation to latest directory..."
+if [ -d "${DOCS_BUILD_DIR}" ] && [ "$(ls -A ${DOCS_BUILD_DIR})" ]; then
+    mkdir -p "${LATEST_DIR}"
+    cp -rv "${DOCS_BUILD_DIR}"/* "${LATEST_DIR}/"
+    echo "Documentation files copied successfully."
+else
+    echo "Warning: No documentation files to copy."
+    mkdir -p "${LATEST_DIR}"
+    echo "<html><body><h1>No Documentation Available</h1></body></html>" > "${LATEST_DIR}/index.html"
+fi
+
+# 5. 验证复制操作
+if [ ! -f "${LATEST_DIR}/index.html" ]; then
+    echo "Warning: index.html not found in latest directory. Creating a placeholder."
+    echo "<html><body><h1>Placeholder Documentation</h1></body></html>" > "${LATEST_DIR}/index.html"
+else
+    echo "Successfully verified documentation copy."
+fi
+
+ls -la "${LATEST_DIR}"
+echo "GitHub Pages structure created and documentation copied successfully."

py_dem_bones-0.4.0/.github/scripts/linux/setup_eigen.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+# Linux 平台安装 Eigen 库
+
+# 安装 Eigen 库
+sudo apt-get update
+sudo apt-get install -y libeigen3-dev
+
+# 创建符号链接
+mkdir -p extern/eigen
+sudo ln -sf /usr/include/eigen3/Eigen extern/eigen/Eigen
+
+echo "Eigen 库已成功安装并链接"

py_dem_bones-0.4.0/.github/scripts/mac/retry_command.sh

@@ -0,0 +1,51 @@
+#!/bin/bash
+# macOS 平台命令重试脚本
+
+# 参数说明
+# $1: 最大重试次数
+# $2: 初始重试延迟（秒）
+# $3 及以后: 要执行的命令及其参数
+
+# 检查参数
+if [ $# -lt 3 ]; then
+  echo "用法: $0 <最大重试次数> <初始重试延迟> <命令...>"
+  exit 1
+fi
+
+MAX_RETRIES=$1
+RETRY_DELAY=$2
+shift 2  # 移除前两个参数，剩下的是要执行的命令
+
+# 执行命令并在失败时重试
+attempt=0
+while [ $attempt -lt $MAX_RETRIES ]; do
+  if [ $attempt -gt 0 ]; then
+    echo "重试尝试 $attempt/$MAX_RETRIES: $@"
+  fi
+  
+  # 执行命令
+  "$@"
+  exit_code=$?
+  
+  # 检查命令是否成功
+  if [ $exit_code -eq 0 ]; then
+    # 命令成功，退出循环
+    if [ $attempt -gt 0 ]; then
+      echo "命令在第 $attempt 次尝试后成功执行"
+    fi
+    exit 0
+  else
+    # 命令失败
+    attempt=$((attempt + 1))
+    if [ $attempt -lt $MAX_RETRIES ]; then
+      echo "命令失败，退出代码: $exit_code"
+      echo "等待 $RETRY_DELAY 秒后重试..."
+      sleep $RETRY_DELAY
+      # 指数退避策略
+      RETRY_DELAY=$((RETRY_DELAY * 2))
+    else
+      echo "命令在 $MAX_RETRIES 次尝试后仍然失败"
+      exit $exit_code
+    fi
+  fi
+done

py_dem_bones-0.4.0/.github/scripts/mac/setup_eigen.sh

@@ -0,0 +1,40 @@
+#!/bin/bash
+# macOS 平台安装 Eigen 库
+
+set -e  # 遇到错误立即退出
+
+# 检查是否已安装
+if [ -d "extern/eigen/Eigen" ]; then
+  echo "Eigen 库已安装，跳过安装步骤..."
+  exit 0
+fi
+
+echo "开始安装 Eigen 库..."
+
+# 创建目录
+mkdir -p extern/eigen
+
+# 检查 brew 是否已安装 eigen
+if brew list eigen &>/dev/null; then
+  echo "Eigen 已通过 brew 安装，使用现有安装..."
+else
+  # 使用重试脚本安装 Eigen
+  echo "通过 brew 安装 Eigen（带重试机制）..."
+  # 确保重试脚本有执行权限
+  chmod +x .github/scripts/mac/retry_command.sh
+  
+  # 使用重试脚本执行 brew 安装命令，最多重试 3 次，初始延迟 5 秒
+  .github/scripts/mac/retry_command.sh 3 5 brew install --quiet eigen
+fi
+
+# 获取 Eigen 路径并创建符号链接
+EIGEN_PATH=$(brew --prefix eigen)
+ln -sf $EIGEN_PATH/include/eigen3/Eigen extern/eigen/Eigen
+
+# 验证安装
+if [ -d "extern/eigen/Eigen" ]; then
+  echo "Eigen 库已成功安装并链接，路径: $EIGEN_PATH"
+else
+  echo "Eigen 库安装失败"
+  exit 1
+fi

py_dem_bones-0.4.0/.github/scripts/py37/setup_env.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+# Python 3.7 环境设置脚本
+
+# 安装基础依赖
+python -m pip install --upgrade pip
+python -m pip install pipx
+pipx install nox
+python -m pip install pytest pytest-cov
+
+# 安装兼容 Python 3.7 的依赖版本
+python -m pip install -e ".[dev]"
+python -m pip install "isort<5.12.0"
+python -m pip install "black<23.0.0"
+python -m pip install "ruff<0.1.0"
+python -m pip install mypy
+
+echo "Python 3.7 环境已设置完成"

py_dem_bones-0.4.0/.github/scripts/win/setup_eigen.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+# Windows 平台安装 Eigen 库
+
+# 创建目录
+mkdir -p extern/eigen
+
+# 直接下载 Eigen 库 zip 文件
+curl -L -o eigen.zip https://gitlab.com/libeigen/eigen/-/archive/3.4.0/eigen-3.4.0.zip
+
+# 解压并复制 Eigen 目录
+unzip -q eigen.zip
+cp -r eigen-3.4.0/Eigen extern/eigen/
+
+# 清理临时文件
+rm -rf eigen.zip eigen-3.4.0
+
+echo "Eigen 库已成功安装到 extern/eigen 目录"

py_dem_bones-0.4.0/.github/workflows/README.md

@@ -0,0 +1,180 @@
+# GitHub Actions 工作流
+
+本项目使用优化的 GitHub Actions 工作流，确保高效的构建、测试和发布流程。
+
+## 目录结构
+
+```
+.github/
+├── scripts/              # 平台特定脚本
+│   ├── linux/            # Linux 平台脚本
+│   │   └── setup_eigen.sh
+│   ├── mac/              # macOS 平台脚本
+│   │   └── setup_eigen.sh
+│   ├── win/              # Windows 平台脚本
+│   │   └── setup_eigen.sh
+│   └── py37/             # Python 3.7 特定脚本
+│       └── setup_env.sh
+└── workflows/            # GitHub Actions 工作流
+    ├── main.yml          # 主工作流（PR 和 push 触发）
+    ├── workflow-dispatch.yml # 手动触发工作流
+    ├── release.yml       # 发布工作流（标签触发）
+    ├── reusable-jobs.yml # 可重用任务定义
+    ├── bumpversion.yml   # 版本更新工作流
+    └── issue-translator.yml # 问题翻译工作流
+```
+
+## 工作流说明
+
+### 主工作流 (`main.yml`)
+
+主工作流在代码推送到主分支或创建 Pull Request 时自动运行。它执行以下任务：
+
+- **构建任务**: 在所有支持的平台（Ubuntu、macOS、Windows）和 Python 版本（3.7-3.13）上构建包
+- **测试任务**: 在 PR 时在所有支持的平台和 Python 版本上运行测试
+- **代码检查任务**: 在 PR 时只在 Python 3.11 + Ubuntu 环境中执行一次
+- **文档构建任务**: 在 PR 时只在 Python 3.10 + Ubuntu 环境中执行一次
+
+### 手动触发工作流 (`workflow-dispatch.yml`)
+
+允许手动触发特定任务，支持以下选项：
+
+- **all**: 运行所有任务
+- **build**: 只运行构建任务
+- **test**: 只运行测试任务
+- **lint**: 只运行代码检查任务
+- **docs**: 只运行文档构建任务
+- **release**: 只运行发布任务（不会实际发布到 PyPI）
+
+### 发布工作流 (`release.yml`)
+
+当创建新的版本标签（以 'v' 开头）时自动运行，执行以下任务：
+
+- 在所有支持的平台和 Python 版本上构建包
+- 构建文档
+- 创建 GitHub Release
+- 发布包到 PyPI
+
+### 可重用任务 (`reusable-jobs.yml`)
+
+定义了可在其他工作流中重用的任务：
+
+- **build-and-test**: 构建和测试任务
+- **lint**: 代码检查任务
+- **docs**: 文档构建任务
+- **release**: 发布任务
+
+## 优化特点
+
+1. **资源优化**: 代码检查和文档构建任务只在单一环境中执行一次，避免重复执行
+2. **Python 版本支持**: 支持 Python 3.7 到 3.13 版本
+3. **平台覆盖**: 在 Ubuntu、macOS 和 Windows 上进行测试
+4. **模块化设计**: 使用可重用任务，简化工作流维护
+5. **自动发布**: 标签推送时自动构建并发布到 PyPI
+
+## 使用方法
+
+- **自动构建和测试**: 创建 Pull Request 或推送到主分支
+- **手动触发特定任务**: 在 GitHub Actions 页面选择 "Workflow Dispatch" 工作流
+- **发布新版本**: 创建以 'v' 开头的新标签（如 v0.1.0）
+
+## GitHub Actions Workflows
+
+This directory contains GitHub Actions workflows for the `py-dem-bones` project. These workflows automate various tasks such as testing, building, documentation generation, and releases.
+
+## Workflows
+
+### 1. Main Workflow (`main.yml`)
+
+The main workflow runs on pull requests to the `main` branch and when code is pushed to the `main` branch. It performs the following tasks:
+
+- **Linting**: Checks code quality using tools like Ruff, Black, and isort
+- **Building**: Builds the project to ensure it compiles correctly
+- **Testing**: Runs unit tests across different Python versions and operating systems
+- **Documentation**:
+  - For PRs: Builds and deploys a preview of the documentation
+  - For main branch: Builds and deploys the latest documentation
+
+#### Documentation URLs
+
+- **Latest Documentation**: https://[owner].github.io/py-dem-bones/latest/
+- **PR Previews**: https://[owner].github.io/py-dem-bones/pr-preview/[PR_NUMBER]/
+
+### 2. Bump Version Workflow (`bumpversion.yml`)
+
+This workflow automatically bumps the version and creates a changelog based on commit messages. It runs when code is pushed to the `main` branch.
+
+Key features:
+- Uses [Commitizen](https://github.com/commitizen-tools/commitizen) to determine the next version
+- Creates a changelog based on commit messages
+- Commits the version bump and changelog to the repository
+
+### 3. Release Workflow (`release.yml`)
+
+This workflow creates a release when a new version tag is pushed to the repository. It performs the following tasks:
+
+- Builds the project for different platforms
+- Creates a GitHub release with release notes
+- Publishes the package to PyPI
+
+## Usage
+
+### Commit Messages
+
+To ensure proper versioning, follow the [Conventional Commits](https://www.conventionalcommits.org/) format for your commit messages:
+
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer]
+```
+
+Where `type` is one of:
+- `feat`: A new feature (triggers a minor version bump)
+- `fix`: A bug fix (triggers a patch version bump)
+- `docs`: Documentation changes
+- `style`: Code style changes (formatting, etc.)
+- `refactor`: Code refactoring
+- `perf`: Performance improvements
+- `test`: Adding or updating tests
+- `chore`: Maintenance tasks
+
+Breaking changes should be indicated with a `!` after the type/scope or with `BREAKING CHANGE:` in the footer, which will trigger a major version bump.
+
+### Manual Workflow Dispatch
+
+The main workflow can be manually triggered using the "workflow_dispatch" event in GitHub's UI. This is useful for running the workflow without making changes to the code.
+
+### Permissions
+
+The workflows require specific permissions to function correctly:
+- `contents: write`: For pushing to branches and creating releases
+- `pull-requests: write`: For adding comments to PRs
+- `pages: write`: For deploying to GitHub Pages
+
+## Troubleshooting
+
+### 404 Errors on GitHub Pages
+
+If you encounter 404 errors when accessing the documentation:
+
+1. Ensure GitHub Pages is enabled in the repository settings
+2. Check that the source is set to the `gh-pages` branch
+3. Wait a few minutes for GitHub Pages to deploy after the workflow completes
+4. Verify that the `gh-pages` branch contains the expected content
+
+### Failed Workflow Runs
+
+If a workflow run fails:
+
+1. Check the workflow logs for error messages
+2. Ensure all dependencies are correctly specified
+3. Verify that the required secrets are configured in the repository settings
+4. Try running the failing steps locally to debug the issue
+
+## Environment Variables
+
+- `SKIP_CMAKE_BUILD`: Set to `1` to skip the CMake build step when building documentation
+- `PERSONAL_ACCESS_TOKEN`: GitHub token with required permissions for version bumping and releases

py_dem_bones-0.4.0/.github/workflows/bumpversion.yml

@@ -0,0 +1,56 @@
+name: Bump version
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+    inputs:
+      bump_type:
+        description: '版本升级类型'
+        required: true
+        default: 'auto'
+        type: choice
+        options:
+          - auto
+          - major
+          - minor
+          - patch
+
+jobs:
+  bump-version:
+    if: "!startsWith(github.event.head_commit.message, 'bump:') && !startsWith(github.event.head_commit.message, 'chore(release)')"
+    runs-on: ubuntu-latest
+    name: "Bump version and create changelog with commitizen"
+    permissions:
+      contents: write
+      pull-requests: write
+    
+    steps:
+      - name: Check out
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: '${{ secrets.PERSONAL_ACCESS_TOKEN }}'
+      
+      - name: Create bump and changelog
+        id: cz
+        uses: commitizen-tools/commitizen-action@0.24.0
+        with:
+          github_token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
+          branch: main
+          version_scheme: ${{ github.event.inputs.bump_type || 'auto' }}
+          version_files: |
+            pyproject.toml:version
+            src/py_dem_bones/__version__.py
+            docs/conf.py:release
+            docs/conf.py:version
+            .github/CITATION.cff:version
+          changelog_increment_filename: .changelog_increment.md
+          changelog: true
+      
+      - name: Print Version
+        run: |
+          echo "Bumped to version ${{ steps.cz.outputs.version }}"
+          echo "Changelog increment:"
+          cat .changelog_increment.md