lupaxa-github-extractor 0.1.0__py3-none-any.whl

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.
@@ -0,0 +1,98 @@
1
+ """List GitHub organisations, repositories, and related data."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from .client import GitHubExtractor
6
+ from .errors import (
7
+ AuthenticationError,
8
+ ForbiddenError,
9
+ MissingOrgNameError,
10
+ MissingTokenError,
11
+ NotFoundError,
12
+ RateLimitExceededError,
13
+ RequestError,
14
+ RequestTimeoutError,
15
+ )
16
+ from .models import (
17
+ AuditEvent,
18
+ Branch,
19
+ Collaborator,
20
+ Commit,
21
+ Content,
22
+ Contributor,
23
+ Deployment,
24
+ Email,
25
+ Environment,
26
+ Event,
27
+ Fork,
28
+ GitHubObject,
29
+ GpgKey,
30
+ Hook,
31
+ Issue,
32
+ Label,
33
+ Milestone,
34
+ Notification,
35
+ Organisation,
36
+ PullRequest,
37
+ Release,
38
+ Repository,
39
+ ResourceError,
40
+ SshKey,
41
+ Stargazer,
42
+ Subscriber,
43
+ Tag,
44
+ Team,
45
+ TokenInformation,
46
+ Topics,
47
+ User,
48
+ Workflow,
49
+ WorkflowRun,
50
+ )
51
+ from .version import __version__, get_version
52
+
53
+ __all__ = [
54
+ "AuditEvent",
55
+ "AuthenticationError",
56
+ "Branch",
57
+ "Collaborator",
58
+ "Commit",
59
+ "Content",
60
+ "Contributor",
61
+ "Deployment",
62
+ "Email",
63
+ "Environment",
64
+ "Event",
65
+ "ForbiddenError",
66
+ "Fork",
67
+ "GitHubExtractor",
68
+ "GitHubObject",
69
+ "GpgKey",
70
+ "Hook",
71
+ "Issue",
72
+ "Label",
73
+ "Milestone",
74
+ "MissingOrgNameError",
75
+ "MissingTokenError",
76
+ "NotFoundError",
77
+ "Notification",
78
+ "Organisation",
79
+ "PullRequest",
80
+ "RateLimitExceededError",
81
+ "Release",
82
+ "Repository",
83
+ "RequestError",
84
+ "RequestTimeoutError",
85
+ "ResourceError",
86
+ "SshKey",
87
+ "Stargazer",
88
+ "Subscriber",
89
+ "Tag",
90
+ "Team",
91
+ "TokenInformation",
92
+ "Topics",
93
+ "User",
94
+ "Workflow",
95
+ "WorkflowRun",
96
+ "__version__",
97
+ "get_version",
98
+ ]
@@ -0,0 +1,10 @@
1
+ """Run GitHub Extractor as a module."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import sys
6
+
7
+ from .cli import main
8
+
9
+ if __name__ == "__main__":
10
+ sys.exit(main())
@@ -0,0 +1,383 @@
1
+ """Command-line interface for GitHub Extractor."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import argparse
6
+ from collections.abc import Callable, Iterable
7
+ from contextlib import redirect_stderr
8
+ import io
9
+ import json
10
+ import os
11
+ import subprocess
12
+ import sys
13
+ from typing import Any
14
+
15
+ from .client import GitHubExtractor
16
+ from .constants import API_ROOT, DEFAULT_MAX_WORKERS, DEFAULT_TIMEOUT, GH_AUTH_TIMEOUT
17
+ from .convert import to_jsonable
18
+ from .errors import (
19
+ AuthenticationError,
20
+ ForbiddenError,
21
+ MissingOrgNameError,
22
+ MissingTokenError,
23
+ NotFoundError,
24
+ RateLimitExceededError,
25
+ )
26
+ from .resources import ORGANISATION_RESOURCES, REPOSITORY_RESOURCES, USER_RESOURCES
27
+
28
+
29
+ def _selected_flag_names(args: argparse.Namespace, names: tuple[str, ...]) -> list[str]:
30
+ """Return flag names that were set, in table order."""
31
+ return [name for name in names if getattr(args, name)]
32
+
33
+
34
+ def _shared_parser(*, suppress_defaults: bool = False) -> argparse.ArgumentParser:
35
+ """Build options shared by every command."""
36
+ parser = argparse.ArgumentParser(add_help=False)
37
+ default = argparse.SUPPRESS if suppress_defaults else None
38
+ parser.add_argument("--token", default=default)
39
+ parser.add_argument(
40
+ "--timeout",
41
+ type=float,
42
+ default=argparse.SUPPRESS if suppress_defaults else DEFAULT_TIMEOUT,
43
+ )
44
+ parser.add_argument(
45
+ "--max-workers",
46
+ type=int,
47
+ default=argparse.SUPPRESS if suppress_defaults else DEFAULT_MAX_WORKERS,
48
+ )
49
+ parser.add_argument("--max-pages", type=int, default=argparse.SUPPRESS if suppress_defaults else None)
50
+ parser.add_argument("--api-root", default=argparse.SUPPRESS if suppress_defaults else API_ROOT)
51
+ return parser
52
+
53
+
54
+ def _parse_params(values: list[str]) -> dict[str, dict[str, str]]:
55
+ """Turn NAME.KEY=VALUE flags into a params mapping. The last value wins."""
56
+ parsed: dict[str, dict[str, str]] = {}
57
+ for item in values:
58
+ name, dot, rest = item.partition(".")
59
+ key, equals, value = rest.partition("=")
60
+ if not dot or not name or not equals or not key:
61
+ raise ValueError("param must be name.key=value")
62
+ parsed.setdefault(name, {})[key] = value
63
+ return parsed
64
+
65
+
66
+ def _add_param_option(parser: argparse.ArgumentParser) -> None:
67
+ """Add repeatable query-parameter flags to a parser."""
68
+ parser.add_argument("--param", action="append", default=[])
69
+
70
+
71
+ def _add_resource_flags(parser: argparse.ArgumentParser, names: tuple[str, ...]) -> None:
72
+ """Add boolean resource flags; argparse dest keeps the Python name."""
73
+ for flag in names:
74
+ parser.add_argument(f"--{flag.replace('_', '-')}", action="store_true")
75
+
76
+
77
+ def _add_organisation_options(parser: argparse.ArgumentParser) -> None:
78
+ """Add organisation-list options to a parser."""
79
+ parser.add_argument("--include", action="append", default=[])
80
+ parser.add_argument("--ignore", action="append", default=[])
81
+ parser.add_argument("--slugs", action="store_true")
82
+ _add_resource_flags(parser, ORGANISATION_RESOURCES)
83
+ _add_param_option(parser)
84
+
85
+
86
+ def _add_repository_resource_options(parser: argparse.ArgumentParser) -> None:
87
+ """Add repository resource flags and query parameters to a parser."""
88
+ _add_resource_flags(parser, REPOSITORY_RESOURCES)
89
+ _add_param_option(parser)
90
+
91
+
92
+ def _add_repository_options(parser: argparse.ArgumentParser) -> None:
93
+ """Add repository filters and addon flags to a parser."""
94
+ parser.add_argument("--include", action="append", default=[])
95
+ parser.add_argument("--ignore", action="append", default=[])
96
+ parser.add_argument("--include-name", action="append", default=[])
97
+ parser.add_argument("--ignore-name", action="append", default=[])
98
+ parser.add_argument("--skip-private", action="store_true")
99
+ parser.add_argument("--slugs", action="store_true")
100
+ _add_resource_flags(parser, REPOSITORY_RESOURCES)
101
+ _add_param_option(parser)
102
+
103
+
104
+ def _add_user_options(parser: argparse.ArgumentParser) -> None:
105
+ """Add authenticated-user extra flags to a parser."""
106
+ _add_resource_flags(parser, USER_RESOURCES)
107
+ _add_resource_flags(parser, REPOSITORY_RESOURCES)
108
+ _add_param_option(parser)
109
+
110
+
111
+ def build_parser() -> argparse.ArgumentParser:
112
+ """Build the complete command-line parser."""
113
+ parser = argparse.ArgumentParser(
114
+ prog="github-extractor",
115
+ parents=[_shared_parser()],
116
+ )
117
+ shared = _shared_parser(suppress_defaults=True)
118
+ commands = parser.add_subparsers(dest="command", required=True)
119
+
120
+ commands.add_parser("token", parents=[shared])
121
+
122
+ get_command = commands.add_parser("get", parents=[shared])
123
+ get_command.add_argument("path")
124
+
125
+ user = commands.add_parser("user", parents=[shared])
126
+ _add_user_options(user)
127
+
128
+ repo = commands.add_parser("repo", parents=[shared])
129
+ repo.add_argument("full_name")
130
+ _add_repository_resource_options(repo)
131
+
132
+ for name in ("organisations", "organizations"):
133
+ organisation = commands.add_parser(name, parents=[shared])
134
+ _add_organisation_options(organisation)
135
+
136
+ repos = commands.add_parser("repos", parents=[shared])
137
+ repo_commands = repos.add_subparsers(dest="repo_command", required=True)
138
+
139
+ repo_user = repo_commands.add_parser("user", parents=[shared])
140
+ _add_repository_options(repo_user)
141
+ repo_user.add_argument("--username")
142
+
143
+ repo_org = repo_commands.add_parser("org", parents=[shared])
144
+ repo_org.add_argument("org")
145
+ _add_repository_options(repo_org)
146
+
147
+ repo_visible = repo_commands.add_parser("visible", parents=[shared])
148
+ _add_repository_options(repo_visible)
149
+
150
+ repo_organisations = repo_commands.add_parser(
151
+ "organisations",
152
+ parents=[shared],
153
+ )
154
+ _add_repository_options(repo_organisations)
155
+ repo_organisations.add_argument("--include-org", action="append", default=[])
156
+ repo_organisations.add_argument("--ignore-org", action="append", default=[])
157
+
158
+ repo_organizations = repo_commands.add_parser(
159
+ "organizations",
160
+ parents=[shared],
161
+ )
162
+ _add_repository_options(repo_organizations)
163
+ repo_organizations.add_argument("--include-org", action="append", default=[])
164
+ repo_organizations.add_argument("--ignore-org", action="append", default=[])
165
+ return parser
166
+
167
+
168
+ def resolve_token(explicit: str | None) -> str:
169
+ """Resolve a token from an argument, environment, or GitHub CLI."""
170
+ token = explicit.strip() if explicit is not None else ""
171
+ if token:
172
+ return token
173
+ token = os.environ.get("GITHUB_TOKEN", "").strip()
174
+ if token:
175
+ return token
176
+ try:
177
+ result = subprocess.run(
178
+ ["gh", "auth", "token"], # noqa: S607
179
+ check=False,
180
+ capture_output=True,
181
+ text=True,
182
+ timeout=GH_AUTH_TIMEOUT,
183
+ )
184
+ except (OSError, subprocess.TimeoutExpired):
185
+ result = None
186
+ if result is not None and result.returncode == 0:
187
+ token = result.stdout.strip()
188
+ if token:
189
+ return token
190
+ raise MissingTokenError
191
+
192
+
193
+ def _user_options(args: argparse.Namespace) -> dict[str, Any]:
194
+ """Return authenticated-user options from parsed arguments."""
195
+ return {
196
+ "resources": _selected_flag_names(args, USER_RESOURCES),
197
+ "repository_resources": _selected_flag_names(args, REPOSITORY_RESOURCES),
198
+ "params": _parse_params(args.param),
199
+ }
200
+
201
+
202
+ def _organisation_options(args: argparse.Namespace) -> dict[str, Any]:
203
+ """Return organisation options from parsed arguments."""
204
+ return {
205
+ "include": args.include,
206
+ "ignore": args.ignore,
207
+ "slugs": args.slugs,
208
+ "resources": _selected_flag_names(args, ORGANISATION_RESOURCES),
209
+ "params": _parse_params(args.param),
210
+ }
211
+
212
+
213
+ def _repository_options(args: argparse.Namespace) -> dict[str, Any]:
214
+ """Return repository options from parsed arguments."""
215
+ return {
216
+ "include": args.include,
217
+ "ignore": args.ignore,
218
+ "include_names": args.include_name,
219
+ "ignore_names": args.ignore_name,
220
+ "skip_private": args.skip_private,
221
+ "slugs": args.slugs,
222
+ "resources": _selected_flag_names(args, REPOSITORY_RESOURCES),
223
+ "params": _parse_params(args.param),
224
+ }
225
+
226
+
227
+ def _dispatch_repositories(client: GitHubExtractor, args: argparse.Namespace) -> Any: # noqa: ANN401
228
+ """Dispatch one repository subcommand."""
229
+ options = _repository_options(args)
230
+ handlers: dict[str, Callable[[], Any]] = {
231
+ "user": lambda: client.user_repositories(
232
+ username=args.username,
233
+ **options,
234
+ ),
235
+ "org": lambda: client.repositories_by_org(args.org, **options),
236
+ "visible": lambda: client.visible_repositories(**options),
237
+ "organisations": lambda: client.organisation_repositories(
238
+ include_orgs=args.include_org,
239
+ ignore_orgs=args.ignore_org,
240
+ **options,
241
+ ),
242
+ "organizations": lambda: client.organisation_repositories(
243
+ include_orgs=args.include_org,
244
+ ignore_orgs=args.ignore_org,
245
+ **options,
246
+ ),
247
+ }
248
+ return handlers[args.repo_command]()
249
+
250
+
251
+ def dispatch(client: GitHubExtractor, args: argparse.Namespace) -> Any: # noqa: ANN401
252
+ """Dispatch one top-level command to the client."""
253
+ handlers: dict[str, Callable[[], Any]] = {
254
+ "token": client.token_information,
255
+ "get": lambda: client.get(args.path),
256
+ "user": lambda: client.authenticated_user(**_user_options(args)),
257
+ "organisations": lambda: client.organisations(**_organisation_options(args)),
258
+ "organizations": lambda: client.organizations(**_organisation_options(args)),
259
+ "repos": lambda: _dispatch_repositories(client, args),
260
+ "repo": lambda: client.repository(
261
+ args.full_name,
262
+ resources=_selected_flag_names(args, REPOSITORY_RESOURCES),
263
+ params=_parse_params(args.param),
264
+ ),
265
+ }
266
+ return handlers[args.command]()
267
+
268
+
269
+ def _exit_code(error: Exception) -> int:
270
+ """Map a public error to its process exit code."""
271
+ if isinstance(error, (MissingTokenError, MissingOrgNameError, ValueError)):
272
+ return 2
273
+ if isinstance(error, AuthenticationError):
274
+ return 3
275
+ if isinstance(error, RateLimitExceededError):
276
+ return 4
277
+ if isinstance(error, NotFoundError):
278
+ return 5
279
+ if isinstance(error, ForbiddenError):
280
+ return 1
281
+ return 1
282
+
283
+
284
+ def _redaction_tokens(token: str | None) -> list[str]:
285
+ """Collect only the token actually used for the successful request."""
286
+ return [token] if token else []
287
+
288
+
289
+ def _print_error(error: Exception, token: str | None) -> None:
290
+ """Write one safe error message to stderr."""
291
+ print(_redact(str(error), [token] if token else []), file=sys.stderr)
292
+
293
+
294
+ _TOKEN_FLAG = "--token" # noqa: S105
295
+
296
+
297
+ def _token_like_flag(flag: str) -> bool:
298
+ """Return whether an argv item names --token, including abbreviations."""
299
+ if not flag.startswith("--"):
300
+ return False
301
+ if "=" in flag:
302
+ flag = flag.partition("=")[0]
303
+ return flag.startswith(_TOKEN_FLAG) or _TOKEN_FLAG.startswith(flag)
304
+
305
+
306
+ def _redact(message: str, tokens: Iterable[str]) -> str:
307
+ """Replace every supplied token in a message, longest values first."""
308
+ unique = {token for token in tokens if token}
309
+ for token in sorted(unique, key=len, reverse=True):
310
+ message = message.replace(token, "[redacted]")
311
+ return message
312
+
313
+
314
+ def _argument_tokens(arguments: list[str]) -> list[str]:
315
+ """Collect token values before argparse can include them in an error."""
316
+ tokens: list[str] = []
317
+ for index, argument in enumerate(arguments):
318
+ if "=" in argument and argument.startswith("--"):
319
+ flag, _, value = argument.partition("=")
320
+ if value and _token_like_flag(flag):
321
+ tokens.append(value)
322
+ continue
323
+ if _token_like_flag(argument) and index + 1 < len(arguments):
324
+ value = arguments[index + 1]
325
+ if value:
326
+ tokens.append(value)
327
+ environment_token = os.environ.get("GITHUB_TOKEN", "").strip()
328
+ if environment_token:
329
+ tokens.append(environment_token)
330
+ return tokens
331
+
332
+
333
+ def _parse_args(argv: list[str] | None) -> argparse.Namespace:
334
+ """Parse arguments while redacting errors before writing to stderr."""
335
+ arguments = list(sys.argv[1:] if argv is None else argv)
336
+ error_output = io.StringIO()
337
+ try:
338
+ with redirect_stderr(error_output):
339
+ return build_parser().parse_args(arguments)
340
+ except SystemExit:
341
+ sys.stderr.write(_redact(error_output.getvalue(), _argument_tokens(arguments)))
342
+ raise
343
+
344
+
345
+ def _validate_client_settings(timeout: float, max_workers: int) -> None:
346
+ """Reject invalid client settings before construction."""
347
+ if not timeout > 0:
348
+ raise ValueError("timeout must be greater than zero")
349
+ if max_workers <= 0:
350
+ raise ValueError("max_workers must be a positive integer")
351
+
352
+
353
+ def main(argv: list[str] | None = None) -> int:
354
+ """Run the command-line interface and return its exit status."""
355
+ try:
356
+ args = _parse_args(argv)
357
+ except SystemExit as error:
358
+ return error.code if isinstance(error.code, int) else 1
359
+
360
+ token: str | None = None
361
+ try:
362
+ token = resolve_token(args.token)
363
+ _validate_client_settings(args.timeout, args.max_workers)
364
+ client = GitHubExtractor(
365
+ token,
366
+ timeout=args.timeout,
367
+ max_workers=args.max_workers,
368
+ max_pages=getattr(args, "max_pages", None),
369
+ api_root=getattr(args, "api_root", API_ROOT),
370
+ )
371
+ payload = dispatch(client, args)
372
+ redaction = _redaction_tokens(token)
373
+ try:
374
+ serialized = json.dumps(to_jsonable(payload), indent=2)
375
+ except (TypeError, ValueError) as error:
376
+ print(_redact(str(error), redaction), file=sys.stderr)
377
+ return 1
378
+ print(_redact(serialized, redaction))
379
+ except Exception as error: # noqa: BLE001
380
+ _print_error(error, token)
381
+ return _exit_code(error)
382
+
383
+ return 0