Update question terminology, make validation text more concise (#189)

* Changing question term `module` into `package`.

* Trying to create a multiline validation error.

* Trying a different line break.

* Gave up, used ChatGPT to help shorten the validator message.

* Updated docs to include formatting requirements.

* Update jinja template directory name.

* Update the tests jinja template directory name too.

* Addressing PR comments.

Author: drewoldag

.github/workflows/ci.yml

@@ -16,14 +16,14 @@ jobs:
         python-version: ['3.8', '3.9', '3.10']
         copier_config:
           - name: Base example
-            module_name: example_project # The default module_name
+            package_name: example_project # The default package_name
             extra_flags: ''
             foldername: base_example
           - name: Black w/o example module
-            module_name: 'drewtonian' # Same module name provided in `extra_flags` on the next line.
+            package_name: 'drewtonian' # Same module name provided in `extra_flags` on the next line.
             extra_flags: >-
               --data project_name=new_science
-              --data module_name=drewtonian
+              --data package_name=drewtonian
               --data author_name=Drew
               --data [email protected]
               --data project_license=BSD
@@ -35,10 +35,10 @@ jobs:
               --data use_gitlfs=disabled
             foldername: 'black_w_o_example_module'
           - name: Black w/ example
-            module_name: 'drewtonian' # Same module name provided in `extra_flags` on the next line.
+            package_name: 'drewtonian' # Same module name provided in `extra_flags` on the next line.
             extra_flags: >-
               --data project_name=new_science
-              --data module_name=drewtonian
+              --data package_name=drewtonian
               --data author_name=Drew
               --data [email protected]
               --data project_license=BSD
@@ -50,10 +50,10 @@ jobs:
               --data use_gitlfs=disabled
             foldername: 'black_w_example_module'
           - name: Pylint w/o example
-            module_name: 'drewtonian' # Same module name provided in `extra_flags` on the next line.
+            package_name: 'drewtonian' # Same module name provided in `extra_flags` on the next line.
             extra_flags: >-
               --data project_name=new_science
-              --data module_name=drewtonian
+              --data package_name=drewtonian
               --data author_name=Drew
               --data [email protected]
               --data project_license=BSD
@@ -132,4 +132,4 @@ jobs:
       if: ${{ !contains(matrix.copier_config.extra_flags, 'create_example_module=no') }}
       run: |
         cd ../test/${{ matrix.copier_config.foldername }}
-        python -m pytest tests --cov=${{ matrix.copier_config.module_name }} --cov-report=xml
+        python -m pytest tests --cov=${{ matrix.copier_config.package_name }} --cov-report=xml

copier.yml

@@ -12,16 +12,16 @@ project_name:
     default: example_project
     validator: >-
         {% if not (project_name | regex_search('^[a-z][a-z0-9\_\-]+$')) %}
-        project_name must start with a letter, followed by one or more letters, digits, hyphens, or underscores (all letters lowercase).
+        Must use a lowercase letter followed by one or more of (a-z, 0-9, _, -).
         {% endif %}
 
-module_name:
+package_name:
     type: str
-    help: What is your python module name?
-    default: example_module
+    help: What is your python package name?
+    default: example_package
     validator: >-
-        {% if not (module_name | regex_search('^[a-z][a-z0-9\_]+$')) %}
-        module_name must start with a letter, followed by one or more letters, digits, or underscores (all letters lowercase).
+        {% if not (package_name | regex_search('^[a-z][a-z0-9\_]+$')) %}
+        Must use a lowercase letter followed by one or more of (a-z, 0-9, _).
         {% endif %}
 
 author_name:

docs/source/new_project.rst

@@ -25,9 +25,9 @@ questions:
    * - *Would you like to use simple (default tooling) or customized installation?*
      - If a simple install is used, the template automatically selects the recommended tooling options (linter, isort, and create example module). 
    * - *What is the name of your project?*
-     - The name of your project.
-   * - *What is your python module name?*
-     - The name of your (first) module. This controls where your source code will live (``src/{{module_name}}``).
+     - The name of your project. If you distribute your code via PyPI, this is the name that will be used. This will allow users to pip install like so: ``pip install <project_name>``. The project name must start with a lowercase letter, followed by one or more of the following (a-z, 0-9, _, -).
+   * - *What is your python package name?*
+     - The name of your top level package. Specifies the location of the source code (``src/{{package_name}}``). The package name must start with a lowercase letter, followed by one or more of the following (a-z, 0-9, _).
    * - *Your first and last name?* 
      -  The name of code's author. This will be used in the project and documentation metadata. This name will also be included as part of the copyright license.
    * - *Your preferred email address?*
@@ -41,7 +41,7 @@ questions:
    * - *Would you like to include mypy to perform static type checking for type hints?*
      - `mypy <https://www.mypy-lang.org>`_ performs static type checking on python code that uses `type hints <https://docs.python.org/3/library/typing.html>`_. This type checking makes sure that the correct data types are being used where type hints are defined. If basic or strict type checking is selected, a pre-commit hook and GitHub actions workflow that perform the type checking are added. Basic type checking performs type checks but ignores code or imports for which type hints are not written. Strict type checking enforces type hints are used by giving errors where no type hints are found.
    * - *Do you want to create some example module code?*
-     - If this option is selected the template will create a model in ``src/{{module_name}}`` and create a corresponding example test file. Defaults to ``True`` during simple installation.
+     - If this option is selected the template will create an example module ``src/{{package_name}}/example_module.py`` and test file ``tests/{{package_name}}/test_example_module.py``. Defaults to ``True`` during simple installation.
    * - *Do you want to include rendered notebooks in your documentation?*
      - The requirements to host rendered notebooks on your Read the Docs (or just build them locally) will be included in your project. A sample notebook will be generated and added to your docs as an example.
    * - *Do you want to add a .gitattributes with entries for git-lfs?*

docs/source/update_project.rst

@@ -60,7 +60,7 @@ If you change any of the initial responses during the update you should
 take some time to review your project for any files or directories that are no 
 longer needed. 
 
-For instance, if you change the ``module_name`` response from "new_project" to 
+For instance, if you change the ``package_name`` response from "new_project" to 
 "great_project", it is unlikely that Copier will be able to create a new 
 directory structure, move and rename your existing files, *and* remove the old 
 directory structure.

python-project-template/.github/workflows/testing-and-coverage.yml.jinja

@@ -32,6 +32,6 @@ jobs:
         if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
     - name: Run unit tests with pytest
       run: |
-        python -m pytest tests --cov={{module_name}} --cov-report=xml
+        python -m pytest tests --cov={{package_name}} --cov-report=xml
     - name: Upload coverage report to codecov
       uses: codecov/codecov-action@v3

python-project-template/docs/index.rst.jinja

@@ -1,8 +1,8 @@
-.. {{module_name}} documentation main file.
+.. {{package_name}} documentation main file.
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to {{module_name}}'s documentation!
+Welcome to {{package_name}}'s documentation!
 ========================================================================================
 
 .. toctree::

python-project-template/pyproject.toml.jinja

@@ -60,7 +60,7 @@ requires = [
 build-backend = "setuptools.build_meta"
 
 [tool.setuptools_scm]
-write_to = "src/{{module_name}}/_version.py"
+write_to = "src/{{package_name}}/_version.py"
 {%- if preferred_linter == 'black' %}
 
 [tool.black]
@@ -69,5 +69,5 @@ line-length = 110
 {%- if mypy_type_checking != 'none' %}
 
 [tool.setuptools.package-data]
-{{module_name}} = ["py.typed"]
+{{package_name}} = ["py.typed"]
 {%- endif %}