README.md

python-gitmojis

Summary

This package provides a few simple utilities to apply the official Gitmoji Guide in Python libraries. It may potentially serve as a helper in projects related to version control systems, versioning, and automatic changelog generation. Applications in automation tools for validating commit and pull request messages seem feasible as well.

Features

• Handle individual Gitmojis and their lists using Python classes. 👔
• Fetch Gitmoji data directly from the official Gitmoji API. 😜
• Graceful degradation: If the API is unavailable, fall back to backup data. 🦺

Installation

It is recommended to install the package directly from PyPI using pip:

$ pip install python-gitmojis

or any other dependency manager of your preference. After installation, the package functionalities can be accessed by importing them from the gitmojis module:

import gitmojis

Usage

Data model

The data model incorporates two classes representing individual Gitmojis and their collections ("guides"), namely, Gitmoji and Guide, respectively.

The classes are defined in gitmojis.model, but can also be accessed directly from gitmojis as well:

from gitmojis import Gitmoji, Guide

gitmojis.model.Gitmoji

The Gitmoji class is a Python @dataclass (PEP 557) that uses a set of fields consistent with the JSON schema proposed in the original Gitmoji project, namely:

• emoji: str – the emoji character representing the Gitmoji;
• entity: str – the HTML entity of the Gitmoji;
• code: str – the emoji's code to be used in rendering Gitmojis in the Markdown documents;
• description: str – a short note on the type of changes represented by the commits or pull requests marked by the Gitmoji;
• name: str – a text identifier of the Gitmoji;
• semver: str | None – the Semantic Versioning level affected by the changes marked with the Gitmoji; the allowed string values are "major", "minor", and "patch".

The class can be used to create immutable objects representing individual Gitmojis, for example:

from gitmojis import Gitmoji

gitmoji = Gitmoji(
    emoji="🤖",
    entity="&#x1f916",
    code=":robot:",
    description="Add or update Dependabot configuration.",
    name="robot",
    semver=None,
)

assert gitmoji.emoji == "🤖"

Note that when creating a new Gitmoji instance, all the @dataclass fields are required. Furthermore, they all must be passed as keyword arguments.

gitmojis.model.Guide

The Guide class aims to provide a custom list-like structure to manage a collection of Gitmojis. Its instances are created simply by passing an iterable of Gitmoji objects (as the gitmojis keyword argument) to the class constructor:

from gitmojis import Gitmoji, Guide

gitmojis_json = [
    {
        "emoji" : "🤖",
        "entity" : "&#x1f916",
        "code" : ":robot:",
        "description" : "Add or update Dependabot configuration.",
        "name" : "robot",
        "semver" : None,
    },
    # ...
]

guide = Guide(
    gitmojis=[Gitmoji(**gitmoji_json) for gitmoji_json in gitmojis_json]
)

assert guide[0].emoji == "🤖"

The class is based on collections.UserList. Currently, it doesn't override any base class methods nor does it implement any custom functionality.

Fetching Gitmojis from the API

The main package functionality is implemented as a plain Python function, named fetch_guide. It can be imported either from gitmojis or directly from its source, i.e. the gitmojis.core module.

Usage of the function is extremely easy. In the simplest case, it can be called without any arguments:

from gitmojis import fetch_guide

guide = fetch_guide()

The function uses the requests library to return a Guide instance containing the current state of the official Gitmoji API. If the API is inaccessible, the guide can be populated using the data retrieved from the local backup file. Such behavior can be triggered by passing True as the value of the use_backup keyword argument (it defaults to False):

from gitmojis import fetch_guide

guide = fetch_guide(use_backup=True)  # will work even if you're offline

Command-line interface (CLI)

The package comes with a simple CLI which can be run using the gitmojis command:

$ gitmojis
Usage: gitmojis [OPTIONS] COMMAND [ARGS]...

  Command-line interface for managing the official Gitmoji guide.

Options:
  --use-backup  Use the backup to fetch data if the API request fails.
  --version     Show the version and exit.
  --help        Show this message and exit.

Commands:
  sync  Synchronize the backup file with the current state of the API.

As seen, currently the CLI provides only the sync command which can be used to update the Gitmoji data backup file to the current state of the official API endpoint.

Checking for the updates of the API state is compared to the backup file by executing the sync command at GitHub Actions runner every week. The respective workflow automatically applies the updates and opens a pull request introducing them to the codebase. We plan to do the version bump (on a patch level) upon merging each of such pull requests. Therefore, to stay tuned with the Gitmoji API backed up by this library, you should update the package systematically. This particularly concerns the developers, who work with local repositories most of the time.

Contributing

This project is open-source and embraces contributions of all types. For comprehensive instructions on how to contribute to the project, please refer to our Contributing Guide.

We require all contributors to adhere to our Code of Conduct. While it may seem intricate at first glance, the essence is simple: treat everyone with kindness! 🙂

Credits

The idea of Gitmoji was originally proposed, developed, and maintained by Carlos Cuesta (@carloscuesta). For more information, see the official repository and website of the project.

Authors

Created by Kamil Paduszyński (@paduszyk).

License

Released under the MIT License.