PyGithub 2.9.0__tar.gz → 2.10.0__tar.gz

pygithub-2.10.0/.claude/skills/openapi/SKILL.md

@@ -0,0 +1,275 @@
+---
+name: OpenAPI
+description: Script to create or modify PyGithub classes according to Github REST API OpenAPI specification.
+---
+
+# OpenAPI script
+
+First read [OPENAPI.md](../../../OPENAPI.md).
+
+The script lives at `scripts/openapi.py`. Invoke the script with `python3 scripts/openapi.py ...`
+
+Generated code is not guaranteed to compile and work. It merely represents a suggestion and best practice.
+
+## Contents
+- Commands
+- Notable files
+
+## Commands
+- help: provide help on using the script
+- init: run before the first use of the OpenAPI Python script
+- fetch: fetch an OpenAPI spec file
+- index: index the OpenAPI spec file and PyGithub code base
+- suggest: suggest paths or schemas
+- apply: apply schema to class' properties (add/update attributes) or class' paths (add/update methods)
+- create: create a new PyGithub class or method
+
+Use option `--dry-run` to make a command read-only.
+
+The index command creates a JSON file that is used by almost all other commands. Any change to PyGithub source code
+requires to rerun (re-index) the index command and update the [OpenAPI index JSON file](#OpenAPI index JSON file). A index file is tightly
+connected with the [OpenAPI spec JSON file](#OpenAPI spec JSON file) that was used in the index command. Using a different spect JSON file
+requires a different index file.
+
+Any code and test changes require fixing linting issues by running `pre-commit` and `mypy`.
+
+Suggest updating this skill whenever interactions with the `openapi.py` script fail and
+inspection of inner mechanics or invocation are needed. Add your findings to this skill
+to avoid such inspections in the future.
+
+### Invocation cheat sheet
+
+Argument placement matters because of argparse:
+- **Global flags** (`--dry-run`, `--verbose`, `--exit-code`) go **before** the command:
+  `openapi.py --dry-run apply ...`
+- **command flags** (e.g. `--new-schemas`, `--tests`, `--add`) go **after** the command but **before** the positional arguments:
+  `openapi.py apply --new-schemas as-dict github/ <spec> <index> <Class>`
+  Placing a command flag after the trailing positional class names fails with `error: unrecognized arguments`.
+
+### help
+Provides input on how to use commands, shows full set of options.
+
+```bash
+openapi.py --help
+openapi.py COMMAND --help
+openapi.py COMMAND SUB-COMMAND --help
+```
+
+### init
+If no [OpenAPI spec JSON file](#OpenAPI spec JSON file) and no [OpenAPI index JSON file](#OpenAPI index JSON file) exists,
+run the following sequence of commands (generates those files):
+- fetch
+- index
+
+### fetch
+Fetches the [OpenAPI spec JSON file](#OpenAPI spec JSON file) from the github.com. It is good practice to
+use the time of retrieval as part of the filename to never overwrite an existing local spec file.
+Create a symbolic link from `api.github.com.YYYY-MM-DD.json` to the latest `api.github.com.YYYY-MM-DD.YYYYMMDDTHHMMSS.json`
+to simplify subsequent reference of the latest spec file.
+
+```
+usage: openapi.py fetch [-h] [--commit [COMMIT]] api api_version spec
+
+positional arguments:
+  api                Github API, e.g. api.github.com, ghec, ghes-3.15. See https://github.com/github/rest-api-description/tree/main/descriptions
+  api_version        Github API version date, e.g. 2022-11-28
+  spec               Github API OpenAPI spec file to be written
+
+options:
+  -h, --help         show this help message and exit
+  --commit [COMMIT]  Specific commit to fetch file from
+```
+
+### index
+Index the spec file and PyGithub codebase and store information in the [OpenAPI index JSON file](#OpenAPI index JSON file).
+```
+usage: openapi.py index [-h] [--check-verbs] github_path [spec] index_filename
+```
+Overwrite an existing index file if needed without asking for approval.
+
+### suggest
+These sub-commands exist:
+- suggest paths
+- suggest schemas
+
+Ask user what to suggest if the sub-command is not clear.
+
+#### suggest paths
+Suggests which paths a class should implement.
+
+```
+usage: openapi.py suggest paths [-h] spec index_filename [class_name ...]
+```
+
+Example output:
+```
+Class Artifact
+- Implements schema /components/schemas/artifact
+  - Returned by path /repos/{owner}/{repo}/actions/artifacts/{artifact_id}
+    - get /repos/{owner}/{repo}/actions/artifacts/{artifact_id}/{archive_format} should be implemented as Artifact.download() or Artifact.get_download_link()
+      python scripts/openapi.py create method api.github.com.2022-11-28.json openapi.index Artifact download get /repos/{owner}/{repo}/actions/artifacts/{artifact_id}/{archive_format}
+      python scripts/openapi.py create method api.github.com.2022-11-28.json openapi.index Artifact get_download_link get /repos/{owner}/{repo}/actions/artifacts/{artifact_id}/{archive_format}
+
+```
+The output provides evidence for the suggestion ("Implements schema", "Returned by path"), the path and verb, suggested method name alternatives ("download", "get_download_link") and a list of openapi.py commands that would create those method alternatives.
+
+This does not modify any files.
+
+#### suggest schemas
+Suggests which schemas a class should implement.
+
+```
+usage: openapi.py suggest schemas [-h] [--add] spec index_filename [class_name ...]
+```
+Example output:
+```
+Class Commit:
+- should implement schema /components/schemas/commit
+  Methods returning the schema:
+  - PullRequest.get_commits
+  - Repository.get_commit
+  - Repository.merge
+  - Repository.get_commits
+Paths returning the class:
+- GET /repos/{owner}/{repo}/commits
+- GET /repos/{owner}/{repo}/commits/{ref}
+- GET /repos/{owner}/{repo}/pulls/{pull_number}/commits
+- POST /repos/{owner}/{repo}/merges
+```
+The output provides evidence which methods return the schema / paths and vers return the class. Those paths have response schemas defined in the OpenAPI spect JSON file.
+
+Option `--add` adds the schemas to the classes.
+
+Only option `--add` modifies files, unless `--dry-run` is given.
+
+### apply
+These sub-commands exist:
+- apply properties
+- apply methods
+
+Ask user what to suggest if the sub-command is not clear.
+
+#### apply properties
+Applies a schema to a class' source code: adds/updates the `_initAttributes`, `@property` accessors and
+`_useAttributes` entries for every property of the schema(s) the class implements. The class' docstring
+lists all OpenAPI schemas it implements.
+
+```
+usage: openapi.py apply properties [-h] [--tests] [--new-schemas {ignore,create-class,as-dict}] github_path spec index_filename [class_name ...]
+
+positional arguments:
+  github_path           Path to PyGithub Python files
+  spec                  Github API OpenAPI spec file
+  index_filename        Path of index file
+  class_name            PyGithub GithubObject class name
+
+options:
+  -h, --help            show this help message and exit
+  --tests               Also apply spec to test files
+  --new-schemas {ignore,create-class,as-dict}
+                        How to handle attributes that return schemas that are not implemented by any PyGithub: 'ignore', 'create-class' crates class implementation drafts, 'as-dict'
+                        return dict[str, Any]). Option 'create-class' does not support --dry-run.
+```
+
+Flag `--new-schemas` controls attributes whose schema is not implemented by any PyGithub class:
+- `ignore` (default): the attribute is skipped (logged as `Schema not implemented: ...`, only with `--verbose`).
+- `as-dict`: the attribute becomes `dict[str, Any]` via `_makeDictAttribute`. Good for nested objects that
+  existing classes already model as a dict (check for precedent before inventing new classes).
+- `create-class`: drafts new class files. Those classes may recursively create more new classes for other new schemas.
+  **Does not support `--dry-run`.**
+
+Preview with `--dry-run` (prints a unified diff). Add `--verbose` to see which properties were skipped as not-implemented.
+
+#### apply methods
+Applies OpenAPI path schemas to existing methods: adds/updates method arguments, docstrings, assertions and web calls.
+
+```
+usage: openapi.py apply methods [-h] [--rewrite] spec index_filename [class_or_class_method_name ...]
+
+positional arguments:
+  spec                  Github API OpenAPI spec file
+  index_filename        Path of index file
+  class_or_class_method_name
+                        PyGithub GithubObject class name (like 'Commit') or class method name (like 'Commit.edit')
+
+options:
+  -h, --help            show this help message and exit
+  --rewrite             Applying schema to methods is free to rewrite existing code. No care is taken to preserve existing documentation or avoid breaking changes.
+```
+
+Flag `--rewrite` (`apply methods` specific) for allows the script to rewrite existing code. No care is taken to preserve existing documentation or avoid breaking changes.
+Without `--rewrite`, no attributes are removed or breaking changes introduced.
+
+### create
+Creates a new PyGithub class or method.
+
+These sub-commands:
+- create class
+- create method
+
+#### create class
+Create a new PyGithub class from an OpenAPI schema.
+
+```
+usage: openapi.py create class [-h] [--completable] [--parent PARENT] [--tests] [--new-schemas {ignore,create-class,as-dict}]
+                               github_path spec index_filename class_name docs_url [schema ...]
+
+positional arguments:
+  github_path           Path to PyGithub Python files
+  spec                  Github API OpenAPI spec file
+  index_filename        Path of index file
+  class_name            PyGithub GithubObject class name
+  docs_url              Github REST API documentation URL, for instance https://docs.github.com/en/rest/commits/commits#get-a-commit-object
+  schema                Github API OpenAPI schema name
+
+options:
+  -h, --help            show this help message and exit
+  --completable         New PyGithub class is completable, implies --parent CompletableGithubObject
+  --parent PARENT       A parent PyGithub class
+  --tests               Also create test file
+  --new-schemas {ignore,create-class,as-dict}
+                        How to handle attributes that return schemas that are not implemented by any PyGithub: 'ignore', 'create-class' crates class implementation drafts, 'as-dict'
+                        return dict[str, Any]). Option 'create-class' does not support --dry-run.
+```
+
+#### create method
+Create a new method from an OpenAPI path.
+
+```
+usage: openapi.py create method [-h] [--new-schemas {ignore,create-class,as-dict}] [--return-property [RETURN_PROPERTY]]
+                                github_path spec index_filename class_name method_name api_verb api_path [api_response]
+
+positional arguments:
+  github_path           Path to PyGithub Python files
+  spec                  Github API OpenAPI spec file
+  index_filename        Path of index file
+  class_name            PyGithub GithubObject class name
+  method_name           PyGithub method name
+  api_verb              OpenAPI verb
+  api_path              OpenAPI path
+  api_response          OpenAPI response, e.g. 200
+
+options:
+  -h, --help            show this help message and exit
+  --new-schemas {ignore,create-class,as-dict}
+                        How to return schemas that are not implemented by any PyGithub: 'ignore', 'create-class' crates class implementation drafts, 'as-dict' return dict[str, Any]).
+                        Option 'create-class' does not support --dry-run.
+  --return-property [RETURN_PROPERTY]
+                        Return the value of this response property, instead of the entire response object
+```
+
+Command `suggest paths` prints ready-to-run `create method` command lines for the alternatives it proposes.
+
+Check for similar methods to find the appropriate class and method name for the respective path.
+
+
+## Notable files
+### OpenAPI spec JSON file
+An OpenAPI spec JSON file is usually named like `api.github.com.YYYY-MM-DD.json` or better `api.github.com.YYYY-MM-DD.YYYYMMDDTHHMMSS.json`,
+where:
+- `api.github.com`: the Github API name
+- `YYYY-MM-DD`: the API version
+- `YYYYMMDDTHHMMSS`: the time of retrieval
+
+### OpenAPI index JSON file
+An OpenAPI index JSON file is usually named `openapi.index`.

pygithub-2.10.0/.claude/skills/sorted-classes/SKILL.md

@@ -0,0 +1,18 @@
+from scripts import openapifrom scripts.sort_class import sort_class---
+name: Sort methods in PyGithub classes
+description: A Python script to make PyGithub class conform to method and attribute order convention
+---
+
+Classes implementing GithubObject must have methods and attributes ordered as specified in "Internal Class Order" section in [ARCHITECTURE.md].
+
+Python script `scripts/sort_class.py` implements order logic and applies this to given (or all) classes.
+
+Run
+```bash
+python scripts/sort_class.py --dry-run openapi.index class1 class2 ...
+```
+
+The file `openapi.index` is a file created via `openapi.py` script. This index file first has to be created if it does not exist. See "openapi" skill.
+
+Option `--dry-run` makes this a read-only operation: it does not change any files. Always show the changes to the user
+for review and ask to apply the changes. Rerun the command and omit `--dry-run` if user explicitly wishes to apply the changes without further review.

pygithub-2.10.0/.github/actions/mypy/action.yml

@@ -0,0 +1,22 @@
+name: 'MyPy'
+author: 'EnricoMi'
+description: 'A GitHub Action that runs mypy'
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Set up Python
+      uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+      with:
+        python-version: "3.x"
+    - run: |
+        python -m pip install --upgrade pip
+        pip install -e .
+        pip install -r requirements/types.txt
+      shell: bash
+    - uses: liskin/gh-problem-matcher-wrap@d31bb388d13cf879e93f878cb2550299f0afb460  # v4.0.0
+      with:
+        action: add
+        linters: mypy
+    - run: mypy --show-column-numbers github tests
+      shell: bash

pygithub-2.10.0/.github/actions/pre-commit/action.yml

@@ -0,0 +1,24 @@
+name: 'Pre-commit'
+author: 'EnricoMi'
+description: 'A GitHub Action that runs pre-commit'
+
+runs:
+  using: 'composite'
+  steps:
+    - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+      with:
+        python-version: "3.13"
+    # FIXME: pin pre-commit<4 pending PyCQA/docformatter#287
+    - name: install pre-commit
+      run: python -m pip install 'pre-commit<4'
+      shell: bash
+    - name: show environment
+      run: python -m pip freeze --local
+      shell: bash
+    - uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9  # v6.1.0
+      with:
+        path: ~/.cache/pre-commit
+        key: pre-commit-${{ hashFiles('.pre-commit-config.yaml') }}
+    - name: run pre-commit
+      run: pre-commit run --show-diff-on-failure --color=always --all-files
+      shell: bash

pygithub-2.10.0/.github/actions/sort-classes/action.yml

@@ -0,0 +1,25 @@
+name: 'Sort classes'
+author: 'EnricoMi'
+description: 'A GitHub Action that sorts classes'
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Set up Python
+      uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+      with:
+        python-version: "3.12"
+    - name: Set up dependencies
+      run: |
+        pip install -r requirements/scripts.txt
+      shell: bash
+    - name: Sort classes
+      shell: bash
+      run: |
+        # Sort classes
+        set -euo pipefail
+
+        echo "::group::Sort classes"
+        python scripts/openapi.py index github openapi.index
+        python scripts/sort_class.py openapi.index $(jq -r ".indices.class_to_descendants.GithubObject | @tsv" < openapi.index)
+        echo "::endgroup::"

pygithub-2.10.0/.github/workflows/_build-pkg.yml

@@ -0,0 +1,32 @@
+name: Build package
+
+on:
+  workflow_call:
+    inputs:
+      artifact-name:
+        description: "Name of an artifact"
+        type: "string"
+        required: false
+        default: "package"
+
+jobs:
+  build-pkg:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+        with:
+          python-version: '3.x'
+
+      - name: Install dependencies
+        run: pip install -U build twine
+      - name: Build 📦 package
+        run: python -m build
+      - name: Check 📦 package
+        run: twine check dist/*
+
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
+        with:
+          name: ${{ inputs.artifact-name }}
+          path: dist

pygithub-2.10.0/.github/workflows/auto-fix.yml

@@ -0,0 +1,60 @@
+name: Auto Fix
+on:
+  workflow_dispatch:
+permissions: {}
+
+jobs:
+  sort:
+    name: "sort classes"
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+      - uses: ./.github/actions/sort-classes
+        continue-on-error: true
+      - name: Commit and push changes
+        run: |
+          # Commit and push changes
+          git config --local user.name "${{ github.actor }}"
+          git config --local user.email "github-action-${{ github.actor }}@users.noreply.github.com"
+          git commit -a -m "Sorting classes" || true
+          git fetch origin $GITHUB_REF_NAME
+          git rebase origin/$GITHUB_REF_NAME
+          git push origin HEAD:$GITHUB_REF_NAME
+
+  mypy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+      - uses: ./.github/actions/mypy
+        continue-on-error: true
+      - name: Commit and push changes
+        run: |
+          # Commit and push changes
+          git config --local user.name "${{ github.actor }}"
+          git config --local user.email "github-action-${{ github.actor }}@users.noreply.github.com"
+          git commit -a -m "Fixing MyPy" || true
+          git fetch origin $GITHUB_REF_NAME
+          git rebase origin/$GITHUB_REF_NAME
+          git push origin HEAD:$GITHUB_REF_NAME
+
+  pre-commit-fix:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+      - uses: ./.github/actions/pre-commit
+        continue-on-error: true
+      - name: Commit and push changes
+        run: |
+          # Commit and push changes
+          git config --local user.name "${{ github.actor }}"
+          git config --local user.email "github-action-${{ github.actor }}@users.noreply.github.com"
+          git commit -a -m "Fixing pre-compile" || true
+          git fetch origin $GITHUB_REF_NAME
+          git rebase origin/$GITHUB_REF_NAME
+          git push origin HEAD:$GITHUB_REF_NAME