butterbot-python 3.1.0.dev1__tar.gz

butterbot_python-3.1.0.dev1/.github/workflows/ci.yml

@@ -0,0 +1,79 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  docs:
+    name: Documentation
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: "24"
+          cache: npm
+
+      - name: Install documentation dependencies
+        run: npm ci
+
+      - name: Build and validate documentation
+        run: npm run docs:check
+
+  test:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --locked --dev --python "${{ matrix.python-version }}"
+
+      - name: Lint
+        if: matrix.python-version == '3.12'
+        run: uv run ruff check .
+
+      - name: Format check
+        if: matrix.python-version == '3.12'
+        run: uv run ruff format --check .
+
+      - name: Type check
+        if: matrix.python-version == '3.12'
+        run: uv run pyright
+
+      - name: Test with coverage gate
+        if: matrix.python-version == '3.12'
+        run: >
+          uv run pytest
+          --cov=butterbot
+          --cov-report=term-missing
+          --cov-fail-under=70
+
+      - name: Test
+        if: matrix.python-version != '3.12'
+        run: uv run pytest
+
+      - name: Build distributions
+        if: matrix.python-version == '3.12'
+        run: uv build

butterbot_python-3.1.0.dev1/.github/workflows/release-on-version.yml

@@ -0,0 +1,125 @@
+name: Release on tag
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --locked --dev --python "3.12"
+
+      - name: Validate tag and branch
+        id: meta
+        shell: bash
+        run: |
+          TAG="${GITHUB_REF_NAME}"
+
+          git fetch origin main dev_main --prune
+
+          PROJECT_VERSION="$(python -c \
+            'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')"
+          PROJECT_NAME="$(python -c \
+            'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["name"])')"
+          if [[ "$PROJECT_NAME" != "butterbot-python" ]]; then
+            echo "Project name $PROJECT_NAME does not match expected package name butterbot-python"
+            exit 1
+          fi
+
+          TAG_VERSION="${TAG#v}"
+          if [[ "$TAG_VERSION" != "$PROJECT_VERSION" ]]; then
+            echo "Tag version $TAG_VERSION does not match project version $PROJECT_VERSION"
+            exit 1
+          fi
+
+          if [[ "$PROJECT_VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            CHANNEL="stable"
+            REQUIRED_BRANCH="main"
+            PRERELEASE="false"
+          elif [[ "$PROJECT_VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+\.dev[0-9]+$ ]]; then
+            CHANNEL="dev"
+            REQUIRED_BRANCH="dev_main"
+            PRERELEASE="true"
+          else
+            echo "Invalid project version: $PROJECT_VERSION"
+            echo "Expected stable tag: v3.0.5"
+            echo "Expected dev tag: v3.0.5.dev1"
+            exit 1
+          fi
+
+          if ! git branch -r --contains "$GITHUB_SHA" | grep -q "origin/${REQUIRED_BRANCH}$"; then
+            echo "Tag $TAG is not on required branch: $REQUIRED_BRANCH"
+            exit 1
+          fi
+
+          echo "tag=$TAG" >> "$GITHUB_OUTPUT"
+          echo "channel=$CHANNEL" >> "$GITHUB_OUTPUT"
+          echo "prerelease=$PRERELEASE" >> "$GITHUB_OUTPUT"
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Format check
+        run: uv run ruff format --check .
+
+      - name: Type check
+        run: uv run pyright
+
+      - name: Test with coverage gate
+        run: >
+          uv run pytest
+          --cov=butterbot
+          --cov-report=term-missing
+          --cov-fail-under=70
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+
+      - name: Create GitHub Release
+        shell: bash
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG_NAME: ${{ steps.meta.outputs.tag }}
+          PRERELEASE: ${{ steps.meta.outputs.prerelease }}
+        run: |
+          RELEASE_ARGS=(
+            --title "$TAG_NAME"
+            --generate-notes
+            --verify-tag
+          )
+
+          if [[ "$PRERELEASE" == "true" ]]; then
+            RELEASE_ARGS+=(--prerelease --latest=false)
+          else
+            RELEASE_ARGS+=(--latest)
+          fi
+
+          gh release create "$TAG_NAME" dist/* "${RELEASE_ARGS[@]}"

butterbot_python-3.1.0.dev1/.gitignore

@@ -0,0 +1,51 @@
+# === Python ===
+__pycache__/
+*.py[cod]
+
+# === Virtual Env ===
+venv/
+.venv/
+
+# === Environment ===
+.env
+.env.*
+
+# === Logs ===
+*.log
+logs
+
+# === IDE ===
+.idea/
+.vscode/
+
+# === OS ===
+.DS_Store
+Thumbs.db
+
+# === Local config ===
+config.local.py
+settings.local.yaml
+
+# === AI ===
+CLAUDE.md
+.claude
+
+# === Dev ===
+dev
+output.txt
+get_txt.py
+.pyright/
+.mypy_cache/
+
+# === VuePress ===
+node_modules/
+docs/.vuepress/.cache/
+docs/.vuepress/.temp/
+docs/.vuepress/dist/
+
+# === 用户凭证配置（切勿提交）===
+/config.yaml
+config.json
+
+# === Coverage ===
+.coverage

butterbot_python-3.1.0.dev1/.markdownlint-cli2.mjs

@@ -0,0 +1,11 @@
+export default {
+  config: {
+    MD013: false,
+    MD024: { siblings_only: true },
+    MD025: false,
+    MD033: false,
+    MD041: false,
+  },
+  globs: ["README.md", "docs/**/*.md"],
+  ignores: ["docs/.vuepress/**", "docs/review/**"],
+}

butterbot_python-3.1.0.dev1/.pre-commit-config.yaml

@@ -0,0 +1,18 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.20
+    hooks:
+      - id: ruff
+        args: ["--fix"]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-json
+      - id: check-merge-conflict
+      - id: detect-private-key

butterbot_python-3.1.0.dev1/.python-version

@@ -0,0 +1 @@
+3.12

butterbot_python-3.1.0.dev1/AGENTS.md

@@ -0,0 +1,71 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+Production code lives in `butterbot/`. `core/` contains framework contracts,
+events, data models, and lifecycle primitives; `app/` provides `BotApp`,
+configuration, and source management; `sources/bilibili/` and
+`sources/napcat/` contain integrations; `utils/` contains logging and WebSocket
+support. Tests mirror this layout under `tests/`. User-facing examples and the
+configuration template are in `examples/`, while architecture and API guides
+are in `docs/`.
+
+Keep dependencies flowing toward `core`: integrations may depend on core
+contracts, but core must not import application or source implementations.
+
+## Build, Test, and Development Commands
+
+- `uv sync --locked --dev` installs the locked runtime and development
+  environment.
+- `uv run pytest` runs the complete test suite.
+- `uv run pytest --cov=butterbot --cov-report=term-missing --cov-fail-under=70`
+  enforces the CI coverage floor.
+- `uv run ruff check .` checks imports and lint rules.
+- `uv run ruff format --check .` verifies formatting; omit `--check` to format.
+- `uv run pyright` runs static type checking.
+- `uv build` creates the wheel and source distribution.
+- `uv run pre-commit run --all-files` reproduces repository hooks.
+
+Copy `examples/config.example.yaml` to `config.yaml` before running examples.
+Never commit the resulting file or real credentials.
+
+## Coding Style & Naming Conventions
+
+Use Python 3.12+ syntax, four-space indentation, double quotes, and an 88-column
+target. Ruff owns formatting and import ordering. Use `snake_case` for
+functions/modules, `PascalCase` for classes, and descriptive type parameters.
+Public APIs require useful type annotations. Preserve lifecycle ownership:
+sources close their tasks, the event bus owns callback tasks, and APIs release
+connections through `aclose()`.
+
+Code comments should be written in Chinese when comments are needed. Prefer
+comments that explain intent, constraints, or non-obvious behavior rather than
+restating the code.
+
+Function names, class names, and variable names should follow normal Python
+naming conventions:
+
+- `snake_case` for functions, methods, modules, and variables
+- `PascalCase` for classes
+- `UPPER_CASE` for constants when appropriate
+
+## Testing Guidelines
+
+Pytest and `pytest-asyncio` are used. Name files `test_*.py`, classes `Test*`,
+and functions `test_*`. Add a regression test before fixing confirmed defects.
+Tests must avoid external networks, ordering dependencies, unnecessary sleeps,
+global-state leakage, and unfinished asyncio tasks. Cover cancellation,
+timeouts, exception propagation, and idempotent shutdown when changing async
+code.
+
+## Commit & Pull Request Guidelines
+
+Follow Conventional Commits for commit messages: keep the type and optional
+scope in English, and write the subject in concise Chinese. Examples:
+`feat: 新增配置加载` or `fix(core): 修复重复初始化`.
+
+Keep each commit focused and include its tests.
+
+Pull requests should explain the problem, behavioral and API impact,
+verification commands, and related issue. Include logs for lifecycle or CLI
+changes; screenshots are only needed for visual changes.