Package: python-gitmojis
python-gitmojisSummaryThis package provides a few simple utilities to apply the officialGitmoji Guidein 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.FeaturesHandle individual Gitmojis and their lists using Python classes. 👔Fetch Gitmoji data directly from the officialGitmoji API. 😜Graceful degradation: If the API is unavailable, fall back to backup data. 🛟InstallationIt is recommended to install the package directly from PyPI usingpip:$pipinstallpython-gitmojisor any other dependency manager of your preference. After installation, the
package functionalities can be accessed by importing them from thegitmojismodule:importgitmojisUsageData modelThe data model incorporates two classes representing individual Gitmojis and
their collections ("guides"), namely,GitmojiandGuide, respectively.The classes are defined ingitmojis.model, but can also be accessed directly
fromgitmojisas well:fromgitmojisimportGitmoji,Guidegitmojis.model.GitmojiTheGitmojiclass is a Python@dataclass(PEP 557) that uses a
set of fields consistent with theJSON schemaproposed 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– theSemantic Versioninglevel 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:fromgitmojisimportGitmojigitmoji=Gitmoji(emoji="🤖",entity="&#x1f916",code=":robot:",description="Add or update Dependabot configuration.",name="robot",semver=None,)assertgitmoji.emoji=="🤖"Note that when creating a newGitmojiinstance, all the@dataclassfields
are required. Furthermore, they all must be passed as keyword arguments.gitmojis.model.GuideTheGuideclass aims to provide a custom list-like structure to manage a
collection of Gitmojis. Its instances are created simply by passing an iterable
ofGitmojiobjects (as thegitmojiskeyword argument) to the class
constructor:fromgitmojisimportGitmoji,Guidegitmojis_json=[{"emoji":"🤖","entity":"&#x1f916","code":":robot:","description":"Add or update Dependabot configuration.","name":"robot","semver":None,},# ...]guide=Guide(gitmojis=[Gitmoji(**gitmoji_json)forgitmoji_jsoningitmojis_json])assertguide[0].emoji=="🤖"The class is based oncollections.UserList. Currently, it doesn't override
any base class methods nor does it implement any custom functionality.Fetching Gitmojis from the APIThe main package functionality is implemented as a plain Python function, namedfetch_guide. It can be imported either fromgitmojisor directly from its
source, i.e. thegitmojis.coremodule.Usage of the function is extremely easy. In the simplest case, it can be called
without any arguments:fromgitmojisimportfetch_guideguide=fetch_guide()The function uses therequestslibrary to return aGuideinstance containing
the current state of the officialGitmoji 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 passingTrueas the value of
theuse_backupkeyword argument (it defaults toFalse):fromgitmojisimportfetch_guideguide=fetch_guide(use_backup=True)# will work even if you're offlineCommand-line interface (CLI)The package comes with a simple CLI which can be run using thegitmojiscommand:$gitmojisUsage: 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 thesynccommand 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 thesynccommand 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.ContributingThis project is open-source and embraces contributions of all types. For
comprehensive instructions on how to contribute to the project, please refer to
ourContributing Guide.We require all contributors to adhere to ourCode of Conduct.
While it may seem intricate at first glance, the essence is simple: treat
everyone with kindness! 🙂CreditsThe idea of Gitmoji was originally proposed, developed, and maintained by
Carlos Cuesta (@carloscuesta). For more information, see
the officialrepositoryandwebsiteof
the project.AuthorsCreated by Kamil Paduszyński (@paduszyk).LicenseReleased under theMIT License.