changelet 0.1.0__tar.gz

changelet-0.1.0/LICENSE

@@ -0,0 +1,25 @@
+MIT License
+
+Copyright (c) 2021 Ross McFarland & the octoDNS Maintainers
+Copyright (c) 2017 GitHub, Inc.
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

changelet-0.1.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: changelet
+Version: 0.1.0
+Summary:  ChangeLog and Release Management Tooling
+Home-page: https://github.com/octodns/changelet
+Author: Ross McFarland
+Author-email: rwmcfa1@gmail.com
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYaml
+Requires-Dist: semver>=3.0.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pytest-network; extra == "dev"
+Requires-Dist: black<25.0.0,>=24.3.0; extra == "dev"
+Requires-Dist: build>=0.7.0; extra == "dev"
+Requires-Dist: isort>=5.11.5; extra == "dev"
+Requires-Dist: pyflakes>=2.2.0; extra == "dev"
+Requires-Dist: readme_renderer[md]>=26.0; extra == "dev"
+Requires-Dist: twine>=3.4.2; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Requires-Dist: pytest-network; extra == "test"
+Dynamic: author
+Dynamic: author-email
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+## ChangeLog and Release Management Tooling
+
+A simple standalone Python module for CHANGELOG and release management. Spun out of [octoDNS](https://github.com/octodns/octodns/).
+
+### Installation
+
+#### Command line
+
+```console
+pip install changelet
+```
+
+### Usage
+
+For help with using the command
+
+```console
+changelet --help
+```
+
+In most cases the only command you're likely to encounter is `create`. It will be used to add a changelog entry to your branch/PR.
+
+```console
+changelet create --type (TYPE) Short description of your change to be included in the changelog
+```
+
+The options for type are
+* `major` - rare for non-maintainers, a change that will break backwards compatibility and require users to take care when updating
+* `minor` - adds new functionality that is either self contained or done in a completely backwards compatible manner
+* `patch` - fixes an issue or bug with existing functionality
+* `none` - change that should not be included in the CHANGELOG and will not directly impact users, e.g. documentation, README, tooling, ...
+
+### Using changlet
+
+Currently the tooling has only been tested with repositories in the octoDNS org, but it should be usable elsewhere. You'll want to have a look at the following for how to incorporate it into your repo and workflows.
+
+* [script/changelog](script/changelog)
+* [.git_hooks_pre-commit](.git_hooks_pre-commit) (and [script/bootstrap](script/bootstrap) which installs it)
+* [.github/workflows/changelog.yml](.github/workflows/changelog.yml)
+
+### Development
+
+See the [/script/](/script/) directory for some tools to help with the development process. They generally follow the [Script to rule them all](https://github.com/github/scripts-to-rule-them-all) pattern. Most useful is `./script/bootstrap` which will create a venv and install both the runtime and development related requirements. It will also hook up a pre-commit hook that covers most of what's run by CI.

changelet-0.1.0/README.md

@@ -0,0 +1,43 @@
+## ChangeLog and Release Management Tooling
+
+A simple standalone Python module for CHANGELOG and release management. Spun out of [octoDNS](https://github.com/octodns/octodns/).
+
+### Installation
+
+#### Command line
+
+```console
+pip install changelet
+```
+
+### Usage
+
+For help with using the command
+
+```console
+changelet --help
+```
+
+In most cases the only command you're likely to encounter is `create`. It will be used to add a changelog entry to your branch/PR.
+
+```console
+changelet create --type (TYPE) Short description of your change to be included in the changelog
+```
+
+The options for type are
+* `major` - rare for non-maintainers, a change that will break backwards compatibility and require users to take care when updating
+* `minor` - adds new functionality that is either self contained or done in a completely backwards compatible manner
+* `patch` - fixes an issue or bug with existing functionality
+* `none` - change that should not be included in the CHANGELOG and will not directly impact users, e.g. documentation, README, tooling, ...
+
+### Using changlet
+
+Currently the tooling has only been tested with repositories in the octoDNS org, but it should be usable elsewhere. You'll want to have a look at the following for how to incorporate it into your repo and workflows.
+
+* [script/changelog](script/changelog)
+* [.git_hooks_pre-commit](.git_hooks_pre-commit) (and [script/bootstrap](script/bootstrap) which installs it)
+* [.github/workflows/changelog.yml](.github/workflows/changelog.yml)
+
+### Development
+
+See the [/script/](/script/) directory for some tools to help with the development process. They generally follow the [Script to rule them all](https://github.com/github/scripts-to-rule-them-all) pattern. Most useful is `./script/bootstrap` which will create a venv and install both the runtime and development related requirements. It will also hook up a pre-commit hook that covers most of what's run by CI.

changelet-0.1.0/changelet/__init__.py

@@ -0,0 +1,5 @@
+#
+#
+#
+
+__version__ = __VERSION__ = '0.1.0'

changelet-0.1.0/changelet/command/__init__.py

@@ -0,0 +1,18 @@
+#
+#
+#
+
+from .bump import Bump
+from .check import Check
+from .create import Create
+
+commands = {}
+
+
+def register(klass):
+    commands[klass.name] = klass()
+
+
+register(Bump)
+register(Check)
+register(Create)

changelet-0.1.0/changelet/command/bump.py

@@ -0,0 +1,134 @@
+#
+#
+#
+
+from datetime import datetime
+from importlib import import_module
+from io import StringIO
+from os.path import abspath, basename, join
+from sys import exit, path
+
+from semver import Version
+
+from changelet.entry import Entry
+
+
+def _get_current_version(module_name, directory='.'):
+    path.append(directory)
+    module = import_module(module_name)
+    return Version.parse(module.__version__)
+
+
+def _get_new_version(current_version, entries):
+    try:
+        bump_type = entries[0].type
+    except IndexError:
+        return None
+    if bump_type == 'major':
+        return current_version.bump_major()
+    elif bump_type == 'minor':
+        return current_version.bump_minor()
+    elif bump_type == 'patch':
+        return current_version.bump_patch()
+    return None
+
+
+def version(value):
+    return Version.parse(value)
+
+
+class Bump:
+    name = 'bump'
+    description = (
+        'Builds a changelog update and calculates a new version number.'
+    )
+
+    def configure(self, parser):
+        parser.add_argument(
+            '--version',
+            type=version,
+            required=False,
+            help='Use the supplied version number for the bump',
+        )
+        parser.add_argument(
+            '--make-changes',
+            action='store_true',
+            help='Write changelog update and bump version number',
+        )
+        parser.add_argument(
+            'title', nargs='*', help='A short title/quip for the release title'
+        )
+
+    def exit(self, code):
+        exit(code)
+
+    def run(self, args, config, root='.'):
+        buf = StringIO()
+
+        module_name = basename(abspath(root)).replace('-', '_')
+
+        buf.write('## ')
+        current_version = _get_current_version(module_name)
+
+        entries = sorted(Entry.load_all(config), reverse=True)
+
+        new_version = (
+            args.version
+            if args.version
+            else _get_new_version(current_version, entries)
+        )
+        if not new_version:
+            print('No changelog entries found that would bump, nothing to do')
+            return self.exit(1)
+        buf.write(str(new_version))
+        buf.write(' - ')
+        buf.write(datetime.now().strftime('%Y-%m-%d'))
+        if args.title:
+            buf.write(' - ')
+            buf.write(' '.join(args.title))
+        buf.write('\n')
+
+        current_type = None
+        for entry in entries:
+            type = entry.type
+            if type == 'none':
+                # these aren't included in the listing
+                continue
+            if type != current_type:
+                buf.write('\n')
+                buf.write(type.capitalize())
+                buf.write(':\n')
+                current_type = type
+            buf.write(entry.markdown)
+
+            buf.write('\n')
+
+        buf.write('\n')
+
+        buf = buf.getvalue()
+        if not args.make_changes:
+            print(f'New version number {new_version}\n')
+            print(buf)
+            self.exit(0)
+        else:
+            changelog = join(root, 'CHANGELOG.md')
+            with open(changelog) as fh:
+                existing = fh.read()
+
+            with open(changelog, 'w') as fh:
+                fh.write(buf)
+                fh.write(existing)
+
+            init = join(root, module_name, '__init__.py')
+            with open(init) as fh:
+                existing = fh.read()
+
+            with open(init, 'w') as fh:
+                fh.write(
+                    existing.replace(str(current_version), str(new_version))
+                )
+
+            for entry in entries:
+                entry.remove()
+
+        return new_version, buf

changelet-0.1.0/changelet/command/check.py

@@ -0,0 +1,30 @@
+#
+#
+#
+
+from sys import argv, exit, stderr
+
+
+class Check:
+    name = 'check'
+    description = (
+        'Checks to see if the current branch contains a changelog entry'
+    )
+
+    def configure(self, parser):
+        pass
+
+    def exit(self, code):
+        exit(code)
+
+    def run(self, args, config):
+        if config.provider.changelog_entries_in_branch(
+            root=config.root, directory=config.directory
+        ):
+            return self.exit(0)
+
+        print(
+            f'PR is missing required changelog file, run {argv[0]} create',
+            file=stderr,
+        )
+        self.exit(1)

changelet-0.1.0/changelet/command/create.py

@@ -0,0 +1,74 @@
+#
+#
+#
+
+from os.path import join
+from uuid import uuid4
+
+from changelet.entry import Entry
+
+
+class Create:
+    name = 'create'
+    description = 'Creates a new changelog entry.'
+
+    def configure(self, parser):
+        parser.add_argument(
+            '-t',
+            '--type',
+            choices=('none', 'patch', 'minor', 'major'),
+            required=True,
+            help='''The scope of the change.
+
+* patch - This is a bug fix
+* minor - This adds new functionality or makes changes in a fully backwards
+          compatible way
+* major - This includes substantial new functionality and/or changes that break
+          compatibility and may require careful migration
+* none - This change does not need to be mentioned in the changelog
+
+See https://semver.org/ for more info''',
+        )
+        parser.add_argument(
+            '-p',
+            '--pr',
+            type=int,
+            help='Manually override the PR number for the change, maintainer use only.',
+        )
+        parser.add_argument(
+            '-a',
+            '--add',
+            action='store_true',
+            default=False,
+            help='`git add` the newly created changelog entry',
+        )
+        parser.add_argument(
+            'description',
+            metavar='change-description',
+            nargs='+',
+            help='''A short description of the changes in this PR, suitable as an entry in
+CHANGELOG.md. Should be a single line. Can option include simple markdown formatting
+and links.''',
+        )
+
+    def run(self, args, config):
+        filename = join(config.directory, f'{uuid4().hex}.md')
+        entry = Entry(
+            type=args.type,
+            description=' '.join(args.description),
+            pr=args.pr,
+            filename=filename,
+        )
+        entry.save()
+
+        if args.add:
+            config.provider.add_file(entry.filename)
+            print(
+                f'Created {entry.filename}, it has been staged and should be committed to your branch.'
+            )
+        else:
+            print(
+                f'Created {entry.filename}, it can be further edited and should be committed to your branch.'
+            )
+
+        return entry

changelet-0.1.0/changelet/config.py

@@ -0,0 +1,107 @@
+#
+#
+#
+
+from importlib import import_module
+from os.path import isfile, join
+from sys import version_info
+from typing import TYPE_CHECKING
+
+from yaml import safe_load as yaml_load
+
+# https://pypi.org/project/tomli/#intro
+# based on code in black.file
+if version_info >= (3, 11):  # pragma: no cover
+    try:
+        from tomllib import load as toml_load
+    except ImportError:
+        # Help users on older alphas
+        if not TYPE_CHECKING:
+            from tomli import load as toml_load
+else:  # pragma: no cover
+    from tomli import load as toml_load
+
+
+class Config:
+    DEFAULT_ROOT = ''
+
+    @classmethod
+    def build(cls, **kwargs):
+        # create w/defaults
+        config = Config()
+
+        root = kwargs.get('root', cls.DEFAULT_ROOT)
+
+        # override w/toml, if applicable
+        pyproject_toml_filename = join(root, 'pyproject.toml')
+        if isfile(pyproject_toml_filename):
+            config.load_pyproject_toml(pyproject_toml_filename)
+
+        # explicit yaml file
+        yaml_filename = kwargs.get('config')
+        if not yaml_filename:
+            # default yaml file
+            yaml_filename = join(root, '.changelet.yaml')
+        # override w/yaml, if applicable
+        if isfile(yaml_filename):
+            config.load_yaml(yaml_filename)
+
+        # override root w/command line arg, if applicable
+        try:
+            config.root = kwargs['root']
+        except KeyError:
+            pass
+
+        # override directory w/command line arg, if applicable
+        try:
+            config.directory = kwargs['directory']
+        except KeyError:
+            pass
+
+        return config
+
+    def __init__(
+        self,
+        root=DEFAULT_ROOT,
+        directory='.changelog',
+        provider={'class': 'changelet.github.GitHubCli'},
+    ):
+        self.root = root
+        self.directory = directory
+
+        # will instantiate & configure
+        self.provider = provider
+
+    @property
+    def provider(self):
+        if self._provider_config is not None:
+            value = dict(self._provider_config)
+            klass = value.pop('class')
+            if isinstance(klass, str):
+                module, klass = klass.rsplit('.', 1)
+                module = import_module(module)
+                klass = getattr(module, klass)
+            self._provider = klass(**value)
+            self._provider_config = None
+        return self._provider
+
+    @provider.setter
+    def provider(self, value):
+        self._provider_config = value
+
+    def load_pyproject_toml(self, filename):
+        with open(filename, 'rb') as fh:
+            config = toml_load(fh).get('tool', {}).get('changelet')
+            if isinstance(config, dict):
+                for k, v in config.items():
+                    setattr(self, k, v)
+
+    def load_yaml(self, filename=None):
+        with open(filename, 'rb') as fh:
+            config = yaml_load(fh)
+            if isinstance(config, dict):
+                for k, v in config.items():
+                    setattr(self, k, v)
+
+    def __repr__(self):
+        return f'Config<root={self.root}, directory={self.directory}, provider={self.provider}>'

changelet-0.1.0/changelet/entry.py

@@ -0,0 +1,120 @@
+#
+#
+#
+
+from datetime import datetime, timezone
+from enum import Enum
+from os import listdir, makedirs, remove
+from os.path import dirname, isdir, join
+
+from yaml import safe_load
+
+
+class EntryType(Enum):
+    NONE = 'none'
+    PATCH = 'patch'
+    MINOR = 'minor'
+    MAJOR = 'major'
+
+
+class Entry:
+    EPOCH = datetime(1970, 1, 1, tzinfo=timezone.utc)
+    ORDERING = {'major': 3, 'minor': 2, 'patch': 1, 'none': 0, '': 0}
+
+    @classmethod
+    def load(self, filename, config):
+        with open(filename, 'r') as fh:
+            pieces = fh.read().split('---\n')
+            data = safe_load(pieces[1])
+            description = pieces[2]
+            if description[-1] == '\n':
+                description = description[:-1]
+            if 'pr' in data:
+                pr = config.provider.pr_by_id(
+                    root=config.root, directory=config.directory, id=data['pr']
+                )
+            else:
+                pr = config.provider.pr_by_filename(
+                    root=config.root,
+                    directory=config.directory,
+                    filename=filename,
+                )
+            return Entry(
+                filename=filename,
+                type=data['type'],
+                description=description,
+                pr=pr,
+            )
+
+    @classmethod
+    def load_all(cls, config):
+        directory = config.directory
+        entries = []
+        if isdir(directory):
+            for filename in sorted(listdir(directory)):
+                if not filename.endswith('.md'):
+                    continue
+                filename = join(directory, filename)
+                entries.append(Entry.load(filename, config))
+        return entries
+
+    def __init__(self, type, description, pr=None, filename=None):
+        self.type = type
+        self.description = description
+        self.pr = pr
+        self.filename = filename
+
+    @property
+    def _ordering(self):
+        return (
+            self.ORDERING[self.type],
+            self.pr.merged_at if self.pr else self.EPOCH,
+        )
+
+    def save(self, filename=None):
+        if filename is None:
+            filename = self.filename
+        directory = dirname(filename)
+        if not isdir(directory):
+            makedirs(directory)
+        with open(filename, 'w') as fh:
+            fh.write('---\ntype: ')
+            fh.write(self.type)
+            if self.pr:
+                fh.write('\npr: ')
+                fh.write(str(self.pr.id))
+            fh.write('\n---\n')
+            fh.write(self.description)
+        self.filename = filename
+
+    def remove(self):
+        if not self.filename:
+            return False
+        remove(self.filename)
+        return True
+
+    @property
+    def text(self):
+        if self.pr:
+            return f'* {self.description} - {self.pr.plain}'
+        return f'* {self.description}'
+
+    @property
+    def markdown(self):
+        if self.pr:
+            return f'* {self.description} - {self.pr.markdown}'
+        return f'* {self.description}'
+
+    def copy(self):
+        return Entry(
+            type=self.type,
+            description=self.description,
+            pr=self.pr,
+            filename=self.filename,
+        )
+
+    def __lt__(self, other):
+        return self._ordering < other._ordering
+
+    def __repr__(self):
+        return f'Entry<{self.type}, {self.description[:16]}, {self.filename}, {self.pr}>'