ghapi 2.1.3__tar.gz → 2.1.4__tar.gz

{ghapi-2.1.3/ghapi.egg-info → ghapi-2.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ghapi
-Version: 2.1.3
+Version: 2.1.4
 Summary: A python client for the GitHub API
 Author-email: Jeremy Howard <info@fast.ai>
 License: Apache-2.0
@@ -15,8 +15,8 @@ Classifier: Programming Language :: Python :: 3 :: Only
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: fastcore>=2.2.7
-Requires-Dist: fastspec>=0.2.1
+Requires-Dist: fastcore>=2.2.23
+Requires-Dist: fastspec>=0.2.5
 Requires-Dist: fasttransport>=0.0.2
 Requires-Dist: tomli; python_version < "3.11"
 Provides-Extra: dev
@@ -27,7 +27,7 @@ Requires-Dist: nbdev; extra == "dev"
 Requires-Dist: pyyaml; extra == "dev"
 Requires-Dist: pysym2md>=0.0.6; extra == "dev"
 Requires-Dist: llms-txt>=0.0.6; extra == "dev"
-Requires-Dist: pyskills; extra == "dev"
+Requires-Dist: pyskills>=0.0.30; extra == "dev"
 Dynamic: license-file
 
 # ghapi
@@ -154,7 +154,7 @@ api.git
 - [git.create_tree](https://docs.github.com/rest/git/trees#create-a-tree)(owner, repo, tree, base_tree): *Create a tree*
 - [git.get_tree](https://docs.github.com/rest/git/trees#get-a-tree)(owner, repo, tree_sha, recursive): *Get a tree*
 
-Here’s how to learn about an endpoint you want to use, e.g.:
+Read an endpoint’s full documentation on the generated object. Its display includes parameter descriptions, bound defaults, request controls, and async usage. With pyskills, use `doc(api.git.get_ref)` for the same documentation, or `xdir(api.git, 'ref')` to search names. Construction and discovery send no requests:
 
 ``` python
 api.git.get_ref

{ghapi-2.1.3 → ghapi-2.1.4}/README.md

@@ -122,7 +122,7 @@ api.git
 - [git.create_tree](https://docs.github.com/rest/git/trees#create-a-tree)(owner, repo, tree, base_tree): *Create a tree*
 - [git.get_tree](https://docs.github.com/rest/git/trees#get-a-tree)(owner, repo, tree_sha, recursive): *Get a tree*
 
-Here’s how to learn about an endpoint you want to use, e.g.:
+Read an endpoint’s full documentation on the generated object. Its display includes parameter descriptions, bound defaults, request controls, and async usage. With pyskills, use `doc(api.git.get_ref)` for the same documentation, or `xdir(api.git, 'ref')` to search names. Construction and discovery send no requests:
 
 ``` python
 api.git.get_ref

ghapi-2.1.4/ghapi/__init__.py

@@ -0,0 +1,8 @@
+"""A python client for the GitHub API
+
+Modules:
+
+- `ghapi.graphql`: Query GitHub's GraphQL API with schema-aware chaining, batched requests and raw GraphQL
+- `ghapi.skill`: GitHub REST and GraphQL access, plus local git operations. Read before working with GitHub issues, PRs, CI, releases, branches, or gists, and before repo-local git operations."""
+
+__version__ = "2.1.4"

{ghapi-2.1.3 → ghapi-2.1.4}/ghapi/_modidx.py

@@ -90,10 +90,11 @@ d = { 'settings': { 'branch': 'main',
                             'ghapi.core._age': ('core.html#_age', 'ghapi/core.py'),
                             'ghapi.core._dur': ('core.html#_dur', 'ghapi/core.py'),
                             'ghapi.core._filter_diff': ('core.html#_filter_diff', 'ghapi/core.py'),
-                            'ghapi.core._find_matches': ('core.html#_find_matches', 'ghapi/core.py'),
                             'ghapi.core._fmt_replies': ('core.html#_fmt_replies', 'ghapi/core.py'),
                             'ghapi.core._include': ('core.html#_include', 'ghapi/core.py'),
                             'ghapi.core._listed': ('core.html#_listed', 'ghapi/core.py'),
+                            'ghapi.core._load_tmpl': ('core.html#_load_tmpl', 'ghapi/core.py'),
+                            'ghapi.core._parse_section': ('core.html#_parse_section', 'ghapi/core.py'),
                             'ghapi.core._parse_tmpl': ('core.html#_parse_tmpl', 'ghapi/core.py'),
                             'ghapi.core._pr_mark': ('core.html#_pr_mark', 'ghapi/core.py'),
                             'ghapi.core._reduce_ctx': ('core.html#_reduce_ctx', 'ghapi/core.py'),

{ghapi-2.1.3 → ghapi-2.1.4}/ghapi/core.py

@@ -5,8 +5,8 @@ Docs: https://ghapi.fast.ai/core.html.md"""
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/00_core.ipynb.
 
 # %% auto #0
-__all__ = ['GH_HOST', 'pspec', 'img_md_pat', 'EMPTY_TREE_SHA', 'MAXLEN', 'GhTransport', 'GhSyncTransport', 'print_summary',
-           'gh_patch', 'GhApi', 'call_gh', 'date2gh', 'gh2date', 'GhRows', 'delete_release', 'create_release',
+__all__ = ['GH_HOST', 'pspec', 'img_md_pat', 'EMPTY_TREE_SHA', 'MAXLEN', 'print_summary', 'GhTransport', 'GhSyncTransport',
+           'gh_patch', 'GhApi', 'call_gh', 'date2gh', 'gh2date', 'GhRows', 'create_release', 'delete_release',
            'list_tags', 'list_branches', 'create_branch_empty', 'delete_tag', 'delete_branch', 'get_branch',
            'commit_tree', 'list_files', 'get_content', 'create_or_update_file', 'create_file', 'delete_file',
            'update_contents', 'enable_pages', 'read_issue', 'read_pr', 'pr_file_diff', 'PullRow', 'PullRows',
@@ -42,9 +42,17 @@ _all_ = ['APIError']
 GH_HOST = os.getenv('GH_HOST', "https://api.github.com")
 _DOC_URL = 'https://docs.github.com/'
 
+_docroot = 'https://docs.github.com/rest/reference/'
+
 # %% ../nbs/00_core.ipynb #ba730c65
 pspec = SpecParser.from_dict(spec)
 
+# %% ../nbs/00_core.ipynb #f361159b
+def print_summary(method, url, kwargs):
+    "Debug callback for `GhApi(debug=...)`: print each request with the token (if any) removed"
+    hdrs = {k:v for k,v in (kwargs.get('headers') or {}).items() if k.lower()!='authorization'}
+    print(method, url, {**kwargs, 'headers':hdrs})
+
 # %% ../nbs/00_core.ipynb #d4a51c1a
 _binary_cts = ('octet-stream', 'zip', 'gzip', 'tar', 'image/', 'audio/', 'video/')
 
@@ -89,15 +97,6 @@ class GhSyncTransport(SyncTransport, GhTransport):
         self._pre(method, url, kwargs)
         return self._post(SyncTransport.request(self, method, url, raw=True, **kwargs), raw)
 
-# %% ../nbs/00_core.ipynb #531aee7d
-_docroot = 'https://docs.github.com/rest/reference/'
-
-# %% ../nbs/00_core.ipynb #f361159b
-def print_summary(method, url, kwargs):
-    "Debug callback for `GhApi(debug=...)`: print each request with the token (if any) removed"
-    hdrs = {k:v for k,v in (kwargs.get('headers') or {}).items() if k.lower()!='authorization'}
-    print(method, url, {**kwargs, 'headers':hdrs})
-
 # %% ../nbs/00_core.ipynb #cecd0177
 _gh_override = ContextVar('_gh_override', default={})
 
@@ -120,8 +119,20 @@ def gh_patch(fn):
 # %% ../nbs/00_core.ipynb #83e8a9ce
 class GhApi(OpenAPIClient):
     "GitHub API client. Endpoint groups (`issues`, `pulls`, ...) are generated per-instance from GitHub's OpenAPI metadata, so the class shows only convenience methods -- inspect a live instance, e.g. `doc(GhApi())`, to see the full API."
-    def __init__(self, owner=None, repo=None, token=None, jwt_token=None, debug=None, limit_cb=None, gh_host=None,  # chkstyle: ignore-node
-                 authenticate=True, timeout=60.0, sync=False, **kwargs):
+    def __init__(self,
+        owner=None, # Default repository owner; endpoint calls can override it
+        repo=None, # Default repository name; endpoint calls can override it
+        token=None, # Personal access token; otherwise GITHUB_TOKEN
+        jwt_token=None, # JWT; otherwise GITHUB_JWT_TOKEN; takes precedence over token
+        debug=None, # Request callback (method, url, kwargs); print_summary omits authorization
+        limit_cb=None, # Callback (remaining, quota) when rate-limit headers change
+        gh_host=None, # API base URL; otherwise GH_HOST
+        authenticate=True, # False skips credentials; missing credentials otherwise warn and remain unauthenticated
+        timeout=60.0, # Request timeout in seconds
+        sync=False, # Generated endpoints block instead of returning awaitables; async convenience methods still need an async client
+        **kwargs # Additional default route/query parameters
+    ):
+        "Construct the generated API locally; no request is made until an operation is called"
         self.headers = { 'Accept': 'application/vnd.github.v3+json' }
         if authenticate:
             token = token or os.getenv('GITHUB_TOKEN', None)
@@ -139,14 +150,6 @@ class GhApi(OpenAPIClient):
         self.groups = mk_groups(self.ops)
         for k,v in self.groups.items(): setattr(self, k, v)
 
-    def __call__(self, path:str, verb:str=None, headers:dict=None, route:dict=None, query:dict=None, data=None):
-        "Call a fully specified `path` (or full URL) using HTTP `verb` directly (returns an awaitable on an async client)"
-        if verb is None: verb = 'POST' if data else 'GET'
-        if route: path = path.format(**{k:quote(str(v), safe='') for k,v in route.items()})
-        if not path.startswith(('http://', 'https://')): path = self.gh_host + path
-        kw = dict(content=data) if isinstance(data, (bytes,str)) else dict(json=data)
-        return self.transport.request(verb, path, headers=headers, params=query, **kw)
-
     @property
     def debug(self): return self.transport.debug
     @debug.setter
@@ -158,10 +161,24 @@ class GhApi(OpenAPIClient):
 
     def _repr_markdown_(self): return "\n".join(f"- [{o}]({_docroot + o.replace('_', '-')})" for o in sorted(self.groups))
 
-    def __getitem__(self, k):
-        "Lookup an endpoint by path and verb (which defaults to 'GET')"
-        a,b = k if isinstance(k,tuple) else (k,'GET')
-        return self.func_dict[f'{a}:{b.upper()}']
+
+# %% ../nbs/00_core.ipynb #5ba617de
+@patch
+def __call__(self:GhApi, path:str, verb:str=None, headers:dict=None, route:dict=None, query:dict=None, data=None):
+    "Call a fully specified `path` (or full URL) using HTTP `verb` directly (returns an awaitable on an async client)"
+    if verb is None: verb = 'POST' if data else 'GET'
+    if route: path = path.format(**{k:quote(str(v), safe='') for k,v in route.items()})
+    if not path.startswith(('http://', 'https://')): path = self.gh_host + path
+    kw = dict(content=data) if isinstance(data, (bytes,str)) else dict(json=data)
+    return self.transport.request(verb, path, headers=headers, params=query, **kw)
+
+
+# %% ../nbs/00_core.ipynb #2f980e70
+@patch
+def __getitem__(self:GhApi, k):
+    "Lookup an endpoint by path and verb (which defaults to 'GET')"
+    a,b = k if isinstance(k,tuple) else (k,'GET')
+    return self.func_dict[f'{a}:{b.upper()}']
 
 # %% ../nbs/00_core.ipynb #562eee39
 def call_gh(op:str, *args, token=None, **kwargs):
@@ -172,12 +189,13 @@ def call_gh(op:str, *args, token=None, **kwargs):
 
 # %% ../nbs/00_core.ipynb #05cbdf91
 def date2gh(dt:datetime)->str:
-    "Convert `dt` (which is assumed to be in UTC time zone) to a format suitable for GitHub API operations"
-    return f'{dt.replace(microsecond=0).isoformat()}Z'
+    "Convert `dt` to GitHub's UTC timestamp format; naive datetimes are assumed UTC"
+    if dt.tzinfo is not None: dt = dt.astimezone(timezone.utc)
+    return f'{dt.replace(tzinfo=None, microsecond=0).isoformat()}Z'
 
 # %% ../nbs/00_core.ipynb #3f4c8b27
 def gh2date(dtstr:str)->datetime:
-    "Convert date string `dtstr` received from a GitHub API operation to a UTC `datetime`"
+    "Convert a GitHub UTC date string to a naive UTC `datetime`"
     return datetime.fromisoformat(dtstr.replace('Z', ''))
 
 # %% ../nbs/00_core.ipynb #7876622c
@@ -231,13 +249,6 @@ async def update_gist(self:GhApi, gist_id:str, content:str):
     fname = first(gist.files.keys())
     return (await self.gists.update(gist_id, files={fname: {'content': content}})).html_url
 
-# %% ../nbs/00_core.ipynb #4b7a278c
-@gh_patch
-async def delete_release(self:GhApi, release):
-    "Delete a release and its associated tag"
-    await self.repos.delete_release(release.id)
-    await self.git.delete_ref(f'tags/{release.tag_name}')
-
 # %% ../nbs/00_core.ipynb #b2bf7e22
 @patch
 async def upload_file(self:GhApi, rel, fn):
@@ -247,17 +258,23 @@ async def upload_file(self:GhApi, rel, fn):
     mime = mimetypes.guess_type(fn, False)[0] or 'application/octet-stream'
     return await self(url, 'POST', headers={'Content-Type':mime}, query = {'name':fn.name}, data=fn.read_bytes())
 
-# %% ../nbs/00_core.ipynb #3cad71a4
 @gh_patch
 async def create_release(self:GhApi, tag_name, branch=None, name=None, body='',
-    draft=False, prerelease=False, files=None, make_latest=UNSET):
+    draft=False, prerelease=False, files=None, make_latest=UNSET, generate_release_notes=UNSET):
     "Wrapper for `GhApi.repos.create_release` which also uploads `files`; `branch` defaults to the repo's default branch"
     if name is None: name = 'v'+tag_name
     rel = await self.repos.create_release(tag_name, target_commitish=branch or UNSET, name=name, body=body,
-        draft=draft, prerelease=prerelease, make_latest=make_latest)
+        draft=draft, prerelease=prerelease, make_latest=make_latest, generate_release_notes=generate_release_notes)
     for file in listify(files): await self.upload_file(rel, file)
     return rel
 
+# %% ../nbs/00_core.ipynb #4b7a278c
+@gh_patch
+async def delete_release(self:GhApi, release):
+    "Delete a release and its associated tag"
+    await self.repos.delete_release(release.id)
+    await self.git.delete_ref(f'tags/{release.tag_name}')
+
 # %% ../nbs/00_core.ipynb #2be73ae0
 @gh_patch
 async def list_tags(self:GhApi, prefix:str=''):
@@ -341,7 +358,6 @@ async def create_or_update_file(self:GhApi, path, message, committer, author, co
     return await self.repos.create_or_update_file_contents(path, message, content=content,
         branch=branch, committer=committer or {}, author=author or {}, **kwargs)
 
-# %% ../nbs/00_core.ipynb #5044445d
 @gh_patch
 async def create_file(self:GhApi, path, message, committer, author, content=None, branch=None):
     if not branch: branch = (await self.repos.get())['default_branch']
@@ -351,21 +367,16 @@ async def create_file(self:GhApi, path, message, committer, author, content=None
 @gh_patch
 async def delete_file(self:GhApi, path, message, committer, author, sha=None, branch=None):
     if not branch: branch = (await self.repos.get())['default_branch']
-    if sha is None: sha = (await self.list_files())[path].sha
+    if sha is None: sha = (await self.list_files(branch))[path].sha
     return await self.repos.delete_file(path, message=message, sha=sha, branch=branch, committer=committer, author=author)
 
 # %% ../nbs/00_core.ipynb #93f6b559
 @gh_patch
 async def update_contents(self:GhApi, path, message, committer, author, content, sha=None, branch=None):
     if not branch: branch = (await self.repos.get())['default_branch']
-    if sha is None: sha = (await self.list_files())[path].sha
+    if sha is None: sha = (await self.list_files(branch))[path].sha
     return await self.create_or_update_file(path, message, committer=committer, author=author, content=content, sha=sha, branch=branch)
 
-# %% ../nbs/00_core.ipynb #444784ce
-def _find_matches(path, pats):
-    "Returns matched patterns"
-    return L(pats).filter(lambda p: fnmatch.fnmatch(path, p))
-
 # %% ../nbs/00_core.ipynb #9ffb3b8f
 def _include(path, include, exclude):
     "Returns True if path matches include patterns (if any) and doesn't match any exclude pattern."
@@ -391,7 +402,6 @@ async def get_file_content(self:GhApi, path, owner, repo, branch="main"):
     o['content_decoded'] = base64.b64decode(o.content).decode('utf-8')
     return o
 
-# %% ../nbs/00_core.ipynb #d02d1bab
 @patch
 @delegates(GhApi.get_repo_files)
 async def get_repo_contents(self:GhApi, owner, repo, branch='main',
@@ -427,12 +437,15 @@ class _IssueInfo(AttrDict):
 
 @gh_patch
 async def read_issue(self:GhApi, issue_number:int):
-    "Fetch an issue or PR: title, body, comments, and (for PRs) diff, review comments, and reviews"
+    """Fetch an issue or PR as structured data with a compact display.
+
+    Fields include `title`, `body`, `is_pr`, and general `comments`. PRs also have the full `diff`, inline `review_comments`, and `reviews`. Display the result bare for the summary; inspect those fields for detail. General PR comments use the Issues API, not the Pulls review API.
+    """
     try: pr = await self.pulls.get(issue_number)
     except APIError: pr = None
     iss = await self.issues.get(issue_number)
-    res = dict(title=iss.title, body=iss.body or '', is_pr=pr is not None,  # chkstyle: ignore-node
-               comments=await self.issues.list_comments(issue_number))
+    res = dict(title=iss.title, body=iss.body or '', is_pr=pr is not None,
+        comments=await self.issues.list_comments(issue_number))
     if pr is not None:
         res['diff'] = await self.pulls.get(issue_number, headers_={'Accept': 'application/vnd.github.v3.diff'})
         res['review_comments'] = await self.pulls.list_review_comments(issue_number)
@@ -447,9 +460,9 @@ async def read_issue(self:GhApi, issue_number:int):
 def _filter_diff(diff, folder='', skip_files=('_modidx.py',)):
     "Filter unified diff to only include files under `folder`, skipping `skip_files`"
     sections = re.split(r'(?=^diff --git )', diff, flags=re.MULTILINE)
-    return ''.join(s for s in sections  # chkstyle: ignore-node
-                   if s.startswith(f'diff --git a/{folder}')
-                   and not any(f'/{f} ' in s.split('\n')[0] for f in skip_files))
+    return ''.join(s for s in sections
+        if s.startswith(f'diff --git a/{folder}')
+        and not any(f'/{f} ' in s.split('\n')[0] for f in skip_files))
 
 def _reduce_ctx(diff):
     "Keep only diff headers and changed lines"
@@ -527,6 +540,7 @@ class PullRow(AttrDict):
     def line(self, maxlen=MAXLEN): return f'#{self.number}  {_age(self.updated_at)}  {_pr_mark(self)}{truncstr(self.title, maxlen)}'
     __repr__ = line
 
+# %% ../nbs/00_core.ipynb #21b48014
 class PullRows(GhRows):
     "Pull request rows, displayed with titles truncated to `maxlen`"
     def __init__(self, items, maxlen=MAXLEN):
@@ -546,18 +560,26 @@ async def list_prs(
     prs = await self.pulls.list(state=state, sort='updated', direction='desc', per_page=per_page, page=page)
     return PullRows([PullRow(o) for o in prs], maxlen=maxlen)
 
+# %% ../nbs/00_core.ipynb #c74057c8
+def _parse_section(b):
+    attrs = b['attributes']
+    options = [o['label'] if isinstance(o, dict) else o for o in attrs.get('options', [])]
+    return dict(label=attrs['label'], type=b['type'], required=bool(nested_idx(b, 'validations', 'required')), options=options)
+
+
 # %% ../nbs/00_core.ipynb #55a976ea
 def _parse_tmpl(name, txt):
     "Parse issue template `txt`: yml forms into section labels for `issue_body`; md templates kept as `raw`"
     if not name.endswith(('.yml','.yaml')): return dict2obj(dict(name=name, raw=txt))
     import yaml
     d = yaml.safe_load(txt)
-    secs = [dict(label=b['attributes']['label'], type=b['type'],  # chkstyle: ignore-node
-                 required=bool(nested_idx(b, 'validations', 'required')),
-                 options=[o['label'] if isinstance(o, dict) else o for o in b['attributes'].get('options', [])])
-            for b in d.get('body', []) if b['type']!='markdown']
+    secs = [_parse_section(b) for b in d.get('body', []) if b['type']!='markdown']
     return dict2obj(dict(name=name, title=d.get('name'), description=d.get('description'), sections=secs))
 
+async def _load_tmpl(api, f, **kw):
+    txt = (await api.get_content(f.path, **kw)).decode()
+    return _parse_tmpl(f.name, txt)
+
 @gh_patch
 async def issue_template(self:GhApi):
     "Parsed issue templates for the repo (or the owner's `.github` repo as fallback); pass one to `issue_body`"
@@ -567,8 +589,8 @@ async def issue_template(self:GhApi):
         except APIError as e:
             if e.status_code != 404: raise
             continue
-        return L([_parse_tmpl(f.name, base64.b64decode((await self.repos.get_content(path=f.path, **kw)).content).decode())  # chkstyle: ignore-node
-                  for f in fs if f.name.endswith(('.md','.yml','.yaml')) and f.name != 'config.yml'])
+        return L([await _load_tmpl(self, f, **kw) for f in fs
+            if f.name.endswith(('.md','.yml','.yaml')) and f.name != 'config.yml'])
     return L()
 
 # %% ../nbs/00_core.ipynb #173fc534
@@ -598,6 +620,7 @@ class CheckRun(AttrDict):
 class CommitStatus(AttrDict):
     def __repr__(self): return f'{self.context}: {self.state}'
 
+# %% ../nbs/00_core.ipynb #6a9289a9
 class _CheckStatus(AttrDict):
     def _repr_markdown_(self):
         runs = self.check_runs
@@ -610,7 +633,10 @@ class _CheckStatus(AttrDict):
 
 @gh_patch
 async def check_status(self:GhApi, ref:str):
-    "Combined commit status and check-run results for `ref` (a SHA, branch, or tag)"
+    """Combined commit status and check-run results for `ref` (a SHA, branch, or tag).
+
+    Display the result bare for the check-run verdict and all run/status rows. `.state` comes only from legacy commit statuses and can be pending even when every Actions check passed. `.check_runs` and `.statuses` retain the structured rows.
+    """
     combined = await self.repos.get_combined_status_for_ref(ref)
     checks = await self.checks.list_for_ref(ref)
     return _CheckStatus(dict(state=combined.state, statuses=GhRows(CommitStatus(o) for o in combined.statuses),
@@ -624,7 +650,10 @@ async def pr_status(self:GhApi, pull_number:int):
 # %% ../nbs/00_core.ipynb #569864f5
 @gh_patch
 async def failed_step_log(self:GhApi, job_id:int):
-    "Log sections of `job_id`'s failed steps, each headed by its step name"
+    """Return the failed steps' log sections, each headed by its step name.
+
+    An Actions check run's id is its job id. Pass that id from `check_status` or `pr_status`. The returned text's display is truncated at 8,000 characters. GitHub can expire or delete stored logs.
+    """
     job = await self.actions.get_job_for_workflow_run(job_id=job_id)
     zf = zipfile.ZipFile(io.BytesIO(await self.actions.download_workflow_run_logs(run_id=job.run_id)))
     res = []