Metadata-Version: 2.4
Name: djangocms-gh-stats
Version: 2026.6.28.1
Summary: A django CMS plugin to display GitHub statistics for organisations and repositories.
Project-URL: Issues, https://github.com/marksweb/djangocms_gh_stats/issues
Project-URL: Source, https://github.com/marksweb/djangocms_gh_stats
Author-email: Mark Walker <mark@django-cms.org>
License-Expression: BSD-3-Clause
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Framework :: Django :: 5.1
Classifier: Framework :: Django :: 5.2
Classifier: Framework :: Django CMS
Classifier: Framework :: Django CMS :: 4.1
Classifier: Framework :: Django CMS :: 5.0
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Requires-Python: >=3.11
Requires-Dist: django-cms>=4.1
Requires-Dist: requests>=2.28
Provides-Extra: dev
Requires-Dist: djangocms-versioning>=2; extra == 'dev'
Requires-Dist: factory-boy; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-django; extra == 'dev'
Description-Content-Type: text/x-rst

========================
djangocms-gh-stats
========================

.. image:: https://img.shields.io/pypi/v/djangocms-gh-stats.svg
    :target: https://pypi.python.org/pypi/djangocms-gh-stats

.. image:: https://github.com/marksweb/djangocms_gh_stats/actions/workflows/ci.yml/badge.svg
    :target: https://github.com/marksweb/djangocms_gh_stats/actions/workflows/ci.yml

A `django CMS`_ plugin package that fetches statistics from the `GitHub REST API`_
and displays them on your CMS-powered website.

.. _django CMS: https://www.django-cms.org/
.. _GitHub REST API: https://docs.github.com/en/rest


Features
--------

The package ships the following CMS plugins, all configurable to target either
a GitHub **organisation** or a specific **repository**:

* **GitHub Stars** — display the star count of a repository.
* **GitHub Forks** — display the fork count of a repository.
* **GitHub Open Issues** — display the open issue count of a repository.
* **GitHub Contributors** — display an avatar grid of top contributors.


Installation
------------

Install using `uv`_ (recommended)::

    uv add djangocms-gh-stats

Or using pip::

    pip install djangocms-gh-stats

.. _uv: https://docs.astral.sh/uv/


Configuration
-------------

Add the application to ``INSTALLED_APPS`` in your Django settings::

    INSTALLED_APPS = [
        ...
        "djangocms_gh_stats",
        ...
    ]

Run the database migrations::

    python manage.py migrate djangocms_gh_stats

Optional settings
~~~~~~~~~~~~~~~~~

``DJANGOCMS_GH_STATS_TOKEN``
    A GitHub Personal Access Token (PAT) for authenticated API requests.
    Unauthenticated requests are subject to GitHub's lower rate limit of
    60 requests per hour per IP address. Providing a token raises this limit
    to 5,000 requests per hour::

        DJANGOCMS_GH_STATS_TOKEN = "github_pat_..."

``DJANGOCMS_GH_STATS_CACHE_TIMEOUT``
    How long (in seconds) to cache API responses. Defaults to ``600`` (10 minutes).
    Set to ``0`` to disable caching::

        DJANGOCMS_GH_STATS_CACHE_TIMEOUT = 600


Usage
-----

After installation, the following plugins are available in the django CMS
plugin picker under the **GitHub Stats** module:

* *GitHub Stars*
* *GitHub Forks*
* *GitHub Open Issues*
* *GitHub Contributors*

Each plugin has the following configuration fields:

* **Scope** — choose between *Organisation* or *Repository*.
* **Organisation** — the GitHub organisation or user name (e.g. ``django-cms``).
* **Repository** — the repository name (required when scope is *Repository*).


Development
-----------

This project is managed with `uv`_.

Clone the repository and install dependencies::

    git clone https://github.com/marksweb/djangocms_gh_stats.git
    cd djangocms_gh_stats
    uv sync

Run the tests::

    uv run pytest

Run the linter::

    uv run ruff check djangocms_gh_stats/ tests/


Releasing
---------

Releases are created with the ``Release and Publish`` GitHub Actions workflow.

The workflow uses CalVer tags in ``YYYY.M.D`` format and can append ``.N`` for
multiple releases on the same day.

To create a release:

1. Run the workflow from the Actions tab.
2. Optionally provide a CalVer version (for example ``2026.6.28``).
3. The workflow creates the Git tag, creates a GitHub release, builds with
   ``uv``, and publishes to PyPI via trusted publishing.
4. The workflow updates ``djangocms_gh_stats/__init__.py`` and inserts a new
   ``<version> (<YYYY-MM-DD>)`` section directly below the top changelog
   section, preserving the unreleased heading.


Contributing
------------

Contributions are welcome! Please open an issue or submit a pull request on
`GitHub <https://github.com/marksweb/djangocms_gh_stats>`_.


License
-------

This project is licensed under the **BSD 3-Clause License** — see the
`LICENSE <LICENSE>`_ file for details.
