Skip to main content

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


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

convcom-0.1.2.tar.gz (18.9 kB view details)

Uploaded Source

Built Distribution

convcom-0.1.2-py3-none-any.whl (16.4 kB view details)

Uploaded Python 3

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

Hashes for convcom-0.1.2.tar.gz
Algorithm Hash digest
SHA256 775309788e3767166d17bf5368ccc088d9bf31b902d89d920f2c28d7c7a4bad7
MD5 fc5dfe5e830e406775b8d26014799948
BLAKE2b-256 eeb852bcc5409e34f0657a0aa37634d910f5d5961ab2f8be4ba2a98559ee2f32

See more details on using hashes here.

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

Hashes for convcom-0.1.2-py3-none-any.whl
Algorithm Hash digest
SHA256 f63c8d263c9f6705edff99e69c1920ec3af7171949b1440248b6ff25ba52848a
MD5 9258c1e1d6a01cbbc6ab55d3c6ad42b1
BLAKE2b-256 47bb5f10cc87ab063f031271fc086fd0afb7fb7dc40b8dc71eb7b4d664b0ef91

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page