emcd-projects 1.15rc0__py3-none-any.whl → 1.17__py3-none-any.whl

{emcd_projects-1.15rc0.dist-info → emcd_projects-1.17.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: emcd-projects
-Version: 1.15rc0
+Version: 1.17
 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.17.dist-info/RECORD

@@ -0,0 +1,27 @@
+emcdproj/data/.gitignore,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+emcdproj/data/copier/answers-default.yaml,sha256=dgdxDTcZZpHjg3-uZyDALzJ0Gc7GBcSSvQ7L_OmebWM,150
+emcdproj/data/copier/answers-maximum.yaml,sha256=aVAiQZgltQYZWf3wYGzw6-Syp2iZr7yjOauqd2lhYfQ,392
+emcdproj/data/templates/coverage.svg.jinja,sha256=UWJE9I1QVoo31DB4PAcf_sYFs1oOViDbnCmhzuoVuq8,1479
+emcdproj/data/templates/website.html.jinja,sha256=V958XUcGdNmvSl_RalRvPRIZ5uUcpaXgycddOLN6rfA,1513
+emcdproj/README.rst,sha256=ThJlTJWDLurnGuhCXlQDRuSYexDJrAUnHIPiTGaAmww,4495
+emcdproj/__init__.py,sha256=UK1t3kKXvsMKGS1ObotJh5JNPjfISHGNNzP16BPl8zY,1582
+emcdproj/__main__.py,sha256=KkTeK75rYgF2yVf2HpTs-L2V1jru3j7ohDSgGXWFXjQ,1409
+emcdproj/cli.py,sha256=WNAF0pmAbdxtmuCcyTBkuG1CQnWixpkDSXNuQ4KwXDE,4414
+emcdproj/exceptions.py,sha256=Y9n5pGh1-hMkKtOYherAjUw19af4-uWDNzUZjiqiU00,2641
+emcdproj/filesystem.py,sha256=YgcX5Q52r2hTYU-7_VoW2inMC4NBTzqSTINB9eNT9Hw,1708
+emcdproj/interfaces.py,sha256=PvNZb4G0EhXbK_yaAOhqcgp0uNR30FCRUf4Qn0e03M8,3185
+emcdproj/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+emcdproj/template.py,sha256=S_SAlrVtEco2c2eO0QNdy-Gffn_hk8zVFFT1GzqXcuc,4823
+emcdproj/website.py,sha256=YfIGPp2WzoL0E9nQLJgbfU6yVbipns-I7F6alkSowb0,10657
+emcdproj/__/__init__.py,sha256=oGdDy7STF7jZlrxKzgvdbqw5-tR-RRWqurizIazVvvg,1598
+emcdproj/__/application.py,sha256=6uF2yTIlAsLWKadus7a7mPvr7q3pagplPrDAA1EUwlw,2316
+emcdproj/__/distribution.py,sha256=9TCSm8oJtIot-MPR8Ypt72gMaUh77WXtkpuxggb6tGQ,3972
+emcdproj/__/imports.py,sha256=P4r8oEkrKGQ0NuA4uTTbM-ZYUJp3QgvjuqJELdlSJH0,2340
+emcdproj/__/preparation.py,sha256=rNbA8VvrspanbP_0O4GjmwaqgzgPf0SdY7WadcINJZE,3824
+emcdproj/__/state.py,sha256=inChROB1WcJ_b9kZ6VfQZr-dLj56-MxWoMHrvB-yXu4,3596
+emcdproj/_typedecls/__builtins__.pyi,sha256=VhJfnYgggXihUzomBHtA1xEKzG7XqEHkSjhl0Ro6qgg,153
+emcd_projects-1.17.dist-info/METADATA,sha256=w1weDAbKQglWr1Hf4Xls8QVY0dzS3DxhSgyoL0j8NL8,6085
+emcd_projects-1.17.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+emcd_projects-1.17.dist-info/entry_points.txt,sha256=22Pc1xg3OboNBxpTnDM3gLYXo8QuY2E0SOv1djo0fdc,43
+emcd_projects-1.17.dist-info/licenses/LICENSE.txt,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+emcd_projects-1.17.dist-info/RECORD,,

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
 

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 ):

emcdproj/__init__.py

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

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

emcdproj/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.'

emcdproj/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

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
 

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

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.dist-info/RECORD

@@ -1,24 +0,0 @@
-emcdproj/data/.gitignore,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-emcdproj/data/templates/coverage.svg.jinja,sha256=UWJE9I1QVoo31DB4PAcf_sYFs1oOViDbnCmhzuoVuq8,1479
-emcdproj/data/templates/website.html.jinja,sha256=V958XUcGdNmvSl_RalRvPRIZ5uUcpaXgycddOLN6rfA,1513
-emcdproj/README.rst,sha256=ThJlTJWDLurnGuhCXlQDRuSYexDJrAUnHIPiTGaAmww,4495
-emcdproj/__init__.py,sha256=5iNawyfbFxQHwJ11Iv5ae73xcsh1BX-0IMK46SEK3OA,1585
-emcdproj/__main__.py,sha256=KkTeK75rYgF2yVf2HpTs-L2V1jru3j7ohDSgGXWFXjQ,1409
-emcdproj/cli.py,sha256=6IEdWtJY4LORb5bUfW0cJDEHFxNSJ867ycs7FLZDz74,4222
-emcdproj/exceptions.py,sha256=Y9n5pGh1-hMkKtOYherAjUw19af4-uWDNzUZjiqiU00,2641
-emcdproj/filesystem.py,sha256=YgcX5Q52r2hTYU-7_VoW2inMC4NBTzqSTINB9eNT9Hw,1708
-emcdproj/interfaces.py,sha256=G7o4XgJB0Ad1UpnYbK3vcnZD7ydszKKhikvW60BiFNo,1771
-emcdproj/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-emcdproj/website.py,sha256=Pqd_BOuGybDEJC19SjhramB_KHZd0j-4fQs1trajWxM,10566
-emcdproj/__/__init__.py,sha256=oGdDy7STF7jZlrxKzgvdbqw5-tR-RRWqurizIazVvvg,1598
-emcdproj/__/application.py,sha256=6uF2yTIlAsLWKadus7a7mPvr7q3pagplPrDAA1EUwlw,2316
-emcdproj/__/distribution.py,sha256=9TCSm8oJtIot-MPR8Ypt72gMaUh77WXtkpuxggb6tGQ,3972
-emcdproj/__/imports.py,sha256=WYkzM0Af4LlI6WzrX3wN1Jt4MxnPoZbbMY2PuZWwYJA,2141
-emcdproj/__/preparation.py,sha256=5GGqf4RVkc8P_fvcT11CUFvU1zTLGjpj7QE2DBRa28w,3837
-emcdproj/__/state.py,sha256=inChROB1WcJ_b9kZ6VfQZr-dLj56-MxWoMHrvB-yXu4,3596
-emcdproj/_typedecls/__builtins__.pyi,sha256=VhJfnYgggXihUzomBHtA1xEKzG7XqEHkSjhl0Ro6qgg,153
-emcd_projects-1.15rc0.dist-info/METADATA,sha256=nbVVPBehRkheTUbwf5Lexk8d5Y_tvRtm8w1zR3lVJGY,6088
-emcd_projects-1.15rc0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-emcd_projects-1.15rc0.dist-info/entry_points.txt,sha256=22Pc1xg3OboNBxpTnDM3gLYXo8QuY2E0SOv1djo0fdc,43
-emcd_projects-1.15rc0.dist-info/licenses/LICENSE.txt,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
-emcd_projects-1.15rc0.dist-info/RECORD,,