mirrors/django
1
0
Fork 0
mirror of https://github.com/django/django.git synced 2024-12-28 03:55:50 +00:00
Code Issues 30 Releases Wiki Activity

[5.0.x] Fixed #35084 -- Recommended 'django_' prefix for reusable app modules.

Browse Source 
Backport of 05f124348e from main
This commit is contained in:
Adam Johnson 2024-01-03 21:21:10 +00:00 committed by Mariusz Felisiak
parent ef8234aef8
commit 4818a139f7
1 changed files with 51 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

79
docs/intro/reusable-apps.txt
View File

@ -121,16 +121,17 @@ Python *packaging* refers to preparing your app in a specific format that can
be easily installed and used. Django itself is packaged very much like be easily installed and used. Django itself is packaged very much like
this. For a small app like polls, this process isn't too difficult. this. For a small app like polls, this process isn't too difficult.
#. First, create a parent directory for ``polls``, outside of your Django #. First, create a parent directory for the package, outside of your Django
project. Call this directory ``django-polls``. project. Call this directory ``django-polls``.
.. admonition:: Choosing a name for your app .. admonition:: Choosing a name for your app
When choosing a name for your package, check resources like PyPI to avoid When choosing a name for your package, check PyPI to avoid naming
naming conflicts with existing packages. It's often useful to prepend conflicts with existing packages. We recommend using a ``django-``
``django-`` to your module name when creating a package to distribute. prefix for package names, to identify your package as specific to
This helps others looking for Django apps identify your app as Django Django, and a corresponding ``django_`` prefix for your module name. For
specific. example, the ``django-ratelimit`` package contains the
``django_ratelimit`` module.
Application labels (that is, the final part of the dotted path to Application labels (that is, the final part of the dotted path to
application packages) *must* be unique in :setting:`INSTALLED_APPS`. application packages) *must* be unique in :setting:`INSTALLED_APPS`.
@ -138,19 +139,35 @@ this. For a small app like polls, this process isn't too difficult.
</ref/contrib/index>`, for example ``auth``, ``admin``, or </ref/contrib/index>`, for example ``auth``, ``admin``, or
``messages``. ``messages``.
#. Move the ``polls`` directory into the ``django-polls`` directory. #. Move the ``polls`` directory into ``django-polls`` directory, and rename it
to ``django_polls``.
#. Edit ``django_polls/apps.py`` so that :attr:`~.AppConfig.name` refers to the
new module name and add :attr:`~.AppConfig.label` to give a short name for
the app:
.. code-block:: python
:caption: ``django-polls/django_polls/apps.py``
from django.apps import AppConfig
class PollsConfig(AppConfig):
default_auto_field = "django.db.models.BigAutoField"
name = "django_polls"
label = "polls"
#. Create a file ``django-polls/README.rst`` with the following contents: #. Create a file ``django-polls/README.rst`` with the following contents:
.. code-block:: rst .. code-block:: rst
:caption: ``django-polls/README.rst`` :caption: ``django-polls/README.rst``
===== ============
Polls django-polls
===== ============
Polls is a Django app to conduct web-based polls. For each question, django-polls is a Django app to conduct web-based polls. For each
visitors can choose between a fixed number of answers. question, visitors can choose between a fixed number of answers.
Detailed documentation is in the "docs" directory. Detailed documentation is in the "docs" directory.
@ -161,19 +178,18 @@ this. For a small app like polls, this process isn't too difficult.
INSTALLED_APPS = [ INSTALLED_APPS = [
..., ...,
"polls", "django_polls",
] ]
2. Include the polls URLconf in your project urls.py like this:: 2. Include the polls URLconf in your project urls.py like this::
path("polls/", include("polls.urls")), path("polls/", include("django_polls.urls")),
3. Run ``python manage.py migrate`` to create the polls models. 3. Run ``python manage.py migrate`` to create the models.
4. Start the development server and visit http://127.0.0.1:8000/admin/ 4. Start the development server and visit the admin to create a poll.
to create a poll (you'll need the Admin app enabled).
5. Visit http://127.0.0.1:8000/polls/ to participate in the poll. 5. Visit the ``/polls/`` URL to participate in the poll.
#. Create a ``django-polls/LICENSE`` file. Choosing a license is beyond the #. Create a ``django-polls/LICENSE`` file. Choosing a license is beyond the
scope of this tutorial, but suffice it to say that code released publicly scope of this tutorial, but suffice it to say that code released publicly
@ -251,8 +267,8 @@ this. For a small app like polls, this process isn't too difficult.
include LICENSE include LICENSE
include README.rst include README.rst
recursive-include polls/static * recursive-include django_polls/static *
recursive-include polls/templates * recursive-include django_polls/templates *
#. It's optional, but recommended, to include detailed documentation with your #. It's optional, but recommended, to include detailed documentation with your
app. Create an empty directory ``django-polls/docs`` for future app. Create an empty directory ``django-polls/docs`` for future
@ -266,8 +282,8 @@ this. For a small app like polls, this process isn't too difficult.
you add some files to it. Many Django apps also provide their documentation you add some files to it. Many Django apps also provide their documentation
online through sites like `readthedocs.org <https://readthedocs.org>`_. online through sites like `readthedocs.org <https://readthedocs.org>`_.
#. Try building your package with ``python setup.py sdist`` (run from inside #. Try building your package by running ``python setup.py sdist`` inside
``django-polls``). This creates a directory called ``dist`` and builds your ``django-polls``. This creates a directory called ``dist`` and builds your
new package, ``django-polls-0.1.tar.gz``. new package, ``django-polls-0.1.tar.gz``.
For more information on packaging, see Python's `Tutorial on Packaging and For more information on packaging, see Python's `Tutorial on Packaging and
@ -299,14 +315,21 @@ working. We'll now fix this by installing our new ``django-polls`` package.
python -m pip install --user django-polls/dist/django-polls-0.1.tar.gz python -m pip install --user django-polls/dist/django-polls-0.1.tar.gz
#. With luck, your Django project should now work correctly again. Run the #. Update ``mysite/settings.py`` to point to the new module name::
server again to confirm this.
#. To uninstall the package, use pip: INSTALLED_APPS = [
"django_polls.apps.PollsConfig",
...,
]
.. code-block:: shell #. Update ``mysite/urls.py`` to point to the new module name::
python -m pip uninstall django-polls urlpatterns = [
path("polls/", include("django_polls.urls")),
...,
]
#. Run the development server to confirm the project continues to work.
Publishing your app Publishing your app
=================== ===================
@ -326,7 +349,7 @@ the world! If this wasn't just an example, you could now:
Installing Python packages with a virtual environment Installing Python packages with a virtual environment
===================================================== =====================================================
Earlier, we installed the polls app as a user library. This has some Earlier, we installed ``django-polls`` as a user library. This has some
disadvantages: disadvantages:
* Modifying the user libraries can affect other Python software on your system. * Modifying the user libraries can affect other Python software on your system.