emcd-projects 1.15rc0__tar.gz → 1.17rc0__tar.gz

{emcd_projects-1.15rc0 → emcd_projects-1.17rc0}/.gitignore

@@ -4,3 +4,5 @@
 __pycache__/
 bugs/
 dist/
+CLAUDE.md
+codex.md

{emcd_projects-1.15rc0 → emcd_projects-1.17rc0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: emcd-projects
-Version: 1.15rc0
+Version: 1.17rc0
 Summary: Project management utilities.
 Project-URL: Homepage, https://github.com/emcd/python-project-common
 Project-URL: Documentation, https://emcd.github.io/python-project-common

emcd_projects-1.17rc0/data/copier/answers-default.yaml

@@ -0,0 +1,4 @@
+project_name: python-test-defaults
+distribution_name: emcdproj-defaults
+package_name: defaults
+description: 'All configuration options are defaults.'

emcd_projects-1.17rc0/data/copier/answers-maximum.yaml

@@ -0,0 +1,14 @@
+project_name: python-test-maximum
+distribution_name: emcdproj-maximum
+package_name: maximum
+description: 'All configuration options set.'
+enable_rust_extension: true
+include_data_resources: true
+enable_property_tests: true
+enable_publication: true
+enable_cli: true
+enable_executables: true
+inject_foundations: true
+inject_exceptions: true
+inject_immutables: true
+inject_docstring_utils: true

emcd_projects-1.17rc0/pyproject.toml

@@ -0,0 +1,329 @@
+# vim: set filetype=toml fileencoding=utf-8:
+# -*- mode: toml ; coding: utf-8 -*-
+
+[build-system]
+requires = [
+  'hatchling',
+]
+build-backend = 'hatchling.build'
+
+[project]
+name = 'emcd-projects'
+description = 'Project management utilities.'
+dynamic = [ 'version' ]
+license = 'Apache-2.0'
+readme = { 'file' = 'sources/emcdproj/README.rst', 'content-type' = 'text/x-rst' }
+requires-python = '>= 3.10'
+dependencies = [
+  'Jinja2',
+  'absence',
+  'defusedxml',
+  'frigid',
+  'icecream-truck',
+  'importlib-metadata', # TODO: Drop once we have separate appcore package.
+  'importlib-resources', # TODO: Drop once we have separate appcore package.
+  'packaging',
+  'platformdirs', # TODO: Drop once we have separate appcore package.
+  'tomli', # TODO: Drop once we have separate appcore package.
+  'typing-extensions',
+  # --- BEGIN: Injected by Copier ---
+  'tyro',
+  # --- END: Injected by Copier ---
+]
+classifiers = [ # https://pypi.org/classifiers
+  'Development Status :: 3 - Alpha',
+  'Intended Audience :: Developers',
+  'License :: OSI Approved :: Apache Software License',
+  'Programming Language :: Python :: 3 :: Only',
+  # --- BEGIN: Injected by Copier ---
+  'Programming Language :: Python :: 3.10',
+  'Programming Language :: Python :: 3.11',
+  'Programming Language :: Python :: 3.12',
+  'Programming Language :: Python :: 3.13',
+  'Programming Language :: Python :: Implementation :: CPython',
+  'Programming Language :: Python :: Implementation :: PyPy',
+  # --- END: Injected by Copier ---
+  'Topic :: Software Development',
+]
+keywords = [ 'maintenance', 'project', 'template' ]
+[[project.authors]]
+name = 'Eric McDonald'
+email = 'emcd@users.noreply.github.com'
+[project.scripts]
+emcdproj = 'emcdproj:main'
+[project.urls]
+'Homepage' = 'https://github.com/emcd/python-project-common'
+'Documentation' = 'https://emcd.github.io/python-project-common'
+'Download' = 'https://pypi.org/project/emcd-projects/#files'
+'Source Code' = 'https://github.com/emcd/python-project-common'
+'Issue Tracker' = 'https://github.com/emcd/python-project-common/issues'
+
+[tool.SELF]
+year-of-origin = 2024
+
+# https://coverage.readthedocs.io/en/latest/config.html
+[tool.coverage.paths]
+gha-runners = [
+  '/home/runner/work/python-project-common/python-project-common/',
+  '/Users/runner/work/python-project-common/python-project-common/',
+  'D:\a\python-project-common\python-project-common\',
+]
+[tool.coverage.run]
+branch = true
+command_line = '-m pytest' # TODO? '--fail-under'
+data_file = '.auxiliary/caches/pytest/coverage.sqlite3'
+parallel = true
+source = [ 'sources' ]
+[tool.coverage.html]
+directory = '.auxiliary/artifacts/coverage-pytest'
+[tool.coverage.xml]
+output = '.auxiliary/artifacts/coverage-pytest/coverage.xml'
+
+# https://hatch.pypa.io/latest/config/metadata/
+[tool.hatch.build]
+directory = '.auxiliary/artifacts/hatch-build'
+[tool.hatch.build.targets.sdist]
+only-include = [
+  'sources/emcdproj',
+  # --- BEGIN: Injected by Copier ---
+  'data',
+  # --- END: Injected by Copier ---
+]
+strict-naming = false
+[tool.hatch.build.targets.wheel]
+only-include = [
+  'sources/emcdproj',
+  # --- BEGIN: Injected by Copier ---
+  'data',
+  # --- END: Injected by Copier ---
+]
+strict-naming = false
+[tool.hatch.build.targets.wheel.sources]
+'sources/emcdproj' = 'emcdproj'
+# --- BEGIN: Injected by Copier ---
+'data' = 'emcdproj/data'
+# --- END: Injected by Copier ---
+[tool.hatch.envs.default]
+python = '3.10'
+[tool.hatch.envs.develop]
+description = ''' Development environment. '''
+dependencies = [
+  'Jinja2',
+  'coverage[toml]',
+  'emcd-projects',
+  'furo',
+  'icecream-truck',
+  'packaging',
+  'pre-commit',
+  'pyfakefs',
+  'pyright',
+  'pytest',
+  'pytest-asyncio',
+  'ruff',
+  'sphinx',
+  'sphinx-copybutton',
+  'sphinx-inline-tabs',
+  'towncrier',
+  # --- BEGIN: Injected by Copier ---
+  # --- END: Injected by Copier ---
+]
+post-install-commands = [
+  # --- BEGIN: Injected by Copier ---
+  # --- END: Injected by Copier ---
+]
+[tool.hatch.envs.develop.env-vars]
+PYTHONUNBUFFERED = 'TRUE' # TODO: Only for coverage/pytest.
+# --- BEGIN: Injected by Copier ---
+# --- END: Injected by Copier ---
+[tool.hatch.envs.develop.scripts]
+docsgen = [
+  '''sphinx-build -E -b doctest -d .auxiliary/caches/sphinx \
+     documentation .auxiliary/artifacts/sphinx-doctest''',
+  '''sphinx-build -E -b linkcheck -d .auxiliary/caches/sphinx \
+     documentation .auxiliary/artifacts/sphinx-linkcheck''',
+  '''sphinx-build -a -d .auxiliary/caches/sphinx \
+     documentation .auxiliary/artifacts/sphinx-html''',
+]
+linters = [
+  '''ruff check --quiet sources documentation tests''',
+  # --- BEGIN: Injected by Copier ---
+  # --- END: Injected by Copier ---
+  '''pyright sources''',
+]
+packagers = [
+  '''hatch build''',
+  # --- BEGIN: Injected by Copier ---
+  # --- END: Injected by Copier ---
+]
+testers = [
+  'coverage erase',
+  'coverage run',
+  'coverage combine',
+  'coverage report --skip-covered',
+  'coverage html',
+  'coverage xml',
+]
+make-all = [
+  'linters',
+  'testers',
+  'packagers',
+  'docsgen',
+]
+[tool.hatch.envs.qa]
+description = ''' Quality assurance environment. '''
+template = 'develop'
+[[tool.hatch.envs.qa.matrix]]
+python = [
+    '3.10',
+    '3.11',
+    '3.12',
+    '3.13',
+    'pypy3.10',
+]
+[tool.hatch.version]
+path = 'sources/emcdproj/__init__.py'
+
+# https://mypy.readthedocs.io/en/stable/config_file.html
+[tool.mypy]
+# Note: Due to repeated painful experiences with Mypy, we use Pyright instead.
+#       Pyright properly handles TypeVars, etc...
+cache_dir = '.auxiliary/caches/mypy'
+exclude = [ '.*' ]  # Ignore everything
+ignore_errors = true
+follow_imports = 'skip'
+pretty = true
+strict = false
+
+# https://microsoft.github.io/pyright/#/configuration
+[tool.pyright]
+ignore = [ 'tests' ] # Stronger hint for language server.
+include = [ 'sources' ]
+reportConstantRedefinition = true
+reportInvalidTypeVarUse = true
+reportMatchNotExhaustive = true
+reportMissingImports = true
+reportMissingTypeStubs = true
+reportMissingTypeArgument = true
+reportPossiblyUnboundVariable = false # Covered by other linters.
+reportPrivateImportUsage = false      # Covered by other linters.
+reportPrivateUsage = false            # Covered by other linters.
+reportSelfClsParameterName = false    # Too opinionated.
+reportUnknownArgumentType = true
+reportUnknownLambdaType = true
+reportUnknownMemberType = true
+reportUnknownParameterType = true
+reportUnknownVariableType = true
+reportUnnecessaryCast = true
+reportUnnecessaryComparison = true
+reportUntypedBaseClass = true
+reportUntypedClassDecorator = true
+reportUntypedFunctionDecorator = true
+reportUntypedNamedTuple = true
+reportUnusedExpression = true
+reportUnusedImport = false            # Covered by other linters.
+reportUnusedVariable = false          # Covered by other linters.
+#strict = [ 'sources' ]
+stubPath = 'sources/emcdproj/_typedecls'
+
+[tool.pytest.ini_options]
+# Note: Cannot run doctests from Pytest, because Pytest tries to update '_'
+#       attribute on protected modules. Instead, we use Sphinx to run doctests.
+minversion = '8.1'
+addopts = '--capture=no --exitfirst -rfE'
+testpaths = [ 'tests' ]
+python_files = [ 'test_*.py' ]
+python_functions = [ 'test_[0-9][0-9][0-9]_*' ]
+cache_dir = '.auxiliary/caches/pytest'
+
+[tool.ruff]
+builtins = [ 'ictr' ]
+cache-dir = '.auxiliary/caches/ruff'
+indent-width = 4
+line-length = 79
+[tool.ruff.lint]
+dummy-variable-rgx = '^_$'
+ignore = [
+  'E701',     # multiple-statements-on-one-line-colon
+  'PLC0415',  # import-outside-top-level
+  'SIM300',   # yoda-condition: scarred by assignment expressions, I am
+]
+select = [ # default: E4, E7, E9, F
+  'A',        # Flake8 builtins rules
+  'B006',     # mutable-argument-default
+  'B008',     # function-call-in-default-argument
+  'B011',     # assert-false
+  'B023',     # function-uses-loop-variable
+  'B904',     # raise-without-from-inside-except
+  'B909',     # PREVIEW: loop-iterator-mutation
+  'C90',      # McCabe complexity rules
+  'E101',     # mixed-spaces-and-tabs
+  'E111',     # PREVIEW: indentation-with-invalid-multiple
+  'E112',     # PREVIEW: no-indented-block
+  'E4',       # Pycodestyle import rules
+  'E501',     # line-too-long
+  'E7',       # Pycodestyle general rules
+  'E9',       # Pycodestyle runtime errors
+  'F',        # Pyflakes rules
+  'PERF',     # Perflint rules
+  'PLC',      # Pylint convention rules
+  'PLE',      # Pylint error rules
+  'PLR',      # Pylint refactor rules
+  'PLW',      # Pylint warning rules
+  'RET',      # Flake8 return rules
+  'RUF',      # Ruff rules
+  'S',        # Flake8 Bandit rules
+  'SIM',      # Flake8 simplify rules
+  'SLF',      # Flake8 self rules
+  'TRY',      # Tryceratops rules
+]
+[tool.ruff.lint.mccabe]
+max-complexity = 12
+[tool.ruff.lint.per-file-ignores]
+'__init__.py' = [
+  'F401',     # unused-import
+  'F403',     # undefined-local-with-import-star
+  'F405',     # undefined-local-with-import-star-usage
+]
+'tests/**/*.py' = [
+  'PLR0124',  # comparison-with-itself
+  'PLR0913',  # too-many-arguments
+  'PLR0915',  # too-many-statements
+  'PLR1704',  # redefined-argument-from-local
+  'PLR2004',  # magic-value-comparison
+  'PLW0129',  # assert-on-string-literal
+  'PLW0603',  # global-statement
+  'PLW0642',  # self-assignment
+  'S101',     # assert
+  'SLF001',   # private-member-accessed
+  'TRY',      # Tryceratops rules
+]
+[tool.ruff.lint.pylint]
+max-locals = 10
+max-public-methods = 10
+max-statements = 30
+
+[tool.towncrier]
+directory = '.auxiliary/data/towncrier'
+filename = 'documentation/changelog.rst'
+package = 'emcdproj'
+package_dir = 'sources'
+[[tool.towncrier.type]]
+# features and other improvements
+directory = 'enhance'
+name = 'Enhancements'
+showcontent = true
+[[tool.towncrier.type]]
+# deprecations and other notices
+directory = 'notify'
+name = 'Notices'
+showcontent = true
+[[tool.towncrier.type]]
+# removals of feature or platform support
+directory = 'remove'
+name = 'Removals'
+showcontent = true
+[[tool.towncrier.type]]
+# bug fixes
+directory = 'repair'
+name = 'Repairs'
+showcontent = true

{emcd_projects-1.15rc0 → emcd_projects-1.17rc0}/sources/emcdproj/__/imports.py

@@ -20,20 +20,22 @@
 
 ''' Common imports and type aliases used throughout the package. '''
 
-# pylint: disable=unused-import
 # ruff: noqa: F401
 
 
 from __future__ import annotations
 
-import abc
-import collections.abc as cabc
-import contextlib as ctxl
-import json
-import math
-import os
-import shutil
-import types
+import                      abc
+import collections.abc as   cabc
+import contextlib as        ctxl
+import                      enum
+import                      io
+import                      json
+import                      math
+import                      os
+import                      shutil
+import                      sys
+import                      types
 
 from pathlib import Path
 

{emcd_projects-1.15rc0 → emcd_projects-1.17rc0}/sources/emcdproj/__/preparation.py

@@ -30,9 +30,10 @@ from . import distribution as _distribution
 from . import state as _state
 
 
-async def prepare( # pylint: disable=too-many-arguments,too-many-locals
+async def prepare(
     exits: __.ctxl.AsyncExitStack,
-    application: _application.Information = _application.Information( ),
+    application: _application.Information = (
+        _application.Information( ) ), # noqa: B008
     # configedits: _dictedits.Edits = ( ),
     # configfile: __.Absential[ __.Path ] = __.absent,
     # environment: bool = False,
@@ -66,7 +67,7 @@ async def prepare( # pylint: disable=too-many-arguments,too-many-locals
         exits = exits )
     # if environment: await _environment.update( auxdata )
     # _inscribe_preparation_report( auxdata )
-    return auxdata
+    return auxdata # noqa: RET504
 
 
 # def _inscribe_preparation_report( auxdata: _state.Globals ):

{emcd_projects-1.15rc0 → emcd_projects-1.17rc0}/sources/emcdproj/__init__.py

@@ -27,7 +27,7 @@ from . import exceptions
 # --- END: Injected by Copier ---
 
 
-__version__ = '1.15rc0'
+__version__ = '1.17rc0'
 
 
 def main( ):

{emcd_projects-1.15rc0 → emcd_projects-1.17rc0}/sources/emcdproj/cli.py

@@ -25,6 +25,7 @@ from __future__ import annotations
 
 from . import __
 from . import interfaces as _interfaces
+from . import template as _template
 from . import website as _website
 
 
@@ -34,8 +35,10 @@ class VersionCommand(
 ):
     ''' Prints version information. '''
 
-    async def __call__( self, auxdata: __.Globals ) -> None:
-        from . import __version__ # pylint: disable=cyclic-import
+    async def __call__(
+        self, auxdata: __.Globals, display: _interfaces.ConsoleDisplay
+    ) -> None:
+        from . import __version__
         print( f"{__package__} {__version__}" )
         raise SystemExit( 0 )
 
@@ -48,8 +51,12 @@ class Cli(
 
     application: __.ApplicationInformation
     # configfile: __.typx.Optional[ str ] = None
-    # display: ConsoleDisplay
+    display: _interfaces.ConsoleDisplay
     command: __.typx.Union[
+        __.typx.Annotated[
+            _template.CommandDispatcher,
+            __.tyro.conf.subcommand( 'template', prefix_name = False ),
+        ],
         __.typx.Annotated[
             _website.CommandDispatcher,
             __.tyro.conf.subcommand( 'website', prefix_name = False ),
@@ -66,8 +73,8 @@ class Cli(
         async with __.ctxl.AsyncExitStack( ) as exits:
             auxdata = await _prepare( exits = exits, **nomargs )
             ictr( 0 )( self.command )
-            await self.command( auxdata = auxdata )
-            # await self.command( auxdata = auxdata, display = self.display )
+            # await self.command( auxdata = auxdata )
+            await self.command( auxdata = auxdata, display = self.display )
 
     def prepare_invocation_args(
         self,
@@ -107,9 +114,8 @@ async def _prepare(
     import ictruck
     # TODO: Finetune Icecream truck installation from CLI arguments.
     ictruck.install( trace_levels = 9 )
-    auxdata = await __.prepare(
+    return await __.prepare(
         application = application,
         # configedits = configedits,
         # environment = environment,
         exits = exits )
-    return auxdata

{emcd_projects-1.15rc0 → emcd_projects-1.17rc0}/sources/emcdproj/interfaces.py

@@ -26,7 +26,47 @@ from __future__ import annotations
 from . import __
 
 
-class CliCommand( # pylint: disable=invalid-metaclass
+class DisplayStreams( __.enum.Enum ): # TODO: Python 3.11: StrEnum
+    # TODO: Protected class attributes.
+    ''' Stream upon which to place output. '''
+
+    Stderr =    'stderr'
+    Stdout =    'stdout'
+
+
+class ConsoleDisplay(
+    metaclass = __.ImmutableDataclass,
+):
+    silence: __.typx.Annotated[
+        bool,
+        __.tyro.conf.arg(
+            aliases = ( '--quiet', '--silent', ), prefix_name = False ),
+    ] = False
+    file: __.typx.Annotated[
+        __.typx.Optional[ __.Path ],
+        __.tyro.conf.arg(
+            name = 'console-capture-file', prefix_name = False ),
+    ] = None
+    stream: __.typx.Annotated[
+        DisplayStreams,
+        __.tyro.conf.arg( name = 'console-stream', prefix_name = False ),
+    ] = DisplayStreams.Stderr
+
+    async def provide_stream( self ) -> __.io.TextIOWrapper:
+        ''' Provides output stream for display. '''
+        # TODO: register file stream as a process-lifetime exit
+        if self.file: return open( self.file, 'w' )
+        # TODO: async context manager for async file streams
+        # TODO: return async stream - need async printers
+        # TODO: handle non-TextIOWrapper streams
+        match self.stream:
+            case DisplayStreams.Stdout:
+                return __.sys.stdout # pyright: ignore[reportReturnType]
+            case DisplayStreams.Stderr:
+                return __.sys.stderr # pyright: ignore[reportReturnType]
+
+
+class CliCommand(
     __.typx.Protocol,
     metaclass = __.ImmutableProtocolDataclass,
     decorators = ( __.typx.runtime_checkable, ),
@@ -34,7 +74,9 @@ class CliCommand( # pylint: disable=invalid-metaclass
     ''' CLI command. '''
 
     @__.abc.abstractmethod
-    async def __call__( self, auxdata: __.Globals ) -> None:
+    async def __call__(
+        self, auxdata: __.Globals, display: ConsoleDisplay
+    ) -> None:
         ''' Executes command with global state. '''
         raise NotImplementedError
 

emcd_projects-1.17rc0/sources/emcdproj/template.py

@@ -0,0 +1,127 @@
+# 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.                                            #
+#                                                                            #
+#============================================================================#
+
+
+''' Copier template maintenance and validation. '''
+
+
+from __future__ import annotations
+
+import subprocess as _subprocess
+import tempfile as _tempfile
+
+from . import __
+from . import interfaces as _interfaces
+
+
+class CommandDispatcher(
+    _interfaces.CliCommand, decorators = ( __.standard_tyro_class, ),
+):
+    ''' Dispatches commands for static website maintenance. '''
+
+    command: __.typx.Union[
+        __.typx.Annotated[
+            SurveyCommand,
+            __.tyro.conf.subcommand( 'survey', prefix_name = False ),
+        ],
+        __.typx.Annotated[
+            ValidateCommand,
+            __.tyro.conf.subcommand( 'validate', prefix_name = False ),
+        ],
+    ]
+
+    async def __call__(
+        self, auxdata: __.Globals, display: _interfaces.ConsoleDisplay
+    ) -> None:
+        ictr( 1 )( self.command )
+        await self.command( auxdata = auxdata, display = display )
+
+
+class SurveyCommand(
+    _interfaces.CliCommand, decorators = ( __.standard_tyro_class, ),
+):
+    ''' Surveys available configuration variants. '''
+
+    async def __call__(
+        self, auxdata: __.Globals, display: _interfaces.ConsoleDisplay
+    ) -> None:
+        stream = await display.provide_stream( )
+        for variant in survey_variants( auxdata ):
+            print( variant, file = stream )
+
+
+class ValidateCommand(
+    _interfaces.CliCommand, decorators = ( __.standard_tyro_class, ),
+):
+    ''' Validates template against configuration variant. '''
+
+    variant: __.typx.Annotated[
+        str,
+        __.typx.Doc( ''' Configuration variant to validate. ''' ),
+        __.tyro.conf.Positional,
+    ]
+
+    async def __call__(
+        self, auxdata: __.Globals, display: _interfaces.ConsoleDisplay
+    ) -> None:
+        ''' Copies new project from template for configuration variant. '''
+        # TODO: Validate variant argument.
+        validate_variant( auxdata, self.variant )
+
+
+def copy_template( answers_file: __.Path, projectdir: __.Path ) -> None:
+    ''' Copies template to target directory using answers. '''
+    _subprocess.run( # noqa: S603
+        (   'copier', 'copy', '--data-file', str( answers_file ),
+            '--defaults', '--overwrite', '--vcs-ref', 'HEAD',
+            '.', str( projectdir ) ),
+        cwd = __.Path( ), check = True )
+
+
+def survey_variants( auxdata: __.Globals ) -> __.cabc.Sequence[ str ]:
+    ''' Surveys available configuration variants. '''
+    location = auxdata.distribution.provide_data_location( 'copier' )
+    return tuple(
+        fsent.stem.lstrip( 'answers-' )
+        for fsent in location.glob( 'answers-*.yaml' )
+        if fsent.is_file( ) )
+
+
+def validate_variant( auxdata: __.Globals, variant: str ) -> None:
+    ''' Validates configuration variant. '''
+    answers_file = (
+        auxdata.distribution.provide_data_location(
+            'copier', f"answers-{variant}.yaml" ) )
+    if not answers_file.is_file( ):
+        # TODO: Raise error.
+        return
+    with _tempfile.TemporaryDirectory( ) as tmpdir:
+        projectdir = __.Path( tmpdir ) / variant
+        copy_template( answers_file, projectdir )
+        validate_variant_project( projectdir )
+
+
+def validate_variant_project( projectdir: __.Path ) -> None:
+    ''' Validates standard project as generated from template. '''
+    for command in (
+        (   'hatch', '--env', 'develop', 'run',
+            'python', '-m', 'pip', 'install',
+            '--upgrade', 'pip', 'build' ),
+        (   'hatch', '--env', 'develop', 'run', 'make-all' ),
+    ): _subprocess.run( command, cwd = str( projectdir ), check = True ) # noqa: S603

{emcd_projects-1.15rc0 → emcd_projects-1.17rc0}/sources/emcdproj/website.py

@@ -33,8 +33,7 @@ from . import interfaces as _interfaces
 
 
 class CommandDispatcher(
-    _interfaces.CliCommand,
-    decorators = ( __.standard_tyro_class, ),
+    _interfaces.CliCommand, decorators = ( __.standard_tyro_class, ),
 ):
     ''' Dispatches commands for static website maintenance. '''
 
@@ -49,25 +48,27 @@ class CommandDispatcher(
         ],
     ]
 
-    async def __call__( self, auxdata: __.Globals ) -> None:
+    async def __call__(
+        self, auxdata: __.Globals, display: _interfaces.ConsoleDisplay
+    ) -> None:
         ictr( 1 )( self.command )
-        await self.command( auxdata = auxdata )
+        await self.command( auxdata = auxdata, display = display )
 
 
 class SurveyCommand(
-    _interfaces.CliCommand,
-    decorators = ( __.standard_tyro_class, ),
+    _interfaces.CliCommand, decorators = ( __.standard_tyro_class, ),
 ):
     ''' Surveys release versions published in static website. '''
 
-    async def __call__( self, auxdata: __.Globals ) -> None:
+    async def __call__(
+        self, auxdata: __.Globals, display: _interfaces.ConsoleDisplay
+    ) -> None:
         # TODO: Implement.
         pass
 
 
 class UpdateCommand(
-    _interfaces.CliCommand,
-    decorators = ( __.standard_tyro_class, ),
+    _interfaces.CliCommand, decorators = ( __.standard_tyro_class, ),
 ):
     ''' Updates static website for particular release version. '''
 
@@ -77,7 +78,9 @@ class UpdateCommand(
         __.tyro.conf.Positional,
     ]
 
-    async def __call__( self, auxdata: __.Globals ) -> None:
+    async def __call__(
+        self, auxdata: __.Globals, display: _interfaces.ConsoleDisplay
+    ) -> None:
         update( auxdata, self.version )
 
 
@@ -146,7 +149,7 @@ def update(
     locations.website.mkdir( exist_ok = True, parents = True )
     if locations.archive.is_file( ):
         with tarfile_open( locations.archive, 'r:xz' ) as archive:
-            archive.extractall( path = locations.website )
+            archive.extractall( path = locations.website ) # noqa: S202
     available_species = _update_available_species( locations, version )
     j2context = _jinja2.Environment(
         loader = _jinja2.FileSystemLoader( locations.templates ),
@@ -157,7 +160,7 @@ def update(
         _update_coverage_badge( locations, j2context )
     ( locations.website / '.nojekyll' ).touch( )
     from .filesystem import chdir
-    with chdir( locations.website ):
+    with chdir( locations.website ): # noqa: SIM117
         with tarfile_open( locations.archive, 'w:xz' ) as archive:
             archive.add( '.' )
 
@@ -195,7 +198,7 @@ def _update_available_species(
     return tuple( available_species )
 
 
-def _update_coverage_badge( # pylint: disable=too-many-locals
+def _update_coverage_badge(
     locations: Locations, j2context: _jinja2.Environment
 ) -> None:
     ''' Updates coverage badge SVG.
@@ -207,11 +210,9 @@ def _update_coverage_badge( # pylint: disable=too-many-locals
         - green: >= 80%
     '''
     coverage = _extract_coverage( locations )
-    # pylint: disable=magic-value-comparison
     color = (
-        'red' if coverage < 50 else (
-            'yellow' if coverage < 80 else 'green' ) )
-    # pylint: enable=magic-value-comparison
+        'red' if coverage < 50 else ( # noqa: PLR2004
+            'yellow' if coverage < 80 else 'green' ) ) # noqa: PLR2004
     label_text = 'coverage'
     value_text = f"{coverage}%"
     label_width = len( label_text ) * 6 + 10

emcd_projects-1.15rc0/pyproject.toml

@@ -1,532 +0,0 @@
-# vim: set filetype=toml fileencoding=utf-8:
-# -*- mode: toml ; coding: utf-8 -*-
-
-[build-system]
-requires = [
-  'hatchling',
-]
-build-backend = 'hatchling.build'
-
-[project]
-name = 'emcd-projects'
-description = 'Project management utilities.'
-dynamic = [ 'version' ]
-license = 'Apache-2.0'
-readme = { 'file' = 'sources/emcdproj/README.rst', 'content-type' = 'text/x-rst' }
-requires-python = '>= 3.10'
-dependencies = [
-  'Jinja2',
-  'absence',
-  'defusedxml',
-  'frigid',
-  'icecream-truck',
-  'importlib-metadata', # TODO: Drop once we have separate appcore package.
-  'importlib-resources', # TODO: Drop once we have separate appcore package.
-  'packaging',
-  'platformdirs', # TODO: Drop once we have separate appcore package.
-  'tomli', # TODO: Drop once we have separate appcore package.
-  'typing-extensions',
-  # --- BEGIN: Injected by Copier ---
-  'tyro',
-  # --- END: Injected by Copier ---
-]
-classifiers = [ # https://pypi.org/classifiers
-  'Development Status :: 3 - Alpha',
-  'Intended Audience :: Developers',
-  'License :: OSI Approved :: Apache Software License',
-  'Programming Language :: Python :: 3 :: Only',
-  # --- BEGIN: Injected by Copier ---
-  'Programming Language :: Python :: 3.10',
-  'Programming Language :: Python :: 3.11',
-  'Programming Language :: Python :: 3.12',
-  'Programming Language :: Python :: 3.13',
-  'Programming Language :: Python :: Implementation :: CPython',
-  'Programming Language :: Python :: Implementation :: PyPy',
-  # --- END: Injected by Copier ---
-  'Topic :: Software Development',
-]
-keywords = [ 'maintenance', 'project', 'template' ]
-[[project.authors]]
-name = 'Eric McDonald'
-email = 'emcd@users.noreply.github.com'
-[project.scripts]
-emcdproj = 'emcdproj:main'
-[project.urls]
-'Homepage' = 'https://github.com/emcd/python-project-common'
-'Documentation' = 'https://emcd.github.io/python-project-common'
-'Download' = 'https://pypi.org/project/emcd-projects/#files'
-'Source Code' = 'https://github.com/emcd/python-project-common'
-'Issue Tracker' = 'https://github.com/emcd/python-project-common/issues'
-
-[tool.SELF]
-year-of-origin = 2024
-
-[tool.bandit]
-exclude_dirs = [ 'tests' ]
-
-# https://coverage.readthedocs.io/en/latest/config.html
-[tool.coverage.run]
-branch = true
-command_line = '-m pytest' # TODO? '--fail-under'
-data_file = '.auxiliary/caches/pytest/coverage.sqlite3'
-parallel = true
-source = [ 'sources' ]
-[tool.coverage.html]
-directory = '.auxiliary/artifacts/coverage-pytest'
-[tool.coverage.xml]
-output = '.auxiliary/artifacts/coverage-pytest/coverage.xml'
-
-# https://hatch.pypa.io/latest/config/metadata/
-[tool.hatch.build]
-directory = '.auxiliary/artifacts/hatch-build'
-[tool.hatch.build.targets.sdist]
-only-include = [
-  'sources/emcdproj',
-  # --- BEGIN: Injected by Copier ---
-  'data',
-  # --- END: Injected by Copier ---
-]
-strict-naming = false
-[tool.hatch.build.targets.wheel]
-only-include = [
-  'sources/emcdproj',
-  # --- BEGIN: Injected by Copier ---
-  'data',
-  # --- END: Injected by Copier ---
-]
-strict-naming = false
-[tool.hatch.build.targets.wheel.sources]
-'sources/emcdproj' = 'emcdproj'
-# --- BEGIN: Injected by Copier ---
-'data' = 'emcdproj/data'
-# --- END: Injected by Copier ---
-[tool.hatch.envs.default]
-python = '3.10'
-[tool.hatch.envs.develop]
-description = ''' Development environment. '''
-dependencies = [
-  'Jinja2',
-  'bandit',
-  'coverage[toml]',
-  'furo',
-  'icecream',
-  'isort',
-  'packaging',
-  'pre-commit',
-  'pyfakefs',
-  'pylint',
-  'pylint-per-file-ignores',
-  'pyright',
-  'pytest',
-  'pytest-asyncio',
-  'ruff',
-  'semgrep;platform_system!="Windows"', # https://github.com/returntocorp/semgrep/issues/1330
-  'sphinx',
-  'sphinx-copybutton',
-  'sphinx-inline-tabs',
-  'towncrier',
-  'tryceratops',
-  'yapf',
-  # --- BEGIN: Injected by Copier ---
-  # --- END: Injected by Copier ---
-]
-post-install-commands = [
-  # --- BEGIN: Injected by Copier ---
-  # --- END: Injected by Copier ---
-]
-[tool.hatch.envs.develop.env-vars]
-PYTHONUNBUFFERED = 'TRUE' # TODO: Only for coverage/pytest.
-# --- BEGIN: Injected by Copier ---
-# --- END: Injected by Copier ---
-[tool.hatch.envs.develop.scripts]
-docsgen = [
-  '''sphinx-build -E -b doctest -d .auxiliary/caches/sphinx \
-     documentation .auxiliary/artifacts/sphinx-doctest''',
-  '''sphinx-build -E -b linkcheck -d .auxiliary/caches/sphinx \
-     documentation .auxiliary/artifacts/sphinx-linkcheck''',
-  '''sphinx-build -a -d .auxiliary/caches/sphinx \
-     documentation .auxiliary/artifacts/sphinx-html''',
-]
-linters = [
-  '''ruff check --quiet sources documentation tests''',
-  # --- BEGIN: Injected by Copier ---
-  # --- END: Injected by Copier ---
-  '''bandit --configfile pyproject.toml --quiet --recursive sources''',
-  '''tryceratops sources''',
-  '''pyright sources''',
-  '''pylint --recursive yes sources documentation tests''',
-  '''semgrep --config p/python --error --quiet --skip-unknown-extensions \
-     sources/emcdproj''',
-  # --- BEGIN: Injected by Copier ---
-  # --- END: Injected by Copier ---
-]
-packagers = [
-  '''hatch build''',
-  # --- BEGIN: Injected by Copier ---
-  # --- END: Injected by Copier ---
-]
-testers = [
-  'coverage erase',
-  'coverage run',
-  'coverage combine',
-  'coverage report --skip-covered',
-  'coverage html',
-  'coverage xml',
-]
-make-all = [
-  'linters',
-  'testers',
-  'packagers',
-  'docsgen',
-]
-[tool.hatch.envs.qa]
-description = ''' Quality assurance environment. '''
-template = 'develop'
-[[tool.hatch.envs.qa.matrix]]
-python = [
-    '3.10',
-    '3.11',
-    '3.12',
-    '3.13',
-    'pypy3.10',
-]
-[tool.hatch.version]
-path = 'sources/emcdproj/__init__.py'
-
-# https://pycqa.github.io/isort/docs/configuration/options.html
-# https://pycqa.github.io/isort/docs/configuration/multi_line_output_modes.html
-[tool.isort]
-atomic = true
-#color = false
-#combine_as = false
-#combine_straight_imports = false
-#extra_standard_library = [ ]
-follow_links = false
-#force_alphabetical_sort_within_sections = false
-#float_to_top = false
-honor_noqa = true
-#ignore_whitespace = false
-include_trailing_comma = true
-# known_OTHER: substitute OTHER
-known_first_party = [ 'emcdproj' ]
-#known_third_party = [ ]
-#line_length = 79
-#lines_after_imports = -1 # automatic
-#lines_before_imports = -1 # automatic
-multi_line_output = 3 # vertical hanging indent
-#quiet = false
-#sections = [ 'FUTURE', 'STDLIB', 'THIRDPARTY', 'FIRSTPARTY', 'LOCALFOLDER' ]
-skip_gitignore = true
-split_on_trailing_comma = true
-#src_paths = [ ]
-#star_first = false
-#supported_extensions = [ 'pxd', 'py', 'pyi', 'pyx' ]
-use_parentheses = true
-
-# https://mypy.readthedocs.io/en/stable/config_file.html
-[tool.mypy]
-# Note: Due to repeated painful experiences with Mypy, we use Pyright instead.
-#       Pyright properly handles TypeVars, etc...
-cache_dir = '.auxiliary/caches/mypy'
-exclude = [ '.*' ]  # Ignore everything
-ignore_errors = true
-follow_imports = 'skip'
-pretty = true
-strict = false
-
-# https://pylint.pycqa.org/en/latest/user_guide/configuration/index.html
-[tool.pylint.main]
-fail-under = 10
-# TODO: jobs: Consider parallelization if output interleaving, dependency
-#             grouping, and similarities detection bugs have been fixed.
-load-plugins = [
-  # 'pylint.extensions.bad_builtin',
-  'pylint.extensions.broad_try_clause',
-  'pylint.extensions.check_elif',
-  'pylint.extensions.code_style',
-  'pylint.extensions.confusing_elif',
-  # 'pylint.extensions.consider_ternary_expression',
-  'pylint.extensions.dict_init_mutate',
-  'pylint.extensions.dunder',
-  'pylint.extensions.eq_without_hash',
-  'pylint.extensions.for_any_all',
-  'pylint.extensions.magic_value',
-  'pylint.extensions.mccabe',
-  'pylint.extensions.no_self_use',
-  'pylint.extensions.overlapping_exceptions',
-  'pylint.extensions.private_import',
-  'pylint.extensions.redefined_loop_name',
-  'pylint.extensions.redefined_variable_type',
-  # 'pylint.extensions.set_membership',
-  # 'pylint.extensions.while_used',
-  'pylint_per_file_ignores',
-]
-recursive = false
-suggestion-mode = true
-[tool.pylint.basic]
-const-rgx = '([A-Za-z_][A-Za-z0-9_]{2,30}|(__.*__))$'
-good-names = [ '_', '__' ]
-include-naming-hint = true
-[tool.pylint.broad_try_clause]
-max-try-statements = 2
-[tool.pylint.classes]
-defining-attr-methods = [ '__init__', '__new__', '__post_init__' ]
-exclude-protected = [ ]
-valid-classmethod-first-arg = [ 'selfclass' ]
-valid-metaclass-classmethod-first-arg = [ 'clscls' ]
-[tool.pylint.design]
-# TODO: exclude-too-few-public-methods: Consider exception hierarchies.
-ignored-parents = [
-  'abc.ABCMeta',
-  'builtins.AttributeError',
-  'builtins.BaseException',
-  'builtins.Exception',
-  'builtins.KeyError',
-  'builtins.TypeError',
-  'builtins.ValueError',
-  'builtins.type',
-  'typing.Protocol',
-  'typing_extensions.Protocol',
-  # --- BEGIN: Injected by Copier ---
-  'emcdproj.exceptions.Omnierror',
-  'emcdproj.exceptions.Omniexception',
-  # --- END: Injected by Copier ---
-]
-max-args = 5
-max-attributes = 7
-max-bool-expr = 3
-max-branches = 12
-max-locals = 10
-max-parents = 3
-max-public-methods = 10
-max-returns = 6
-max-statements = 30
-min-public-methods = 1
-[tool.pylint.exceptions]
-overgeneral-exceptions = [
-  'builtins.BaseException',
-  'builtins.Exception',
-  # --- BEGIN: Injected by Copier ---
-  'emcdproj.exceptions.Omnierror',
-  'emcdproj.exceptions.Omniexception',
-  # --- END: Injected by Copier ---
-]
-[tool.pylint.format]
-ignore-long-lines = '''^(\s*<?https?://\S+>?|([^'"]*\s+)?#.*)$'''
-max-line-length = 79
-max-module-lines = 800
-single-line-class-stmt = true
-single-line-if-stmt = true
-[tool.pylint.imports]
-allow-wildcard-with-all = false
-# TODO: ext-import-graph
-# TODO: int-import-graph
-[tool.pylint.logging]
-logging-format-style = 'new'
-[tool.pylint.'messages control']
-disable = [
-  'bad-dunder-name',
-  'consider-using-assignment-expr',
-  'consider-using-f-string',
-  'duplicate-code',  # TODO: Re-enable after heuristic is fixed.
-  'fixme',
-  'f-string-without-interpolation',
-  'import-outside-toplevel',
-  'invalid-name',
-  'logging-format-interpolation',
-  'logging-fstring-interpolation',
-  'multiple-statements',
-  'reimported',
-  'too-few-public-methods',
-  'too-many-positional-arguments',  # 'too-many-arguments' is good enough
-  'ungrouped-imports',
-  'unused-wildcard-import',
-  'use-dict-literal',
-  'using-exception-groups-in-unsupported-version',
-  '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,comparison-with-itself,magic-value-comparison,missing-class-docstring,missing-function-docstring,protected-access,redefined-outer-name,singleton-comparison,superfluous-parens,too-many-try-statements,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' ]
-[tool.pylint.reports]
-msg-template = '{path} {line:3d},{column:2d} [{symbol}] {msg}'
-output-format = 'colorized'
-reports = false
-score = true
-[tool.pylint.similarities]
-ignore-comments = true
-ignore-docstrings = true
-ignore-imports = true
-ignore-signatures = true
-min-similarity-lines = 5
-[tool.pylint.spelling]
-max-spelling-suggestions = 4
-# TODO: spelling-dict
-[tool.pylint.typecheck]
-contextmanager-decorators = [ 'contextlib.contextmanager' ]
-ignored-checks-for-mixins = [
-  'attribute-defined-outside-init',
-  'no-member',
-  'not-async-context-manager',
-  'not-context-manager',
-]
-#ignored-classes = [ 'thread._local', '_thread._local', 'argparse.Namespace' ]
-ignore-mixin-members = false
-missing-member-hint = true
-missing-member-hint-distance = 1
-missing-member-max-choices = 2
-#mixin-class-rgx = '.*[Mm]ixin'
-#signature-mutators = [ ]
-[tool.pylint.variables]
-additional-builtins = [ 'ictr' ]
-callbacks = [ ]
-dummy-variables-rgx = '''_$'''
-ignored-argument-names = '''_.*'''
-redefining-builtins-modules = [ 'builtins', 'io' ]
-
-# https://microsoft.github.io/pyright/#/configuration
-[tool.pyright]
-include = [ 'sources' ]
-ignore = [ 'tests' ]
-reportConstantRedefinition = true
-reportInvalidTypeVarUse = true
-reportMatchNotExhaustive = true
-reportMissingImports = true
-reportMissingTypeStubs = true
-reportMissingTypeArgument = true
-reportPossiblyUnboundVariable = false # Covered by other linters.
-reportPrivateImportUsage = false      # Covered by other linters.
-reportPrivateUsage = false            # Covered by other linters.
-reportSelfClsParameterName = false    # Too opinionated.
-reportUnknownArgumentType = true
-reportUnknownLambdaType = true
-reportUnknownMemberType = true
-reportUnknownParameterType = true
-reportUnknownVariableType = true
-reportUnnecessaryCast = true
-reportUnnecessaryComparison = true
-reportUntypedBaseClass = true
-reportUntypedClassDecorator = true
-reportUntypedFunctionDecorator = true
-reportUntypedNamedTuple = true
-reportUnusedExpression = true
-reportUnusedImport = false            # Covered by other linters.
-reportUnusedVariable = false          # Covered by other linters.
-#strict = [ 'sources' ]
-stubPath = 'sources/emcdproj/_typedecls'
-
-[tool.pytest.ini_options]
-# Note: Cannot run doctests from Pytest, because Pytest tries to update '_'
-#       attribute on protected modules. Instead, we use Sphinx to run doctests.
-minversion = '8.1'
-addopts = '--capture=no --exitfirst -rfE'
-testpaths = [ 'tests' ]
-python_files = [ 'test_*.py' ]
-python_functions = [ 'test_[0-9][0-9][0-9]_*' ]
-cache_dir = '.auxiliary/caches/pytest'
-
-[tool.ruff]
-builtins = [ 'ictr' ]
-cache-dir = '.auxiliary/caches/ruff'
-[tool.ruff.lint]
-ignore = [
-  '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]
-directory = '.auxiliary/data/towncrier'
-filename = 'documentation/changelog.rst'
-package = 'emcdproj'
-package_dir = 'sources'
-[[tool.towncrier.type]]
-directory = 'bugfix'
-name = 'Bugfixes'
-showcontent = true
-[[tool.towncrier.type]]
-directory = 'docs'
-name = 'Documentation Improvements'
-showcontent = true
-[[tool.towncrier.type]]
-directory = 'feature'
-name = 'Features'
-showcontent = true
-[[tool.towncrier.type]]
-directory = 'platform'
-name = 'Supported Platforms'
-showcontent = true
-[[tool.towncrier.type]]
-directory = 'removal'
-name = 'Deprecations and Removals'
-showcontent = true
-
-[tool.tryceratops]
-exclude = [ 'tests' ]
-
-# https://github.com/google/yapf?tab=readme-ov-file#knobs
-# yapf --style-help
-[tool.yapf]
-align_closing_bracket_with_visual_indent = false
-allow_multiline_dictionary_keys = true
-allow_multiline_lambdas = true
-#allow_split_before_default_or_named_assigns = true
-#allow_split_before_dict_value = true
-blank_line_before_module_docstring = true
-#blank_line_before_nested_class_or_def = true
-#blank_lines_around_top_level_definition = 2
-blank_lines_between_top_level_imports_and_variables = 2
-#coalesce_brackets = false
-#column_limit = 79
-#continuation_align_style = 'SPACE'
-#continuation_indent_width = 4
-dedent_closing_brackets = true
-#disable_ending_comma_heuristic = false
-#disable_split_list_with_comment = false
-#each_dict_entry_on_separate_line = true
-#force_multiline_dict = false
-indent_dictionary_value = true
-#indent_width = 4
-join_multiple_lines = true
-#space_between_ending_comma_and_closing_bracket = true
-space_inside_brackets = true
-spaces_around_default_or_named_assign = true
-spaces_around_dict_delimiters = true
-spaces_around_list_delimiters = true
-spaces_around_power_operator = true
-spaces_around_subscript_colon = true
-spaces_around_tuple_delimiters = true
-#spaces_before_comment = 2
-#split_all_comma_separated_values = false
-#split_all_top_level_comma_separated_values = false
-split_arguments_when_comma_terminated = true
-split_before_arithmetic_operator = true
-split_before_bitwise_operator = true
-split_before_closing_bracket = false
-#split_before_dict_set_generator = true
-split_before_dot = true
-split_before_expression_after_opening_paren = true
-split_before_first_argument = true
-split_before_logical_operator = true
-#split_before_named_assigns = true
-split_complex_comprehension = true
-split_penalty_after_opening_bracket = 100   # default: 300
-#split_penalty_after_unary_operator = 10000
-#split_penalty_arithmetic_operator = 300
-#split_penalty_before_if_expr = 0
-#split_penalty_bitwise_operator = 300
-#split_penalty_comprehension = 80
-#split_penalty_excess_character = 7000
-#split_penalty_for_added_line_split = 30
-#split_penalty_import_names = 0
-#split_penalty_logical_operator = 300