dex-connector-github 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (32) hide show
  1. dex_connector_github-0.1.0/.gitignore +16 -0
  2. dex_connector_github-0.1.0/LICENSE +21 -0
  3. dex_connector_github-0.1.0/PKG-INFO +39 -0
  4. dex_connector_github-0.1.0/README.md +26 -0
  5. dex_connector_github-0.1.0/examples/profile/README.md +22 -0
  6. dex_connector_github-0.1.0/examples/profile/__init__.py +3 -0
  7. dex_connector_github-0.1.0/examples/profile/flow.py +75 -0
  8. dex_connector_github-0.1.0/examples/profile/integration_test.py +101 -0
  9. dex_connector_github-0.1.0/examples/profile/main.py +40 -0
  10. dex_connector_github-0.1.0/pyproject.toml +41 -0
  11. dex_connector_github-0.1.0/src/dex_connectors/github/__init__.py +47 -0
  12. dex_connector_github-0.1.0/src/dex_connectors/github/_generated/__init__.py +2 -0
  13. dex_connector_github-0.1.0/src/dex_connectors/github/_generated/config.py +34 -0
  14. dex_connector_github-0.1.0/src/dex_connectors/github/_generated/connection.py +245 -0
  15. dex_connector_github-0.1.0/src/dex_connectors/github/_generated/definitions.py +143 -0
  16. dex_connector_github-0.1.0/src/dex_connectors/github/_generated/mock.py +665 -0
  17. dex_connector_github-0.1.0/src/dex_connectors/github/_generated/models.py +464 -0
  18. dex_connector_github-0.1.0/src/dex_connectors/github/_generated/refresh.py +9 -0
  19. dex_connector_github-0.1.0/src/dex_connectors/github/_generated/steps.py +385 -0
  20. dex_connector_github-0.1.0/src/dex_connectors/github/_generated/timestamps.py +60 -0
  21. dex_connector_github-0.1.0/src/dex_connectors/github/client.py +367 -0
  22. dex_connector_github-0.1.0/src/dex_connectors/github/connection.py +5 -0
  23. dex_connector_github-0.1.0/src/dex_connectors/github/dex-connector.json +304 -0
  24. dex_connector_github-0.1.0/src/dex_connectors/github/githubmock/__init__.py +6 -0
  25. dex_connector_github-0.1.0/src/dex_connectors/github/models.py +5 -0
  26. dex_connector_github-0.1.0/src/dex_connectors/github/operations.py +861 -0
  27. dex_connector_github-0.1.0/src/dex_connectors/github/steps.py +5 -0
  28. dex_connector_github-0.1.0/tests/refresh_agreement_cases.json +649 -0
  29. dex_connector_github-0.1.0/tests/test_client.py +156 -0
  30. dex_connector_github-0.1.0/tests/test_conformance.py +61 -0
  31. dex_connector_github-0.1.0/tests/test_refresh_agreement.py +278 -0
  32. dex_connector_github-0.1.0/uv.lock +934 -0
@@ -0,0 +1,16 @@
1
+ .DS_Store
2
+ __pycache__/
3
+ *.py[cod]
4
+ node_modules/
5
+ dist/
6
+ sdkpython/dist/dex_connectors_sdk-0.1.0-py3-none-any.whl
7
+ /.bin/dexcli
8
+ /.bin/dex-server-zd
9
+ /sdkpython/.dexcli-data/
10
+ site/.catalog.yaml
11
+ coverage/
12
+ *.out
13
+ *.test
14
+ go.work
15
+ go.work.sum
16
+ .idea/
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Super Durable
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,39 @@
1
+ Metadata-Version: 2.5
2
+ Name: dex-connector-github
3
+ Version: 0.1.0
4
+ Summary: Dex-native GitHub connector
5
+ Project-URL: Source, https://github.com/superdurable/dex-connectors-library/tree/main/connectors/github/python
6
+ License-Expression: MIT
7
+ License-File: LICENSE
8
+ Requires-Python: >=3.11
9
+ Requires-Dist: dex-connectors-sdk==0.7.0
10
+ Requires-Dist: dex-python-sdk>=1.28.0
11
+ Requires-Dist: httpx>=0.27
12
+ Description-Content-Type: text/markdown
13
+
14
+ # GitHub Python connector
15
+
16
+ `dex-connector-github` implements the six GitHub Query operations declared in
17
+ [`connector.yaml`](../connector.yaml): `getAuthenticatedProfile`,
18
+ `listPublicRepositories`, `listMergedPullRequests`, `listPullRequestFiles`,
19
+ `listReleases`, and `listCommits`. Its Python release is `v0.1.0`; the Go release
20
+ version remains independent.
21
+
22
+ The generated project connection resolves credentials at call time and uses the
23
+ manifest-driven OAuth refresh driver. It requests `read:user`, `user:email`, and
24
+ `offline_access` during authorization. The provider responses must advertise
25
+ exactly `read:user` and `user:email` in `X-OAuth-Scopes`; broader scopes select
26
+ `insufficientScope`. The package never stores tokens in Flow input, Attributes,
27
+ Results, receipts, or logs.
28
+
29
+ The [profile example](examples/profile/README.md) is the runnable consuming
30
+ application. Its Worker entrypoint is `examples/profile/main.py`; the Flow
31
+ source is `examples/profile/flow.py`. The real Dex integration test runs that
32
+ Flow with an inert local provider stand-in. Provider replay tests use the
33
+ Go-recorded scenarios in [`conformance/connectors/github`](../../../conformance/connectors/github/).
34
+
35
+ From this directory, run `uv sync` and `uv run pytest -q tests`. With a local
36
+ Dex stack running, set `DEX_FLOW_SERVICE_ADDRESS` to its gRPC address and run
37
+ `uv run pytest -q examples/profile/integration_test.py`. The local integration
38
+ test does not authorize against GitHub.com. Use Dex Web Connections and the
39
+ GitHub OAuth App guide in the manifest for live provider authorization.
@@ -0,0 +1,26 @@
1
+ # GitHub Python connector
2
+
3
+ `dex-connector-github` implements the six GitHub Query operations declared in
4
+ [`connector.yaml`](../connector.yaml): `getAuthenticatedProfile`,
5
+ `listPublicRepositories`, `listMergedPullRequests`, `listPullRequestFiles`,
6
+ `listReleases`, and `listCommits`. Its Python release is `v0.1.0`; the Go release
7
+ version remains independent.
8
+
9
+ The generated project connection resolves credentials at call time and uses the
10
+ manifest-driven OAuth refresh driver. It requests `read:user`, `user:email`, and
11
+ `offline_access` during authorization. The provider responses must advertise
12
+ exactly `read:user` and `user:email` in `X-OAuth-Scopes`; broader scopes select
13
+ `insufficientScope`. The package never stores tokens in Flow input, Attributes,
14
+ Results, receipts, or logs.
15
+
16
+ The [profile example](examples/profile/README.md) is the runnable consuming
17
+ application. Its Worker entrypoint is `examples/profile/main.py`; the Flow
18
+ source is `examples/profile/flow.py`. The real Dex integration test runs that
19
+ Flow with an inert local provider stand-in. Provider replay tests use the
20
+ Go-recorded scenarios in [`conformance/connectors/github`](../../../conformance/connectors/github/).
21
+
22
+ From this directory, run `uv sync` and `uv run pytest -q tests`. With a local
23
+ Dex stack running, set `DEX_FLOW_SERVICE_ADDRESS` to its gRPC address and run
24
+ `uv run pytest -q examples/profile/integration_test.py`. The local integration
25
+ test does not authorize against GitHub.com. Use Dex Web Connections and the
26
+ GitHub OAuth App guide in the manifest for live provider authorization.
@@ -0,0 +1,22 @@
1
+ # GitHub profile Python example
2
+
3
+ From `connectors/github/python`, generate the strict FDG 2.0 artifact:
4
+
5
+ ```sh
6
+ uv sync
7
+ dexcli visualize ./examples/profile/flow.py --language python \
8
+ --python .venv/bin/python --schema-version 2.0 --json \
9
+ --out ./build/github-profile
10
+ ```
11
+
12
+ The output must have `"valid": true` and no blocking diagnostics. Start
13
+ `dexcli dev -flow-rendering-dir ./build`, then set up the `github-profile`
14
+ OAuth connection in Dex Web. Its authorization guide lists the GitHub OAuth
15
+ App, callback URL, and requested scopes. Run
16
+ `uv run python -m examples.profile.main` from `connectors/github/python`.
17
+ Start `GitHubAuthenticatedProfilePython` with
18
+ `{"requested_by":"operator"}`. The Flow stores the verified profile in the
19
+ `github-profile-result` Attribute and completes with the same value.
20
+
21
+ The integration test uses an inert token and a local GitHub stand-in. Run it
22
+ with `DEX_FLOW_SERVICE_ADDRESS=<dexcli-address> uv run pytest -q examples/profile/integration_test.py`.
@@ -0,0 +1,3 @@
1
+ # Copyright (c) 2026 Super Durable
2
+ # SPDX-License-Identifier: MIT
3
+ """GitHub profile Flow example."""
@@ -0,0 +1,75 @@
1
+ # Copyright (c) 2026 Super Durable
2
+ # SPDX-License-Identifier: MIT
3
+ """Runnable GitHub authenticated profile Flow."""
4
+
5
+ from dataclasses import dataclass
6
+
7
+ import dex
8
+ from dex_connectors.sdk import QueryResult
9
+
10
+ from dex_connectors.github import (
11
+ AuthenticatedProfile,
12
+ Connection,
13
+ GetAuthenticatedProfileInput,
14
+ new_get_authenticated_profile_step,
15
+ )
16
+
17
+ CONNECTION_NAME = "github-profile"
18
+
19
+
20
+ @dataclass(frozen=True, slots=True)
21
+ class ProfileRequest:
22
+ """Safe request to inspect the connected GitHub account."""
23
+
24
+ requested_by: str
25
+
26
+ def to_operation_input(self) -> GetAuthenticatedProfileInput:
27
+ """Map the Flow start input to the no-argument profile query."""
28
+ return GetAuthenticatedProfileInput()
29
+
30
+
31
+ profile_result = dex.Attribute("github-profile-result", AuthenticatedProfile)
32
+
33
+
34
+ # dex:group group-id:github-profile group-label:"GitHub Profile"
35
+ # dex:explanation text:"Persist the verified public profile and complete the Flow."
36
+ class CompleteProfile(dex.Step[QueryResult[AuthenticatedProfile]]):
37
+ """Retain the safe profile returned by GitHub."""
38
+
39
+ def execute(self, context: dex.Context, input: QueryResult[AuthenticatedProfile]) -> dex.StepDecision:
40
+ """Store the typed profile and complete the Flow."""
41
+ profile_result.set(context, input.value)
42
+ return dex.graceful_complete(input.value)
43
+
44
+
45
+ class ProfileFlow(dex.Flow[ProfileRequest]):
46
+ """Read the authenticated account with the static GitHub connection."""
47
+
48
+ def __init__(self, connection: Connection) -> None:
49
+ """Bind the connector Query before Worker registration."""
50
+ self.complete = CompleteProfile()
51
+ self.profile = new_get_authenticated_profile_step(
52
+ step_type="GetAuthenticatedProfile",
53
+ step_input_type=ProfileRequest,
54
+ annotations={
55
+ "groupId": "github-profile",
56
+ "groupLabel": "GitHub Profile",
57
+ "explanation": "Read the connected GitHub account and verified primary email.",
58
+ },
59
+ connection=connection,
60
+ connection_name=CONNECTION_NAME,
61
+ map_to_operation_input=ProfileRequest.to_operation_input,
62
+ profile_loaded=self.complete,
63
+ )
64
+
65
+ def get_flow_type(self) -> str:
66
+ """Return the stable Flow identity."""
67
+ return "GitHubAuthenticatedProfilePython"
68
+
69
+ def get_steps(self) -> dex.StepList[ProfileRequest]:
70
+ """Start with the provider Query and complete on its happy path."""
71
+ return dex.StepList.start_step(self.profile).other_steps(self.complete)
72
+
73
+ def get_persistence_schema(self) -> dex.PersistenceSchema:
74
+ """Register the profile Attribute used by the completion Step."""
75
+ return dex.PersistenceSchema.of(profile_result)
@@ -0,0 +1,101 @@
1
+ # Copyright (c) 2026 Super Durable
2
+ # SPDX-License-Identifier: MIT
3
+ """Run the GitHub profile example through a real Dex Worker and Client."""
4
+
5
+ import asyncio
6
+ import json
7
+ import os
8
+ import tempfile
9
+ import threading
10
+ from datetime import timedelta
11
+ from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
12
+ from pathlib import Path
13
+ from uuid import uuid4
14
+
15
+ import dex
16
+ import pytest
17
+ from dex_connectors.sdk import ConnectionRef, SecretString, StaticCredentialProvider
18
+
19
+ from dex_connectors.github import AuthenticatedProfile, Client, Config, Credentials, new_connection
20
+
21
+ from .flow import CONNECTION_NAME, ProfileFlow, ProfileRequest
22
+
23
+
24
+ class GitHubStandIn(BaseHTTPRequestHandler):
25
+ """Serve inert profile and email responses on an OS-assigned port."""
26
+
27
+ requests: list[str] = []
28
+
29
+ def do_GET(self) -> None:
30
+ """Return the two responses needed by the profile operation."""
31
+ self.requests.append(self.path)
32
+ if self.path == "/user":
33
+ body = {"id": 42, "login": "octocat", "name": "Mona"}
34
+ status = 200
35
+ elif self.path == "/user/emails?per_page=100":
36
+ body = [{"email": "octocat@example.com", "primary": True, "verified": True}]
37
+ status = 200
38
+ else:
39
+ body = {}
40
+ status = 404
41
+ payload = json.dumps(body).encode()
42
+ self.send_response(status)
43
+ self.send_header("Content-Type", "application/json")
44
+ self.send_header("Content-Length", str(len(payload)))
45
+ self.send_header("X-OAuth-Scopes", "read:user, user:email")
46
+ self.end_headers()
47
+ self.wfile.write(payload)
48
+
49
+ def log_message(self, format: str, *args: object) -> None:
50
+ """Keep inert request details out of test output."""
51
+ return
52
+
53
+
54
+ @pytest.mark.asyncio
55
+ async def test_profile_flow_through_real_dex() -> None:
56
+ """Complete the profile Flow using the same application and real Dex stack."""
57
+ server_address = os.environ["DEX_FLOW_SERVICE_ADDRESS"]
58
+ stand_in = ThreadingHTTPServer(("127.0.0.1", 0), GitHubStandIn)
59
+ server_thread = threading.Thread(target=stand_in.serve_forever, daemon=True)
60
+ server_thread.start()
61
+ reference = ConnectionRef("github", CONNECTION_NAME)
62
+ credentials = Credentials(
63
+ "client-id", SecretString("client-secret"), SecretString("inert-token"), SecretString("")
64
+ )
65
+ client = Client(
66
+ Config(base_url=f"http://127.0.0.1:{stand_in.server_port}"),
67
+ StaticCredentialProvider({reference: credentials}),
68
+ )
69
+ connection = new_connection(client, reference)
70
+ try:
71
+ flow = ProfileFlow(connection)
72
+ registry = dex.Registry([flow], allow_async_handlers=True)
73
+ with tempfile.TemporaryDirectory(prefix="github-python-dex-blobs-") as cache_directory:
74
+ cache = dex.open_blob_cache(dex.BlobCacheConfig(str(Path(cache_directory) / "blobs"), 1 << 24))
75
+ try:
76
+ worker = dex.AsyncWorker(registry, cache, dex.WorkerOptions(server_address=server_address))
77
+ worker_task = asyncio.create_task(worker.start())
78
+ try:
79
+ await worker.wait_pull_registered(timeout=15)
80
+ async with dex.AsyncClient(
81
+ registry, cache, dex.ClientOptions(server_address=server_address)
82
+ ) as dex_client:
83
+ flow_id = f"github-python-{uuid4().hex}"
84
+ await dex_client.start_flow(flow, flow_id, ProfileRequest("test"))
85
+ result = await asyncio.wait_for(
86
+ dex_client.wait_for_flow(flow_id, timedelta(seconds=20)), 30
87
+ )
88
+ assert result.status == dex.FlowStatus.COMPLETED, result.error_message
89
+ profile = result.single_output(AuthenticatedProfile)
90
+ assert profile.subject == "42" and profile.verified_email == "octocat@example.com"
91
+ assert GitHubStandIn.requests == ["/user", "/user/emails?per_page=100"]
92
+ finally:
93
+ await worker.stop()
94
+ await worker_task
95
+ finally:
96
+ cache.close()
97
+ finally:
98
+ await connection.aclose()
99
+ stand_in.shutdown()
100
+ stand_in.server_close()
101
+ server_thread.join(timeout=5)
@@ -0,0 +1,40 @@
1
+ # Copyright (c) 2026 Super Durable
2
+ # SPDX-License-Identifier: MIT
3
+ """Run the GitHub profile Worker with a Dex project connection."""
4
+
5
+ import asyncio
6
+ import os
7
+ import tempfile
8
+ from pathlib import Path
9
+
10
+ import dex
11
+ from dex_connectors.sdk.projectconfig import load_from_environment
12
+
13
+ from dex_connectors.github import new_project_connection
14
+
15
+ from .flow import CONNECTION_NAME, ProfileFlow
16
+
17
+
18
+ async def run() -> None:
19
+ """Load the OAuth connection and serve profile requests."""
20
+ project = await load_from_environment()
21
+ connection = new_project_connection(project, CONNECTION_NAME)
22
+ cache = dex.open_blob_cache(
23
+ dex.BlobCacheConfig(str(Path(tempfile.gettempdir()) / "dex-github-python-blobs"), 1 << 30)
24
+ )
25
+ try:
26
+ registry = dex.Registry([ProfileFlow(connection)], allow_async_handlers=True)
27
+ async with dex.AsyncWorker(
28
+ registry,
29
+ cache,
30
+ dex.WorkerOptions(server_address=os.environ.get("DEX_FLOW_SERVICE_ADDRESS", "localhost:8801")),
31
+ ) as worker:
32
+ await worker.start()
33
+ finally:
34
+ cache.close()
35
+ await connection.aclose()
36
+ await project.close()
37
+
38
+
39
+ if __name__ == "__main__":
40
+ asyncio.run(run())
@@ -0,0 +1,41 @@
1
+ [build-system]
2
+ requires = ["hatchling>=1.27"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "dex-connector-github"
7
+ version = "0.1.0"
8
+ description = "Dex-native GitHub connector"
9
+ readme = "README.md"
10
+ requires-python = ">=3.11"
11
+ license = "MIT"
12
+ license-files = ["LICENSE"]
13
+ dependencies = ["dex-connectors-sdk==0.7.0", "dex-python-sdk>=1.28.0", "httpx>=0.27"]
14
+
15
+ [project.urls]
16
+ Source = "https://github.com/superdurable/dex-connectors-library/tree/main/connectors/github/python"
17
+
18
+ [dependency-groups]
19
+ dev = ["pytest>=8", "pytest-asyncio>=0.24", "mypy>=1.13", "ruff>=0.7", "PyYAML>=6", "types-PyYAML>=6"]
20
+
21
+ [tool.hatch.build.targets.wheel]
22
+ packages = ["src/dex_connectors"]
23
+
24
+ [tool.pytest.ini_options]
25
+ testpaths = ["tests"]
26
+ pythonpath = [".", "src"]
27
+ asyncio_mode = "auto"
28
+ asyncio_default_fixture_loop_scope = "function"
29
+
30
+ [tool.mypy]
31
+ python_version = "3.11"
32
+ strict = true
33
+ mypy_path = "src"
34
+ explicit_package_bases = true
35
+
36
+ [tool.ruff]
37
+ target-version = "py311"
38
+ line-length = 110
39
+
40
+ [tool.ruff.lint]
41
+ select = ["E", "F", "I", "UP", "B"]
@@ -0,0 +1,47 @@
1
+ # Copyright (c) 2026 Super Durable
2
+ # SPDX-License-Identifier: MIT
3
+ # ruff: noqa: F403, F405
4
+ """Dex-native GitHub connector."""
5
+
6
+ from .client import Client as Client
7
+ from .client import Config as Config
8
+ from .client import Credentials as Credentials
9
+ from .connection import Connection as Connection
10
+ from .connection import new_connection as new_connection
11
+ from .connection import new_connection_with_operations as new_connection_with_operations
12
+ from .connection import new_project_connection as new_project_connection
13
+ from .models import * # noqa: F403
14
+ from .steps import * # noqa: F403
15
+
16
+ __all__ = [
17
+ "Client",
18
+ "Config",
19
+ "Credentials",
20
+ "Connection",
21
+ "new_connection",
22
+ "new_connection_with_operations",
23
+ "new_project_connection",
24
+ "GetAuthenticatedProfileInput",
25
+ "AuthenticatedProfile",
26
+ "ListPublicRepositoriesInput",
27
+ "Repository",
28
+ "PublicRepositories",
29
+ "ListMergedPullRequestsInput",
30
+ "MergedPullRequest",
31
+ "MergedPullRequestPage",
32
+ "ListPullRequestFilesInput",
33
+ "PullRequestFile",
34
+ "PullRequestFilePage",
35
+ "ListReleasesInput",
36
+ "Release",
37
+ "ReleasePage",
38
+ "ListCommitsInput",
39
+ "CommitSummary",
40
+ "CommitPage",
41
+ "new_get_authenticated_profile_step",
42
+ "new_list_public_repositories_step",
43
+ "new_list_merged_pull_requests_step",
44
+ "new_list_pull_request_files_step",
45
+ "new_list_releases_step",
46
+ "new_list_commits_step",
47
+ ]
@@ -0,0 +1,2 @@
1
+ # Copyright (c) 2026 Super Durable
2
+ # SPDX-License-Identifier: MIT
@@ -0,0 +1,34 @@
1
+ # Copyright (c) 2026 Super Durable
2
+ # SPDX-License-Identifier: MIT
3
+ # ruff: noqa
4
+
5
+ from dataclasses import dataclass
6
+
7
+ from dex_connectors.sdk import SecretString
8
+
9
+
10
+ @dataclass(frozen=True, slots=True)
11
+ class Config:
12
+
13
+ base_url: str = "https://api.github.com"
14
+ api_version: str = "2026-03-10"
15
+ timeout_seconds: float = 15
16
+ max_response_bytes: int = 2097152
17
+ default_repository_limit: int = 100
18
+ max_repositories: int = 500
19
+ max_pull_request_body_characters: int = 4000
20
+ max_patch_characters: int = 4000
21
+ max_commit_message_characters: int = 4000
22
+
23
+ setattr(Config, '__module__', 'dex_connectors.github.client')
24
+
25
+
26
+ @dataclass(frozen=True, slots=True)
27
+ class Credentials:
28
+
29
+ oauth_client_id: str
30
+ oauth_client_secret: SecretString
31
+ access_token: SecretString
32
+ refresh_token: SecretString
33
+
34
+ setattr(Credentials, '__module__', 'dex_connectors.github.client')