A simple pure-Python module for parsing conventional commits.
Project description
convcom
A simple pure-Python module for parsing V1 of the conventional commits specification.
Install
To install the latest release, run:
$ pip install convcom
To upgrade convcom
to the latest version, add the --upgrade
flag to the above command.
Quickstart
To get started, first open your Python interpreter:
$ python
Now, let's parse our first commit:
>>> from convcom.v1.parse import parse_commit
>>> parse_commit('feat: my new feature!')
ConventionalCommit(header=Header(type='feat', description='my new feature!', scope=None, is_breaking_change=False), body=None, footer=None)
Next, let's do the same thing, but in reverse:
>>> from convcom.v1.types import ConventionalCommit, Header
>>> from convcom.v1.unparse import unparse_commit
>>> unparse_commit(ConventionalCommit(header=Header(type='feat', description='my new feature!')))
'feat: my new feature!'
Ta-da! 🎉 You should now have all the tools you need to start working with conventional commits.
For more advanced use-cases, keep reading.
Advanced
Adding a scope
A scope can be added to a header after the type:
>>> from convcom.v1.parse import parse_commit
>>> parse_commit('feat(website): my new UI feature!')
ConventionalCommit(header=Header(type='feat', description='my new UI feature!', scope='website', is_breaking_change=False), body=None, footer=None)
Adding a body
Paragraphs can be added to a body:
>>> from convcom.v1.parse import parse_commit
>>> parse_commit('feat(website): my new UI feature!\n\nSome details...\n\nSome more details...')
ConventionalCommit(header=Header(type='feat', description='my new UI feature!', scope='website', is_breaking_change=False), body=Body(paragraphs=['Some details...', 'Some more details...']), footer=None)
Adding a footer
Trailers can be added to a footer:
>>> from convcom.v1.parse import parse_commit
>>> parse_commit('feat: my new feature!\n\nIssue: #1')
ConventionalCommit(header=Header(type='feat', description='my new feature!', scope=None, is_breaking_change=False), body=None, footer=Footer(trailers=OrderedDict({'Issue': ['#1']}), is_breaking_change=False))
A trailers token can also repeat multiple times within a footer:
>>> from convcom.v1.parse import parse_commit
>>> parse_commit('feat: my new feature!\n\nIssue: #1\nIssue: #2')
ConventionalCommit(header=Header(type='feat', description='my new feature!', scope=None, is_breaking_change=False), body=None, footer=Footer(trailers=OrderedDict({'Issue': ['#1', '#2']}), is_breaking_change=False))
Indicating a breaking change
Breaking changes can indicated using a '!' in the header:
>>> from convcom.v1.parse import parse_commit
>>> parse_commit('feat!: my new breaking feature!')
ConventionalCommit(header=Header(type='feat', description='my new breaking feature!', scope=None, is_breaking_change=True), body=None, footer=None)
Breaking changes can also be indicated using a 'BREAKING CHANGE' or 'BREAKING-CHANGE' trailer in the footer:
>>> from convcom.v1.parse import parse_commit
>>> parse_commit('feat: my new feature!\n\nBREAKING-CHANGE: This feature breaks things...')
ConventionalCommit(header=Header(type='feat', description='my new feature!', scope=None, is_breaking_change=False), body=None, footer=Footer(trailers=OrderedDict({'BREAKING-CHANGE': ['This feature breaks things...']}), is_breaking_change=True))
To simplify things, the ConventionalCommit
class has a convenience method for checking if the commit is a breaking change:
>>> from convcom.v1.parse import parse_commit
>>> parse_commit('feat!: my new breaking feature!').is_breaking_change()
True
>>> parse_commit('feat: my new feature!\n\nBREAKING-CHANGE: This feature breaks things...').is_breaking_change()
True
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.