diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 000000000..3088a753b --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,11 @@ +version: 2 +updates: + - package-ecosystem: github-actions + directory: / + schedule: + interval: daily + + - package-ecosystem: pip + directory: /docs/source + schedule: + interval: daily diff --git a/.github/labels.yml b/.github/labels.yml new file mode 100644 index 000000000..f7f83aad8 --- /dev/null +++ b/.github/labels.yml @@ -0,0 +1,66 @@ +--- +# Labels names are important as they are used by Release Drafter to decide +# regarding where to record them in changelog or if to skip them. +# +# The repository labels will be automatically configured using this file and +# the GitHub Action https://github.com/marketplace/actions/github-labeler. +- name: breaking + description: Breaking Changes + color: bfd4f2 +- name: bug + description: Something isn't working + color: d73a4a +- name: build + description: Build System and Dependencies + color: bfdadc +- name: ci + description: Continuous Integration + color: 4a97d6 +- name: dependencies + description: Pull requests that update a dependency file + color: 0366d6 +- name: documentation + description: Improvements or additions to documentation + color: 0075ca +- name: duplicate + description: This issue or pull request already exists + color: cfd3d7 +- name: enhancement + description: New feature or request + color: a2eeef +- name: github_actions + description: Pull requests that update Github_actions code + color: "000000" +- name: good first issue + description: Good for newcomers + color: 7057ff +- name: help wanted + description: Extra attention is needed + color: 008672 +- name: invalid + description: This doesn't seem right + color: e4e669 +- name: performance + description: Performance + color: "016175" +- name: python + description: Pull requests that update Python code + color: 2b67c6 +- name: question + description: Further information is requested + color: d876e3 +- name: refactoring + description: Refactoring + color: ef67c4 +- name: removal + description: Removals and Deprecations + color: 9ae7ea +- name: style + description: Style + color: c120e5 +- name: testing + description: Testing + color: b1fc6f +- name: wontfix + description: This will not be worked on + color: ffffff diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 000000000..a324494a9 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,26 @@ +Before opening a new issue, please [search][] for a previously filed +issue to ensure you're not creating a duplicate. + +**Note** Bug reports without the following will receive requests for these +details to be provided. + +## Version Information + +Please provide: + +- The version of Python you're using + +- The version of pip you used to install github3.py + +- The version of github3.py, requests, uritemplate, and python-dateutil installed + +## Minimum Reproducible Example + +Please provide an example of the code that generates the error you're seeing. + +## Exception information + +What is exceptional about what you're seeing versus what you expected to see. + + +[search]: https://github.com/sigmavirus24/github3.py/issues?utf8=%E2%9C%93&q=is%3Aissue diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml new file mode 100644 index 000000000..13faa6d2d --- /dev/null +++ b/.github/workflows/build.yml @@ -0,0 +1,56 @@ +name: Python tests + +on: [push, pull_request] + +permissions: + contents: read + +jobs: + test: + runs-on: ubuntu-latest + strategy: + matrix: + python: + - { VERSION: "3.9", TOXENV: "py39", ALLOW_FAILURE: false } + - { VERSION: "3.10", TOXENV: "py310", ALLOW_FAILURE: false } + - { VERSION: "3.11", TOXENV: "py311", ALLOW_FAILURE: false } + - { VERSION: "3.12", TOXENV: "py312", ALLOW_FAILURE: false } + - { VERSION: "3.13", TOXENV: "py313", ALLOW_FAILURE: false } + - { + VERSION: "3.13", + TOXENV: "flake8,doclint,docs,commitlint", + ALLOW_FAILURE: false, + } + - { VERSION: "3.13", TOXENV: "docstrings", ALLOW_FAILURE: true } + - { VERSION: "pypy3.9", TOXENV: "pypy", ALLOW_FAILURE: false } + + steps: + - name: Harden the runner (Audit all outbound calls) + uses: step-security/harden-runner@0634a2670c59f64b4a01f0f96f84700a4088b9f0 # v2.12.0 + with: + egress-policy: audit + + - name: Check out the repository + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + + - name: Setup Python + uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0 + with: + python-version: ${{ matrix.PYTHON.VERSION }} + + - name: Upgrade pip + run: | + pip install pip + pip --version + + - name: Install Tox + run: | + pip install tox + tox --version + + - name: Run Tox + run: tox + env: + TOXENV: ${{ matrix.PYTHON.TOXENV }} + GH_RECORD_MODE: "none" + continue-on-error: ${{ matrix.PYTHON.ALLOW_FAILURE }} diff --git a/.github/workflows/codeql-analysis.yml b/.github/workflows/codeql-analysis.yml new file mode 100644 index 000000000..0c54bc03d --- /dev/null +++ b/.github/workflows/codeql-analysis.yml @@ -0,0 +1,78 @@ +# For most projects, this workflow file will not need changing; you simply need +# to commit it to your repository. +# +# You may wish to alter this file to override the set of languages analyzed, +# or to provide custom queries or build logic. +# +# ******** NOTE ******** +# We have attempted to detect the languages in your repository. Please check +# the `language` matrix defined below to confirm you have the correct set of +# supported CodeQL languages. +# +name: "CodeQL" + +on: + push: + branches: [ main, debian ] + pull_request: + # The branches below must be a subset of the branches above + branches: [ main ] + schedule: + - cron: '32 17 * * 6' + +permissions: + contents: read + +jobs: + analyze: + name: Analyze + runs-on: ubuntu-latest + permissions: + actions: read + contents: read + security-events: write + + strategy: + fail-fast: false + matrix: + language: [ 'python' ] + # CodeQL supports [ 'cpp', 'csharp', 'go', 'java', 'javascript', 'python', 'ruby' ] + # Learn more about CodeQL language support at https://git.io/codeql-language-support + + steps: + - name: Harden the runner (Audit all outbound calls) + uses: step-security/harden-runner@0634a2670c59f64b4a01f0f96f84700a4088b9f0 # v2.12.0 + with: + egress-policy: audit + + - name: Checkout repository + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + + # Initializes the CodeQL tools for scanning. + - name: Initialize CodeQL + uses: github/codeql-action/init@60168efe1c415ce0f5521ea06d5c2062adbeed1b # v3.28.17 + with: + languages: ${{ matrix.language }} + # If you wish to specify custom queries, you can do so here or in a config file. + # By default, queries listed here will override any specified in a config file. + # Prefix the list here with "+" to use these queries and those in the config file. + # queries: ./path/to/local/query, your-org/your-repo/queries@main + + # Autobuild attempts to build any compiled languages (C/C++, C#, or Java). + # If this step fails, then you should remove it and run the build manually (see below) + - name: Autobuild + uses: github/codeql-action/autobuild@60168efe1c415ce0f5521ea06d5c2062adbeed1b # v3.28.17 + + # ℹ️ Command-line programs to run using the OS shell. + # 📚 https://git.io/JvXDl + + # ✏️ If the Autobuild fails above, remove it and uncomment the following three lines + # and modify them (or add more) to build your code if your project + # uses a compiled language + + #- run: | + # make bootstrap + # make release + + - name: Perform CodeQL Analysis + uses: github/codeql-action/analyze@60168efe1c415ce0f5521ea06d5c2062adbeed1b # v3.28.17 diff --git a/.github/workflows/dependency-review.yml b/.github/workflows/dependency-review.yml new file mode 100644 index 000000000..3629898fa --- /dev/null +++ b/.github/workflows/dependency-review.yml @@ -0,0 +1,27 @@ +# Dependency Review Action +# +# This Action will scan dependency manifest files that change as part of a Pull Request, +# surfacing known-vulnerable versions of the packages declared or updated in the PR. +# Once installed, if the workflow run is marked as required, +# PRs introducing known-vulnerable packages will be blocked from merging. +# +# Source repository: https://github.com/actions/dependency-review-action +name: 'Dependency Review' +on: [pull_request] + +permissions: + contents: read + +jobs: + dependency-review: + runs-on: ubuntu-latest + steps: + - name: Harden the runner (Audit all outbound calls) + uses: step-security/harden-runner@0634a2670c59f64b4a01f0f96f84700a4088b9f0 # v2.12.0 + with: + egress-policy: audit + + - name: 'Checkout Repository' + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + - name: 'Dependency Review' + uses: actions/dependency-review-action@67d4f4bd7a9b17a0db54d2a7519187c65e339de8 # v4 diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 000000000..f38983bc0 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,53 @@ +--- +name: Check documentation + +"on": + schedule: + - cron: "0 1 * * *" # everyday at 1am + push: + paths: + - "**.rst" + - "docs/**" + pull_request: + paths: + - "**.rst" + - "docs/**" + +permissions: + contents: read + +jobs: + docs: + name: Build documentation & check links + runs-on: ubuntu-latest + steps: + - name: Harden the runner (Audit all outbound calls) + uses: step-security/harden-runner@0634a2670c59f64b4a01f0f96f84700a4088b9f0 # v2.12.0 + with: + egress-policy: audit + + - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0 + with: + python-version: "3.11" + + - name: Upgrade pip + run: | + pip install -U pip + pip --version + + - name: Install Tox + run: | + pip install tox + tox --version + + - name: Build documentation + run: tox + env: + TOXENV: docs + + - name: Upload documentation + uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2 + with: + name: docs + path: docs/build diff --git a/.github/workflows/labeler.yml b/.github/workflows/labeler.yml new file mode 100644 index 000000000..a893f9f54 --- /dev/null +++ b/.github/workflows/labeler.yml @@ -0,0 +1,30 @@ +name: Labeler + +on: + push: + branches: + - main + - master + +permissions: + contents: read + +jobs: + labeler: + permissions: + contents: read # for actions/checkout to fetch code + issues: write # for crazy-max/ghaction-github-labeler to create, rename, update and delete label + runs-on: ubuntu-latest + steps: + - name: Harden the runner (Audit all outbound calls) + uses: step-security/harden-runner@0634a2670c59f64b4a01f0f96f84700a4088b9f0 # v2.12.0 + with: + egress-policy: audit + + - name: Check out the repository + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + + - name: Run Labeler + uses: crazy-max/ghaction-github-labeler@24d110aa46a59976b8a7f35518cb7f14f434c916 # v5.3.0 + with: + skip-delete: true diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 000000000..09ac18a6d --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,89 @@ +name: Publish to PyPI + +on: + push: + tags: + - "*" + +permissions: + contents: read + +jobs: + build: + name: "Build dists" + runs-on: "ubuntu-latest" + environment: + name: "publish" + outputs: + hashes: ${{ steps.hash.outputs.hashes }} + + steps: + - name: Harden the runner (Audit all outbound calls) + uses: step-security/harden-runner@0634a2670c59f64b4a01f0f96f84700a4088b9f0 # v2.12.0 + with: + egress-policy: audit + + - name: "Checkout repository" + uses: "actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683" + + - name: "Setup Python" + uses: "actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065" + with: + python-version: "3.x" + + - name: "Install dependencies" + run: python -m pip install build==0.8.0 + + - name: "Build dists" + run: | + SOURCE_DATE_EPOCH=$(git log -1 --pretty=%ct) \ + python -m build + + - name: "Generate hashes" + id: hash + run: | + cd dist && echo "::set-output name=hashes::$(sha256sum * | base64 -w0)" + + - name: "Upload dists" + uses: "actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02" + with: + name: "dist" + path: "dist/" + if-no-files-found: error + retention-days: 5 + + provenance: + needs: [build] + permissions: + actions: read + contents: write + id-token: write # Needed to access the workflow's OIDC identity. + uses: "slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@v2.1.0" + with: + base64-subjects: "${{ needs.build.outputs.hashes }}" + upload-assets: true + compile-generator: true # Workaround for https://github.com/slsa-framework/slsa-github-generator/issues/1163 + + publish: + name: "Publish" + if: startsWith(github.ref, 'refs/tags/') + needs: ["build", "provenance"] + permissions: + contents: write + id-token: write + runs-on: "ubuntu-latest" + + steps: + - name: Harden the runner (Audit all outbound calls) + uses: step-security/harden-runner@0634a2670c59f64b4a01f0f96f84700a4088b9f0 # v2.12.0 + with: + egress-policy: audit + + - name: "Download dists" + uses: "actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093" + with: + name: "dist" + path: "dist/" + + - name: "Publish dists to PyPI" + uses: "pypa/gh-action-pypi-publish@76f52bc884231f62b9a034ebfe128415bbaabdfc" diff --git a/.github/workflows/scorecards.yml b/.github/workflows/scorecards.yml new file mode 100644 index 000000000..462c3a86c --- /dev/null +++ b/.github/workflows/scorecards.yml @@ -0,0 +1,81 @@ +# This workflow uses actions that are not certified by GitHub. They are provided +# by a third-party and are governed by separate terms of service, privacy +# policy, and support documentation. + +name: Scorecard supply-chain security +on: + # For Branch-Protection check. Only the default branch is supported. See + # https://github.com/ossf/scorecard/blob/main/docs/checks.md#branch-protection + branch_protection_rule: + # To guarantee Maintained check is occasionally updated. See + # https://github.com/ossf/scorecard/blob/main/docs/checks.md#maintained + schedule: + - cron: '20 7 * * 2' + push: + branches: ["main"] + +# Declare default permissions as read only. +permissions: read-all + +jobs: + analysis: + name: Scorecard analysis + runs-on: ubuntu-latest + permissions: + # Needed to upload the results to code-scanning dashboard. + security-events: write + # Needed to publish results and get a badge (see publish_results below). + id-token: write + contents: read + actions: read + # To allow GraphQL ListCommits to work + issues: read + pull-requests: read + # To detect SAST tools + checks: read + + steps: + - name: Harden the runner (Audit all outbound calls) + uses: step-security/harden-runner@0634a2670c59f64b4a01f0f96f84700a4088b9f0 # v2.12.0 + with: + egress-policy: audit + + - name: "Checkout code" + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + with: + persist-credentials: false + + - name: "Run analysis" + uses: ossf/scorecard-action@f49aabe0b5af0936a0987cfb85d86b75731b0186 # v2.4.1 + with: + results_file: results.sarif + results_format: sarif + # (Optional) "write" PAT token. Uncomment the `repo_token` line below if: + # - you want to enable the Branch-Protection check on a *public* repository, or + # - you are installing Scorecards on a *private* repository + # To create the PAT, follow the steps in https://github.com/ossf/scorecard-action#authentication-with-pat. + # repo_token: ${{ secrets.SCORECARD_TOKEN }} + + # Public repositories: + # - Publish results to OpenSSF REST API for easy access by consumers + # - Allows the repository to include the Scorecard badge. + # - See https://github.com/ossf/scorecard-action#publishing-results. + # For private repositories: + # - `publish_results` will always be set to `false`, regardless + # of the value entered here. + publish_results: true + + # Upload the results as artifacts (optional). Commenting out will disable uploads of run results in SARIF + # format to the repository Actions tab. + - name: "Upload artifact" + uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2 + with: + name: SARIF file + path: results.sarif + retention-days: 5 + + # Upload the results to GitHub's code scanning dashboard. + - name: "Upload to code-scanning" + uses: github/codeql-action/upload-sarif@60168efe1c415ce0f5521ea06d5c2062adbeed1b # v3.28.17 + with: + sarif_file: results.sarif diff --git a/.gitignore b/.gitignore index 72ea0602b..e4375d82c 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,7 @@ *.pyc *.swp docs/_build +docs/build bin/ include/ lib/ @@ -9,3 +10,19 @@ dist/ *.egg-info/ .coverage htmlcov/ +.tox/ +venv/ +venv*/ +build/ +*.egg +.env +.ipynb_checkpoints +.cache/ +tests/id_rsa +*.DS_Store +.mypy_cache/ +.pytest_cache/ +t.py +*.pem +/.python-version +/.tool-versions diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 000000000..ec2c88aae --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,49 @@ +repos: + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v5.0.0 + hooks: + - id: check-added-large-files + - id: check-toml + types: [toml] + - id: check-yaml + types: [yaml] + - id: end-of-file-fixer + types: [text] + stages: [pre-commit, pre-push, manual] + - id: trailing-whitespace + types: [text] + stages: [pre-commit, pre-push, manual] + - repo: https://github.com/PyCQA/isort + rev: 6.0.1 + hooks: + - id: isort + - repo: https://github.com/psf/black + rev: 25.1.0 + hooks: + - id: black + - repo: https://github.com/asottile/pyupgrade + rev: v3.19.1 + hooks: + - id: pyupgrade + args: [--py37-plus] + - repo: https://github.com/pre-commit/mirrors-mypy + rev: v1.15.0 + hooks: + - id: mypy + additional_dependencies: + - types-python-dateutil + - types-requests + exclude: ^(docs/|tests/) + - repo: https://github.com/jorisroovers/gitlint + rev: v0.19.1 + hooks: + - id: gitlint + - repo: https://github.com/asottile/setup-cfg-fmt + rev: v2.8.0 + hooks: + - id: setup-cfg-fmt + args: [--min-py3-version, '3.7'] + - repo: https://github.com/gitleaks/gitleaks + rev: v8.25.1 + hooks: + - id: gitleaks diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 000000000..2fd286913 --- /dev/null +++ b/.readthedocs.yml @@ -0,0 +1,12 @@ +version: 2 +build: + os: ubuntu-22.04 + tools: + python: "3.11" +sphinx: + configuration: docs/source/conf.py +formats: all +python: + install: + - requirements: docs/source/requirements.txt + - path: . diff --git a/.travis.yml b/.travis.yml deleted file mode 100644 index ed9748d25..000000000 --- a/.travis.yml +++ /dev/null @@ -1,24 +0,0 @@ -language: python -python: - - 2.6 - - 2.7 - - 3.1 - - 3.2 - - pypy -# command to install dependencies, e.g. pip install -r requirements.txt -# --use-mirrors -install: - pip install -r requirements.txt -# # command to run tests, e.g. python setup.py test -script: make travis -notifications: - on_success: change - on_failure: always - -branches: - except: - - uricore - -matrix: - allow_failures: - - python: 3.1 diff --git a/AUTHORS.rst b/AUTHORS.rst index 1e2916053..c28d9b352 100644 --- a/AUTHORS.rst +++ b/AUTHORS.rst @@ -1,7 +1,18 @@ Development Lead ---------------- -- Ian Cordasco +- Ian Stapleton Cordasco + +- Matt Chung (@itsmemattchung) + +Maintainer(s) +````````````` + +- Barry Morrison (@esacteksab) + +- Matt Chung (@itsmemattchung) + +- Thiago (@staticdev) Requests ```````` @@ -31,3 +42,189 @@ Contributors - Kristian Glass (@doismellburning) - Alejandro Gómez (@alejandrogomez) + +- Tom Parker (@palfrey) + +- Malcolm Box (@mbox) + +- Tom Petr (@tpetr) + +- David Pachura (@detenebrator) + +- Barry Morrison (@esacteksab) + +- James Pearson (@xiongchiamiov) + +- INADA Naoki (@methane) + +- Matias Bordese (@matiasb) + +- Aleksey Ostapenko (@kbakba) + +- Vincent Driessen (@nvie) + +- Philip Chimento (@ptomato) + +- Benjamin Gilbert (@bgilbert) + +- Daniel Johnson (@danielj7) + +- David Moss (@damoss007) + +- John Barbuto (@jbarbuto) + +- Nikolay Bryskin (@nikicat) + +- Tomi Äijö (@tomiaijo) + +- jnothman (@jnothman) + +- Cameron Davidson-Pilon (@CamDavidsonPilon) + +- Alex Couper (@alexcouper) + +- Marc Abramowitz (@msabramo) + +- Adrian Moisey (@adrianmoisey) + +- Bryce Boe (@bboe) + +- Ryan Weald (@rweald) + +- Lars Holm Nielsen (@larshankat) + +- Ryan Pitts (@ryanpitts) + +- Jürgen Hermann (@jhermann) + +- Antoine Giraudmaillet (@antoine-g) + +- Paulus Schoutsen (@balloob) + +- Nolan Bruabker (@nrb) + +- Marcin Wielgoszewski (@mwielgoszewski) + +- Omri Harel (@omriharel) + +- Noel Lee (@noellee) + +- Sourav Singh(@souravsingh) + +- Matt Chung (@itsmemattchung) + +- Martin Ek (@ekmartin) + +- Chris Thompson (@notyetsecure) + +- Bastien Gandouet (@b4stien) + +- Usman Ehtesham Gul (@ueg1990) + +- Derek Gustafson (@degustaf) + +- Christophe Lecointe (@christophelec) + +- Abhijeet Kasurde (@akasurde) + +- Matthew Krueger (@mlkrueger1987) + +- Dejan Svetec (@dsvetec) + +- Billy Keyes (@bluekeyes) + +- Evan Borgstrom (@borgstrom) + +- Jordan Moldow (@jmoldow) + +- Goodwillcoding (@goodwillcoding) + +- Andreas Backx (@AndreasBackx) + +- Alexander Koshelev + +- Gabi Davar (@mindw) + +- Björn Kautler (@Vampire) + +- David Prothero (@dprothero) + +- Jesse Keating (@omgjlk) + +- @rco-ableton + +- Mark Troyer (@discogestalt) + +- Becca James (@beccasjames) + +- Walid Ziouche (@01walid) + +- Katie Bell (@katharosada) + +- Jeff Quast (@jquast) + +- Hal Wine (@hwine) + +- Jacopo Notarstefano (@jacquerie) + +- Taylor Edmiston (@tedmiston) + +- Jenny Li (@imjennyli) + +- Chandan Singh (@cs-shadow) + +- Raphael Vogel (@RaphaelVogel) + +- Andreas Burger (@AndreasBurger) + +- James E. Blair (@jeblair) + +- Simon Westphahl (@westphahl) + +- Steven Nyman (@stevennyman) + +- Tigran Tchougourian (@NargiT) + +- Samuel Mendes (@smendes) + +- Dimitri Merejkowsky (@dmerejkowsky) + +- Erico Fusco (@ericofusco) + +- Radomir Stevanovic (@randomir) + +- Ben Jefferies (@benjefferies) + +- Bharat Raghunathan (@Bharat123rox) + +- Kevin P. Fleming (@kpfleming) + +- Andrew Hayworth (@ahayworth) + +- Dmitry Kiselev (@dmitrykiselev27) + +- Adeodato Simó (@dato) + +- Gunnar Andersson (@gunnarx) + +- Thomas Lam (@lamcw) + +- David Glick (@davisagli) + +- Greg Gilbert (@greggilbert) + +- Philipp Heil (@zkdev) + +- Petter Kvalvaag (@pettermk) + +- Peter Küffner (@kuepe-sl) + +- Andrew MacCormack (@amaccormack-lumira) + +- Chris R (@offbyone) + +- Thomas Buchner (@MrBatschner) + +- Chris Cotter (@ccotter) + +- Daniel Diniz (@devdanzin) diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 000000000..01b8644f1 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,22 @@ +# Contributor Code of Conduct + +As contributors and maintainers of this project, and in the interest of fostering an open and welcoming community, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities. + +We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, religion, or nationality. + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery +* Personal attacks +* Trolling or insulting/derogatory comments +* Public or private harassment +* Publishing other's private information, such as physical or electronic addresses, without explicit permission +* Other unethical or unprofessional conduct. + +Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. By adopting this Code of Conduct, project maintainers commit themselves to fairly and consistently applying these principles to every aspect of managing this project. Project maintainers who do not follow or enforce the Code of Conduct may be permanently removed from the project team. + +This code of conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers. + +This Code of Conduct is adapted from the [Contributor Covenant](http://contributor-covenant.org), version 1.2.0, available at [http://contributor-covenant.org/version/1/2/0/](http://contributor-covenant.org/version/1/2/0/) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index f87628019..94af4d0d4 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -1,11 +1,25 @@ Guidelines for Contributing to github3.py ========================================= -1. Regardless of the magnitude your pull request (a couple lines to a couple - hundred lines), please add your name to the AUTHORS.rst file under the +#. Read the README_ + +#. Please do **not** use the issue tracker for questions. + +#. Please use GitHub's search feature to look for already reported issues + before reporting your own. + +#. Regardless of the magnitude your pull request (a couple lines to a couple + hundred lines), please add your name to the AUTHORS.rst_ file under the heading Contributors. -2. If you're fixing a bug, please write a regression test. All the tests are +#. There is a label for issues that should be minor and should be a good way + to become acquainted with the project. The easy_ label is the over-arching + way to determine which issues you can dig into without a great deal of + prior knowledge. Most of these issues have a `Pair with Ian`_ label which + means that if you would like, I (@sigmavirus24) will happily pair program + with you to solve the issue. + +#. If you're fixing a bug, please write a regression test. All the tests are structured like so:: tests/ @@ -13,35 +27,43 @@ Guidelines for Contributing to github3.py + Test - def test_function_or_attribute - Please do not add your regression test to an existing test, but create a - new one. You can use the form ``test_issue_``. In a docstring add - the link and a short description of the regression issue. For example, if - you found a bug in the class ``Issue``, write your test in the file - ``test_issues.py`` in the class ``TestIssue``. You can place the new test + Please do not add your regression test to an existing test, but create a + new one. You can use the form ``test_issue_``. In a docstring add + the link and a short description of the regression issue. For example, if + you found a bug in the class ``Issue``, write your test in the file + ``test_issues.py`` in the class ``TestIssue``. You can place the new test in any order, e.g., below all the existing tests, near a related one, &c. -3. If you're adding a new section of the API that does not already exist, +#. If you're adding a new section of the API that does not already exist, please also add tests to the test suite. -4. If you're adding additional functionality beyond what the API covers, - please open an issue reqeust first and of course add tests to cover the +#. If you're adding additional functionality beyond what the API covers, + please open an issue request first and of course add tests to cover the functionality in the event it is accepted. - Also, please be certain to add docstrings_ to these functions. Follow the + Also, please be certain to add docstrings_ to these functions. Follow the example of other docstrings. -5. In case you haven't caught on, for anything you add, write tests. +#. In case you haven't caught on, for anything you add, write tests. -6. Be cordial_. +#. Be cordial_. Seriously, anyone who isn't cordial will be sent packing, + regardless of the value of their contributions. I will not tolerate some + contributors creating a hostile environment for others. -7. Rebase your fork/branch if needed and possible before submitting a pull - request. This makes my life easier. If you honestly have no idea what I'm +#. Rebase your fork/branch if needed and possible before submitting a pull + request. This makes my life easier. If you honestly have no idea what I'm talking about, don't worry, I'll take care of it. -8. Please follow pep-0008_. Feel free to also use flake8_ to help. +#. Please follow pep-0008_. Feel free to also use flake8_ to help. + +#. Import modules, not class or functions .. links -.. _cordial: http://kennethreitz.com/be-cordial-or-be-on-your-way.html +.. _README: ./README.rst +.. _easy: https://github.com/sigmavirus24/github3.py/issues?labels=Easy&page=1&state=open +.. _Pair with Ian: https://github.com/sigmavirus24/github3.py/issues?labels=Pair+with+Ian&page=1&state=open +.. _AUTHORS.rst: ./AUTHORS.rst +.. _cordial: http://www.kennethreitz.org/essays/be-cordial-or-be-on-your-way .. _pep-0008: http://www.python.org/dev/peps/pep-0008/ .. _docstrings: http://www.python.org/dev/peps/pep-0257/ .. _flake8: http://pypi.python.org/pypi/flake8 diff --git a/HISTORY.rst b/HISTORY.rst deleted file mode 100644 index 4dc1f5707..000000000 --- a/HISTORY.rst +++ /dev/null @@ -1,97 +0,0 @@ -History/Changelog -================= - -0.3: xxxx-xx-xx ---------------- - -- In github3.repos.Repository - - - is_fork() and fork return the same thing - - is_private() and private return the same thing as well - - has_downloads, has_issues, has_wiki are now straight attributes - -- In github3.repos.Hook - - - is_active() and active return the same value - -- Some objects now have ``__str__`` methods. You can now do things like: - - :: - - import github3 - u = github3.user('sigmavirus24') - r = github3.repository(u, 'github3.py') - - And - - :: - - import github3 - - r = github3.repository('sigmavirus24', 'github3.py') - - template = """Some kind of template where you mention this repository - {0}""" - - print(template.format(r)) - # Some kind of template where you mention this repository - # sigmavirus24/github3.py - - Current list of objects with this feature: - - - github3.users.User (uses the login name) - - github3.users.Key (uses the key text) - - github3.users.Repository (uses the login/name pair) - - github3.users.RepoTag (uses the tag name) - - github3.users.Contents (uses the decoded content) - -0.2: 2012-11-21 ---------------- - -- MAJOR API CHANGES: - - - ``GitHub.iter_subscribed`` --> ``GitHub.iter_subscriptions`` - - Broken ``list_*`` functions in github3.api have been renamed to the correct - ``iter_*`` methods on ``GitHub``. - - Removed ``list_*`` functions from ``Repository``, ``Gist``, - ``Organization``, and ``User`` objects - -- Added zen of GitHub method. -- More tests -- Changed the way ``Repository.edit`` works courtesy of Kristian Glass - (@doismellburning) -- Changed ``Repository.contents`` behaviour when acting on a 404. -- 50% test coverage via mock tests - -0.1: 2012-11-13 ---------------- - -- Add API for GitHub Enterprise customers. - -0.1b2: 2012-11-10 ------------------ - -- Handle 500 errors better, courtesy of Kristian Glass (@doismellburning) -- Handle sending json with `%` symbols better, courtesy of Kristian Glass -- Correctly handle non-GitHub committers and authors courtesy of Paul Swartz - (@paulswartz) -- Correctly display method signatures in documentation courtesy of (@seveas) - -0.1b1: 2012-10-31 ------------------ - -- unit tests implemented using mock instead of hitting the GitHub API (#37) -- removed ``list_*`` functions from GitHub object -- Notifications API coverage - -0.1b0: 2012-10-06 ------------------ - -- Support for the complete GitHub API (accomplished) - - - Now also includes the Statuses API - - Also covers the auto_init parameters to the Repository creation - methodology - - Limited implementation of iterators in the place of list functions. - -- 98% coverage by unit tests diff --git a/LICENSE b/LICENSE index ee1eb0587..09556bc76 100644 --- a/LICENSE +++ b/LICENSE @@ -1,23 +1,29 @@ -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are +BSD 3-Clause License + +Copyright (c) 2012, Ian Stapleton Cordasco + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: -1. Redistributions of source code must retain the above copyright +1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. -2. Redistributions in binary form must reproduce the above copyright -notice, this list of conditions and the following disclaimer in the + +2. Redistributions in binary form must reproduce the above copyright +notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. -3. The name of the author may not be used to endorse or promote products -derived from this software without specific prior written permission. -THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR -IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED -WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, -INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES -(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR -SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, -STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN -ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE -POSSIBILITY OF SUCH DAMAGE. +3. Neither the name of the copyright holder nor the names of its +contributors may be used to endorse or promote products derived from +this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE +FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/MANIFEST.in b/MANIFEST.in index b4b20c743..70a2deaa7 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1 +1,13 @@ -include README.rst LICENSE HISTORY.rst AUTHORS.rst +include README.rst +include LICENSE +include AUTHORS.rst +include CONTRIBUTING.rst +include tox.ini +include report_issue.py +prune *.pyc +recursive-include docs *.rst *.py +recursive-include tests *.py *.json +recursive-include tests/json * +recursive-include tests/unit/json * +recursive-include images *.png +prune docs/_build diff --git a/Makefile b/Makefile index a90d97d10..4801b4104 100644 --- a/Makefile +++ b/Makefile @@ -1,18 +1,26 @@ # Makefile for github3.py # -# Copyright 2012, Ian Cordasco +# Copyright 2015, Ian Cordasco COVERAGE_INCLUDE := github3/*.py -TEST_RUNNER := run_tests.py +TEST_RUNNER := tox + +.DEFAULT_GOAL := tests clean: git clean -Xdf rm -rf build/ dist/ -travis: - python $(TEST_RUNNER) +ga: + $(TEST_RUNNER) + +tests: ga + +test-deps: + pip install -e .[dev] -tests: travis +htmlcov: .coverage + coverage html --omit=github3/packages/* -docs: - make -C docs/ html +docs: docs/*.rst + tox -e docs diff --git a/README.rst b/README.rst index c3ecb0f29..f46d3ee5f 100644 --- a/README.rst +++ b/README.rst @@ -1,15 +1,10 @@ -github3.py -========== - .. image:: - https://secure.travis-ci.org/sigmavirus24/github3.py.png?branch=mock - :alt: Build Status - :target: http://travis-ci.org/sigmavirus24/github3.py + https://raw.github.com/sigmavirus24/github3.py/master/docs/img/gh3-logo.png -github3.py is a comprehensive, actively developed and extraordinarily stable +github3.py is a comprehensive, actively developed, and extraordinarily stable wrapper around the GitHub API (v3). -See HISTORY.rst for any "breaking" changes. +Note: This library currently works with Python 3.7+ or pypy3. For older versions, please use version 1.3.0. Installation ------------ @@ -21,74 +16,85 @@ Installation Dependencies ------------ -- requests_ by Kenneth Reitz +- requests_ +- uritemplate_ +- python-dateutil_ +- PyJWT_ .. _requests: https://github.com/kennethreitz/requests +.. _uritemplate: https://github.com/sigmavirus24/uritemplate +.. _python-dateutil: https://github.com/dateutil/dateutil +.. _PyJWT: https://github.com/jpadilla/pyjwt + + +Contributing +------------ + +Please read the `CONTRIBUTING`_ document. + +.. _CONTRIBUTING: https://github.com/sigmavirus24/github3.py/blob/master/CONTRIBUTING.rst Testing ~~~~~~~ -- expecter_ by Gary Bernhardt -- mock_ by Michael Foord +You can run ``pip install -e .[dev]`` to install the following before testing or +simply ``make test-deps``. It is suggested you do this in a virtual environment. +These need to be installed for the tests to run. + +- betamax_ - coverage_ by Ned Batchelder -.. _expecter: https://github.com/garybernhardt/expecter +.. _betamax: https://github.com/sigmavirus24/betamax .. _coverage: http://nedbatchelder.com/code/coverage/ -.. _mock: http://mock.readthedocs.org/en/latest/ + +Build status +~~~~~~~~~~~~ + +You can find build statuses for different environments. + +- Github_ + +.. _Github: https://github.com/sigmavirus24/github3.py/actions License ------- Modified BSD license_ -.. _license: +.. _license: https://github.com/sigmavirus24/github3.py/blob/master/LICENSE Examples -------- See the docs_ for more examples. -.. _docs: http://github3py.readthedocs.org/en/latest/index.html#more-examples +.. _docs: https://github3.readthedocs.io/en/latest/index.html#more-examples Testing ~~~~~~~ -:: - - make tests - -These coverage numbers are from the old-style tests and still apply to master. +Install the dependencies from requirements.txt e.g.: :: - Name Stmts Miss Cover - ---------------------------------------- - github3/__init__ 8 0 100% - github3/api 54 1 98% - github3/auths 50 0 100% - github3/decorators 27 0 100% - github3/events 89 0 100% - github3/gists 101 0 100% - github3/git 93 0 100% - github3/github 374 0 100% - github3/issues 204 0 100% - github3/legacy 97 0 100% - github3/models 189 0 100% - github3/orgs 177 0 100% - github3/pulls 138 6 96% - github3/repos 790 22 97% - github3/users 160 0 100% - ---------------------------------------- - TOTAL 2551 29 99% + make tests Author ------ -Ian Cordasco (sigmavirus24) +Ian Stapleton Cordasco (sigmavirus24_) + +.. _sigmavirus24: https://github.com/sigmavirus24 Contact Options --------------- -- It is preferred that you send an email to github3.py@librelist.com -- You may also contact (via email) the author directly with - questions/suggestions/comments +- Feel free to use the `github3.py`_ tag on Stack Overflow for any questions + you may have. +- If you dislike Stack Overflow, it is preferred that you use Github + discussions (https://github.com/sigmavirus24/github3.py/discussions). +- You may also contact (via email_) the author directly with + questions/suggestions/comments or if you wish to include sensitive data. + +.. _github3.py: http://stackoverflow.com/questions/tagged/github3.py +.. _email: mailto:graffatcolmingov@gmail.com diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 000000000..fc20da2e3 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,18 @@ +# Security Policy + +github3.py takes security seriously. Any vulnerability discovered in the +library will be addressed with best possible urgency. This is, however, +a passion project that I may not have enough time to spend in order to fix +a larger security issue in an expedient fashion. + +All reports will be responded to within 7 days. + +## Supported Versions + +The latest version is the only supported version for security reports. We do +not maintain branches for older versions or long term support releases. + +## Reporting a Vulnerability + +Please use the security tab on GitHub to report a vulnerability. If this is +insufficient, please use the email address for @sigmavirus24. diff --git a/TODO.rst b/TODO.rst deleted file mode 100644 index 6d4f63165..000000000 --- a/TODO.rst +++ /dev/null @@ -1,35 +0,0 @@ -TODO -==== - -High priority -------------- - -(In order of priority) - -unittests -~~~~~~~~~ - -Rewrite all unittests with mock. - -github3.api -~~~~~~~~~~~ - -- Add anonymous functionality for more areas of the API - -github3.* -~~~~~~~~~ - -- Add sensible defaults to all attributes instead of just using None, e.g., - if the user is expecting a string but there is no data to provide, return - ``''``. - -Low priority ------------- - -(In order of priority) - -logging -~~~~~~~ - -I need to determine if there is a desire for logging and where it would be -most useful. I would probably take a cue from urllib3 in this instance. diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index bf49b5422..000000000 --- a/docs/Makefile +++ /dev/null @@ -1,130 +0,0 @@ -# Makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -PAPER = -BUILDDIR = _build - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . - -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest - -help: - @echo "Please use \`make ' where is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " singlehtml to make a single large HTML file" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - -clean: - -rm -rf $(BUILDDIR)/* - -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Raclette.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Raclette.qhc" - -devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/Raclette" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Raclette" - @echo "# devhelp" - -epub: - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make' in that directory to run these through (pdf)latex" \ - "(use \`make latexpdf' here to do that automatically)." - -latexpdf: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - make -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." diff --git a/docs/api.rst b/docs/api.rst deleted file mode 100644 index 0e326cbd6..000000000 --- a/docs/api.rst +++ /dev/null @@ -1,172 +0,0 @@ -.. _api: - -API -=== - -.. module:: github3 -.. module:: github3.api - -This part of the documentation covers the API. This is intended to be a -beautifully written module which allows the user (developer) to interact with -``github3.py`` elegantly and easily. - -Module Contents ---------------- - -To interact with the GitHub API you can either authenticate to access protected -functionality or you can interact with it anonymously. Authenticating provides -more functionality to the the user (developer). - -To authenticate, you simply use :func:`github3.login`. - -.. autofunction:: github3.login - -With the :class:`GitHub ` object that is returned you have access -to more functionality. See that object's documentation for more information. - -To use the API anonymously, you can create a new -:class:`GitHub ` object, e.g., - -:: - - from github3 import GitHub - - gh = GitHub() - -Or you can simply use the following functions - ------- - -.. autofunction:: github3.authorize - ------- - -.. autofunction:: github3.create_gist - ------- - -.. autofunction:: github3.gist - ------- - -.. autofunction:: github3.gitignore_template - ------- - -.. autofunction:: github3.gitignore_templates - ------- - -.. autofunction:: github3.issue - ------- - -.. autofunction:: github3.iter_all_repos - ------- - -.. autofunction:: github3.iter_all_users - ------- - -.. autofunction:: github3.iter_events - ------- - -.. autofunction:: github3.iter_followers - ------- - -.. autofunction:: github3.iter_following - ------- - -.. autofunction:: github3.iter_gists - ------- - -.. autofunction:: github3.iter_orgs - ------- - -.. autofunction:: github3.iter_repos - ------- - -.. autofunction:: github3.iter_repo_issues - ------- - -.. autofunction:: github3.iter_starred - ------- - -.. autofunction:: github3.iter_subscriptions - ------- - -.. autofunction:: github3.markdown - ------- - -.. autofunction:: github3.octocat - ------- - -.. autofunction:: github3.organization - ------- - -.. autofunction:: github3.pull_request - ------- - -.. autofunction:: github3.ratelimit_remaining - ------- - -.. autofunction:: github3.repository - ------- - -.. autofunction:: github3.search_issues - ------- - -.. autofunction:: github3.search_repos - ------- - -.. autofunction:: github3.search_users - ------- - -.. autofunction:: github3.search_email - ------- - -.. autofunction:: github3.user - ------- - -.. autofunction:: github3.zen - ------- - -Enterprise Use --------------- - -If you're using github3.py to interact with an enterprise installation of -GitHub, you must use the -:class:`GitHubEnterprise ` object. Upon -initialization, the only parameter you must supply is the URL of your -enterprise installation, e.g. - -:: - - from github import GitHubEnterprise - - g = GitHubEnterprise('https://github.examplesintl.com') - stats = g.admin_stats('all') - assert 'issues' in stats, ('Key issues is not included in the admin' - 'statistics') diff --git a/docs/auths.rst b/docs/auths.rst deleted file mode 100644 index 2245a30e7..000000000 --- a/docs/auths.rst +++ /dev/null @@ -1,11 +0,0 @@ -.. module:: github3 -.. module:: github3.auths - -Authorization -============= - -This part of the documentation covers the -:class:`Authorization ` object. - -.. autoclass:: Authorization - :inherited-members: diff --git a/docs/bin/lint b/docs/bin/lint new file mode 100755 index 000000000..93c1ccb6f --- /dev/null +++ b/docs/bin/lint @@ -0,0 +1,8 @@ +#!/bin/sh +output="$(find docs/source -name '*.rst' | grep -v docs/source/examples/octocat.rst | xargs proselint)" +exit_code=$? + +if echo "$output" | grep -qve 'typography' ; then + echo $output + exit $exit_code +fi diff --git a/docs/decorators.rst b/docs/decorators.rst deleted file mode 100644 index ff081ca71..000000000 --- a/docs/decorators.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. _decorators: - -Decorators -========== - -.. module:: github3 -.. module:: github3.decorators - -This part of the documentation covers the decorators module which contains all -of the decorators used in github3.py. - - -Contents --------- - -.. autofunction:: github3.decorators.requires_auth diff --git a/docs/events.rst b/docs/events.rst deleted file mode 100644 index c97c6962a..000000000 --- a/docs/events.rst +++ /dev/null @@ -1,37 +0,0 @@ -Events -====== - -.. module:: github3 -.. module:: github3.events - -This part of the documentation covers the :class:`Event ` object. - -Event Objects -------------- - -.. autoclass:: Event - :inherited-members: - -When accessing the payload of the event, you should notice that you receive a -dictionary where the keys depend on the event type_. Note: - -- where they reference an array in the documentation but index it like a - dictionary, you are given a regular dictionary -- where they reference a key as returning an object, you receive the equivalent - object from the dictionary, e.g., for a Fork Event:: - - >>> event - - >>> event.payload - {u'forkee': } - >>> event.payload['forkee'] - - -Using the dictionary returned as the payload makes far more sense than creating -an object for the payload in this instance. For one, creating a class for each -payload type would be insanity. I did it once, but it isn't worth the effort. -Having individual handlers as we have now which modify the payload to use our -objects when available is more sensible. - -.. links -.. _type: http://developer.github.com/v3/events/types diff --git a/docs/examples/issue.rst b/docs/examples/issue.rst deleted file mode 100644 index eaf4dca1a..000000000 --- a/docs/examples/issue.rst +++ /dev/null @@ -1,39 +0,0 @@ -Issue Code Examples -=================== - -Examples using ``Issue``\ s - -Administrating Issues ---------------------- - -Let's assume you have your username and password stored in ``user`` and ``pw`` -respectively, you have your repository name stored in ``repo``, and the number -of the issue you're concerned with in ``num``. - -:: - - from github3 import login - - gh = login(user, pw) - issue = gh.issue(user, repo, num) - if issue.is_closed(): - issue.reopen() - - issue.edit('New issue title', issue.body + '\n------\n**Update:** Text to append') - -:: - - # Assuming issue is the same as above ... - issue.create_comment('This should be fixed in 6d4oe5. Closing as fixed.') - issue.close() - -The following shows how you could use github3.py to fetch and display your -issues in your own style and in your webbrowser. - -.. include:: source/browser.py - :code: python - -Or how to do the same by wrapping the lines in your terminal. - -.. include:: source/wrap_text.py - :code: python diff --git a/docs/gists.rst b/docs/gists.rst deleted file mode 100644 index 0188a8b0f..000000000 --- a/docs/gists.rst +++ /dev/null @@ -1,31 +0,0 @@ -.. _gists: - -Gists -===== - -.. module:: github3 -.. module:: github3.gists - -.. |Gist| replace:: :class:`Gist ` -.. |GistComment| replace:: :class:`GistComment ` -.. |GistFile| replace:: :class:`GistFile ` - -This part of the documentation details the properties and methods associated -with |Gist|, |GistComment|, and |GistFile| objects. These classes should never -be instantiated by the user (developer) directly. - -Gist Objects ------------- - -.. autoclass:: Gist - :inherited-members: - ------- - -.. autoclass:: GistComment - :inherited-members: - ------- - -.. autoclass:: GistFile - :inherited-members: diff --git a/docs/git.rst b/docs/git.rst deleted file mode 100644 index 7bfb133ec..000000000 --- a/docs/git.rst +++ /dev/null @@ -1,61 +0,0 @@ -.. module:: github3 -.. module:: github3.git - -Git -=== - -This part of the documentation covers the module associated with the `Git Data`_ -section of the GitHub API. - -- :class:`Blob ` -- :class:`Commit ` -- :class:`GitData ` -- :class:`GitObject ` -- :class:`Hash ` -- :class:`Reference ` -- :class:`Tag ` -- :class:`Tree ` - -.. links -.. _Git Data: http://developer.github.com/v3/git - -Git Objects ------------ - -.. autoclass:: Blob - :inherited-members: - ------- - -.. autoclass:: Commit - :inherited-members: - ------- - -.. autoclass:: GitData - :inherited-members: - ------- - -.. autoclass:: GitObject - :inherited-members: - ------- - -.. autoclass:: Hash - :inherited-members: - ------- - -.. autoclass:: Reference - :inherited-members: - ------- - -.. autoclass:: Tag - :inherited-members: - ------- - -.. autoclass:: Tree - :inherited-members: diff --git a/docs/github.rst b/docs/github.rst deleted file mode 100644 index 423d07ad4..000000000 --- a/docs/github.rst +++ /dev/null @@ -1,26 +0,0 @@ -.. _githubex: - -GitHub -====== - -.. module:: github3 -.. module:: github3.github - -This part of the documentation covers the :class:`GitHub ` object. A -large portion of what you will likely want to do can be found in this class. If -you're looking for anonymous functions, you're most likely looking for the -:ref:`API `. - -Examples --------- - -Examples utilizing this object can be found here_. - -GitHub Object -------------- - -.. autoclass:: GitHub - :inherited-members: - -.. links -.. _here: examples/githubex.html diff --git a/docs/img/gh3-logo-transparent.png b/docs/img/gh3-logo-transparent.png new file mode 100644 index 000000000..ecaab7ac5 Binary files /dev/null and b/docs/img/gh3-logo-transparent.png differ diff --git a/docs/img/gh3-logo.png b/docs/img/gh3-logo.png new file mode 100644 index 000000000..2dd3d847d Binary files /dev/null and b/docs/img/gh3-logo.png differ diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index a0e8fd4c3..000000000 --- a/docs/index.rst +++ /dev/null @@ -1,231 +0,0 @@ -github3.py -========== - -Release v\ |version|. - -github3.py is wrapper for the `GitHub API`_ written in python. The design of -github3.py is centered around having a logical organization of the methods -needed to interact with the API. Let me demonstrate this with a code example. - -Example -------- - -Let's get information about a user:: - - from github3 import login - - gh = login('sigmavirus24', password='') - - sigmavirus24 = gh.user() - # - - print(sigmavirus24.name) - # Ian Cordasco - print(sigmavirus24.login) - # sigmavirus24 - print(sigmavirus24.followers) - # 4 - - gh.list_followers() - - kennethreitz = gh.user('kennethreitz') - # - - print(kennethreitz.name) - print(kennethreitz.login) - print(kennethreitz.followers) - - gh.list_followers('kennethreitz') - - -More Examples -~~~~~~~~~~~~~ - -.. toctree:: - :maxdepth: 2 - - examples/oauth - examples/gist - examples/git - examples/github - examples/issue - - -.. links - -.. _GitHub API: http://developer.github.com - - -Modules -------- - -.. toctree:: - :maxdepth: 1 - - api - auths - events - gists - git - github - issues - legacy - models - orgs - pulls - repos - users - -Internals -~~~~~~~~~ - -For objects you're not likely to see in practice. This is useful if you ever -feel the need to contribute to the project. - -.. toctree:: - :maxdepth: 1 - - models - decorators - - -Installation ------------- - -.. code-block:: sh - - $ pip install github3.py - # OR: - $ git clone git://github.com/sigmavirus24/github3.py.git github3.py - $ cd github3.py - $ python setup.py install - - -Dependencies -~~~~~~~~~~~~ - -- requests_ by Kenneth Reitz - -.. _requests: https://github.com/kennethreitz/requests - - -API Coverage ------------- - -- Gists - - - Comments - -- Git Data - - - Blobs - - Commits - - References - - Tags - - Trees - -- Issues - - - Comments - - Events - - Labels - - Milestones - -- Orgs - - - Members - - Teams - -- Pull Requests - - - Review Comments - -- Repos - - - Collaborators - - Comments - - Commits - - Contents - - Downloads - - Forks - - Keys - - Watching - - Hooks - -- Users - - - Emails - - Followers - - Keys - -- Events - - - Types - -- Search - -- Markdown - -Contributing ------------- - -I'm maintaining two public copies of the project. The first can be found on -GitHub_ and the second on BitBucket_. I would prefer pull requests to take -place on GitHub, but feel free to do them via BitBucket. Please make sure to -add yourself to the list of contributors in AUTHORS.rst, especially if you're -going to be working on the list below. - -.. links -.. _GitHub: https://github.com/sigmavirus24/github3.py -.. _BitBucket: https://bitbucket.org/icordasc/github3.py/src - -Contributor Friendly Work -~~~~~~~~~~~~~~~~~~~~~~~~~ - -In order of importance: - -Unittests - - I really should have written these as I wrote the code. I didn't, so they - need to be written now. If you want to write some, I would sincerely - appreciate it. - -Documentation - - I know I'm not the best at writing documentation so if you want to clarify - or correct something, please do so. - -Examples - - Have a clever example that takes advantage of github3.py? Feel free to - share it. - -Running the Unittests -~~~~~~~~~~~~~~~~~~~~~ - -To run the tests as they would be run by Travis CI:: - - CI=true ./unittests.py - -To test functions that require proper authentication:: - - ./unittests.py - -The latter will prompt you for your username and password, e.g.:: - - [ sigma: ~/sandbox/github3.py ] ./unittests.py - Enter GitHub username: sigmavirus24 - Password for sigmavirus24: - -This will generally fail until we can generalize the authenticated tests via a -config file. - - -Contact -------- - -- Twitter: @\ sigmavirus24_ -- Private email: graffatcolmingov [at] gmail -- Mailing list: github3.py [at] librelist.com - -.. _sigmavirus24: https://twitter.com/sigmavirus24 diff --git a/docs/issues.rst b/docs/issues.rst deleted file mode 100644 index bda4ffdbe..000000000 --- a/docs/issues.rst +++ /dev/null @@ -1,41 +0,0 @@ -.. _issue: - -Issue -===== - -.. module:: github3 -.. module:: github3.issues - -This part of the documentation covers the module which handles :class:`Issue -`\ s and their related objects: - -- :class:`IssueComment ` -- :class:`IssueEvent ` -- :class:`Milestone ` -- :class:`Label