changelist 0.1__tar.gz

changelist-0.1/LICENSE.txt

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2023, Scientific Python
+
+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 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 documentation
+   and/or other materials provided with the distribution.
+
+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.

changelist-0.1/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.1
+Name: changelist
+Version: 0.1
+License: BSD 3-Clause License
+        
+        Copyright (c) 2023, Scientific Python
+        
+        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 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 documentation
+           and/or other materials provided with the distribution.
+        
+        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.
+        
+Project-URL: Source, https://github.com/scientific-python/changelist
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: lint
+License-File: LICENSE.txt
+
+# changelist
+
+Prepare an automatic changelog from GitHub pull requests.
+
+_This project is currently in its alpha stage and might be incomplete or change a lot!_
+
+## Installation
+
+```sh
+pip install changelist
+```
+
+## Set up your repository
+
+To categorize merged PRs in the changelist, each PR
+must have have one of the following labels:
+
+- `type: Highlights`
+- `type: New features`
+- `type: Enhancements`
+- `type: Performance`
+- `type: Bug fix`
+- `type: API`
+- `type: Maintenance`
+- `type: Documentation`
+- `type: Infrastructure`
+
+This list will soon be configurable.
+
+### Label checking
+
+To ensure that each PR has an associated `type: ` label,
+we recommend adding an action that fails CI if the label is missing.
+
+To do so, place the following in `.github/workflows/label-check.yaml`:
+
+```yaml
+name: Labels
+
+on:
+  pull_request:
+    types:
+      - opened
+      - labeled
+      - unlabeled
+
+env:
+  LABELS: ${{ join( github.event.pull_request.labels.*.name, ' ' ) }}
+
+jobs:
+  check-type-label:
+    name: ensure type label
+    runs-on: ubuntu-latest
+    steps:
+      - if: "contains( env.LABELS, 'type: ' ) == false"
+        run: exit 1
+```
+
+### Milestones
+
+Often, it is helpful to have milestones that reflect the actual PRs
+merged. We therefore recommend adding an action that attached the
+next open milestone to any merged PR.
+
+To do so, place the following in `.github/workflows/milestone-merged-prs.yaml`:
+
+```yaml
+name: Milestone
+
+on:
+  pull_request_target:
+    types:
+      - closed
+    branches:
+      - "main"
+
+jobs:
+  milestone_pr:
+    name: attach to PR
+    runs-on: ubuntu-latest
+    steps:
+      - uses: scientific-python/attach-next-milestone-action@f94a5235518d4d34911c41e19d780b8e79d42238
+        with:
+          token: ${{ secrets.MILESTONE_LABELER_TOKEN }}
+          force: true
+```
+
+See https://github.com/scientific-python/attach-next-milestone-action for more information.
+
+## Usage
+
+```sh
+export GH_TOKEN='...'
+changelist scikit-image/scikit-image v0.21.0 main
+```
+
+The script requires a [GitHub personal access
+token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens).
+The token does not need any permissions, since it is used only to
+increase query limits.

changelist-0.1/README.md

@@ -0,0 +1,100 @@
+# changelist
+
+Prepare an automatic changelog from GitHub pull requests.
+
+_This project is currently in its alpha stage and might be incomplete or change a lot!_
+
+## Installation
+
+```sh
+pip install changelist
+```
+
+## Set up your repository
+
+To categorize merged PRs in the changelist, each PR
+must have have one of the following labels:
+
+- `type: Highlights`
+- `type: New features`
+- `type: Enhancements`
+- `type: Performance`
+- `type: Bug fix`
+- `type: API`
+- `type: Maintenance`
+- `type: Documentation`
+- `type: Infrastructure`
+
+This list will soon be configurable.
+
+### Label checking
+
+To ensure that each PR has an associated `type: ` label,
+we recommend adding an action that fails CI if the label is missing.
+
+To do so, place the following in `.github/workflows/label-check.yaml`:
+
+```yaml
+name: Labels
+
+on:
+  pull_request:
+    types:
+      - opened
+      - labeled
+      - unlabeled
+
+env:
+  LABELS: ${{ join( github.event.pull_request.labels.*.name, ' ' ) }}
+
+jobs:
+  check-type-label:
+    name: ensure type label
+    runs-on: ubuntu-latest
+    steps:
+      - if: "contains( env.LABELS, 'type: ' ) == false"
+        run: exit 1
+```
+
+### Milestones
+
+Often, it is helpful to have milestones that reflect the actual PRs
+merged. We therefore recommend adding an action that attached the
+next open milestone to any merged PR.
+
+To do so, place the following in `.github/workflows/milestone-merged-prs.yaml`:
+
+```yaml
+name: Milestone
+
+on:
+  pull_request_target:
+    types:
+      - closed
+    branches:
+      - "main"
+
+jobs:
+  milestone_pr:
+    name: attach to PR
+    runs-on: ubuntu-latest
+    steps:
+      - uses: scientific-python/attach-next-milestone-action@f94a5235518d4d34911c41e19d780b8e79d42238
+        with:
+          token: ${{ secrets.MILESTONE_LABELER_TOKEN }}
+          force: true
+```
+
+See https://github.com/scientific-python/attach-next-milestone-action for more information.
+
+## Usage
+
+```sh
+export GH_TOKEN='...'
+changelist scikit-image/scikit-image v0.21.0 main
+```
+
+The script requires a [GitHub personal access
+token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens).
+The token does not need any permissions, since it is used only to
+increase query limits.

changelist-0.1/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["setuptools>=43.0.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "changelist"
+version = "0.1"
+requires-python = ">=3.9"
+readme = "README.md"
+license = {file = "LICENSE.txt"}
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "License :: OSI Approved :: BSD License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3 :: Only",
+]
+
+dependencies = [
+    "requests",
+    "requests-cache",
+    "tqdm",
+    "PyGithub"
+]
+
+[project.urls]
+"Source" = "https://github.com/scientific-python/changelist"
+
+[project.scripts]
+changelist = "changelist.__main__:main"
+
+[project.optional-dependencies]
+lint = ["pre-commit == 3.3.3"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py39"
+select = [
+    "C",
+    "E",
+    "F",
+    "W",
+    "B",
+    "I",
+    "UP",
+]

changelist-0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

changelist-0.1/src/changelist/__main__.py

@@ -0,0 +1,527 @@
+"""Prepare an automatic changelog from GitHub's pull requests."""
+
+
+import argparse
+import json
+import logging
+import os
+import re
+import sys
+import tempfile
+from collections import OrderedDict
+from collections.abc import Iterable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable, Union
+
+import requests
+import requests_cache
+from github import Github
+from github.Commit import Commit
+from github.NamedUser import NamedUser
+from github.PullRequest import PullRequest
+from tqdm import tqdm
+
+logger = logging.getLogger(__name__)
+
+here = Path(__file__).parent
+
+REQUESTS_CACHE_PATH = Path(tempfile.gettempdir()) / "github_cache.sqlite"
+
+GH_URL = "https://github.com"
+
+
+def lazy_tqdm(*args, **kwargs):
+    """Defer initialization of progress bar until first item is requested.
+
+    Calling `tqdm(...)` prints the progress bar right there and then. This can scramble
+    output, if more than one progress bar are initialized at the same time but their
+    iteration is meant to be done later in successive order.
+    """
+    kwargs["file"] = kwargs.get("file", sys.stderr)
+    yield from tqdm(*args, **kwargs)
+
+
+def commits_between(
+    gh: Github, org_name: str, start_rev: str, stop_rev: str
+) -> set[Commit]:
+    """Fetch commits between two revisions excluding the commit of `start_rev`."""
+    repo = gh.get_repo(org_name)
+    comparison = repo.compare(base=start_rev, head=stop_rev)
+    commits = set(comparison.commits)
+    assert repo.get_commit(start_rev) not in commits
+    assert repo.get_commit(stop_rev) in commits
+    return commits
+
+
+def pull_requests_from_commits(commits: Iterable[Commit]) -> set[PullRequest]:
+    """Fetch pull requests that are associated with the given `commits`."""
+    all_pull_requests = set()
+    for commit in commits:
+        commit_pull_requests = list(commit.get_pulls())
+        if len(commit_pull_requests) != 1:
+            logger.info(
+                "%s with no or multiple PR(s): %r",
+                commit.html_url,
+                [p.html_url for p in commit_pull_requests],
+            )
+        if any(not p.merged for p in commit_pull_requests):
+            logger.error(
+                "%s with unmerged PRs: %r",
+            )
+        for pull in commit_pull_requests:
+            if pull in all_pull_requests:
+                # Expected if pull request is merged without squashing
+                logger.debug(
+                    "%r associated with multiple commits",
+                    pull.html_url,
+                )
+        all_pull_requests.update(commit_pull_requests)
+    return all_pull_requests
+
+
+@dataclass(frozen=True, kw_only=True)
+class GitHubGraphQl:
+    """Interface to query GitHub's GraphQL API for a particular repository."""
+
+    org_name: str
+    repo_name: str
+
+    URL: str = "https://api.github.com/graphql"
+    GRAPHQL_AUTHORS: str = """
+    query {{
+      repository (owner: "{org_name}" name: "{repo_name}") {{
+        object(expression: "{commit_sha}" ) {{
+          ... on Commit {{
+            commitUrl
+            authors(first:{page_limit}) {{
+              edges {{
+                cursor
+                node {{
+                  name
+                  email
+                  user {{
+                    login
+                    databaseId
+                  }}
+                }}
+              }}
+            }}
+          }}
+        }}
+      }}
+    }}
+    """
+    PAGE_LIMIT: int = 100
+
+    def _run_query(self, query: str) -> dict:
+        """Fetch results for a GraphQl query."""
+        headers = {"Authorization": f"Bearer {os.environ.get('GH_TOKEN')}"}
+        sanitized_query = json.dumps({"query": query.replace("\n", "")})
+        response = requests.post(self.URL, data=sanitized_query, headers=headers)
+        data = response.json()
+        return data
+
+    def find_authors(self, commit_sha: str) -> dict[int, str]:
+        """Find ID and login of (co-)author(s) for a commit.
+
+        Other than GitHub's REST API, the GraphQL API supports returning all authors,
+        including co-authors, of a commit.
+        """
+        query = self.GRAPHQL_AUTHORS.format(
+            org_name=self.org_name,
+            repo_name=self.repo_name,
+            commit_sha=commit_sha,
+            page_limit=self.PAGE_LIMIT,
+        )
+        data = self._run_query(query)
+        commit = data["data"]["repository"]["object"]
+        edges = commit["authors"]["edges"]
+        if len(edges) == self.PAGE_LIMIT:
+            # TODO implement pagination if this becomes an issue, e.g. see
+            # https://github.com/scientific-python/devstats-data/blob/e3cd826518bf590083409318b0a7518f7781084f/query.py#L92-L107
+            logger.warning(
+                "reached page limit while querying authors in %r, "
+                "only the first %i authors will be included",
+                commit["commitUrl"],
+                self.PAGE_LIMIT,
+            )
+
+        coauthors = {}
+        for _i, edge in enumerate(edges):
+            node = edge["node"]
+            user = node["user"]
+            if user is None:
+                logger.warning(
+                    "could not determine GitHub user for %r in %r",
+                    node,
+                    commit["commitUrl"],
+                )
+                continue
+            coauthors[user["databaseId"]] = user["login"]
+
+        assert coauthors
+        return coauthors
+
+
+def contributors(
+    gh: Github,
+    org_repo: str,
+    commits: Iterable[Commit],
+    pull_requests: Iterable[PullRequest],
+) -> tuple[set[NamedUser], set[NamedUser]]:
+    """Fetch commit authors, co-authors and reviewers.
+
+    `authors` are users which created or co-authored a commit.
+    `reviewers` are users, who added reviews to a merged pull request or merged a
+    pull request (committer of the merge commit).
+    """
+    authors = set()
+    reviewers = set()
+
+    org_name, repo_name = org_repo.split("/")
+    ql = GitHubGraphQl(org_name=org_name, repo_name=repo_name)
+
+    for commit in commits:
+        if commit.author:
+            authors.add(commit.author)
+        if commit.committer:
+            reviewers.add(commit.committer)
+        if "Co-authored-by:" in commit.commit.message:
+            # Fallback on GraphQL API to find co-authors as well
+            user_ids = ql.find_authors(commit.sha)
+            for user_id, user_login in user_ids.items():
+                named_user = gh.get_user_by_id(user_id)
+                assert named_user.login == user_login
+                authors.add(named_user)
+        else:
+            logger.debug("no co-authors in %r", commit.html_url)
+
+    for pull in pull_requests:
+        for review in pull.get_reviews():
+            if review.user:
+                reviewers.add(review.user)
+
+    return authors, reviewers
+
+
+@dataclass(frozen=True, kw_only=True)
+class MdFormatter:
+    """Format release notes in Markdown from PRs, authors and reviewers."""
+
+    repo_name: str
+    pull_requests: set[PullRequest]
+    authors: set[Union[NamedUser]]
+    reviewers: set[NamedUser]
+
+    version: str = "x.y.z"
+    title_template: str = "{repo_name} {version}"
+    intro_template: str = """
+We're happy to announce the release of {repo_name} {version}!
+"""
+    outro_template: str = (
+        "_These lists are automatically generated, and may not be complete or may "
+        "contain duplicates._\n"
+    )
+    # Associate regexes matching PR labels to a section titles in the release notes
+    regex_section_map: tuple[tuple[str, str], ...] = (
+        (".*Highlight.*", "Highlights"),
+        (".*New feature.*", "New Features"),
+        (".*Enhancement.*", "Enhancements"),
+        (".*Performance.*", "Performance"),
+        (".*Bug fix.*", "Bug Fixes"),
+        (".*API.*", "API Changes"),
+        (".*Maintenance.*", "Maintenance"),
+        (".*Documentation.*", "Documentation"),
+        (".*Infrastructure.*", "Infrastructure"),
+    )
+    ignored_user_logins: tuple[str] = ("web-flow",)
+    pr_summary_regex = re.compile(
+        r"^```release-note\s*(?P<summary>[\s\S]*?\w[\s\S]*?)\s*^```", flags=re.MULTILINE
+    )
+
+    def __str__(self) -> str:
+        """Return complete release notes document as a string."""
+        return self.document
+
+    def __iter__(self) -> Iterable[str]:
+        """Iterate the release notes document line-wise."""
+        return self.iter_lines()
+
+    @property
+    def document(self) -> str:
+        """Return complete release notes document as a string."""
+        return "".join(self.iter_lines())
+
+    def iter_lines(self) -> Iterable[str]:
+        """Iterate the release notes document line-wise."""
+        title = self.title_template.format(
+            repo_name=self.repo_name, version=self.version
+        )
+        yield from self._format_section_title(title, level=1)
+        yield from self._format_intro()
+        for title, pull_requests in self._prs_by_section.items():
+            yield from self._format_pr_section(title, pull_requests)
+        yield from self._format_contributor_section(self.authors, self.reviewers)
+        yield from self._format_outro()
+
+    @property
+    def _prs_by_section(self) -> OrderedDict[str, set[PullRequest]]:
+        """Map pull requests to section titles.
+
+        Pull requests whose labels do not match one of the sections given in
+        `regex_section_map`, are sorted into a section named "Other".
+        """
+        label_section_map = {
+            re.compile(pattern): section_name
+            for pattern, section_name in self.regex_section_map
+        }
+        prs_by_section = OrderedDict()
+        for _, section_name in self.regex_section_map:
+            prs_by_section[section_name] = set()
+        prs_by_section["Other"] = set()
+
+        for pr in self.pull_requests:
+            matching_sections = [
+                section_name
+                for regex, section_name in label_section_map.items()
+                if any(regex.match(label.name) for label in pr.labels)
+            ]
+            for section_name in matching_sections:
+                prs_by_section[section_name].add(pr)
+            if not matching_sections:
+                logger.warning(
+                    "%s without matching label, sorting into section 'Other'",
+                    pr.html_url,
+                )
+                prs_by_section["Other"].add(pr)
+
+        return prs_by_section
+
+    def _sanitize_text(self, text: str) -> str:
+        text = text.strip()
+        text = text.replace("\r\n", " ")
+        text = text.replace("\n", " ")
+        return text
+
+    def _format_link(self, name: str, target: str) -> str:
+        return f"[{name}]({target})"
+
+    def _format_section_title(self, title: str, *, level: int) -> Iterable[str]:
+        yield f"{'#' * level} {title}\n"
+
+    def _parse_pull_request_summary(self, pr: PullRequest) -> str:
+        if pr.body and (match := self.pr_summary_regex.search(pr.body)):
+            summary = match["summary"]
+        else:
+            logger.debug("falling back to title for %s", pr.html_url)
+            summary = pr.title
+        summary = self._sanitize_text(summary)
+        return summary
+
+    def _format_pull_request(self, pr: PullRequest) -> Iterable[str]:
+        summary = self._parse_pull_request_summary(pr).rstrip(".")
+        yield f"- {summary}\n"
+        link = self._format_link(f"#{pr.number}", f"{pr.html_url}")
+        yield f"  ({link}).\n"
+
+    def _format_pr_section(
+        self, title: str, pull_requests: set[PullRequest]
+    ) -> Iterable[str]:
+        """Format a section title and list its pull requests sorted by merge date."""
+        if pull_requests:
+            yield from self._format_section_title(title, level=2)
+            for pr in sorted(pull_requests, key=lambda pr: pr.merged_at):
+                yield from self._format_pull_request(pr)
+            yield "\n"
+
+    def _format_user_line(self, user: Union[NamedUser]) -> str:
+        line = f"@{user.login}"
+        line = self._format_link(line, user.html_url)
+        if user.name:
+            line = f"{user.name} ({line})"
+        return line + ",\n"
+
+    def _format_contributor_section(
+        self,
+        authors: set[Union[NamedUser]],
+        reviewers: set[NamedUser],
+    ) -> Iterable[str]:
+        """Format contributor section and list users sorted by login handle."""
+        authors = {u for u in authors if u.login not in self.ignored_user_logins}
+        reviewers = {u for u in reviewers if u.login not in self.ignored_user_logins}
+
+        yield from self._format_section_title("Contributors", level=2)
+        yield "\n"
+
+        yield f"{len(authors)} authors added to this release (alphabetically):\n"
+        author_lines = map(self._format_user_line, authors)
+        yield from sorted(author_lines, key=lambda s: s.lower())
+        yield "\n"
+
+        yield f"{len(reviewers)} reviewers added to this release (alphabetically):\n"
+        reviewers_lines = map(self._format_user_line, reviewers)
+        yield from sorted(reviewers_lines, key=lambda s: s.lower())
+        yield "\n"
+
+    def _format_intro(self):
+        intro = self.intro_template.format(
+            repo_name=self.repo_name, version=self.version
+        )
+        # Make sure to return exactly one line at a time
+        yield from (f"{line}\n" for line in intro.split("\n"))
+
+    def _format_outro(self) -> Iterable[str]:
+        outro = self.outro_template
+        # Make sure to return exactly one line at a time
+        yield from (f"{line}\n" for line in outro.split("\n"))
+
+
+class RstFormatter(MdFormatter):
+    """Format release notes in reStructuredText from PRs, authors and reviewers."""
+
+    def _sanitize_text(self, text) -> str:
+        text = super()._sanitize_text(text)
+        text = text.replace("`", "``")
+        return text
+
+    def _format_link(self, name: str, target: str) -> str:
+        return f"`{name} <{target}>`_"
+
+    def _format_section_title(self, title: str, *, level: int) -> Iterable[str]:
+        yield title + "\n"
+        underline = {1: "=", 2: "-", 3: "~"}
+        yield underline[level] * len(title) + "\n"
+
+
+def parse_command_line(func: Callable) -> Callable:
+    """Define and parse command line options.
+
+    Has no effect if any keyword argument is passed to the underlying function.
+    """
+    parser = argparse.ArgumentParser(usage=__doc__)
+    parser.add_argument(
+        "org_repo",
+        help="Org and repo name of a repository on GitHub (delimited by a slash), "
+        "e.g. 'numpy/numpy'",
+    )
+    parser.add_argument(
+        "start_rev",
+        help="The starting revision (excluded), e.g. the tag of the previous release",
+    )
+    parser.add_argument(
+        "stop_rev",
+        help="The stop revision (included), e.g. the 'main' branch or the current "
+        "release",
+    )
+    parser.add_argument(
+        "--version",
+        default="0.0.0",
+        help="Version you're about to release, used title and description of the notes",
+    )
+    parser.add_argument("--out", help="Write to file, prints to STDOUT otherwise")
+    parser.add_argument(
+        "--format",
+        choices=["rst", "md"],
+        default="md",
+        help="Choose format, defaults to Markdown",
+    )
+    parser.add_argument(
+        "--clear-cache",
+        action="store_true",
+        help="Clear cached requests to GitHub's API before running",
+    )
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="count",
+        default=0,
+        help="Increase logging level",
+    )
+
+    def wrapped(**kwargs):
+        if not kwargs:
+            kwargs = vars(parser.parse_args())
+        return func(**kwargs)
+
+    return wrapped
+
+
+@parse_command_line
+def main(
+    *,
+    org_repo: str,
+    start_rev: str,
+    stop_rev: str,
+    version: str,
+    out: str,
+    format: str,
+    clear_cache: bool,
+    verbose: int,
+):
+    """Main function of the script.
+
+    See :func:`parse_command_line` for a description of the accepted input.
+    """
+    level = {0: logging.WARNING, 1: logging.INFO}.get(verbose, logging.DEBUG)
+    logger.setLevel(level)
+
+    requests_cache.install_cache(
+        REQUESTS_CACHE_PATH, backend="sqlite", expire_after=3600
+    )
+    print(f"Using requests cache at {REQUESTS_CACHE_PATH}", file=sys.stderr)
+    if clear_cache:
+        requests_cache.clear()
+        logger.info("cleared requests cache at %s", REQUESTS_CACHE_PATH)
+
+    gh_token = os.environ.get("GH_TOKEN")
+    if gh_token is None:
+        raise RuntimeError(
+            "You need to set the environment variable `GH_TOKEN`. "
+            "The token is used to avoid rate limiting, "
+            "and can be created at https://github.com/settings/tokens.\n\n"
+            "The token does not require any permissions (we only use the public API)."
+        )
+    gh = Github(gh_token)
+
+    print("Fetching commits...", file=sys.stderr)
+    commits = commits_between(gh, org_repo, start_rev, stop_rev)
+    pull_requests = pull_requests_from_commits(
+        lazy_tqdm(commits, desc="Fetching pull requests")
+    )
+    authors, reviewers = contributors(
+        gh=gh,
+        org_repo=org_repo,
+        commits=lazy_tqdm(commits, desc="Fetching authors"),
+        pull_requests=lazy_tqdm(pull_requests, desc="Fetching reviewers"),
+    )
+
+    Formatter = {"md": MdFormatter, "rst": RstFormatter}[format]
+    formatter = Formatter(
+        repo_name=org_repo.split("/")[-1],
+        pull_requests=pull_requests,
+        authors=authors,
+        reviewers=reviewers,
+        version=version,
+    )
+
+    if out:
+        out_path = Path(out)
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+        with open(out, "w") as io:
+            io.writelines(formatter.iter_lines())
+    else:
+        print()
+        for line in formatter.iter_lines():
+            assert line.endswith("\n")
+            assert line.count("\n") == 1
+            print(line, end="", file=sys.stdout)
+
+
+if __name__ == "__main__":
+    logging.basicConfig(
+        level=logging.WARNING,
+        format="%(levelname)s: %(filename)s::%(funcName)s: %(message)s",
+        stream=sys.stderr,
+    )
+    main()

changelist-0.1/src/changelist.egg-info/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.1
+Name: changelist
+Version: 0.1
+License: BSD 3-Clause License
+        
+        Copyright (c) 2023, Scientific Python
+        
+        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 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 documentation
+           and/or other materials provided with the distribution.
+        
+        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.
+        
+Project-URL: Source, https://github.com/scientific-python/changelist
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: lint
+License-File: LICENSE.txt
+
+# changelist
+
+Prepare an automatic changelog from GitHub pull requests.
+
+_This project is currently in its alpha stage and might be incomplete or change a lot!_
+
+## Installation
+
+```sh
+pip install changelist
+```
+
+## Set up your repository
+
+To categorize merged PRs in the changelist, each PR
+must have have one of the following labels:
+
+- `type: Highlights`
+- `type: New features`
+- `type: Enhancements`
+- `type: Performance`
+- `type: Bug fix`
+- `type: API`
+- `type: Maintenance`
+- `type: Documentation`
+- `type: Infrastructure`
+
+This list will soon be configurable.
+
+### Label checking
+
+To ensure that each PR has an associated `type: ` label,
+we recommend adding an action that fails CI if the label is missing.
+
+To do so, place the following in `.github/workflows/label-check.yaml`:
+
+```yaml
+name: Labels
+
+on:
+  pull_request:
+    types:
+      - opened
+      - labeled
+      - unlabeled
+
+env:
+  LABELS: ${{ join( github.event.pull_request.labels.*.name, ' ' ) }}
+
+jobs:
+  check-type-label:
+    name: ensure type label
+    runs-on: ubuntu-latest
+    steps:
+      - if: "contains( env.LABELS, 'type: ' ) == false"
+        run: exit 1
+```
+
+### Milestones
+
+Often, it is helpful to have milestones that reflect the actual PRs
+merged. We therefore recommend adding an action that attached the
+next open milestone to any merged PR.
+
+To do so, place the following in `.github/workflows/milestone-merged-prs.yaml`:
+
+```yaml
+name: Milestone
+
+on:
+  pull_request_target:
+    types:
+      - closed
+    branches:
+      - "main"
+
+jobs:
+  milestone_pr:
+    name: attach to PR
+    runs-on: ubuntu-latest
+    steps:
+      - uses: scientific-python/attach-next-milestone-action@f94a5235518d4d34911c41e19d780b8e79d42238
+        with:
+          token: ${{ secrets.MILESTONE_LABELER_TOKEN }}
+          force: true
+```
+
+See https://github.com/scientific-python/attach-next-milestone-action for more information.
+
+## Usage
+
+```sh
+export GH_TOKEN='...'
+changelist scikit-image/scikit-image v0.21.0 main
+```
+
+The script requires a [GitHub personal access
+token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens).
+The token does not need any permissions, since it is used only to
+increase query limits.

changelist-0.1/src/changelist.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE.txt
+README.md
+pyproject.toml
+src/changelist/__init__.py
+src/changelist/__main__.py
+src/changelist.egg-info/PKG-INFO
+src/changelist.egg-info/SOURCES.txt
+src/changelist.egg-info/dependency_links.txt
+src/changelist.egg-info/entry_points.txt
+src/changelist.egg-info/requires.txt
+src/changelist.egg-info/top_level.txt

changelist-0.1/src/changelist.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

changelist-0.1/src/changelist.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+changelist = changelist.__main__:main

changelist-0.1/src/changelist.egg-info/requires.txt

@@ -0,0 +1,7 @@
+requests
+requests-cache
+tqdm
+PyGithub
+
+[lint]
+pre-commit==3.3.3

changelist-0.1/src/changelist.egg-info/top_level.txt

@@ -0,0 +1 @@
+changelist