emcd-projects 1.14__py3-none-any.whl

emcdproj/__/imports.py

@@ -0,0 +1,60 @@
+# 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 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
+
+from pathlib import Path
+
+import typing_extensions as typx
+# --- BEGIN: Injected by Copier ---
+import tyro
+# --- END: Injected by Copier ---
+
+from absence import Absential, absent, is_absent
+from frigid.qaliases import (
+    ImmutableClass,
+    ImmutableDataclass,
+    ImmutableProtocolDataclass,
+    immutable,
+)
+from platformdirs import PlatformDirs
+
+
+ComparisonResult: typx.TypeAlias = bool | types.NotImplementedType
+
+
+package_name = __name__.split( '.', maxsplit = 1 )[ 0 ]
+simple_tyro_class = tyro.conf.configure( )
+standard_tyro_class = tyro.conf.configure( tyro.conf.OmitArgPrefixes )

emcdproj/__/preparation.py

@@ -0,0 +1,83 @@
+# 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.                                            #
+#                                                                            #
+#============================================================================#
+
+
+''' Preparation of the library core. '''
+
+
+from . import imports as __
+from . import application as _application
+# from . import configuration as _configuration
+# from . import dictedits as _dictedits
+from . import distribution as _distribution
+# from . import environment as _environment
+from . import state as _state
+
+
+async def prepare( # pylint: disable=too-many-arguments,too-many-locals
+    exits: __.ctxl.AsyncExitStack,
+    application: _application.Information = _application.Information( ),
+    # configedits: _dictedits.Edits = ( ),
+    # configfile: __.Absential[ __.Path ] = __.absent,
+    # environment: bool = False,
+) -> _state.Globals:
+    ''' Prepares globals DTO for use with library functions.
+
+        Also:
+        * Configures logging for library package (not application).
+        * Optionally, loads process environment from files.
+
+        Note that asynchronous preparation allows for applications to
+        concurrently initialize other entities outside of the library, even
+        though the library initialization, itself, is inherently sequential.
+    '''
+    directories = application.produce_platform_directories( )
+    distribution = (
+        await _distribution.Information.prepare(
+            package = __.package_name, exits = exits ) )
+    # configuration = (
+    #     await _configuration.acquire(
+    #         application_name = application.name,
+    #         directories = directories,
+    #         distribution = distribution,
+    #         edits = configedits,
+    #         file = configfile ) )
+    auxdata = _state.Globals(
+        application = application,
+        # configuration = configuration,
+        directories = directories,
+        distribution = distribution,
+        exits = exits )
+    # if environment: await _environment.update( auxdata )
+    # _inscribe_preparation_report( auxdata )
+    return auxdata
+
+
+# def _inscribe_preparation_report( auxdata: _state.Globals ):
+#     scribe = __.produce_scribe( __.package_name )
+#     scribe.debug( f"Application Name: {auxdata.application.name}" )
+#     # scribe.debug( f"Execution ID: {auxdata.application.execution_id}" )
+#     scribe.debug( "Application Cache Location: {}".format(
+#         auxdata.provide_cache_location( ) ) )
+#     scribe.debug( "Application Data Location: {}".format(
+#         auxdata.provide_data_location( ) ) )
+#     scribe.debug( "Application State Location: {}".format(
+#         auxdata.provide_state_location( ) ) )
+#     scribe.debug( "Package Data Location: {}".format(
+#         auxdata.distribution.provide_data_location( ) ) )

emcdproj/__/state.py

@@ -0,0 +1,80 @@
+# 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.                                            #
+#                                                                            #
+#============================================================================#
+
+
+''' Immutable global state. '''
+
+
+from . import imports as __
+from . import application as _application
+from . import distribution as _distribution
+
+
+# class DirectorySpecies( __.enum.Enum ): # TODO: Python 3.11: StrEnum
+#     ''' Possible species for locations. '''
+#
+#     Cache = 'cache'
+#     Data = 'data'
+#     State = 'state'
+
+
+class Globals( metaclass = __.ImmutableDataclass ):
+    ''' Immutable global data. Required by some library functions. '''
+
+    application: _application.Information
+    # configuration: __.AccretiveDictionary[ str, __.typx.Any ]
+    directories: __.PlatformDirs
+    distribution: _distribution.Information
+    exits: __.ctxl.AsyncExitStack
+
+    def as_dictionary( self ) -> __.cabc.Mapping[ str, __.typx.Any ]:
+        ''' Returns shallow copy of state. '''
+        from dataclasses import fields
+        return {
+            field.name: getattr( self, field.name )
+            for field in fields( self ) }
+
+    # def provide_cache_location( self, *appendages: str ) -> __.Path:
+    #     ''' Provides cache location from configuration. '''
+    #     return self.provide_location( DirectorySpecies.Cache, *appendages )
+
+    # def provide_data_location( self, *appendages: str ) -> __.Path:
+    #     ''' Provides data location from configuration. '''
+    #     return self.provide_location( DirectorySpecies.Data, *appendages )
+
+    # def provide_state_location( self, *appendages: str ) -> __.Path:
+    #     ''' Provides state location from configuration. '''
+    #     return self.provide_location( DirectorySpecies.State, *appendages )
+
+    # def provide_location(
+    #     self, species: DirectorySpecies, *appendages: str
+    # ) -> __.Path:
+    #     ''' Provides particular species of location from configuration. '''
+    #     species_name = species.value
+    #     base = getattr( self.directories, f"user_{species_name}_path" )
+    #     spec = self.configuration.get( 'locations', { } ).get( species_name )
+    #     if spec:
+    #         args: dict[ str, str | __.Path ] = {
+    #             f"user_{species_name}": base,
+    #             'user_home': __.Path.home( ),
+    #             'application_name': self.application.name,
+    #         }
+    #         base = __.Path( spec.format( **args ) )
+    #     if appendages: return base.joinpath( *appendages )
+    #     return base

emcdproj/__init__.py

@@ -0,0 +1,39 @@
+# 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.                                            #
+#                                                                            #
+#============================================================================#
+
+
+''' Project management utilities. '''
+
+
+from . import __
+# --- BEGIN: Injected by Copier ---
+from . import exceptions
+# --- END: Injected by Copier ---
+
+
+__version__ = '1.14'
+
+
+def main( ):
+    ''' Entrypoint. '''
+    from .cli import execute
+    execute( )
+
+
+# TODO: Reclassify package modules as immutable and concealed.

emcdproj/__main__.py

@@ -0,0 +1,28 @@
+# 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.                                            #
+#                                                                            #
+#============================================================================#
+
+
+''' Entrypoint. '''
+
+
+# Note: Use absolute import for PyInstaller happiness.
+from emcdproj.cli import execute
+
+
+if '__main__' == __name__: execute( )

emcdproj/_typedecls/__builtins__.pyi

@@ -0,0 +1,7 @@
+''' Stubs for additional "builtin" types. '''
+
+# https://github.com/microsoft/pyright/blob/main/docs/builtins.md
+
+from ictruck import Truck
+
+ictr: Truck

emcdproj/cli.py

@@ -0,0 +1,115 @@
+# 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.                                            #
+#                                                                            #
+#============================================================================#
+
+
+''' Command-line interface. '''
+
+
+from __future__ import annotations
+
+from . import __
+from . import interfaces as _interfaces
+from . import website as _website
+
+
+class VersionCommand(
+    _interfaces.CliCommand,
+    decorators = ( __.standard_tyro_class, ),
+):
+    ''' Prints version information. '''
+
+    async def __call__( self, auxdata: __.Globals ) -> None:
+        from . import __version__ # pylint: disable=cyclic-import
+        print( f"{__package__} {__version__}" )
+        raise SystemExit( 0 )
+
+
+class Cli(
+    metaclass = __.ImmutableDataclass,
+    decorators = ( __.simple_tyro_class, ),
+):
+    ''' Various utilities for projects by Github user '@emcd'. '''
+
+    application: __.ApplicationInformation
+    # configfile: __.typx.Optional[ str ] = None
+    # display: ConsoleDisplay
+    command: __.typx.Union[
+        __.typx.Annotated[
+            _website.CommandDispatcher,
+            __.tyro.conf.subcommand( 'website', prefix_name = False ),
+        ],
+        __.typx.Annotated[
+            VersionCommand,
+            __.tyro.conf.subcommand( 'version', prefix_name = False ),
+        ],
+    ]
+
+    async def __call__( self ):
+        ''' Invokes command after library preparation. '''
+        nomargs = self.prepare_invocation_args( )
+        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 )
+
+    def prepare_invocation_args(
+        self,
+    ) -> __.cabc.Mapping[ str, __.typx.Any ]:
+        ''' Prepares arguments for initial configuration. '''
+        # configedits: __.DictionaryEdits = (
+        #     self.command.provide_configuration_edits( ) )
+        args: dict[ str, __.typx.Any ] = dict(
+            application = self.application,
+            # configedits = configedits,
+            # environment = True,
+        )
+        # if self.configfile: args[ 'configfile' ] = self.configfile
+        return args
+
+
+def execute( ) -> None:
+    ''' Entrypoint for CLI execution. '''
+    from asyncio import run
+    config = (
+        __.tyro.conf.HelptextFromCommentsOff,
+    )
+    try: run( __.tyro.cli( Cli, config = config )( ) )
+    except SystemExit: raise
+    except BaseException:
+        # TODO: Log exception.
+        raise SystemExit( 1 ) from None
+
+
+async def _prepare(
+    application: __.ApplicationInformation,
+    # configedits: __.DictionaryEdits,
+    # environment: bool,
+    exits: __.ctxl.AsyncExitStack,
+) -> __.Globals:
+    ''' Configures logging based on verbosity. '''
+    import ictruck
+    # TODO: Finetune Icecream truck installation from CLI arguments.
+    ictruck.install( trace_levels = 9 )
+    auxdata = await __.prepare(
+        application = application,
+        # configedits = configedits,
+        # environment = environment,
+        exits = exits )
+    return auxdata

emcdproj/data/templates/coverage.svg.jinja

@@ -0,0 +1,35 @@
+<svg xmlns="http://www.w3.org/2000/svg"
+  width="{{ total_width }}" height="20"
+  role="img" aria-label="{{ label_text }}: {{ value_text }}"
+>
+  <title>{{ label_text }}: {{ value_text }}</title>
+  <linearGradient id="s" x2="0" y2="100%">
+    <stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
+    <stop offset="1" stop-opacity=".1"/>
+  </linearGradient>
+  <clipPath id="r">
+    <rect width="{{ total_width }}" height="20" rx="3" fill="#fff"/>
+  </clipPath>
+  <g clip-path="url(#r)">
+    <rect width="{{ label_width }}" height="20" fill="#555"/>
+    <rect x="{{ label_width }}" width="{{ value_width }}" height="20" fill="{{ color }}"/>
+    <rect width="{{ total_width }}" height="20" fill="url(#s)"/>
+  </g>
+  <g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110">
+    <text aria-hidden="true"
+      x="{{ label_width / 2 * 10 }}" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)"
+    >
+      {{ label_text }}
+    </text>
+    <text x="{{ label_width / 2 * 10 }}" y="140" transform="scale(.1)" fill="#fff">{{ label_text }}</text>
+    <text aria-hidden="true"
+      x="{{ label_width * 10 + value_width / 2 * 10 }}" y="150"
+      fill="#010101" fill-opacity=".3" transform="scale(.1)"
+    >
+      {{ value_text }}
+    </text>
+    <text x="{{ label_width * 10 + value_width / 2 * 10 }}" y="140" transform="scale(.1)" fill="#fff">
+      {{ value_text }}
+    </text>
+  </g>
+</svg>

emcdproj/data/templates/website.html.jinja

@@ -0,0 +1,58 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Available Releases</title>
+    <style>
+        table {
+            width: 100%;
+            border-collapse: collapse;
+        }
+        th, td {
+            padding: 8px;
+            text-align: left;
+            border-bottom: 1px solid #ddd;
+        }
+        th {
+            background-color: #f2f2f2;
+        }
+        tr:hover {
+            background-color: #f5f5f5;
+        }
+    </style>
+</head>
+<body>
+    <h1>Available Releases</h1>
+    <table>
+        <thead>
+            <tr>
+                <th>Version</th>
+                <th>Documentation</th>
+                <th>Coverage</th>
+            </tr>
+        </thead>
+        <tbody>
+        {% for version, attributes in versions.items() %}
+            <tr>
+                <td>{{ version }}</td>
+                <td>
+                {% if 'sphinx-html' in attributes %}
+                    <a href="{{ version }}/sphinx-html/index.html">Docs</a>
+                {% else %}
+                    N/A
+                {% endif %}
+                </td>
+                <td>
+                {% if 'coverage-pytest' in attributes %}
+                    <a href="{{ version }}/coverage-pytest/index.html">Coverage</a>
+                {% else %}
+                    N/A
+                {% endif %}
+                </td>
+            </tr>
+        {% endfor %}
+        </tbody>
+    </table>
+</body>
+</html>

emcdproj/exceptions.py

@@ -0,0 +1,69 @@
+# 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.                                            #
+#                                                                            #
+#============================================================================#
+
+
+''' Family of exceptions for package API. '''
+
+
+from . import __
+
+
+class Omniexception(
+    BaseException,
+    metaclass = __.ImmutableClass,
+    decorators = ( __.immutable, ),
+):
+    ''' Base for all exceptions raised by package API. '''
+    # TODO: Class and instance attribute concealment.
+
+    _attribute_visibility_includes_: __.cabc.Collection[ str ] = (
+        frozenset( ( '__cause__', '__context__', ) ) )
+
+
+class Omnierror( Omniexception, Exception ):
+    ''' Base for error exceptions raised by package API. '''
+
+
+class DataAwol( Omnierror, AssertionError ):
+    ''' Unexpected data absence. '''
+
+    def __init__( self, source: str, label: str ):
+        super( ).__init__(
+            f"Necessary data with label '{label}' is missing from {source}." )
+
+
+class FileDataAwol( DataAwol ):
+    ''' Unexpected data absence from file. '''
+
+    def __init__( self, file: str | __.Path, label: str ):
+        super( ).__init__( source = f"file '{file}'", label = label )
+
+
+class FileAwol( Omnierror, AssertionError ):
+    ''' Unexpected file absence. '''
+
+    def __init__( self, file: str | __.Path ):
+        super( ).__init__( f"Necessary file is missing at '{file}'." )
+
+
+class FileEmpty( Omnierror, AssertionError ):
+    ''' Unexpectedly empty file. '''
+
+    def __init__( self, file: str| __.Path ):
+        super( ).__init__( f"Unexpectedly empty file at '{file}'." )

emcdproj/filesystem.py

@@ -0,0 +1,39 @@
+# 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.                                            #
+#                                                                            #
+#============================================================================#
+
+
+''' Filesystem operations and utilities. '''
+
+
+from __future__ import annotations
+
+from . import __
+
+
+@__.ctxl.contextmanager
+def chdir( directory: __.Path ) -> __.cabc.Iterator[ __.Path ]:
+    ''' Temporarily changes working directory.
+
+        Not thread-safe or async-safe.
+    '''
+    # TODO: Python 3.11: contextlib.chdir
+    original = __.os.getcwd( )
+    __.os.chdir( directory )
+    try: yield directory
+    finally: __.os.chdir( original )

emcdproj/interfaces.py

@@ -0,0 +1,41 @@
+# 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.                                            #
+#                                                                            #
+#============================================================================#
+
+
+''' Abstract bases and interfaces. '''
+
+
+from __future__ import annotations
+
+from . import __
+
+
+class CliCommand( # pylint: disable=invalid-metaclass
+    __.typx.Protocol,
+    metaclass = __.ImmutableProtocolDataclass,
+    decorators = ( __.typx.runtime_checkable, ),
+):
+    ''' CLI command. '''
+
+    @__.abc.abstractmethod
+    async def __call__( self, auxdata: __.Globals ) -> None:
+        ''' Executes command with global state. '''
+        raise NotImplementedError
+
+    # TODO: provide_configuration_edits