{"id":16418724,"url":"https://github.com/paduszyk/python-gitmojis","last_synced_at":"2025-03-23T06:31:39.186Z","repository":{"id":213174499,"uuid":"713363235","full_name":"paduszyk/python-gitmojis","owner":"paduszyk","description":"😜 The official Gitmoji Guide in Python projects 🐍","archived":false,"fork":false,"pushed_at":"2024-10-29T19:27:41.000Z","size":136,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-10-29T21:36:44.658Z","etag":null,"topics":["gitmoji","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/paduszyk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-11-02T11:20:04.000Z","updated_at":"2024-10-29T19:27:46.000Z","dependencies_parsed_at":"2023-12-27T09:26:13.316Z","dependency_job_id":"6b151bc4-820b-4fab-9635-4b93167878d7","html_url":"https://github.com/paduszyk/python-gitmojis","commit_stats":null,"previous_names":["paduszyk/python-gitmojis"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paduszyk%2Fpython-gitmojis","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paduszyk%2Fpython-gitmojis/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paduszyk%2Fpython-gitmojis/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paduszyk%2Fpython-gitmojis/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/paduszyk","download_url":"https://codeload.github.com/paduszyk/python-gitmojis/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245066497,"owners_count":20555402,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gitmoji","python"],"created_at":"2024-10-11T07:14:53.615Z","updated_at":"2025-03-23T06:31:38.756Z","avatar_url":"https://github.com/paduszyk.png","language":"Python","readme":"# python-gitmojis\n\n[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?style=flat-square\u0026logo=pre-commit)][pre-commit.ci]\n[![github-build-workflow](https://img.shields.io/github/actions/workflow/status/paduszyk/python-gitmojis/build-package.yml?style=flat-square\u0026logo=github)][github-build-workflow]\n[![codecov](https://img.shields.io/codecov/c/github/paduszyk/python-gitmojis?style=flat-square\u0026logo=codecov)][codecov]\n\n[![nox](https://img.shields.io/badge/%F0%9F%A6%8A-Nox-D85E00.svg?style=flat-square)][nox]\n[![ruff](https://img.shields.io/endpoint?style=flat-square\u0026url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)][ruff]\n[![mypy](https://img.shields.io/badge/type--checked-mypy-blue?style=flat-square)][mypy]\n[![black](https://img.shields.io/badge/code%20style-black-black?style=flat-square)][black]\n\n[![pypi-status](https://img.shields.io/pypi/status/python-gitmojis?style=flat-square\u0026logo=pypi\u0026logoColor=white)][pypi]\n[![pypi-version](https://img.shields.io/pypi/v/python-gitmojis?style=flat-square\u0026logo=pypi\u0026logoColor=white)][pypi]\n[![pypi-python-version](https://img.shields.io/pypi/pyversions/python-gitmojis?style=flat-square\u0026logo=python\u0026logoColor=white)][pypi]\n[![pypi-license](https://img.shields.io/pypi/l/python-gitmojis?style=flat-square\u0026label=license)][pypi]\n\n## Summary\n\nThis package provides a few simple utilities to apply the official\n[Gitmoji Guide][gitmoji-website] in Python libraries. It may potentially serve\nas a helper in projects related to version control systems, versioning, and\nautomatic changelog generation. Applications in automation tools for validating\ncommit and pull request messages seem feasible as well.\n\n## Features\n\n- Handle individual Gitmojis and their lists using Python classes. 👔\n- Fetch Gitmoji data directly from the official [Gitmoji API][gitmoji-api]. 😜\n- Graceful degradation: If the API is unavailable, fall back to backup data. 🦺\n\n## Installation\n\nIt is recommended to install the package directly from PyPI using `pip`:\n\n```console\n$ pip install python-gitmojis\n```\n\nor any other dependency manager of your preference. After installation, the\npackage functionalities can be accessed by importing them from the `gitmojis`\nmodule:\n\n```python\nimport gitmojis\n```\n\n## Usage\n\n### Data model\n\nThe data model incorporates two classes representing individual Gitmojis and\ntheir collections (\"guides\"), namely, `Gitmoji` and `Guide`, respectively.\n\nThe classes are defined in `gitmojis.model`, but can also be accessed directly\nfrom `gitmojis` as well:\n\n```python\nfrom gitmojis import Gitmoji, Guide\n```\n\n#### `gitmojis.model.Gitmoji`\n\nThe `Gitmoji` class is a Python `@dataclass` ([PEP 557][PEP-557]) that uses a\nset of fields consistent with the [JSON schema][gitmoji-schema] proposed in the\noriginal Gitmoji project, namely:\n\n- `emoji: str` \u0026ndash; the emoji character representing the Gitmoji;\n- `entity: str` \u0026ndash; the HTML entity of the Gitmoji;\n- `code: str` \u0026ndash; the emoji's code to be used in rendering Gitmojis in the\n  Markdown documents;\n- `description: str` \u0026ndash; a short note on the type of changes represented by\n  the commits or pull requests marked by the Gitmoji;\n- `name: str` \u0026ndash; a text identifier of the Gitmoji;\n- `semver: str | None` \u0026ndash; the [Semantic Versioning](https://semver.org)\n  level affected by the changes marked with the Gitmoji; the allowed string\n  values are `\"major\"`, `\"minor\"`, and `\"patch\"`.\n\nThe class can be used to create immutable objects representing individual\nGitmojis, for example:\n\n```python\nfrom gitmojis import Gitmoji\n\ngitmoji = Gitmoji(\n    emoji=\"🤖\",\n    entity=\"\u0026#x1f916\",\n    code=\":robot:\",\n    description=\"Add or update Dependabot configuration.\",\n    name=\"robot\",\n    semver=None,\n)\n\nassert gitmoji.emoji == \"🤖\"\n```\n\n\u003e Note that when creating a new `Gitmoji` instance, all the `@dataclass` fields\n\u003e are required. Furthermore, they all must be passed as keyword arguments.\n\n#### `gitmojis.model.Guide`\n\nThe `Guide` class aims to provide a custom list-like structure to manage a\ncollection of Gitmojis. Its instances are created simply by passing an iterable\nof `Gitmoji` objects (as the `gitmojis` keyword argument) to the class\nconstructor:\n\n```python\nfrom gitmojis import Gitmoji, Guide\n\ngitmojis_json = [\n    {\n        \"emoji\" : \"🤖\",\n        \"entity\" : \"\u0026#x1f916\",\n        \"code\" : \":robot:\",\n        \"description\" : \"Add or update Dependabot configuration.\",\n        \"name\" : \"robot\",\n        \"semver\" : None,\n    },\n    # ...\n]\n\nguide = Guide(\n    gitmojis=[Gitmoji(**gitmoji_json) for gitmoji_json in gitmojis_json]\n)\n\nassert guide[0].emoji == \"🤖\"\n```\n\nThe class is based on `collections.UserList`. Currently, it doesn't override\nany base class methods nor does it implement any custom functionality.\n\n### Fetching Gitmojis from the API\n\nThe main package functionality is implemented as a plain Python function, named\n`fetch_guide`. It can be imported either from `gitmojis` or directly from its\nsource, i.e. the `gitmojis.core` module.\n\nUsage of the function is extremely easy. In the simplest case, it can be called\nwithout any arguments:\n\n```python\nfrom gitmojis import fetch_guide\n\nguide = fetch_guide()\n```\n\nThe function uses the `requests` library to return a `Guide` instance containing\nthe current state of the official [Gitmoji API][gitmoji-api]. If the API is\ninaccessible, the guide can be populated using the data retrieved from the local\nbackup file. Such behavior can be triggered by passing `True` as the value of\nthe `use_backup` keyword argument (it defaults to `False`):\n\n```python\nfrom gitmojis import fetch_guide\n\nguide = fetch_guide(use_backup=True)  # will work even if you're offline\n```\n\n### Command-line interface (CLI)\n\nThe package comes with a simple CLI which can be run using the `gitmojis`\ncommand:\n\n```console\n$ gitmojis\nUsage: gitmojis [OPTIONS] COMMAND [ARGS]...\n\n  Command-line interface for managing the official Gitmoji guide.\n\nOptions:\n  --use-backup  Use the backup to fetch data if the API request fails.\n  --version     Show the version and exit.\n  --help        Show this message and exit.\n\nCommands:\n  sync  Synchronize the backup file with the current state of the API.\n```\n\nAs seen, currently the CLI provides only the `sync` command which can be used\nto update the Gitmoji data backup file to the current state of the official API\nendpoint.\n\n\u003e Checking for the updates of the API state is compared to the backup file by\n\u003e executing the `sync` command at GitHub Actions runner every week. The\n\u003e respective workflow automatically applies the updates and opens a pull\n\u003e request introducing them to the codebase. We plan to do the version bump (on\n\u003e a patch level) upon merging each of such pull requests. Therefore, to stay\n\u003e tuned with the Gitmoji API backed up by this library, you should update\n\u003e the package systematically. This particularly concerns the developers, who\n\u003e work with local repositories most of the time.\n\n## Contributing\n\nThis project is open-source and embraces contributions of all types. For\ncomprehensive instructions on how to contribute to the project, please refer to\nour [Contributing Guide][contributing-guide].\n\nWe require all contributors to adhere to our [Code of Conduct][code-of-conduct].\nWhile it may seem intricate at first glance, the essence is simple: treat\neveryone with kindness! 🙂\n\n## Credits\n\nThe idea of Gitmoji was originally proposed, developed, and maintained by\nCarlos Cuesta ([@carloscuesta][github-carlosquesta]). For more information, see\nthe official [repository][gitmoji-repository] and [website][gitmoji-website] of\nthe project.\n\n## Authors\n\nCreated by Kamil Paduszyński ([@paduszyk][github-paduszyk]).\n\n## License\n\nReleased under the [MIT License][license].\n\n[black]: https://github.com/psf/black\n[code-of-conduct]: https://github.com/paduszyk/python-gitmojis/blob/main/.github/CODE_OF_CONDUCT.md\n[codecov]: https://app.codecov.io/gh/paduszyk/python-gitmojis\n[contributing-guide]: https://github.com/paduszyk/python-gitmojis/blob/main/.github/CONTRIBUTING.md\n[github-build-workflow]: https://github.com/paduszyk/python-gitmojis/actions/workflows/build-package.yml\n[github-carlosquesta]: https://github.com/carloscuesta\n[github-paduszyk]: https://github.com/paduszyk\n[gitmoji-api]: https://github.com/carloscuesta/gitmoji/tree/master/packages/gitmojis#api\n[gitmoji-repository]: https://github.com/carloscuesta/gitmoji\n[gitmoji-schema]: https://github.com/carloscuesta/gitmoji/blob/master/packages/gitmojis/src/schema.json\n[gitmoji-website]: https://gitmoji.dev\n[license]: https://github.com/paduszyk/python-gitmojis/blob/main/LICENSE\n[mypy]: https://github.com/python/mypy\n[nox]: https://github.com/wntrblm/nox\n[pep-557]: https://peps.python.org/pep-0557/\n[pre-commit.ci]: https://results.pre-commit.ci/latest/github/paduszyk/python-gitmojis/main\n[pypi]: https://pypi.org/project/python-gitmojis/\n[ruff]: https://github.com/astral-sh/ruff\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaduszyk%2Fpython-gitmojis","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpaduszyk%2Fpython-gitmojis","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaduszyk%2Fpython-gitmojis/lists"}