#1316 Update packaging-projects.rst with a tip on good module naming

source/discussions/choosing-a-package-module-name.rst

@@ -0,0 +1,36 @@
+Choosing a Package/Module Name
+==============================
+
+This discussion is a complement to :doc:`/tutorials/packaging-projects`.
+
+Make sure to have a valid :ref:`Python identifier <python:identifiers>` for your import package/module name.
+The (PyPI) :term:`project<Project>`/:term:`distribution package <Distribution Package>` name
+and the Python :term:`import package <Import Package>`/module may differ slightly.
+Moreover, one PyPI project/dist may ship more than one module or importable package — it is only possible that one matches the name, others can't.
+For example, your package in :file:`pyproject.toml` and on PyPI may have the name ``abcd-1234``.
+But a module named ``abcd-1234`` would be cumbersome to import in Python,
+since it isn't a valid identifier.
+(It would be cumbersome, completely unnatural and against the long-established conventions in the Python community;
+see, for example, :pep:`8#package-and-module-names`.
+There is a way to import it anyway, see :doc:`importlib <python:library/importlib>` and this question_.)
+
+.. code-block:: pycon
+
+   >>> import abcd-1234
+   >>> from abcd-1234 import something
+
+would not work.
+But having a directory structure with ``src/abcd_1234/`` instead of ``src/abcd-1234/`` has 2 consequences:
+
+- The following works:
+
+  .. code-block:: pycon
+
+     >>> import abcd_1234
+     >>> from abcd_1234 import something
+
+- Hatch will recognize that the module corresponding to the package is ``abcd_1234`` instead of defaulting to ``src`` and building a not working wheel.
+
+More information about :doc:`Python imports <python:reference/import>` and its :doc:`grammar <python:reference/grammar>`.
+
+.. _question: https://stackoverflow.com/questions/8350853/how-to-import-module-when-module-name-has-a-dash-or-hyphen-in-it

source/discussions/index.rst

@@ -14,3 +14,4 @@ specific topic. If you're just trying to get stuff done, see
    wheel-vs-egg
    src-layout-vs-flat-layout
    setup-py-deprecated
+   choosing-a-package-module-name

source/tutorials/packaging-projects.rst

@@ -493,7 +493,7 @@ Make sure you're still in your virtual environment, then run Python:
 
 and import the package:
 
-.. code-block:: python
+.. code-block:: pycon
 
     >>> from example_package_YOUR_USERNAME_HERE import example
     >>> example.add_one(2)
@@ -537,7 +537,7 @@ some things you can do:
   :ref:`pdm`, and :ref:`poetry`.
 * Read :pep:`517` and :pep:`518` for background and details on build tool configuration.
 * Read about :doc:`/guides/packaging-binary-extensions`.
-
+* Read about :doc:`/discussions/choosing-a-package-module-name`.
 
 ----