python-gitmojis 1.0.0

Description:

pythongitmojis 1.0.0

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.