Copier Template: Support injection of common internals for foundation…

…al packages.

Also:

- Add Pylint plugin for disabling checks by path regexes.

copier.yaml

@@ -138,6 +138,23 @@ enable_publication:
     help: 'Enable package and documentation publication?'
     default: false
 
+inject_foundations:
+    type: bool
+    help: 'Include foundational constructs?'
+    default: false
+
+inject_immutables:
+    type: bool
+    help: 'Include support for immutables with concealment?'
+    when: "{{ inject_foundations }}"
+    default: false
+
+inject_docstring_utils:
+    type: bool
+    help: 'Include utilities for docstring generation?'
+    when: "{{ inject_foundations }}"
+    default: false
+
 gh_owner:
     type: str
     help: Github repository owner

template/documentation/sphinx/conf.py.jinja

@@ -77,6 +77,8 @@ nitpick_ignore = [
     ( 'py:class', "module" ),
     ( 'py:class',
       "v, remove specified key and return the corresponding value." ),
+    # Type annotation weirdnesses.
+    ( 'py:class', "typing_extensions.Any" ),
 ]
 
 # -- Options for linkcheck builder -------------------------------------------

template/pyproject.toml.jinja

@@ -101,6 +101,7 @@ dependencies = [
   'packaging',
   'pre-commit',
   'pylint',
+  'pylint-per-file-ignores',
   'pyright',
   'pytest',
   'ruff',
@@ -233,6 +234,7 @@ load-plugins = [
   'pylint.extensions.redefined_variable_type',
   # 'pylint.extensions.set_membership',
   # 'pylint.extensions.while_used',
+  'pylint_per_file_ignores',
 ]
 recursive = false
 suggestion-mode = true
@@ -305,6 +307,11 @@ disable = [
   'wrong-import-order',
   'wrong-import-position',
 ]
+# TODO: Latest 'per-file-ignores' code may supports dicts and lists in addition to strings.
+per-file-ignores = '''
+  /tests/:attribute-defined-outside-init,magic-value-comparison,missing-class-docstring,missing-function-docstring,protected-access,unexpected-keyword-arg
+  __init__\.py:unused-import
+''' # Note: Paths are regexes.
 [tool.pylint.refactoring]
 max-nested-blocks = 3
 never-returning-functions = [ 'sys.exit', 'argparse.parse_error' ]
@@ -385,7 +392,13 @@ builtins = [ 'ic' ]
 cache-dir = '.auxiliary/caches/ruff'
 [tool.ruff.lint]
 ignore = [
-  'E701', # Multiple statements on one line
+  'E701', # multiple-statements-on-one-line-colon
+]
+[tool.ruff.lint.per-file-ignores]
+'__init__.py' = [
+  'F401', # unused-import
+  'F403', # undefined-local-with-import-star
+  'F405', # undefined-local-with-import-star-usage
 ]
 
 [tool.towncrier]

template/sources/{{ package_name }}/__/__init__.py.jinja

@@ -0,0 +1,34 @@
+# vim: set filetype=python fileencoding=utf-8:
+# -*- coding: utf-8 -*-
+
+#============================================================================#
+#                                                                            #
+#  Licensed under the Apache License, Version 2.0 (the "License");           #
+#  you may not use this file except in compliance with the License.          #
+#  You may obtain a copy of the License at                                   #
+#                                                                            #
+#      http://www.apache.org/licenses/LICENSE-2.0                            #
+#                                                                            #
+#  Unless required by applicable law or agreed to in writing, software       #
+#  distributed under the License is distributed on an "AS IS" BASIS,         #
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  #
+#  See the License for the specific language governing permissions and       #
+#  limitations under the License.                                            #
+#                                                                            #
+#============================================================================#
+
+
+''' Common constants, imports, and utilities. '''
+
+
+# Expose everything from internal modules.
+{%- if inject_docstring_utils %}
+from .docstrings import *  # Managed by Copier.
+{%- endif %}
+{%- if inject_immutables %}
+from .immutables import *  # Managed by Copier.
+{%- endif %}
+from .imports import *
+
+
+__all__ = ( )

template/sources/{{ package_name }}/__.py → template/sources/{{ package_name }}/__/imports.py

@@ -18,22 +18,18 @@
 #============================================================================#
 
 
-''' Common constants, imports, and utilities. '''
+''' Common imports and type aliases used throughout the package. '''
 
-# ruff: noqa: F401
 # pylint: disable=unused-import
+# ruff: noqa: F401
 
 
 from __future__ import annotations
 
 import collections.abc as cabc
-import functools as funct
 import types
 
 import typing_extensions as typx
 
 
 ComparisonResult: typx.TypeAlias = bool | types.NotImplementedType
-
-
-__all__ = ( )

template/sources/{{ package_name }}/__/{% if inject_docstring_utils %}docstrings.py{% endif %}.jinja

@@ -0,0 +1,49 @@
+# vim: set filetype=python fileencoding=utf-8:
+# -*- coding: utf-8 -*-
+
+#============================================================================#
+#                                                                            #
+#  Licensed under the Apache License, Version 2.0 (the "License");           #
+#  you may not use this file except in compliance with the License.          #
+#  You may obtain a copy of the License at                                   #
+#                                                                            #
+#      http://www.apache.org/licenses/LICENSE-2.0                            #
+#                                                                            #
+#  Unless required by applicable law or agreed to in writing, software       #
+#  distributed under the License is distributed on an "AS IS" BASIS,         #
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  #
+#  See the License for the specific language governing permissions and       #
+#  limitations under the License.                                            #
+#                                                                            #
+#============================================================================#
+
+
+''' Docstring utilities. '''
+
+# pylint: disable=unused-wildcard-import,wildcard-import
+# ruff: noqa: F403,F405
+
+
+from __future__ import annotations
+
+from . import doctab
+from .imports import *
+
+
+class Docstring( str ):
+    ''' Dedicated docstring container. '''
+
+
+def generate_docstring(
+    *fragment_ids: type | Docstring | str,
+    table: cabc.Mapping[ str, str ] = doctab.TABLE,
+) -> str:
+    ''' Sews together docstring fragments into clean docstring. '''
+    from inspect import cleandoc, getdoc, isclass
+    fragments: list[ str ] = [ ]
+    for fragment_id in fragment_ids:
+        if isclass( fragment_id ): fragment = getdoc( fragment_id ) or ''
+        elif isinstance( fragment_id, Docstring ): fragment = fragment_id
+        else: fragment = table[ fragment_id ]
+        fragments.append( cleandoc( fragment ) )
+    return '\n\n'.join( fragments )

template/tests/test_000_{{ package_name }}/__init__.py → template/sources/{{ package_name }}/__/{% if inject_docstring_utils %}doctab.py{% endif %}.jinja

@@ -18,9 +18,15 @@
 #============================================================================#
 
 
-''' Package of tests. '''
+''' Docstrings table for reuse across entities. '''
 
-# ruff: noqa: F401
+# pylint: disable=unused-wildcard-import,wildcard-import
+# ruff: noqa: F403,F405
 
 
-from . import __
+from __future__ import annotations
+
+from .imports import *
+
+
+TABLE: types.MappingProxyType[ str, str ] = types.MappingProxyType( { } )