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.
Source Distribution
Built Distribution
File details
Details for the file convcom-0.1.2.tar.gz
.
File metadata
- Download URL: convcom-0.1.2.tar.gz
- Upload date:
- Size: 18.9 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/5.0.0 CPython/3.12.3
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 775309788e3767166d17bf5368ccc088d9bf31b902d89d920f2c28d7c7a4bad7 |
|
MD5 | fc5dfe5e830e406775b8d26014799948 |
|
BLAKE2b-256 | eeb852bcc5409e34f0657a0aa37634d910f5d5961ab2f8be4ba2a98559ee2f32 |
File details
Details for the file convcom-0.1.2-py3-none-any.whl
.
File metadata
- Download URL: convcom-0.1.2-py3-none-any.whl
- Upload date:
- Size: 16.4 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/5.0.0 CPython/3.12.3
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | f63c8d263c9f6705edff99e69c1920ec3af7171949b1440248b6ff25ba52848a |
|
MD5 | 9258c1e1d6a01cbbc6ab55d3c6ad42b1 |
|
BLAKE2b-256 | 47bb5f10cc87ab063f031271fc086fd0afb7fb7dc40b8dc71eb7b4d664b0ef91 |