python-gitmojis 0.1.5__py3-none-any.whl → 1.1.0__py3-none-any.whl

gitmojis/__init__.py

@@ -1,3 +1,8 @@
-from .core import gitmojis
+from .core import fetch_guide
+from .model import Gitmoji, Guide
 
-__version__ = "0.1.5"
+__all__ = [
+    "Gitmoji",
+    "Guide",
+    "fetch_guide",
+]

gitmojis/__main__.py

@@ -0,0 +1,4 @@
+from gitmojis.cli import gitmojis_cli as main
+
+if __name__ == "__main__":
+    main()

gitmojis/cli/__init__.py

@@ -0,0 +1,37 @@
+import click
+
+from gitmojis.core import fetch_guide
+
+
+def get_commands() -> list[click.Command]:
+    """Return a list of `@click` commands defined in `gitmojis.cli.commands`."""
+    from gitmojis.cli import commands as commands_module
+
+    return [
+        command
+        for command in commands_module.__dict__.values()
+        if isinstance(command, click.Command)
+    ]
+
+
+@click.group(
+    name="gitmojis",
+    commands=get_commands(),
+)
+@click.option(
+    "--use-backup",
+    is_flag=True,
+    help="Use the backup to fetch data if the API request fails.",
+)
+@click.version_option(
+    package_name="python-gitmojis",
+    prog_name="gitmojis",
+)
+@click.pass_context
+def gitmojis_cli(context: click.Context, use_backup: bool) -> None:
+    """Command-line interface for managing the official Gitmoji guide."""
+    # Initialize the context object
+    context.ensure_object(dict)
+
+    # Pass the current state of the Gitmoji guide to the group context
+    context.obj["guide"] = fetch_guide(use_backup=use_backup)

gitmojis/cli/commands.py

@@ -0,0 +1,24 @@
+import json
+from dataclasses import asdict
+
+import click
+
+from gitmojis import defaults
+
+
+@click.command()
+@click.pass_context
+def sync(context: click.Context) -> None:
+    """Synchronize the backup file with the current state of the API."""
+    # Get the `Guide` object from the command's context
+    guide = context.obj["guide"]
+
+    # Covert the `Guide` instance from context to a format defined by the API schema
+    gitmojis_json = list(map(asdict, guide))
+
+    with defaults.GITMOJI_API_PATH.open("w", encoding="UTF-8") as f:
+        # Dump the Gitmoji data to the backup file
+        json.dump(gitmojis_json, f, ensure_ascii=False, indent=2)
+
+        # Append a newline to avoid the `end-of-file-fixer` Pre-commit hook error
+        f.write("\n")

gitmojis/core.py

@@ -1,17 +1,47 @@
-from gitmojis.loaders import load_gitmojis_api, load_gitmojis_json
-from gitmojis.models import GitmojiList
+import json
 
-__all__ = [
-    "gitmojis",
-]
+import requests
 
+from . import defaults
+from .exceptions import ApiRequestError, ResponseJsonError
+from .model import Gitmoji, Guide
 
-def get_gitmojis() -> GitmojiList:
+
+def fetch_guide(*, use_backup: bool = False) -> Guide:
+    """Fetch the Gitmoji guide from the official Gitmoji API.
+
+    This function sends a GET request to the Gitmoji API to retrieve the current state
+    of the Gitmoji guide. If the request is successful and contains the expected JSON
+    data, a `Guide` object is returned. If the expected JSON data is not present, a
+    `ResponseJsonError` is raised. In case of an HTTP error during the request
+    (e.g., connection error, timeout), and if `use_backup` is set to `True`, the function
+    falls back to loading a local copy of the Gitmoji guide. Otherwise, it raises an
+    `ApiRequestError`.
+
+    Args:
+        use_backup: A flag indicating whether to use a local backup in case of a request
+            failure. Defaults to `False`.
+
+    Returns:
+        A `Guide` object representing the current state of the Gitmoji API.
+
+    Raises:
+        ApiRequestError: If the API request fails and `use_backup` is `False`.
+        ResponseJsonError: If the API response doesn't contain the expected JSON data or
+            if there is an error loading the local backup of the Gitmoji guide.
+    """
     try:
-        gitmojis = load_gitmojis_api()
-    except ConnectionError:
-        gitmojis = load_gitmojis_json()
-    return gitmojis
+        (response := requests.get(defaults.GITMOJI_API_URL)).raise_for_status()
+
+        if (gitmojis_json := response.json().get(defaults.GITMOJI_API_KEY)) is None:
+            raise ResponseJsonError
+    except requests.RequestException as exc_info:
+        if use_backup:
+            with defaults.GITMOJI_API_PATH.open(encoding="UTF-8") as f:
+                gitmojis_json = json.load(f)
+        else:
+            raise ApiRequestError from exc_info
 
+    guide = Guide(gitmojis=[Gitmoji(**gitmoji_json) for gitmoji_json in gitmojis_json])
 
-gitmojis = get_gitmojis()
+    return guide

gitmojis/defaults.py

@@ -0,0 +1,10 @@
+from pathlib import Path
+from typing import Final
+
+import gitmojis
+
+GITMOJI_API_URL: Final = "https://gitmoji.dev/api/gitmojis"
+
+GITMOJI_API_KEY: Final = "gitmojis"
+
+GITMOJI_API_PATH: Final = Path(gitmojis.__file__).parent / "assets" / "gitmojis.json"

gitmojis/exceptions.py

@@ -0,0 +1,13 @@
+class GitmojisException(Exception):
+    message: str
+
+    def __init__(self, message: str | None = None) -> None:
+        super().__init__(message or getattr(self.__class__, "message", ""))
+
+
+class ApiRequestError(GitmojisException):
+    message = "request to get the Gitmoji data from the API failed"
+
+
+class ResponseJsonError(ApiRequestError):
+    message = "unsupported format of the JSON data returned by the API"

gitmojis/model.py

@@ -0,0 +1,53 @@
+from collections import UserList
+from dataclasses import dataclass
+from typing import Iterable, Literal
+
+
+@dataclass(frozen=True, kw_only=True)
+class Gitmoji:
+    """Represents a single Gitmoji and its data.
+
+    The data model is adapted from the schema of the original Gitmoji project.
+
+    Attributes:
+        emoji: The emoji symbol representing the Gitmoji.
+        entity: The HTML entity corresponding to the Gitmoji.
+        code: The Markdown code of the Gitmoji's emoji.
+        description: A brief description of changes introduced by commits and pull
+            requests marked by the Gitmoji.
+        name: The user-defined name or identifier of the Gitmoji.
+        semver: The Semantic Versioning level affected by the commits or pull requests
+            marked by the emoji associated with the Gitmoji, if specified. May be `None`
+            or one of the following: `"major"`, `"minor"`, `"patch"`.
+    """
+
+    emoji: str
+    entity: str
+    code: str
+    description: str
+    name: str
+    semver: Literal["major", "minor", "patch"] | None
+
+
+class Guide(UserList[Gitmoji]):
+    """Represents a list of (a "guide" through) `Gitmoji` objects.
+
+    This class is used to create a collection of `Gitmoji` objects, providing a simple
+    framework for accessing various Gitmojis and their data.
+    """
+
+    def __init__(self, *, gitmojis: Iterable[Gitmoji] | None = None) -> None:
+        """Construct a new `Guide` object.
+
+        Args:
+            gitmojis: An optional iterable of `Gitmoji` objects used to create
+                the guide. If `None`, the guide is initialized as empty. Note
+                that the data must be passed as a keyword argument, in contrast
+                to the implementation provided by the base class.
+        """
+        super().__init__(gitmojis)
+
+    @property
+    def gitmojis(self) -> list[Gitmoji]:
+        """Return the guide's data with a semantically meaningful attribute name."""
+        return self.data

python_gitmojis-1.1.0.dist-info/METADATA

@@ -0,0 +1,257 @@
+Metadata-Version: 2.4
+Name: python-gitmojis
+Version: 1.1.0
+Summary: 😜 The official Gitmoji Guide in Python projects 🐍
+Author-email: Kamil Paduszyński <paduszyk@gmail.com>
+Keywords: emoji,git,gitmoji
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click<9.0.0,>=8.4.2
+Requires-Dist: requests<3.0.0,>=2.34.2
+Dynamic: license-file
+
+# python-gitmojis
+
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?style=flat-square&logo=pre-commit)][pre-commit.ci]
+[![github-build-workflow](https://img.shields.io/github/actions/workflow/status/paduszyk/python-gitmojis/build-package.yml?style=flat-square&logo=github)][github-build-workflow]
+[![codecov](https://img.shields.io/codecov/c/github/paduszyk/python-gitmojis?style=flat-square&logo=codecov)][codecov]
+
+[![nox](https://img.shields.io/badge/%F0%9F%A6%8A-Nox-D85E00.svg?style=flat-square)][nox]
+[![ruff](https://img.shields.io/endpoint?style=flat-square&url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)][ruff]
+[![mypy](https://img.shields.io/badge/type--checked-mypy-blue?style=flat-square)][mypy]
+[![black](https://img.shields.io/badge/code%20style-black-black?style=flat-square)][black]
+
+[![pypi-status](https://img.shields.io/pypi/status/python-gitmojis?style=flat-square&logo=pypi&logoColor=white)][pypi]
+[![pypi-version](https://img.shields.io/pypi/v/python-gitmojis?style=flat-square&logo=pypi&logoColor=white)][pypi]
+[![pypi-python-version](https://img.shields.io/pypi/pyversions/python-gitmojis?style=flat-square&logo=python&logoColor=white)][pypi]
+[![pypi-license](https://img.shields.io/pypi/l/python-gitmojis?style=flat-square&label=license)][pypi]
+
+## Summary
+
+This package provides a few simple utilities to apply the official
+[Gitmoji Guide][gitmoji-website] 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][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`:
+
+```console
+$ 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:
+
+```python
+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:
+
+```python
+from gitmojis import Gitmoji, Guide
+```
+
+#### `gitmojis.model.Gitmoji`
+
+The `Gitmoji` class is a Python `@dataclass` ([PEP 557][PEP-557]) that uses a
+set of fields consistent with the [JSON schema][gitmoji-schema] proposed in the
+original Gitmoji project, namely:
+
+- `emoji: str` &ndash; the emoji character representing the Gitmoji;
+- `entity: str` &ndash; the HTML entity of the Gitmoji;
+- `code: str` &ndash; the emoji's code to be used in rendering Gitmojis in the
+  Markdown documents;
+- `description: str` &ndash; a short note on the type of changes represented by
+  the commits or pull requests marked by the Gitmoji;
+- `name: str` &ndash; a text identifier of the Gitmoji;
+- `semver: str | None` &ndash; the [Semantic Versioning](https://semver.org)
+  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:
+
+```python
+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:
+
+```python
+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:
+
+```python
+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][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`):
+
+```python
+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:
+
+```console
+$ 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][contributing-guide].
+
+We require all contributors to adhere to our [Code of Conduct][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][github-carlosquesta]). For more information, see
+the official [repository][gitmoji-repository] and [website][gitmoji-website] of
+the project.
+
+## Authors
+
+Created by Kamil Paduszyński ([@paduszyk][github-paduszyk]).
+
+## License
+
+Released under the [MIT License][license].
+
+[black]: https://github.com/psf/black
+[code-of-conduct]: https://github.com/paduszyk/python-gitmojis/blob/main/.github/CODE_OF_CONDUCT.md
+[codecov]: https://app.codecov.io/gh/paduszyk/python-gitmojis
+[contributing-guide]: https://github.com/paduszyk/python-gitmojis/blob/main/.github/CONTRIBUTING.md
+[github-build-workflow]: https://github.com/paduszyk/python-gitmojis/actions/workflows/build-package.yml
+[github-carlosquesta]: https://github.com/carloscuesta
+[github-paduszyk]: https://github.com/paduszyk
+[gitmoji-api]: https://github.com/carloscuesta/gitmoji/tree/master/packages/gitmojis#api
+[gitmoji-repository]: https://github.com/carloscuesta/gitmoji
+[gitmoji-schema]: https://github.com/carloscuesta/gitmoji/blob/master/packages/gitmojis/src/schema.json
+[gitmoji-website]: https://gitmoji.dev
+[license]: https://github.com/paduszyk/python-gitmojis/blob/main/LICENSE
+[mypy]: https://github.com/python/mypy
+[nox]: https://github.com/wntrblm/nox
+[pep-557]: https://peps.python.org/pep-0557/
+[pre-commit.ci]: https://results.pre-commit.ci/latest/github/paduszyk/python-gitmojis/main
+[pypi]: https://pypi.org/project/python-gitmojis/
+[ruff]: https://github.com/astral-sh/ruff

python_gitmojis-1.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+gitmojis/__init__.py,sha256=cFSBvuzXrwJzX6b5TF1m7aY9tyAWj2qb_pW7IgAzCOQ,126
+gitmojis/__main__.py,sha256=TpZKhx32bh5RqAsGuHtNYcB75tPbthqkUfwlXGyyHfI,85
+gitmojis/core.py,sha256=sYj9goHiurbks7CmuET5Hw4XYLdR9pCTv9dlBbX_aic,1871
+gitmojis/defaults.py,sha256=kNrtmSUohor-WrM-H3EilyaPC7-9qEOfw9_vqZHFgXU,252
+gitmojis/exceptions.py,sha256=kzJUWNxtW42kYe2OovBOwOhDLZnhwmTiFsINh8k4Ekg,418
+gitmojis/model.py,sha256=u_PbVBslbWDMl6zcuQ_nwp9bhtozewOeDRBlY_sCYIo,1974
+gitmojis/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gitmojis/cli/__init__.py,sha256=mkPm04uX4jBP8Lm6uwBH82LL7zwQj3uuzQuPTvHvLcY,1015
+gitmojis/cli/commands.py,sha256=AxJoE0cee8UzROdFbZWSJ74jTWW3-PqVX3kK-bPU_HU,754
+python_gitmojis-1.1.0.dist-info/licenses/LICENSE,sha256=DGTOQe3hoUVVVxkAQq6G5colipirMi1t39vhJ0FIkFE,1080
+python_gitmojis-1.1.0.dist-info/METADATA,sha256=Kck2cEB4hvLeRpaWKirSYWmRGZSKZLenZx9duY7dEAs,9903
+python_gitmojis-1.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+python_gitmojis-1.1.0.dist-info/entry_points.txt,sha256=ikh4RpFvqZT85TD0aUtoOT7C6LbaKNV0RU-iPNXCv1g,52
+python_gitmojis-1.1.0.dist-info/top_level.txt,sha256=hEF9XSDmvmTWl3k8rl92pxO-pG7vEC9EqHjXQkoyY_k,9
+python_gitmojis-1.1.0.dist-info/RECORD,,

{python_gitmojis-0.1.5.dist-info → python_gitmojis-1.1.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: bdist_wheel (0.41.2)
+Generator: setuptools (83.0.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

python_gitmojis-1.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+gitmojis = gitmojis.__main__:main

{python_gitmojis-0.1.5.dist-info → python_gitmojis-1.1.0.dist-info/licenses}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 Kamil Paduszyński
+Copyright (c) 2023-2026 Kamil Paduszyński
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal