django5-spoll 0.3.0
A Django 5 app to conduct web-based soccer polls.
Requires Python: >=3.14.1

==================
django5-soccerpoll
==================

The **django5-soccerpoll** is a Django package created to conduct web-based soccer polls. For each question, visitors can choose between a fixed number of answers, to vote for questions in 3 different categories (until now):

**Note:** The app within this pkg could be extended by adding categories (Django models) like Tournament, Referee, Ball, Stadium, Fan, Goal, Play, etc.

* **Player**
* **Team**
* **Coach**

Detailed documentation is within "docs" directory of this GitLab repository. In example, you can find SQLite DB E-R UML diagram developed with Google's SaaS tool, draw.io (redirects to https://app.diagrams.net/).

Pkg Quick start
---------------

This section describes how to integrate package into an existent Django project.

1. Add "soccerpoll" to your INSTALLED_APPS setting like this::

    INSTALLED_APPS = [
        ...,
        "django5_soccerpoll",
    ]

2. Include the polls URLconf in your project urls.py like this::

    path("soccerpoll/", include("django5_soccerpoll.urls")),

3. Run ``python3 manage.py migrate`` to create the models.

4. Start the dev server & visit the admin to create your soccer poll.

5. Visit the ``/soccerpoll/`` URL to participate in the poll.

Packaging Details
-----------------

The following steps were done to create this Python pkg & embedded module:

1. Create a pkg folder (separated with hyphens if more than one word) to add all pkg needed content::

    mkdir django5-soccerpoll

2. Import folder of previously developed app, i.e. soccerpoll, into this Python pkg project (add hyphens if more than one word)::

    cd ~/workspaces/python/django-tests/ | cd C:\..\workspaces\python\django-tests
    mv soccerpoll/ ../pkgs/django5-soccerpoll | move soccerpoll ..\pkgs\django5-soccerpoll
    cd ../pkgs/django5-soccerpoll | cd ..\pkgs\django5-soccerpoll
    mv soccerpoll django5_soccerpoll | move soccerpoll django5_soccerpoll


3. Edit **apps.py** file to validate / rename **name** & **label** variables with your preferred text editor, be aware to separate words with hyphens in **name** variable (refers to pkg module name) & use a simple name in **label** variable, which is used to give a short name for the Django app:

..  figure:: /docs/imgs/python/apps-file-name-&-label-config.png
    :alt: some img

    name & label vars config. - ./django5_soccerpoll/apps.py

4. Add docs folder::

    mkdir docs

5. Add LICENSE file & add the desired License content with you preferred text editor::

    touch LICENSE | edit LICENSE

6. Add MANIFEST.in file & add the following content via CLI::

    touch MANIFEST.in | edit MANIFEST.in
    echo "recursive-include django5_soccerpoll/static *" > MANIFEST.in
    echo "recursive-include django5_soccerpoll/templates *" >> MANIFEST.in

7. Add pyproject.toml & add the following content with your preferred text editor (be sure to adapt it to use only the needed modules, dependencies, libraries & classifiers with the right versions)::

    touch pyproject.toml | edit pyproject.toml

Content::

    [build-system]
    requires = ["setuptools>=80.9.0"]
    build-backend = "setuptools.build_meta"

    [project]
    name = "django5-soccerpoll"
    version = "0.2.0"
    dependencies = [
        "django>=6",
    ]
    description = "A Django 5 app to conduct web-based soccer polls."
    readme = "README.rst"
    license = "BSD-3-Clause"
    requires-python = ">= 3.14.1"
    authors = [
        {name = "Omar Abraham", email = "oym7@msn.com"},
    ]
    classifiers = [
        "Environment :: Web Environment",
        "Framework :: Django",
        "Framework :: Django :: 6.0",
        "Intended Audience :: Developers",
        "Operating System :: OS Independent",
        "Programming Language :: Python",
        "Programming Language :: Python :: 3",
        "Programming Language :: Python :: 3 :: Only",
        "Programming Language :: Python :: 3.10",
        "Programming Language :: Python :: 3.11",
        "Programming Language :: Python :: 3.12",
        "Programming Language :: Python :: 3.13",
        "Programming Language :: Python :: 3.14",
        "Topic :: Internet :: WWW/HTTP",
        "Topic :: Internet :: WWW/HTTP :: Dynamic Content",
    ]

    [project.urls]
    Homepage = "http://127.0.0.1/soccerpoll/"

8. Add the README.rst file that you are just reading & add the needed content or adapt it to your needs::

    touch README.rst | edit README.rst

Once everything was created / added, let's build the package by executing the following commands::

    python3 -m pip install build | python -m pip install build
    python3 -m pip freeze > requirements.txt | python -m pip freeze > requirements.txt
    more requirements.txt
    python3 -m build | python -m build
    ll | dir

When executing the build cmd, you should see something similar to the following output:

**Note:** Be aware that the build is executed in the background in an isolated environment (venv+pip).

..  figure:: /docs/imgs/python/py-pkg-build.png
    :alt: some image

    Python 3 - Build sample output

Notice the 2 files created during the build process, the ***.tar.gz** & ***.whl** files. That's it, the Python pkg is ready to be imported by any other Django project.

Django 6 Project Reference
--------------------------

The Django 6 project used to build this Python 3 pkg could be found in the following GitLab repository:

* **https://gitlab.com/pythones2/django-spoll.git**

**Master Author:** CSE. Omar Abraham - mailto:oym7@msn.com?Subject=Python3%20+%20Django%205%20Soccerpoll%20app%20setup%20+%20Tests%20+%20Deployment%20+%20Python%20Packaging%20-%20Doubt