Skip to content

Commit 6f0d6ef

Browse files
EnricoMiEnricoMi
authored
Update docs on development (#3352)
Adds notes on testing, OpenAPI, GraphQL and automation scripts.
1 parent 12d8d10 commit 6f0d6ef

141 files changed

Lines changed: 1288 additions & 441 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/ci.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -102,7 +102,7 @@ jobs:
102102
python head/scripts/openapi.py --verbose index --check-verbs base/github openapi.base.index | tee verbs.base.txt
103103
echo "::endgroup::"
104104
105-
if ! (diff verbs.base.txt verbs.head.txt > diff.txt)
105+
if ! (diff <(grep -v -E -e "^Index(ing|ed) " verbs.base.txt) <(grep -v -E -e "^Index(ing|ed) " verbs.head.txt) > diff.txt)
106106
then
107107
echo ""
108108
echo "Difference:"
@@ -156,7 +156,7 @@ jobs:
156156
python head/scripts/openapi.py --verbose suggest schemas openapi.json openapi.base.index | tee schemas.base.txt
157157
echo "::endgroup::"
158158
159-
if ! (diff schemas.base.txt schemas.head.txt > diff.txt)
159+
if ! (diff <(grep -v -E -e "^Index(ing|ed) " schemas.base.txt) <(grep -v -E -e "^Index(ing|ed) " schemas.head.txt) > diff.txt)
160160
then
161161
echo ""
162162
echo "Difference:"

‎.github/workflows/lint.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ jobs:
2727
- uses: actions/checkout@v5
2828
- uses: actions/setup-python@v5
2929
with:
30-
python-version: "3.8"
30+
python-version: "3.x"
3131

3232
- run: pip install -r requirements/docs.txt
3333
- run: pip install -e .

‎.readthedocs.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,9 @@
66
version: 2
77

88
build:
9-
os: ubuntu-22.04
9+
os: ubuntu-24.04
1010
tools:
11-
python: "3.8"
11+
python: "3.13"
1212

1313
sphinx:
1414
configuration: doc/conf.py

‎CONTRIBUTING.md‎

Lines changed: 13 additions & 130 deletions
Original file line numberDiff line numberDiff line change
@@ -5,146 +5,29 @@
55
A good issue includes a [short, self contained, correct example](http://sscce.org/) of the problem, something like:
66

77
```python
8-
assert github.Github().get_user("jacquev6").name == "Vincent Jacques"
8+
from github import Github
9+
from github import Auth
10+
11+
g = Github(auth=Auth.Token("****"))
12+
assert g.get_user("jacquev6").name == "Vincent Jacques"
913
```
1014

1115
It is even better if you provide the debug logs associated with your issue.
1216
Enable them with `github.enable_console_debug_logging` and copy them in the body of the issue.
13-
**Warning:** you may want to remove some private information (authentication information is removed, but there may be private stuff in the messages)
17+
**Warning:** you may want to remove private information from the log.
1418

15-
If for any reason you are not able to do that, open your issue anyway and a maintainer will see what is needed to solve your problem.
19+
If for any reason you are not able to do that, open your issue anyway and a maintainer or community member may be able to help.
1620

1721
## Pull Requests
1822

19-
Pull Requests should clearly describe two things:
23+
Pull Requests should contain the following things:
2024

21-
1. The problem they attempt to solve
22-
2. How the author went about solving the problem
25+
1. Describe the problem the Pull Request attempts to solve
26+
2. Explain how the you went about solving the problem
27+
3. Provide a test that exemplifies the expected behaviour
2328

2429
Ideally, changes should be made in logical commits and tests added to improve the project's coverage of the GitHub API.
2530

26-
## Coding style
27-
28-
PyGithub adopts the black coding style.
29-
30-
To manually format the code:
31-
```bash
32-
tox -e lint
33-
```
34-
35-
## Pre-commit plugin
36-
37-
To forget about coding style and let [pre-commit](https://pre-commit.com/#installation) fix your flake8/isort/black issue.
38-
39-
```
40-
pre-commit install
41-
```
42-
43-
That's it!
44-
45-
## Adding missing attributes for a GithubObject
46-
47-
```bash
48-
$ python scripts/add_attribute.py [class_name] [attribute_name] [attribute_type]
49-
50-
# For example, if you want to add a `url` attribute of string type to the Commit class
51-
# Note: adding multiple attributes you have to run the script multiple times
52-
53-
$ python scripts/add_attribute.py Commit url string
54-
```
55-
56-
## Deprecation warning
57-
58-
Before removing attributes/methods, consider adding deprecation warnings instead. The [typing_extensions](https://pypi.org/project/typing-extensions/) package provides a handy decorator to add deprecation warnings.
59-
60-
```python
61-
from typing_extensions import deprecated
62-
63-
@property
64-
@deprecated("Use core instead")
65-
def rate(self):
66-
pass
67-
68-
@deprecated("Deprecated in favor of the new branch protection")
69-
def get_protected_branch(self):
70-
pass
71-
```
72-
73-
## Automated tests
74-
75-
First you need to install the test dependencies:
76-
```bash
77-
pip install -r requirements/test.txt
78-
```
79-
80-
Then you can run the tests through `pytest`.
81-
Run a specific test with `pytest tests/tests_filename.py` or `pytest tests/tests_filename.py -k testMethod` or `pytest -k TestClass.testMethod`.
31+
## Development
8232

83-
If you add or modify a test, for example `Repository.testCompare`, you have to run `pytest -k Repository.testCompare --record` to create or update the `tests/ReplayData/*.txt` files needed for your new test.
84-
Check them in to git and commit them as well.
85-
86-
You will need a `GithubCredentials.py` file at the root of the project with the following contents:
87-
88-
```python
89-
oauth_token = "my_token"
90-
jwt = "my_json_web_token" # Can be left empty if not used
91-
app_id = "my_app_id" # Can be left empty if not used
92-
app_private_key = "my_app_private_key" # Can be left empty if not used
93-
```
94-
95-
The `oauth_token` field in `GithubCredentials.py` is used by default to record test data.
96-
Tests that require JWT (`jwt` field) or App authentication (`app_id` and `app_private_key` field)
97-
have to enable `"jwt"` or `"app"` auth mode in their `setUp` method:
98-
99-
```python
100-
def setUp(self):
101-
self.authMode = "jwt"
102-
super().setUp()
103-
...
104-
```
105-
106-
A test method that needs a different authentication than configured in `setUp` can simply
107-
create a new `Github` object with the respective authentication:
108-
109-
```python
110-
def testGetUserWithOAuth(self):
111-
# this test needs OAuth authentication
112-
g = self.get_github("oauth_token")
113-
self.assertEqual(g.get_user("jacquev6").name, "Vincent Jacques")
114-
115-
def testGetUserWithJwt(self):
116-
# this test needs JWT authentication
117-
g = self.get_github("jwt")
118-
self.assertEqual(g.get_user("jacquev6").name, "Vincent Jacques")
119-
120-
def testGetUserWithAppAuth(self):
121-
# this test needs App authentication
122-
g = self.get_github("app")
123-
self.assertEqual(g.get_user("jacquev6").name, "App name")
124-
```
125-
126-
To run manual tests with external scripts that use the PyGithub package, you can install your development version with:
127-
128-
```bash
129-
pip install --editable path/to/project
130-
```
131-
132-
You may also want to investigate `tox` to run tests:
133-
134-
```bash
135-
pip install tox
136-
tox -epy310
137-
```
138-
139-
## Build documentation locally
140-
141-
```bash
142-
pip install -r requirements/docs.txt
143-
sphinx-build doc build
144-
```
145-
146-
If you use tox:
147-
148-
```bash
149-
tox -edocs
150-
```
33+
See our [Development guide](https://pygithub.readthedocs.io/en/stable/development.html) for details.

‎doc/conf.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,7 @@
7272

7373
# General information about the project.
7474
project = "PyGithub"
75-
copyright = "%d, Vincent Jacques" % datetime.date.today().year
75+
copyright = "%d, Vincent Jacques, Liuyang Wan, Steve Kowalik, Enrico Minack" % datetime.date.today().year
7676

7777
# The version info for the project you're documenting, acts as replacement for
7878
# |version| and |release|, also used in various other places throughout the

‎doc/development.rst‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
Development
2+
===========
3+
4+
.. toctree::
5+
:maxdepth: 2
6+
7+
getting-started
8+
testing
9+
openapi
10+
graphql
11+
12+
Deprecation warning
13+
-------------------
14+
15+
Before removing attributes/methods, consider adding deprecation warnings instead.
16+
The `typing_extensions <https://pypi.org/project/typing-extensions/>`__ package provides a handy decorator to add deprecation warnings.
17+
18+
.. code-block:: python
19+
20+
from typing_extensions import deprecated
21+
22+
@property
23+
@deprecated("Use core instead")
24+
def rate(self):
25+
pass
26+
27+
@deprecated("Deprecated in favor of the new branch protection")
28+
def get_protected_branch(self):
29+
pass

‎doc/getting-started.rst‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
Getting started
2+
===============
3+
4+
Source code
5+
-----------
6+
7+
This project's sources can be found at Github: https://github.com/PyGithub/PyGithub
8+
9+
Coding style
10+
------------
11+
12+
PyGithub adopts the black coding style.
13+
14+
To manually format the code::
15+
16+
pre-commit run --all-files --show-diff-on-failure
17+
mypy github tests
18+
19+
If you use tox::
20+
21+
tox -e lint
22+
23+
Pre-commit plugin
24+
-----------------
25+
26+
To forget about coding style and let `pre-commit <https://pre-commit.com/#installation>`__ fix your flake8/isort/black issue::
27+
28+
pre-commit install
29+
30+
That's it!
31+
32+
Build documentation locally
33+
---------------------------
34+
35+
You can build the documentation with Sphinx::
36+
37+
pip install -r requirements/docs.txt
38+
sphinx-build doc build
39+
40+
If you use tox::
41+
42+
tox -edocs

‎doc/graphql.rst‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
Github GraphQL
2+
==============
3+
4+
The PyGithub project primarily accesses the Github REST API v3. However, Github has started to provide
5+
more functionality behind a separate GraphQL API. Further benefits of the GraphQL endpoint is that the
6+
caller has full control over the structure and complexity (or simplicity) of the response, hence can reduce
7+
both number of calls and size of transferred data.
8+
9+
PyGithub provides access to the GraphQL API while providing results using the usual object-oriented PyGithub objects
10+
hierarchy.
11+
12+
This documents the current support for the GraphQL API.
13+
14+
GraphQL Classes
15+
---------------
16+
17+
Some PyGithub classes represent GraphQL schemas, where no equivalent Github REST API schema exists.
18+
GraphQL API data of those classes are translated (see ``as_rest_api_attributes(attributes)`` below)
19+
into REST API equivalent data and backed by ordinary PyGithub classes.
20+
21+
A good example is ``RepositoryDiscussion``:
22+
23+
.. code-block:: python
24+
25+
class RepositoryDiscussion(GraphQlObject, DiscussionBase):
26+
"""
27+
This class represents GraphQL Discussion.
28+
29+
The reference can be found here
30+
https://docs.github.com/en/graphql/reference/objects#discussion
31+
32+
"""
33+
34+
...
35+
36+
def _useAttributes(self, attributes: dict[str, Any]) -> None:
37+
# super class is a REST API GithubObject, attributes are coming from GraphQL
38+
super()._useAttributes(as_rest_api_attributes(attributes))
39+
if "answer" in attributes: # pragma no branch
40+
self._answer = self._makeClassAttribute(
41+
github.RepositoryDiscussionComment.RepositoryDiscussionComment, attributes["answer"]
42+
)
43+
if "bodyText" in attributes: # pragma no branch
44+
self._body_text = self._makeStringAttribute(attributes["bodyText"])
45+
...
46+
47+
Query
48+
-----
49+
50+
GraphQL data can be retrieved by GraphQL queries. A good example can be found in :class:`github.Repository.Repository` method ``get_discussion``.
51+
52+
GraphQL queries can be sent to the Github GraphQL API via these methods:
53+
54+
- :func:`github.Requester.Requester.graphql_node`
55+
- :func:`github.Requester.Requester.graphql_node_class`
56+
- :func:`github.Requester.Requester.graphql_query`
57+
- :func:`github.Requester.Requester.graphql_query_class`
58+
59+
Mutation
60+
--------
61+
62+
The GraphQL API can also be used to manipulate GraphQL data server-side.
63+
Example where GraphQL mutation is used can be found in:
64+
65+
- :class:`github.RepositoryDiscussion.RepositoryDiscussion` method ``add_comment``
66+
- :class:`github.RepositoryDiscussionComment.RepositoryDiscussionComment` method ``edit``
67+
- :class:`github.RepositoryDiscussionComment.RepositoryDiscussionComment` method ``delete``
68+
69+
GraphQL mutations can be sent to the Github GraphQL API via these methods:
70+
71+
- :func:`github.Requester.Requester.graphql_named_mutation`
72+
- :func:`github.Requester.Requester.graphql_named_mutation_class`
73+
74+
Pagination
75+
----------
76+
77+
An example where GraphQL results are provided through pagination can be found in :class:`github.Repository.Repository` method ``get_discussions``.
78+
79+
The response has to contain a GraphQL pagination object for :func:`github.PaginatedList.PaginatedList` to be able to paginate through the results::
80+
81+
totalCount
82+
pageInfo {
83+
startCursor
84+
endCursor
85+
hasNextPage
86+
hasPreviousPage
87+
}

‎doc/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,4 +7,5 @@ PyGithub
77
introduction
88
examples
99
reference
10+
development
1011
changes

‎doc/introduction.rst‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,17 @@ What next?
5858

5959
You need to use a Github API and wonder which class implements it? `Reference of APIs <https://pygithub.readthedocs.io/en/latest/apis.html>`__.
6060

61-
You want all the details about PyGithub classes? `Reference of Classes <https://pygithub.readthedocs.io/en/latest/github_objects.html>`__.
61+
Contributing
62+
------------
63+
64+
This project is community-driven. New PyGithub classes, methods and fixes are authored by the community, then reviewed and released by the project maintainers.
65+
66+
See our :doc:`development` guide for further details.
67+
68+
Sponsoring
69+
----------
70+
71+
Please consider sponsoring this project. Look out for the "Sponsor this project" area on the `PyGithub project page <https://github.com/PyGithub/PyGithub>`__.
6272

6373
Projects using PyGithub
6474
-----------------------

0 commit comments

Comments
 (0)