Release 1.1.0: first-class async client support

.github/workflows/build-and-test.yml

@@ -4,11 +4,11 @@ on:
   pull_request:
     branches:
       - main
-      - release/1.0.0
+      - "release/**"
   push:
     branches:
       - main
-      - release/1.0.0
+      - "release/**"
   workflow_dispatch:
 
 permissions:
@@ -27,7 +27,7 @@ jobs:
       # first failure, so a single-version incompatibility is easy to isolate.
       fail-fast: false
       # Python 3.15 is intentionally absent: it is still a prerelease during the
-      # 1.0 release work and is not claimed as a supported version.
+      # 1.1 release work and is not claimed as a supported version.
       matrix:
         python-version:
           - "3.10"
@@ -48,13 +48,53 @@ jobs:
           virtualenvs-create: true
           virtualenvs-in-project: true
       - name: Install dependencies
-        run: poetry install --no-interaction
+        run: poetry install --no-interaction -E async
       - name: Run offline tests
         run: |
           poetry run pytest \
             tests/ \
             --ignore=tests/external_tests
 
+  sync-only:
+    name: Sync-only installation
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.14
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+
+      - name: Install Poetry
+        uses: snok/install-poetry@v1
+        with:
+          virtualenvs-create: true
+          virtualenvs-in-project: true
+
+      - name: Install dependencies without async extra
+        run: poetry install --no-interaction --only main
+
+      - name: Verify sync-only installation
+        run: |
+          poetry run python - <<'PY'
+          import importlib.util
+
+          assert importlib.util.find_spec("httpx") is None, (
+              "HTTPX should not be installed without the async extra"
+          )
+
+          import mlbstatsapi
+          from mlbstatsapi import Mlb, MlbDataAdapter
+
+          assert mlbstatsapi.Mlb is Mlb
+          assert mlbstatsapi.MlbDataAdapter is MlbDataAdapter
+
+          print("Sync-only installation verified without HTTPX")
+          PY
+
+
   build-package:
     name: Build and validate package
     needs: offline-tests

.github/workflows/claude-code-review.yml

@@ -0,0 +1,45 @@
+name: Claude Code Review
+
+on:
+  pull_request:
+    types: [opened, synchronize, ready_for_review, reopened]
+    # Optional: Only run on specific file changes
+    # paths:
+    #   - "src/**/*.ts"
+    #   - "src/**/*.tsx"
+    #   - "src/**/*.js"
+    #   - "src/**/*.jsx"
+
+jobs:
+  claude-review:
+    # Optional: Filter by PR author
+    # if: |
+    #   github.event.pull_request.user.login == 'external-contributor' ||
+    #   github.event.pull_request.user.login == 'new-developer' ||
+    #   github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'
+
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code Review
+        id: claude-review
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          plugin_marketplaces: 'https://github.com/anthropics/claude-code.git'
+          plugins: 'code-review@claude-code-plugins'
+          prompt: '/code-review:code-review --comment ${{ github.repository }}/pull/${{ github.event.pull_request.number }}'
+          claude_args: '--allowedTools "mcp__github_inline_comment__create_inline_comment"'
+          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
+          # or https://code.claude.com/docs/en/cli-reference for available options
+

.github/workflows/claude.yml

@@ -0,0 +1,50 @@
+name: Claude Code
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened, assigned]
+  pull_request_review:
+    types: [submitted]
+
+jobs:
+  claude:
+    if: |
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+      actions: read # Required for Claude to read CI results on PRs
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code
+        id: claude
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+
+          # This is an optional setting that allows Claude to read CI results on PRs
+          additional_permissions: |
+            actions: read
+
+          # Optional: Give a custom prompt to Claude. If this is not specified, Claude will perform the instructions specified in the comment that tagged it.
+          # prompt: 'Update the pull request description to include a summary of changes.'
+
+          # Optional: Add claude_args to customize behavior and configuration
+          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
+          # or https://code.claude.com/docs/en/cli-reference for available options
+          # claude_args: '--allowed-tools Bash(gh pr *)'
+

.github/workflows/external-tests.yml

@@ -26,7 +26,7 @@ jobs:
           virtualenvs-create: true
           virtualenvs-in-project: true
       - name: Install dependencies
-        run: poetry install --no-interaction
+        run: poetry install --no-interaction -E async
       - name: Run external MLB API tests
         run: |
           poetry run pytest \

CONTRIBUTING.md

@@ -19,11 +19,60 @@ Pull requests are the best way to propose changes to the codebase. We actively w
 4. Ensure the test suite passes.
 5. Issue that pull request!
 
+## Development
+
+Install dependencies:
+
+```bash
+poetry install -E async
+```
+
+Offline tests are deterministic and should run before every pull request:
+
+```bash
+poetry run pytest \
+  tests/ \
+  --ignore=tests/external_tests
+```
+
+External tests contact the live MLB API. They require internet access and are separate from normal offline CI:
+
+```bash
+poetry run pytest \
+  tests/external_tests/
+```
+
+These live tests may fail because the MLB service is unavailable or because MLB changes undocumented payloads.
+
+Full local validation:
+
+```bash
+poetry run pytest tests/
+rm -rf dist
+poetry build
+python3 scripts/validate_release.py
+poetry run twine check dist/*
+```
+
+`scripts/validate_release.py` is the same release check offline CI runs. It inspects the built wheel and source distribution, clean-installs each artifact into its own temporary virtual environment, and runs the same public-API smoke test against both installed artifacts. Every response it observes comes from injected fake HTTP clients, so it never contacts the MLB API.
+
+Offline CI is the normal pull-request gate. External tests are available manually, on a weekly schedule, and before releases.
+
+## Pull Request Guidelines
+
+- Run offline tests before submitting a PR
+- Use the [PR template](.github/pull_request_template.md) when creating your pull request
+- Follow the branch naming convention:
+  - `feat/` - New features
+  - `fix/` - Bug fixes
+  - `docs/` - Documentation updates
+  - `refactor/` - Code improvements
+
 ## Any contributions you make will be under the MIT Software License
 In short, when you submit code changes, your submissions are understood to be under the same [MIT License](http://choosealicense.com/licenses/mit/) that covers the project. Feel free to contact the maintainers if that's a concern.
 
 ## Report bugs using Github's [issues](https://github.com/zero-sum-seattle/python-mlb-statsapi/issues)
-We use GitHub issues to track public bugs. Report a bug by [opening a new issue](); it's that easy!
+We use GitHub issues to track public bugs. Report a bug by [opening a new issue](https://github.com/zero-sum-seattle/python-mlb-statsapi/issues/new).
 
 ## Write bug reports with detail, background, and sample code
 **Great Bug Reports** tend to have:
@@ -37,7 +86,7 @@ We use GitHub issues to track public bugs. Report a bug by [opening a new issue]
 - Notes (possibly including why you think this might be happening, or stuff you tried that didn't work)
 
 ## Use a Consistent Coding Style
-* Adhere to this projects coding style
+* Adhere to this project's coding style
 
 ## License
-By contributing, you agree that your contributions will be licensed under its MIT License.
+By contributing, you agree that your contributions will be licensed under its MIT License.