From 17e76becd7d9ff381ccb260528a351dde7ac2e3e Mon Sep 17 00:00:00 2001 From: Laurent Lyaudet Date: Thu, 30 Nov 2023 22:22:20 +0100 Subject: [PATCH 01/30] Update packaging-projects.rst with a tip on good module naming --- source/tutorials/packaging-projects.rst | 31 +++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/source/tutorials/packaging-projects.rst b/source/tutorials/packaging-projects.rst index 23742c7d8..c5309a4d5 100644 --- a/source/tutorials/packaging-projects.rst +++ b/source/tutorials/packaging-projects.rst @@ -538,7 +538,38 @@ some things you can do: * Read :pep:`517` and :pep:`518` for background and details on build tool configuration. * Read about :doc:`/guides/packaging-binary-extensions`. +.. tip:: + + Make sure to have a valid `Python identifier`_ for your module name. + The PyPI project/dist name and the Python module may differ slightly. + For example, your package in 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. + (There is a way to import it anyway, see importlib_ and this question_.) + + .. code-block:: python + + >>> 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:: python + + >>> 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 `Python imports`_ and its grammar_. +.. _Python identifier: https://docs.python.org/3/reference/lexical_analysis.html#identifiers +.. _importlib: https://docs.python.org/3/library/importlib.html +.. _question: https://stackoverflow.com/questions/8350853/how-to-import-module-when-module-name-has-a-dash-or-hyphen-in-it +.. _Python imports: https://docs.python.org/3/reference/import.html +.. _grammar: https://docs.python.org/3/reference/grammar.html ---- .. rubric:: Notes From 18159962c6e327787b3f6ed340aa42b0dceffe26 Mon Sep 17 00:00:00 2001 From: Laurent Lyaudet Date: Sat, 2 Dec 2023 00:26:01 +0100 Subject: [PATCH 02/30] Update packaging-projects.rst add empty line after items --- source/tutorials/packaging-projects.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/source/tutorials/packaging-projects.rst b/source/tutorials/packaging-projects.rst index c5309a4d5..6a92ffd87 100644 --- a/source/tutorials/packaging-projects.rst +++ b/source/tutorials/packaging-projects.rst @@ -223,7 +223,7 @@ following this tutorial. long as it only contains letters, numbers, ``.``, ``_`` , and ``-``. It also must not already be taken on PyPI. **Be sure to update this with your username** for this tutorial, as this ensures you won't try to upload a - package with the same name as one which already exists. + package with the same name as one which alrPyPUGeady exists. - ``version`` is the package version. (Some build backends allow it to be specified another way, such as from a file or Git tag.) - ``authors`` is used to identify the author of the package; you specify a name @@ -563,6 +563,7 @@ some things you can do: >>> 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 `Python imports`_ and its grammar_. .. _Python identifier: https://docs.python.org/3/reference/lexical_analysis.html#identifiers From 24d81e55de23562cca2432369e8eab50b20955c7 Mon Sep 17 00:00:00 2001 From: Laurent Lyaudet Date: Sat, 2 Dec 2023 00:31:45 +0100 Subject: [PATCH 03/30] Update packaging-projects.rst ??? --- source/tutorials/packaging-projects.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/tutorials/packaging-projects.rst b/source/tutorials/packaging-projects.rst index 6a92ffd87..fe7d74235 100644 --- a/source/tutorials/packaging-projects.rst +++ b/source/tutorials/packaging-projects.rst @@ -223,7 +223,7 @@ following this tutorial. long as it only contains letters, numbers, ``.``, ``_`` , and ``-``. It also must not already be taken on PyPI. **Be sure to update this with your username** for this tutorial, as this ensures you won't try to upload a - package with the same name as one which alrPyPUGeady exists. + package with the same name as one which already exists. - ``version`` is the package version. (Some build backends allow it to be specified another way, such as from a file or Git tag.) - ``authors`` is used to identify the author of the package; you specify a name From b8890ba2f88a5653e88e3da507f3218b8a9b5982 Mon Sep 17 00:00:00 2001 From: Laurent Lyaudet Date: Sat, 2 Dec 2023 00:51:02 +0100 Subject: [PATCH 04/30] Update packaging-projects.rst use intersphinx --- source/tutorials/packaging-projects.rst | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/source/tutorials/packaging-projects.rst b/source/tutorials/packaging-projects.rst index fe7d74235..81f630bdf 100644 --- a/source/tutorials/packaging-projects.rst +++ b/source/tutorials/packaging-projects.rst @@ -540,12 +540,14 @@ some things you can do: .. tip:: - Make sure to have a valid `Python identifier`_ for your module name. + Make sure to have a valid + :doc:`Python identifier ` + for your module name. The PyPI project/dist name and the Python module may differ slightly. For example, your package in 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. - (There is a way to import it anyway, see importlib_ and this question_.) + (There is a way to import it anyway, see :doc:`importlib ` and this question_.) .. code-block:: python @@ -564,13 +566,9 @@ some things you can do: - 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 `Python imports`_ and its grammar_. + More information about :doc:`Python imports ` and its :doc:`grammar `. -.. _Python identifier: https://docs.python.org/3/reference/lexical_analysis.html#identifiers -.. _importlib: https://docs.python.org/3/library/importlib.html .. _question: https://stackoverflow.com/questions/8350853/how-to-import-module-when-module-name-has-a-dash-or-hyphen-in-it -.. _Python imports: https://docs.python.org/3/reference/import.html -.. _grammar: https://docs.python.org/3/reference/grammar.html ---- .. rubric:: Notes From 2779b98b97562c51533b6dd997239556f15569a0 Mon Sep 17 00:00:00 2001 From: Laurent Lyaudet Date: Sat, 2 Dec 2023 22:54:31 +0100 Subject: [PATCH 05/30] Update packaging-projects.rst use correctly intersphinx --- source/tutorials/packaging-projects.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/tutorials/packaging-projects.rst b/source/tutorials/packaging-projects.rst index 81f630bdf..f012863db 100644 --- a/source/tutorials/packaging-projects.rst +++ b/source/tutorials/packaging-projects.rst @@ -541,13 +541,13 @@ some things you can do: .. tip:: Make sure to have a valid - :doc:`Python identifier ` + :ref:`Python identifier ` for your module name. The PyPI project/dist name and the Python module may differ slightly. For example, your package in 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. - (There is a way to import it anyway, see :doc:`importlib ` and this question_.) + (There is a way to import it anyway, see :doc:`importlib ` and this question_.) .. code-block:: python @@ -566,7 +566,7 @@ some things you can do: - 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 ` and its :doc:`grammar `. + More information about :doc:`Python imports ` and its :doc:`grammar `. .. _question: https://stackoverflow.com/questions/8350853/how-to-import-module-when-module-name-has-a-dash-or-hyphen-in-it ---- From c12f3388fb0ec3b200987a352ce5a61d8607194c Mon Sep 17 00:00:00 2001 From: Laurent Lyaudet Date: Sat, 2 Dec 2023 23:26:34 +0100 Subject: [PATCH 06/30] LL: create discussion choosing-a-module-name and link between it and packaging-projects. --- source/discussions/choosing-a-module-name.rst | 33 +++++++++++++++++++ source/tutorials/packaging-projects.rst | 32 +----------------- 2 files changed, 34 insertions(+), 31 deletions(-) create mode 100644 source/discussions/choosing-a-module-name.rst diff --git a/source/discussions/choosing-a-module-name.rst b/source/discussions/choosing-a-module-name.rst new file mode 100644 index 000000000..9df384189 --- /dev/null +++ b/source/discussions/choosing-a-module-name.rst @@ -0,0 +1,33 @@ +Choosing a Module Name +========================= + +This discussion is a complement to :doc:`tutorials/packaging-projects`. + +Make sure to have a valid :ref:`Python identifier ` for your module name. +The PyPI project/dist name and the Python module may differ slightly. +For example, your package in 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. +(There is a way to import it anyway, see :doc:`importlib ` and this question_.) + +.. code-block:: python + + >>> 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:: python + + >>> 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 ` and its :doc:`grammar `. + +.. _question: https://stackoverflow.com/questions/8350853/how-to-import-module-when-module-name-has-a-dash-or-hyphen-in-it + diff --git a/source/tutorials/packaging-projects.rst b/source/tutorials/packaging-projects.rst index f012863db..ad63309b8 100644 --- a/source/tutorials/packaging-projects.rst +++ b/source/tutorials/packaging-projects.rst @@ -537,38 +537,8 @@ 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-module-name`. -.. tip:: - - Make sure to have a valid - :ref:`Python identifier ` - for your module name. - The PyPI project/dist name and the Python module may differ slightly. - For example, your package in 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. - (There is a way to import it anyway, see :doc:`importlib ` and this question_.) - - .. code-block:: python - - >>> 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:: python - - >>> 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 ` and its :doc:`grammar `. - -.. _question: https://stackoverflow.com/questions/8350853/how-to-import-module-when-module-name-has-a-dash-or-hyphen-in-it ---- .. rubric:: Notes From cc8ffd5b3111f2e2e9c5da04834de895c897d99e Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Sat, 2 Dec 2023 22:27:10 +0000 Subject: [PATCH 07/30] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- source/discussions/choosing-a-module-name.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/source/discussions/choosing-a-module-name.rst b/source/discussions/choosing-a-module-name.rst index 9df384189..ecc0a4fa3 100644 --- a/source/discussions/choosing-a-module-name.rst +++ b/source/discussions/choosing-a-module-name.rst @@ -30,4 +30,3 @@ But having a directory structure with src/abcd_1234/ instead of src/abcd-1234/ h More information about :doc:`Python imports ` and its :doc:`grammar `. .. _question: https://stackoverflow.com/questions/8350853/how-to-import-module-when-module-name-has-a-dash-or-hyphen-in-it - From 614bf97fb273a1fcbcb3c33ad7e6e712e062a77a Mon Sep 17 00:00:00 2001 From: Laurent Lyaudet Date: Sat, 2 Dec 2023 23:40:00 +0100 Subject: [PATCH 08/30] LL: correction nox build. --- source/discussions/choosing-a-module-name.rst | 2 +- source/discussions/index.rst | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/source/discussions/choosing-a-module-name.rst b/source/discussions/choosing-a-module-name.rst index ecc0a4fa3..e30e20e6d 100644 --- a/source/discussions/choosing-a-module-name.rst +++ b/source/discussions/choosing-a-module-name.rst @@ -1,7 +1,7 @@ Choosing a Module Name ========================= -This discussion is a complement to :doc:`tutorials/packaging-projects`. +This discussion is a complement to :doc:`/tutorials/packaging-projects`. Make sure to have a valid :ref:`Python identifier ` for your module name. The PyPI project/dist name and the Python module may differ slightly. diff --git a/source/discussions/index.rst b/source/discussions/index.rst index e5411ece3..5c75a23f9 100644 --- a/source/discussions/index.rst +++ b/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-module-name From 5f7790eba460ee64d2178307d7b1fec8ed9838cd Mon Sep 17 00:00:00 2001 From: Laurent Lyaudet Date: Sun, 3 Dec 2023 12:36:40 +0100 Subject: [PATCH 09/30] Update source/discussions/choosing-a-module-name.rst Co-authored-by: Sviatoslav Sydorenko --- source/discussions/choosing-a-module-name.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/discussions/choosing-a-module-name.rst b/source/discussions/choosing-a-module-name.rst index e30e20e6d..310ff5a70 100644 --- a/source/discussions/choosing-a-module-name.rst +++ b/source/discussions/choosing-a-module-name.rst @@ -5,7 +5,7 @@ This discussion is a complement to :doc:`/tutorials/packaging-projects`. Make sure to have a valid :ref:`Python identifier ` for your module name. The PyPI project/dist name and the Python module may differ slightly. -For example, your package in pyproject.toml and on PyPI may have the name abcd-1234. +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. (There is a way to import it anyway, see :doc:`importlib ` and this question_.) From 408d7aa2eb1ced874e88629deb7e5e8f478d081c Mon Sep 17 00:00:00 2001 From: Laurent Lyaudet Date: Sun, 3 Dec 2023 12:38:39 +0100 Subject: [PATCH 10/30] Update source/discussions/choosing-a-module-name.rst Co-authored-by: Sviatoslav Sydorenko --- source/discussions/choosing-a-module-name.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/discussions/choosing-a-module-name.rst b/source/discussions/choosing-a-module-name.rst index 310ff5a70..7d520abc1 100644 --- a/source/discussions/choosing-a-module-name.rst +++ b/source/discussions/choosing-a-module-name.rst @@ -10,7 +10,7 @@ But a module named abcd-1234 would be cumbersome to import in Python, since it isn't a valid identifier. (There is a way to import it anyway, see :doc:`importlib ` and this question_.) -.. code-block:: python +.. code-block:: pycon >>> import abcd-1234 >>> from abcd-1234 import something From 2893273c348a03072a6bbb332b2271be359541fe Mon Sep 17 00:00:00 2001 From: Laurent Lyaudet Date: Sun, 3 Dec 2023 12:42:22 +0100 Subject: [PATCH 11/30] LL: correction code-block python -> pycon. --- source/discussions/choosing-a-module-name.rst | 2 +- source/tutorials/packaging-projects.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/source/discussions/choosing-a-module-name.rst b/source/discussions/choosing-a-module-name.rst index 7d520abc1..b1f2a3e2f 100644 --- a/source/discussions/choosing-a-module-name.rst +++ b/source/discussions/choosing-a-module-name.rst @@ -20,7 +20,7 @@ But having a directory structure with src/abcd_1234/ instead of src/abcd-1234/ h - The following works: - .. code-block:: python + .. code-block:: pycon >>> import abcd_1234 >>> from abcd_1234 import something diff --git a/source/tutorials/packaging-projects.rst b/source/tutorials/packaging-projects.rst index ad63309b8..cb09d9fba 100644 --- a/source/tutorials/packaging-projects.rst +++ b/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) From 81d8d5209f2fbe2326b5ca65d8052a7469466f4d Mon Sep 17 00:00:00 2001 From: Laurent Lyaudet Date: Sun, 3 Dec 2023 12:45:11 +0100 Subject: [PATCH 12/30] LL : more markup in choosing-a-module-name. --- source/discussions/choosing-a-module-name.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/source/discussions/choosing-a-module-name.rst b/source/discussions/choosing-a-module-name.rst index b1f2a3e2f..af7eb679e 100644 --- a/source/discussions/choosing-a-module-name.rst +++ b/source/discussions/choosing-a-module-name.rst @@ -5,8 +5,9 @@ This discussion is a complement to :doc:`/tutorials/packaging-projects`. Make sure to have a valid :ref:`Python identifier ` for your module name. The PyPI project/dist name and the Python 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, +But a module named ``abcd-1234`` would be cumbersome to import in Python, since it isn't a valid identifier. (There is a way to import it anyway, see :doc:`importlib ` and this question_.) @@ -16,7 +17,7 @@ since it isn't a valid identifier. >>> 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: +But having a directory structure with ``src/abcd_1234/`` instead of ``src/abcd-1234/`` has 2 consequences: - The following works: @@ -25,7 +26,7 @@ But having a directory structure with src/abcd_1234/ instead of src/abcd-1234/ h >>> 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. +- 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 ` and its :doc:`grammar `. From 43e64d9cd75aa6686bd7b5baaf5c603ddda3451c Mon Sep 17 00:00:00 2001 From: Laurent Lyaudet Date: Sun, 3 Dec 2023 20:23:46 +0100 Subject: [PATCH 13/30] LL: add warning and ref to PEP8 for unnatural module names. --- source/discussions/choosing-a-module-name.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/source/discussions/choosing-a-module-name.rst b/source/discussions/choosing-a-module-name.rst index af7eb679e..e5b3a27ce 100644 --- a/source/discussions/choosing-a-module-name.rst +++ b/source/discussions/choosing-a-module-name.rst @@ -9,7 +9,9 @@ Moreover, one PyPI project/dist may ship more than one module or importable pack 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. -(There is a way to import it anyway, see :doc:`importlib ` and this question_.) +(It would be cumbersone, 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 ` and this question_.) .. code-block:: pycon From 76bb7bf08b96d9e81e9329e1b2c3be7cb9b00337 Mon Sep 17 00:00:00 2001 From: Laurent Lyaudet Date: Sun, 3 Dec 2023 20:31:05 +0100 Subject: [PATCH 14/30] LL: add import package since import packages are a special case of modules. --- ...a-module-name.rst => choosing-a-package-module-name.rst} | 6 +++--- source/discussions/index.rst | 2 +- source/tutorials/packaging-projects.rst | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) rename source/discussions/{choosing-a-module-name.rst => choosing-a-package-module-name.rst} (90%) diff --git a/source/discussions/choosing-a-module-name.rst b/source/discussions/choosing-a-package-module-name.rst similarity index 90% rename from source/discussions/choosing-a-module-name.rst rename to source/discussions/choosing-a-package-module-name.rst index e5b3a27ce..4d387a8ad 100644 --- a/source/discussions/choosing-a-module-name.rst +++ b/source/discussions/choosing-a-package-module-name.rst @@ -1,10 +1,10 @@ -Choosing a Module Name +Choosing a Package/Module Name ========================= This discussion is a complement to :doc:`/tutorials/packaging-projects`. -Make sure to have a valid :ref:`Python identifier ` for your module name. -The PyPI project/dist name and the Python module may differ slightly. +Make sure to have a valid :ref:`Python identifier ` for your import package/module name. +The PyPI project/dist name and the Python 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, diff --git a/source/discussions/index.rst b/source/discussions/index.rst index 5c75a23f9..a52f53de3 100644 --- a/source/discussions/index.rst +++ b/source/discussions/index.rst @@ -14,4 +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-module-name + choosing-a-package-module-name diff --git a/source/tutorials/packaging-projects.rst b/source/tutorials/packaging-projects.rst index cb09d9fba..63b78ea8e 100644 --- a/source/tutorials/packaging-projects.rst +++ b/source/tutorials/packaging-projects.rst @@ -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-module-name`. +* Read about :doc:`/discussions/choosing-a-package-module-name`. ---- From 4e5053e3b4e012c5de054ad05c77b0b5577282c8 Mon Sep 17 00:00:00 2001 From: Laurent Lyaudet Date: Sun, 3 Dec 2023 20:53:06 +0100 Subject: [PATCH 15/30] LL: clarify terminology with links to the glossary. --- source/discussions/choosing-a-package-module-name.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/source/discussions/choosing-a-package-module-name.rst b/source/discussions/choosing-a-package-module-name.rst index 4d387a8ad..b405d9a17 100644 --- a/source/discussions/choosing-a-package-module-name.rst +++ b/source/discussions/choosing-a-package-module-name.rst @@ -4,7 +4,8 @@ Choosing a Package/Module Name This discussion is a complement to :doc:`/tutorials/packaging-projects`. Make sure to have a valid :ref:`Python identifier ` for your import package/module name. -The PyPI project/dist name and the Python package/module may differ slightly. +The (PyPI) :term:`project`/:term:`distribution package ` name +and the Python :term:`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, From 8f314aed7b263f4ee6adca57c87a6aa0b7b77c95 Mon Sep 17 00:00:00 2001 From: Laurent Lyaudet Date: Sun, 3 Dec 2023 20:55:37 +0100 Subject: [PATCH 16/30] LL: typo cumbersone -> cumbersome. --- source/discussions/choosing-a-package-module-name.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/discussions/choosing-a-package-module-name.rst b/source/discussions/choosing-a-package-module-name.rst index b405d9a17..07e6aa586 100644 --- a/source/discussions/choosing-a-package-module-name.rst +++ b/source/discussions/choosing-a-package-module-name.rst @@ -10,7 +10,7 @@ Moreover, one PyPI project/dist may ship more than one module or importable pack 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 cumbersone, completely unnatural and against the long-established conventions in the Python community; +(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 ` and this question_.) From 8115dae68c67a74997fb1b74689e7ebb32f5da9c Mon Sep 17 00:00:00 2001 From: Laurent Lyaudet Date: Sun, 3 Dec 2023 21:03:56 +0100 Subject: [PATCH 17/30] LL: correction Title underline too short. --- source/discussions/choosing-a-package-module-name.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/discussions/choosing-a-package-module-name.rst b/source/discussions/choosing-a-package-module-name.rst index 07e6aa586..d82cb390d 100644 --- a/source/discussions/choosing-a-package-module-name.rst +++ b/source/discussions/choosing-a-package-module-name.rst @@ -1,5 +1,5 @@ Choosing a Package/Module Name -========================= +============================== This discussion is a complement to :doc:`/tutorials/packaging-projects`. From 23e289e5ab467062fbb5215f9afaac5f7d7c643a Mon Sep 17 00:00:00 2001 From: Laurent Lyaudet Date: Sun, 10 Dec 2023 22:13:20 +0100 Subject: [PATCH 18/30] Update source/discussions/choosing-a-package-module-name.rst Co-authored-by: sinoroc <5529267+sinoroc@users.noreply.github.com> --- source/discussions/choosing-a-package-module-name.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/discussions/choosing-a-package-module-name.rst b/source/discussions/choosing-a-package-module-name.rst index d82cb390d..603e5dcc2 100644 --- a/source/discussions/choosing-a-package-module-name.rst +++ b/source/discussions/choosing-a-package-module-name.rst @@ -3,7 +3,7 @@ Choosing a Package/Module Name This discussion is a complement to :doc:`/tutorials/packaging-projects`. -Make sure to have a valid :ref:`Python identifier ` for your import package/module name. +Make sure to choose a valid :ref:`Python identifier ` for the names of all your :term:`import packages ` and :term:`modules `. The (PyPI) :term:`project`/:term:`distribution package ` name and the Python :term:`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. From de7fbfaa2d36c1cdd2904eef2b59aaf9a9a1c8a3 Mon Sep 17 00:00:00 2001 From: Laurent Lyaudet Date: Sun, 10 Dec 2023 22:23:58 +0100 Subject: [PATCH 19/30] LL: add recommendation to have only one importable package. --- source/discussions/choosing-a-package-module-name.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/source/discussions/choosing-a-package-module-name.rst b/source/discussions/choosing-a-package-module-name.rst index 603e5dcc2..c3c9c4224 100644 --- a/source/discussions/choosing-a-package-module-name.rst +++ b/source/discussions/choosing-a-package-module-name.rst @@ -6,7 +6,10 @@ This discussion is a complement to :doc:`/tutorials/packaging-projects`. Make sure to choose a valid :ref:`Python identifier ` for the names of all your :term:`import packages ` and :term:`modules `. The (PyPI) :term:`project`/:term:`distribution package ` name and the Python :term:`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. +It is recommended to have only one importable package, with a name as similar as possible as the `dist-info` file in the installation folder. + 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. From f96255487b1b7f188d3eca44b4fd7f3428d85098 Mon Sep 17 00:00:00 2001 From: Laurent Lyaudet Date: Sun, 10 Dec 2023 22:30:47 +0100 Subject: [PATCH 20/30] Update source/discussions/choosing-a-package-module-name.rst Co-authored-by: sinoroc <5529267+sinoroc@users.noreply.github.com> --- source/discussions/choosing-a-package-module-name.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/source/discussions/choosing-a-package-module-name.rst b/source/discussions/choosing-a-package-module-name.rst index c3c9c4224..2b3122527 100644 --- a/source/discussions/choosing-a-package-module-name.rst +++ b/source/discussions/choosing-a-package-module-name.rst @@ -4,8 +4,7 @@ Choosing a Package/Module Name This discussion is a complement to :doc:`/tutorials/packaging-projects`. Make sure to choose a valid :ref:`Python identifier ` for the names of all your :term:`import packages ` and :term:`modules `. -The (PyPI) :term:`project`/:term:`distribution package ` name -and the Python :term:`import package `/module may differ slightly. +The name of the :term:`project` and the name of the :term:`distribution package` are one and the same. The name of the project and the name of the top-level :term:`import package` (or :term:`module`) can be different. 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. It is recommended to have only one importable package, with a name as similar as possible as the `dist-info` file in the installation folder. From b5fdb5c1b96410787f2ac600f0b224c3f66e1f3f Mon Sep 17 00:00:00 2001 From: Laurent Lyaudet Date: Sun, 10 Dec 2023 22:33:06 +0100 Subject: [PATCH 21/30] LL: PyPI back after applying suggestion. --- source/discussions/choosing-a-package-module-name.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/source/discussions/choosing-a-package-module-name.rst b/source/discussions/choosing-a-package-module-name.rst index 2b3122527..016fd8915 100644 --- a/source/discussions/choosing-a-package-module-name.rst +++ b/source/discussions/choosing-a-package-module-name.rst @@ -4,7 +4,9 @@ Choosing a Package/Module Name This discussion is a complement to :doc:`/tutorials/packaging-projects`. Make sure to choose a valid :ref:`Python identifier ` for the names of all your :term:`import packages ` and :term:`modules `. -The name of the :term:`project` and the name of the :term:`distribution package` are one and the same. The name of the project and the name of the top-level :term:`import package` (or :term:`module`) can be different. +The name of the :term:`project` and the name of the :term:`distribution package` are one and the same. +It is the name you will see on PyPI, for example. +The name of the project and the name of the top-level :term:`import package` (or :term:`module`) can be different. 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. It is recommended to have only one importable package, with a name as similar as possible as the `dist-info` file in the installation folder. From b93f306e817b2541ff82b8ff0abf4de15a90e23e Mon Sep 17 00:00:00 2001 From: Laurent Lyaudet Date: Sun, 10 Dec 2023 22:56:20 +0100 Subject: [PATCH 22/30] LL: partial rewrite following in part suggestions by sinoroc. --- .../choosing-a-package-module-name.rst | 28 +++++++++++++------ 1 file changed, 19 insertions(+), 9 deletions(-) diff --git a/source/discussions/choosing-a-package-module-name.rst b/source/discussions/choosing-a-package-module-name.rst index 016fd8915..8377b297e 100644 --- a/source/discussions/choosing-a-package-module-name.rst +++ b/source/discussions/choosing-a-package-module-name.rst @@ -11,20 +11,27 @@ The name of the project and the name of the top-level :term:`import package` (or 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. It is recommended to have only one importable package, with a name as similar as possible as the `dist-info` file in the installation folder. -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 ` and this question_.) +Project names (usually found in :file:`pyproject.toml`) and import package names follow different rules and conventions. +The normalized form (and thus the preferred form) for project names +is the so-called "kebab case" (see :ref:`name normalization`), for example ``abcd-1234``. +But import packages and modules should have a valid Python identifier as a name. +With an import package name ``abcd-1234``, the following would not work: .. 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: +Since ``abcd-1234`` is not a valid Python identifier. +(Importing such a module 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 ` and this question_.) + +:ref:`Python identifiers ` follow the so-called "snake case". +The preferred form for an import package name is ``abcd_1234`` which is a valid Python identifier. +Note the underscore ``_`` as separation character instead of of the dash ``-`` seen in the project name. + +Having a directory structure with ``src/abcd_1234/`` instead of ``src/abcd-1234/`` has 2 consequences: - The following works: @@ -33,7 +40,10 @@ But having a directory structure with ``src/abcd_1234/`` instead of ``src/abcd-1 >>> 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. +- All four build backends covered in the tutorial :doc:`/tutorials/packaging-projects` will work: + + - Flit will not crash with an error; + - 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 ` and its :doc:`grammar `. From a1745efb585ddae74aa8319dae4f25c4336c29b6 Mon Sep 17 00:00:00 2001 From: Laurent Lyaudet Date: Sun, 10 Dec 2023 23:21:31 +0100 Subject: [PATCH 23/30] LL: add section on the consequences of naming for consistency of the build files. --- .../choosing-a-package-module-name.rst | 21 +++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/source/discussions/choosing-a-package-module-name.rst b/source/discussions/choosing-a-package-module-name.rst index 8377b297e..c25966c8b 100644 --- a/source/discussions/choosing-a-package-module-name.rst +++ b/source/discussions/choosing-a-package-module-name.rst @@ -47,4 +47,25 @@ Having a directory structure with ``src/abcd_1234/`` instead of ``src/abcd-1234/ More information about :doc:`Python imports ` and its :doc:`grammar `. +Another aspect of choosing a package/module name is the naming consistency +of the files generated by the build backend. +With the four build backends covered in the tutorial (Flit, Hatchling, PDM, and setuptools), +when the correct import package is found, its name is always leaved as is. + +But, starting from the project name, the build backend also generates: +- an archive file like ``abcd_1234-1.0.0.tar.gz`` with Flit, Hatchling, and PDM, + or ``abcd-1234-1.0.0.tar.gz`` with setup-tools; + here we can see that some backends but not all + apply a normalization on the project name: lowercase, underscore ("snake case") instead of hyphen; +- a wheel like ``abcd_1234-1.0.0-py3-none-any.whl`` with all build backends; +- a dist-info like ``abcd_1234-1.0.0.dist-info`` with all build backends; +- in the case of setuptools, an egg-info like ``abcd_1234-1.0.0.egg-info``. + +Thus, except for the archive with setuptools, all prefixes of filenames +use a normalization of project name. +This normalization will match an import package name chosen consistently +by normalization of the project name. +You may see an interest in installing a wheel named ``abcd_1234-1.0.0-py3-none-any.whl``, +and having as a result ``abcd_1234-1.0.0.dist-info`` and ``abcd_1234/`` (or ``abcd_1234.py``) in your installation directory :). + .. _question: https://stackoverflow.com/questions/8350853/how-to-import-module-when-module-name-has-a-dash-or-hyphen-in-it From dfe196ddd28cb6e5f4d0dbfd17cdb08e27e4efd8 Mon Sep 17 00:00:00 2001 From: Laurent Lyaudet Date: Sun, 10 Dec 2023 23:26:20 +0100 Subject: [PATCH 24/30] LL: refs for build backends. --- source/discussions/choosing-a-package-module-name.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/source/discussions/choosing-a-package-module-name.rst b/source/discussions/choosing-a-package-module-name.rst index c25966c8b..5667f0f71 100644 --- a/source/discussions/choosing-a-package-module-name.rst +++ b/source/discussions/choosing-a-package-module-name.rst @@ -49,7 +49,8 @@ More information about :doc:`Python imports ` and its : Another aspect of choosing a package/module name is the naming consistency of the files generated by the build backend. -With the four build backends covered in the tutorial (Flit, Hatchling, PDM, and setuptools), +With the four build backends covered in the tutorial +(:ref:`Flit `, :ref:`Hatchling `, :ref:`PDM `, and :ref:`setuptools`), when the correct import package is found, its name is always leaved as is. But, starting from the project name, the build backend also generates: From 7a5230530cd67aac8aad96d21f3ff0f7fa8e1a4b Mon Sep 17 00:00:00 2001 From: Laurent Lyaudet Date: Sun, 10 Dec 2023 23:27:22 +0100 Subject: [PATCH 25/30] LL: missing new line before pycon. --- source/discussions/choosing-a-package-module-name.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/source/discussions/choosing-a-package-module-name.rst b/source/discussions/choosing-a-package-module-name.rst index 5667f0f71..4a18622c8 100644 --- a/source/discussions/choosing-a-package-module-name.rst +++ b/source/discussions/choosing-a-package-module-name.rst @@ -17,6 +17,7 @@ is the so-called "kebab case" (see :ref:`name normalization`), for example ``abc But import packages and modules should have a valid Python identifier as a name. With an import package name ``abcd-1234``, the following would not work: + .. code-block:: pycon >>> import abcd-1234 From 8a20cac48c3fd1d5f79b372bbb59372fd20225e1 Mon Sep 17 00:00:00 2001 From: Laurent Lyaudet Date: Sun, 10 Dec 2023 23:31:42 +0100 Subject: [PATCH 26/30] LL: another missing new line. --- source/discussions/choosing-a-package-module-name.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/source/discussions/choosing-a-package-module-name.rst b/source/discussions/choosing-a-package-module-name.rst index 4a18622c8..91a8bf7bd 100644 --- a/source/discussions/choosing-a-package-module-name.rst +++ b/source/discussions/choosing-a-package-module-name.rst @@ -55,6 +55,7 @@ With the four build backends covered in the tutorial when the correct import package is found, its name is always leaved as is. But, starting from the project name, the build backend also generates: + - an archive file like ``abcd_1234-1.0.0.tar.gz`` with Flit, Hatchling, and PDM, or ``abcd-1234-1.0.0.tar.gz`` with setup-tools; here we can see that some backends but not all From eecfc2ff418e12c2e706b697a5f03d441a33889f Mon Sep 17 00:00:00 2001 From: Laurent Lyaudet Date: Sun, 10 Dec 2023 23:34:36 +0100 Subject: [PATCH 27/30] LL: correction `dist-info` -> ``dist-info``. --- source/discussions/choosing-a-package-module-name.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/discussions/choosing-a-package-module-name.rst b/source/discussions/choosing-a-package-module-name.rst index 91a8bf7bd..d4d194161 100644 --- a/source/discussions/choosing-a-package-module-name.rst +++ b/source/discussions/choosing-a-package-module-name.rst @@ -9,7 +9,7 @@ It is the name you will see on PyPI, for example. The name of the project and the name of the top-level :term:`import package` (or :term:`module`) can be different. 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. -It is recommended to have only one importable package, with a name as similar as possible as the `dist-info` file in the installation folder. +It is recommended to have only one importable package, with a name as similar as possible as the ``dist-info`` file in the installation folder. Project names (usually found in :file:`pyproject.toml`) and import package names follow different rules and conventions. The normalized form (and thus the preferred form) for project names From 7d29053084877a3556bc43b1bc13e86dfe521c31 Mon Sep 17 00:00:00 2001 From: Laurent Lyaudet Date: Sun, 10 Dec 2023 23:44:22 +0100 Subject: [PATCH 28/30] LL: correct name normalization ref that fails in nox. --- source/discussions/choosing-a-package-module-name.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/discussions/choosing-a-package-module-name.rst b/source/discussions/choosing-a-package-module-name.rst index d4d194161..06e46fe7a 100644 --- a/source/discussions/choosing-a-package-module-name.rst +++ b/source/discussions/choosing-a-package-module-name.rst @@ -13,7 +13,7 @@ It is recommended to have only one importable package, with a name as similar as Project names (usually found in :file:`pyproject.toml`) and import package names follow different rules and conventions. The normalized form (and thus the preferred form) for project names -is the so-called "kebab case" (see :ref:`name normalization`), for example ``abcd-1234``. +is the so-called "kebab case" (see :doc:`/specifications/name-normalization`), for example ``abcd-1234``. But import packages and modules should have a valid Python identifier as a name. With an import package name ``abcd-1234``, the following would not work: From fcff555551ca6f02b7ad7fbcda3ef56c8728b650 Mon Sep 17 00:00:00 2001 From: Laurent Lyaudet Date: Sun, 10 Dec 2023 23:50:36 +0100 Subject: [PATCH 29/30] LL: warning about 2 types of name normalization. --- source/discussions/choosing-a-package-module-name.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/source/discussions/choosing-a-package-module-name.rst b/source/discussions/choosing-a-package-module-name.rst index 06e46fe7a..580e64110 100644 --- a/source/discussions/choosing-a-package-module-name.rst +++ b/source/discussions/choosing-a-package-module-name.rst @@ -60,6 +60,8 @@ But, starting from the project name, the build backend also generates: or ``abcd-1234-1.0.0.tar.gz`` with setup-tools; here we can see that some backends but not all apply a normalization on the project name: lowercase, underscore ("snake case") instead of hyphen; + note that we do not talk about the same normalization referenced at the beginning of this document + (:doc:`/specifications/name-normalization`); - a wheel like ``abcd_1234-1.0.0-py3-none-any.whl`` with all build backends; - a dist-info like ``abcd_1234-1.0.0.dist-info`` with all build backends; - in the case of setuptools, an egg-info like ``abcd_1234-1.0.0.egg-info``. From 401d037fa3c3acb0d6fe6d447043f20f7e5a55f0 Mon Sep 17 00:00:00 2001 From: Laurent Lyaudet Date: Mon, 11 Dec 2023 00:00:40 +0100 Subject: [PATCH 30/30] LL: naming gymnastic at the end with a little joke :). --- source/discussions/choosing-a-package-module-name.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/source/discussions/choosing-a-package-module-name.rst b/source/discussions/choosing-a-package-module-name.rst index 580e64110..6d5eee522 100644 --- a/source/discussions/choosing-a-package-module-name.rst +++ b/source/discussions/choosing-a-package-module-name.rst @@ -71,6 +71,7 @@ use a normalization of project name. This normalization will match an import package name chosen consistently by normalization of the project name. You may see an interest in installing a wheel named ``abcd_1234-1.0.0-py3-none-any.whl``, -and having as a result ``abcd_1234-1.0.0.dist-info`` and ``abcd_1234/`` (or ``abcd_1234.py``) in your installation directory :). +and having as a result ``abcd_1234-1.0.0.dist-info`` and ``abcd_1234/`` (or ``abcd_1234.py``) in your installation directory :) +(instead of a project ``aBcD-1234``, a wheel ``abcd_1234-1.0.0-py3-none-any.whl``, installing ``abcd_1234-1.0.0.dist-info`` and ``4-3-2-1cDbA/`` ;) ). .. _question: https://stackoverflow.com/questions/8350853/how-to-import-module-when-module-name-has-a-dash-or-hyphen-in-it