ictr 1.0a0__py3-none-any.whl

ictr/__/__init__.py

@@ -0,0 +1,27 @@
+# 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. '''
+
+
+from .imports import *
+from .miscellany import *
+from .nomina import *
+from .validators import *

ictr/__/imports.py

@@ -0,0 +1,61 @@
+# 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 used throughout the package. '''
+
+# ruff: noqa: F401
+
+
+import                      abc
+import collections.abc as   cabc
+import                      codecs
+import dataclasses as       dcls
+import                      enum
+import functools as         funct
+import                      inspect
+import                      io
+import itertools as         itert
+import                      locale
+import                      os
+import                      pprint
+import                      re
+import                      shutil
+import                      sys
+import traceback as         tb
+import                      textwrap
+import threading as         threads
+import                      time
+import                      types
+import                      warnings
+
+from datetime import datetime as Datetime, timezone as Timezone
+
+import accretive as         accret
+import exceptiongroup as    excg
+import typing_extensions as typx
+import                      wcwidth
+# --- BEGIN: Injected by Copier ---
+import dynadoc as           ddoc
+import frigid as            immut
+# --- END: Injected by Copier ---
+
+# --- BEGIN: Injected by Copier ---
+from absence import Absential, absent, is_absent
+# --- END: Injected by Copier ---

ictr/__/miscellany.py

@@ -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.                                            #
+#                                                                            #
+#============================================================================#
+
+
+''' Miscellaneous package internals. '''
+
+
+
+from . import imports as __
+
+
+def install_builtin_safely(
+    alias: str, installee: __.typx.Any, errorclass: type[ Exception ]
+) -> None:
+    ''' Adds attribute to interpreter builtins, if absent. '''
+    import builtins
+    if hasattr( builtins, alias ): raise errorclass( builtins, alias )
+    setattr( builtins, alias, installee )

ictr/__/nomina.py

@@ -0,0 +1,54 @@
+# 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 names and type aliases. '''
+
+
+from . import imports as __
+
+
+H = __.typx.TypeVar( 'H', bound = __.cabc.Hashable ) # Hash Key
+V = __.typx.TypeVar( 'V' ) # Value
+
+
+ComparisonResult: __.typx.TypeAlias = bool | __.types.NotImplementedType
+NominativeArguments: __.typx.TypeAlias = __.cabc.Mapping[ str, __.typx.Any ]
+PositionalArguments: __.typx.TypeAlias = __.cabc.Sequence[ __.typx.Any ]
+
+DictionaryNominativeArgument: __.typx.TypeAlias = __.typx.Annotated[
+    V,
+    __.ddoc.Doc(
+        'Zero or more keyword arguments from which to initialize '
+        'dictionary data.' ),
+]
+DictionaryPositionalArgument: __.typx.TypeAlias = __.typx.Annotated[
+    __.cabc.Mapping[ H, V ] | __.cabc.Iterable[ tuple[ H, V ] ],
+    __.ddoc.Doc(
+        'Zero or more iterables from which to initialize dictionary data. '
+        'Each iterable must be dictionary or sequence of key-value pairs. '
+        'Duplicate keys will result in an error.' ),
+]
+ExceptionInfo: __.typx.TypeAlias = tuple[
+    type[ BaseException ] | None,
+    BaseException | None,
+    __.types.TracebackType | None ]
+
+
+package_name = __name__.split( '.', maxsplit = 1 )[ 0 ]

ictr/__/validators.py

@@ -0,0 +1,77 @@
+# 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.                                            #
+#                                                                            #
+#============================================================================#
+
+
+''' Validators for internal use. '''
+
+
+
+from . import imports as __
+
+
+def validate_arguments(
+    globalvars: dict[ str, __.typx.Any ],
+    errorclass: type[ Exception ],
+):
+    ''' Decorator factory which produces argument validators. '''
+
+    def decorate( function: __.cabc.Callable[ ..., __.typx.Any ] ):
+        ''' Decorates function to be validated. '''
+
+        @__.funct.wraps( function )
+        def validate( *posargs: __.typx.Any, **nomargs: __.typx.Any ):
+            ''' Validates arguments before invocation. '''
+            signature = __.inspect.signature( function )
+            inspectee = signature.bind( *posargs, **nomargs )
+            inspectee.apply_defaults( )
+            for name, value in inspectee.arguments.items( ):
+                param = signature.parameters[ name ]
+                annotation = param.annotation
+                if __.is_absent( value ): continue
+                if annotation is param.empty: continue
+                classes = _reduce_annotation(
+                    annotation, globalvars = globalvars )
+                if not isinstance( value, classes ):
+                    raise errorclass( name, classes )
+            return function( *posargs, **nomargs )
+
+        return validate
+
+    return decorate
+
+
+def _reduce_annotation(
+    annotation: __.typx.Any, globalvars: dict[ str, __.typx.Any ]
+) -> tuple[ type, ... ]:
+    if isinstance( annotation, str ):
+        return _reduce_annotation(
+            eval( annotation, globalvars ), # noqa: S307
+            globalvars = globalvars )
+    origin = __.typx.get_origin( annotation )
+    if isinstance( annotation, __.types.UnionType ) or origin is __.typx.Union:
+        return tuple( __.itert.chain.from_iterable(
+            map(
+                lambda a: _reduce_annotation( a, globalvars = globalvars ),
+                __.typx.get_args( annotation ) ) ) )
+    if origin is None: return ( annotation, )
+    if origin is __.typx.Annotated:
+        return _reduce_annotation(
+            annotation.__origin__, globalvars = globalvars )
+    # TODO? Other special forms.
+    return ( origin, )

ictr/__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.                                            #
+#                                                                            #
+#============================================================================#
+
+
+''' Non-intrusive system for logging and debug printing. '''
+
+
+from . import __
+from . import standard
+# --- BEGIN: Injected by Copier ---
+from . import exceptions
+# --- END: Injected by Copier ---
+
+
+from .dispatchers import *
+from .printers import *
+from .textualizers import *
+
+
+__version__ = '1.0a0'
+
+
+__.immut.finalize_module( __name__, recursive = True )

ictr/_typedecls/wcwidth/__init__.pyi

@@ -0,0 +1,9 @@
+# Copied from dedicated project to avoid additional dependency:
+#   https://github.com/trim21/wcwidth-stubs/blob/master/src/wcwidth-stubs/__init__.pyi
+def list_versions() -> tuple[str, ...]: ...
+def wcwidth(wc: str, unicode_version: str = ...) -> int: ...
+def wcswidth(
+    pwcs: str, n: int | None = None, unicode_version: str = ...
+) -> int: ...
+
+__all__ = ("list_versions", "wcswidth", "wcwidth")

ictr/configuration.py

@@ -0,0 +1,107 @@
+# 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.                                            #
+#                                                                            #
+#============================================================================#
+
+
+''' Portions of configuration hierarchy. '''
+
+
+from . import __
+from . import flavors as _flavors
+from . import textualizers as _texts
+
+
+class FlavorConfiguration( __.immut.DataclassObject ):
+    ''' Per-flavor configuration. '''
+
+    compositor_factory: __.typx.Annotated[
+        __.typx.Optional[ _texts.CompositorFactory ],
+        __.typx.Doc(
+            ''' Factory which produces compositor callable.
+
+                Takes address and flavor as arguments. Returns compositor.
+
+                Default ``None`` inherits from cumulative configuration.
+            ''' ),
+    ] = None
+
+
+FlavorsRegistry: __.typx.TypeAlias = (
+    __.immut.Dictionary[ _flavors.Flavor, FlavorConfiguration ] )
+FlavorsRegistryLiberal: __.typx.TypeAlias = (
+    __.cabc.Mapping[ _flavors.Flavor, FlavorConfiguration ] )
+
+
+def produce_flavors_default( ) -> FlavorsRegistry:
+    ''' Produces registry of all standard flavors without customization. '''
+    flavors: FlavorsRegistryLiberal = { }
+    for name, spec in _flavors.flavor_specifications_standard.items( ):
+        tfactory = _texts.produce_compositor_factory_default(
+            introducer = f"{spec.label}| ", trace_exceptions = spec.stack )
+        flavors[ name ] = FlavorConfiguration(
+            compositor_factory = tfactory )
+    for alias, name in _flavors.flavor_aliases_standard.items( ):
+        flavors[ alias ] = flavors[ name ]
+    for level in range( 10 ):
+        indent_i = '  ' * level
+        indent_s = '  ' * ( level + 1 )
+        tfactory = _texts.produce_compositor_factory_default(
+            introducer = f"TRACE{level}| ",
+            line_prefix_initial = indent_i,
+            line_prefix_subsequent = indent_s )
+        flavors[ level ] = FlavorConfiguration(
+            compositor_factory = tfactory )
+    return __.immut.Dictionary( flavors )
+
+
+class AddressConfiguration( __.immut.DataclassObject ):
+    ''' Per-address configuration. '''
+
+    compositor_factory: __.typx.Annotated[
+        __.typx.Optional[ _texts.CompositorFactory ],
+        __.typx.Doc(
+            ''' Factory which produces compositor callable.
+
+                Takes address and flavor as arguments. Returns compositor.
+
+                Default ``None`` inherits from cumulative configuration.
+            ''' ),
+    ] = None
+    flavors: __.typx.Annotated[
+        FlavorsRegistry,
+        __.typx.Doc(
+            ''' Registry of flavor identifiers to configurations. ''' ),
+    ] = __.dcls.field( default_factory = FlavorsRegistry )
+
+
+class DispatcherConfiguration( __.immut.DataclassObject ):
+    ''' Per-dispatcher configuration. '''
+
+    compositor_factory: __.typx.Annotated[
+        _texts.CompositorFactory,
+        __.typx.Doc(
+            ''' Factory which produces compositor callable.
+
+                Takes address and flavor as arguments. Returns compositor.
+            ''' ),
+    ] = _texts.produce_compositor_factory_default( )
+    flavors: __.typx.Annotated[
+        FlavorsRegistry,
+        __.typx.Doc(
+            ''' Registry of flavor identifiers to configurations. ''' ),
+    ] = __.dcls.field( default_factory = produce_flavors_default )