frigid 2.0__tar.gz → 3.0__tar.gz

{frigid-2.0 → frigid-3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: frigid
-Version: 2.0
+Version: 3.0
 Summary: Immutable data structures.
 Project-URL: Homepage, https://github.com/emcd/python-frigid
 Project-URL: Documentation, https://emcd.github.io/python-frigid
@@ -87,7 +87,7 @@ Key Features ⭐
   be modified or removed. Also has variant for validation on initialization.
   And provides set operations not found on `MappingProxyType
   <https://docs.python.org/3/library/types.html#types.MappingProxyType>`_.
-* 📇 **Immutable Namespace**: Similar to `SimpleNamespace
+* 🗃️ **Immutable Namespace**: Similar to `SimpleNamespace
   <https://docs.python.org/3/library/types.html#types.SimpleNamespace>`_, but
   attributes are immutable from creation.
 * 🧱 **Additional Types**: Classes (including abstract base classes), modules,
@@ -124,12 +124,12 @@ Examples 💡
 ===============================================================================
 
 
-Immutable Namespace 📇
+Immutable Namespaces 🗃️
 -------------------------------------------------------------------------------
 
 An immutable namespace, similar to ``types.SimpleNamespace``, is available.
-This namespace is initialized from keyword arguments and becomes completely
-immutable. (Keyword arguments shown below; see documentation for additional
+This namespace can be initialized from multiple iterables and from keyword
+arguments. (Keyword arguments shown below; see documentation for additional
 forms of initialization.)
 
 >>> from frigid import Namespace
@@ -146,13 +146,13 @@ frigid.exceptions.AttributeImmutabilityError: Cannot delete attribute 'apples'.
 frigid.namespaces.Namespace( apples = 12, bananas = 6 )
 
 
-Immutable Dictionary 📖
+Immutable Dictionaries 📖
 -------------------------------------------------------------------------------
 
-An immutable dictionary, similar to ``dict``, is available. This dictionary is
-initialized from iterables and keyword arguments and becomes completely
-immutable. (Keyword arguments shown below; see documentation for additional
-forms of initialization.)
+An immutable dictionary, similar to ``dict``, is available. This dictionary can
+be initialized from multiple iterables and from keyword arguments. (Keyword
+arguments shown below; see documentation for additional forms of
+initialization.)
 
 >>> from frigid import Dictionary
 >>> dct = Dictionary( apples = 12, bananas = 6)
@@ -168,6 +168,28 @@ frigid.exceptions.EntryImmutabilityError: Cannot delete entry for 'bananas'.
 frigid.dictionaries.Dictionary( {'apples': 12, 'bananas': 6} )
 
 
+Immutable Objects 🧱
+-------------------------------------------------------------------------------
+
+The ``immutable`` decorator can be applied to any class to make its instances fully immutable after initialization.
+
+>>> from frigid import immutable
+>>> @immutable
+... class Config:
+...     def __init__( self, debug = False ):
+...         self.debug = debug
+...
+>>> config = Config( debug = True )
+>>> config.verbose = True  # ❌ Attempted addition raises error
+Traceback (most recent call last):
+...
+frigid.exceptions.AttributeImmutabilityError: Cannot assign or delete attribute 'verbose'.
+>>> config.debug = False   # ❌ Attempted reassignment raises error
+Traceback (most recent call last):
+...
+frigid.exceptions.AttributeImmutabilityError: Cannot assign or delete attribute 'debug'.
+
+
 Use Cases 🎯
 ===============================================================================
 

{frigid-2.0 → frigid-3.0}/README.rst

@@ -58,7 +58,7 @@ Key Features ⭐
   be modified or removed. Also has variant for validation on initialization.
   And provides set operations not found on `MappingProxyType
   <https://docs.python.org/3/library/types.html#types.MappingProxyType>`_.
-* 📇 **Immutable Namespace**: Similar to `SimpleNamespace
+* 🗃️ **Immutable Namespace**: Similar to `SimpleNamespace
   <https://docs.python.org/3/library/types.html#types.SimpleNamespace>`_, but
   attributes are immutable from creation.
 * 🧱 **Additional Types**: Classes (including abstract base classes), modules,
@@ -95,12 +95,12 @@ Examples 💡
 ===============================================================================
 
 
-Immutable Namespace 📇
+Immutable Namespaces 🗃️
 -------------------------------------------------------------------------------
 
 An immutable namespace, similar to ``types.SimpleNamespace``, is available.
-This namespace is initialized from keyword arguments and becomes completely
-immutable. (Keyword arguments shown below; see documentation for additional
+This namespace can be initialized from multiple iterables and from keyword
+arguments. (Keyword arguments shown below; see documentation for additional
 forms of initialization.)
 
 >>> from frigid import Namespace
@@ -117,13 +117,13 @@ frigid.exceptions.AttributeImmutabilityError: Cannot delete attribute 'apples'.
 frigid.namespaces.Namespace( apples = 12, bananas = 6 )
 
 
-Immutable Dictionary 📖
+Immutable Dictionaries 📖
 -------------------------------------------------------------------------------
 
-An immutable dictionary, similar to ``dict``, is available. This dictionary is
-initialized from iterables and keyword arguments and becomes completely
-immutable. (Keyword arguments shown below; see documentation for additional
-forms of initialization.)
+An immutable dictionary, similar to ``dict``, is available. This dictionary can
+be initialized from multiple iterables and from keyword arguments. (Keyword
+arguments shown below; see documentation for additional forms of
+initialization.)
 
 >>> from frigid import Dictionary
 >>> dct = Dictionary( apples = 12, bananas = 6)
@@ -139,6 +139,28 @@ frigid.exceptions.EntryImmutabilityError: Cannot delete entry for 'bananas'.
 frigid.dictionaries.Dictionary( {'apples': 12, 'bananas': 6} )
 
 
+Immutable Objects 🧱
+-------------------------------------------------------------------------------
+
+The ``immutable`` decorator can be applied to any class to make its instances fully immutable after initialization.
+
+>>> from frigid import immutable
+>>> @immutable
+... class Config:
+...     def __init__( self, debug = False ):
+...         self.debug = debug
+...
+>>> config = Config( debug = True )
+>>> config.verbose = True  # ❌ Attempted addition raises error
+Traceback (most recent call last):
+...
+frigid.exceptions.AttributeImmutabilityError: Cannot assign or delete attribute 'verbose'.
+>>> config.debug = False   # ❌ Attempted reassignment raises error
+Traceback (most recent call last):
+...
+frigid.exceptions.AttributeImmutabilityError: Cannot assign or delete attribute 'debug'.
+
+
 Use Cases 🎯
 ===============================================================================
 

{frigid-2.0 → frigid-3.0}/pyproject.toml

@@ -1,3 +1,6 @@
+# vim: set filetype=toml fileencoding=utf-8:
+# -*- mode: toml ; coding: utf-8 -*-
+
 [build-system]
 requires = [
   'hatchling',
@@ -14,6 +17,9 @@ requires-python = '>= 3.10'
 dependencies = [
   'absence',
   'typing-extensions',
+  # --- BEGIN: Injected by Copier ---
+
+  # --- END: Injected by Copier ---
 ]
 classifiers = [ # https://pypi.org/classifiers
   'Development Status :: 5 - Production/Stable',
@@ -52,7 +58,7 @@ branch = true
 command_line = '-m pytest' # TODO? '--fail-under'
 data_file = '.auxiliary/caches/pytest/coverage.sqlite3'
 parallel = true
-source = [ 'sources', 'tests' ]
+source = [ 'sources' ]
 [tool.coverage.html]
 directory = '.auxiliary/artifacts/coverage-pytest'
 [tool.coverage.xml]
@@ -62,10 +68,20 @@ output = '.auxiliary/artifacts/coverage-pytest/coverage.xml'
 [tool.hatch.build]
 directory = '.auxiliary/artifacts/hatch-build'
 [tool.hatch.build.targets.sdist]
-only-include = [ 'sources/frigid' ]
+only-include = [
+  'sources/frigid',
+  # --- BEGIN: Injected by Copier ---
+
+  # --- END: Injected by Copier ---
+]
 strict-naming = false
 [tool.hatch.build.targets.wheel]
-only-include = [ 'sources/frigid' ]
+only-include = [
+  'sources/frigid',
+  # --- BEGIN: Injected by Copier ---
+
+  # --- END: Injected by Copier ---
+]
 strict-naming = false
 [tool.hatch.build.targets.wheel.sources]
 'sources/frigid' = 'frigid'
@@ -79,6 +95,7 @@ dependencies = [
   'coverage[toml]',
   'furo',
   'icecream',
+  'isort',
   'packaging',
   'pre-commit',
   'pylint',
@@ -93,8 +110,16 @@ dependencies = [
   '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.
@@ -117,8 +142,10 @@ linters = [
      sources/frigid''',
 ]
 packagers = [
-  'hatch build',
-  # TODO? Sign packages.
+  '''hatch build''',
+  # --- BEGIN: Injected by Copier ---
+
+  # --- END: Injected by Copier ---
 ]
 testers = [
   'coverage erase',
@@ -242,9 +269,12 @@ ignored-parents = [
   'builtins.TypeError',
   'builtins.ValueError',
   'builtins.type',
-  'frigid.__.ClassConcealerExtension',
+  'frigid.__.exceptions.Omnierror',
+  'frigid.__.exceptions.Omniexception',
   'frigid.objects.Class',
   'frigid.objects.Object',
+  'typing.Protocol',
+  'typing_extensions.Protocol',
   # --- BEGIN: Injected by Copier ---
   'frigid.exceptions.Omnierror',
   'frigid.exceptions.Omniexception',
@@ -296,7 +326,9 @@ disable = [
   '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',
@@ -304,7 +336,7 @@ disable = [
 ]
 # 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,singleton-comparison,superfluous-parens,unexpected-keyword-arg
+  /tests/:attribute-defined-outside-init,comparison-with-itself,magic-value-comparison,missing-class-docstring,missing-function-docstring,protected-access,singleton-comparison,superfluous-parens,too-many-try-statements,unexpected-keyword-arg
   __init__\.py:unused-import
 ''' # Note: Paths are regexes.
 [tool.pylint.refactoring]
@@ -355,6 +387,7 @@ 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.
@@ -380,8 +413,8 @@ stubPath = 'sources/frigid/_typedecls'
 #       attribute on protected modules. Instead, we use Sphinx to run doctests.
 minversion = '8.1'
 addopts = '--capture=no --exitfirst -rfE'
-testpaths = [ 'tests', 'sources' ]
-python_files = [ '*.py' ]
+testpaths = [ 'tests' ]
+python_files = [ 'test_*.py' ]
 python_functions = [ 'test_[0-9][0-9][0-9]_*' ]
 cache_dir = '.auxiliary/caches/pytest'
 
@@ -480,4 +513,4 @@ split_penalty_after_opening_bracket = 100   # default: 300
 #split_penalty_excess_character = 7000
 #split_penalty_for_added_line_split = 30
 #split_penalty_import_names = 0
-#split_penalty_logical_operator = 300
+#split_penalty_logical_operator = 300

{frigid-2.0 → frigid-3.0}/sources/frigid/__/dictionaries.py

@@ -24,6 +24,10 @@
 # ruff: noqa: F401
 
 
+# TODO: Consider a dictionary factory to allow 'mutables' closure
+#       to be referenced in the '__setitem__' and '__delitem__' methods.
+
+
 from __future__ import annotations
 
 from . import imports as __
@@ -66,11 +70,11 @@ class ImmutableDictionary(
         self._behaviors_.add( _immutables.behavior_label )
 
     def __delitem__( self, key: _H ) -> None:
-        from ..exceptions import EntryImmutabilityError
+        from .exceptions import EntryImmutabilityError
         raise EntryImmutabilityError( key )
 
     def __setitem__( self, key: _H, value: _V ) -> None:
-        from ..exceptions import EntryImmutabilityError
+        from .exceptions import EntryImmutabilityError
         default: set[ str ] = set( )
         if _immutables.behavior_label in getattr(
             self, '_behaviors_', default
@@ -80,7 +84,7 @@ class ImmutableDictionary(
 
     def clear( self ) -> __.typx.Never:
         ''' Raises exception. Cannot clear immutable entries. '''
-        from ..exceptions import OperationInvalidity
+        from .exceptions import OperationInvalidity
         raise OperationInvalidity( 'clear' )
 
     def copy( self ) -> __.typx.Self:
@@ -91,12 +95,12 @@ class ImmutableDictionary(
         self, key: _H, default: __.Absential[ _V ] = __.absent
     ) -> __.typx.Never:
         ''' Raises exception. Cannot pop immutable entry. '''
-        from ..exceptions import OperationInvalidity
+        from .exceptions import OperationInvalidity
         raise OperationInvalidity( 'pop' )
 
     def popitem( self ) -> __.typx.Never:
         ''' Raises exception. Cannot pop immutable entry. '''
-        from ..exceptions import OperationInvalidity
+        from .exceptions import OperationInvalidity
         raise OperationInvalidity( 'popitem' )
 
     def update( # type: ignore
@@ -105,5 +109,5 @@ class ImmutableDictionary(
         **entries: __.DictionaryNominativeArgument[ _V ],
     ) -> None:
         ''' Raises exception. Cannot perform mass update. '''
-        from ..exceptions import OperationInvalidity
+        from .exceptions import OperationInvalidity
         raise OperationInvalidity( 'update' )

frigid-3.0/sources/frigid/__/exceptions.py

@@ -0,0 +1,53 @@
+# 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 internals. '''
+
+
+from __future__ import annotations
+
+from . import imports as __
+from . import immutables as _immutables
+
+
+class Omniexception( _immutables.ImmutableObject, BaseException ):
+    ''' Base for all exceptions raised internally. '''
+
+    _attribute_visibility_includes_: __.cabc.Collection[ str ] = (
+        frozenset( ( '__cause__', '__context__', ) ) )
+
+
+class Omnierror( Omniexception, Exception ):
+    ''' Base for error exceptions raised internally. '''
+
+
+class EntryImmutabilityError( Omnierror, TypeError ):
+    ''' Attempt to update or remove immutable dictionary entry. '''
+
+    def __init__( self, indicator: __.cabc.Hashable ) -> None:
+        super( ).__init__(
+            f"Cannot alter or remove existing entry for {indicator!r}." )
+
+
+class OperationInvalidity( Omnierror, RuntimeError, TypeError ):
+    ''' Attempt to perform invalid operation. '''
+
+    def __init__( self, name: str ) -> None:
+        super( ).__init__( f"Operation {name!r} is not valid on this object." )

{frigid-2.0 → frigid-3.0}/sources/frigid/__/imports.py

@@ -28,12 +28,16 @@ from __future__ import annotations
 
 import abc
 import collections.abc as cabc
+import dataclasses as dcls
 import types
 
 import typing_extensions as typx
+# --- BEGIN: Injected by Copier ---
 
+# --- END: Injected by Copier ---
 
-from absence import Absential, absent, is_absent
+
+from absence import AbsentSingleton, Absential, absent, is_absent
 
 
 C = typx.TypeVar( 'C' )  # Class

{frigid-2.0 → frigid-3.0}/sources/frigid/__init__.py

@@ -20,19 +20,12 @@
 
 ''' Immutable data structures. '''
 
-# ruff: noqa: F401,F403
-
 
 from . import __
-from . import classes
-from . import dictionaries
-from . import exceptions
-from . import installers
-from . import modules
-from . import namespaces
-from . import objects
 from . import qaliases
-from . import sequences
+# --- BEGIN: Injected by Copier ---
+from . import exceptions
+# --- END: Injected by Copier ---
 
 from .classes import *
 from .dictionaries import *
@@ -43,7 +36,7 @@ from .objects import *
 from .sequences import *
 
 
-__version__ = '2.0'
+__version__ = '3.0'
 
 
 _attribute_visibility_includes_ = frozenset( ( '__version__', ) )

{frigid-2.0 → frigid-3.0}/sources/frigid/classes.py

@@ -22,7 +22,8 @@
 ''' Immutable classes.
 
     Provides metaclasses for creating classes with immutable attributes. Once a
-    class is initialized, its attributes cannot be reassigned or deleted.
+    class is initialized, new attributes may not be assigned to it and its
+    existing attributes cannot be reassigned or deleted.
 
     The implementation includes:
 
@@ -33,11 +34,7 @@
     * ``ProtocolClass``: Metaclass for protocol classes; derived from
       :py:class:`typing.Protocol`.
 
-    These metaclasses are particularly useful for:
-
-    * Creating classes with constant class attributes
-    * Defining stable abstract base classes
-    * Building protocol classes with fixed interfaces
+    Additionally, metaclasses for dataclasses are provided as a convenience.
 
     >>> from frigid import Class
     >>> class Example( metaclass = Class ):
@@ -106,6 +103,67 @@ Class.__doc__ = __.generate_docstring(
     'class attributes immutability' )
 
 
+@__.typx.dataclass_transform( kw_only_default = True )
+class Dataclass( Class ):
+    ''' Immutable dataclass factory. '''
+
+    def __new__( # pylint: disable=too-many-arguments
+        clscls: type[ Dataclass ],
+        name: str,
+        bases: tuple[ type, ... ],
+        namespace: dict[ str, __.typx.Any ], *,
+        decorators: ClassDecorators = ( ),
+        docstring: __.Absential[ __.typx.Optional[ str ] ] = __.absent,
+        mutables: __.cabc.Collection[ str ] = ( ),
+        **args: __.typx.Any
+    ) -> Dataclass:
+        decorators_ = (
+            __.dcls.dataclass( kw_only = True, slots = True ),
+            *decorators )
+        return Class.__new__( # pyright: ignore
+            clscls, name, bases, namespace,
+            decorators = decorators_,
+            docstring = docstring,
+            mutables = mutables,
+            **args )
+
+Dataclass.__doc__ = __.generate_docstring(
+    Dataclass,
+    'description of class factory class',
+    'class attributes immutability' )
+
+
+@__.typx.dataclass_transform( frozen_default = True, kw_only_default = True )
+class CompleteDataclass( Class ):
+    ''' Immutable dataclass factory.
+
+        Dataclasses from this factory produce immutable instances. '''
+    def __new__( # pylint: disable=too-many-arguments
+        clscls: type[ CompleteDataclass ],
+        name: str,
+        bases: tuple[ type, ... ],
+        namespace: dict[ str, __.typx.Any ], *,
+        decorators: ClassDecorators = ( ),
+        docstring: __.Absential[ __.typx.Optional[ str ] ] = __.absent,
+        mutables: __.cabc.Collection[ str ] = ( ),
+        **args: __.typx.Any
+    ) -> CompleteDataclass:
+        decorators_ = (
+            __.dcls.dataclass( frozen = True, kw_only = True, slots = True ),
+            *decorators )
+        return Class.__new__( # pyright: ignore
+            clscls, name, bases, namespace,
+            decorators = decorators_,
+            docstring = docstring,
+            mutables = mutables,
+            **args )
+
+CompleteDataclass.__doc__ = __.generate_docstring(
+    CompleteDataclass,
+    'description of class factory class',
+    'class attributes immutability' )
+
+
 class ABCFactory( __.abc.ABCMeta ):
     ''' Immutable abstract base class factory. '''
 
@@ -185,6 +243,70 @@ ProtocolClass.__doc__ = __.generate_docstring(
     'class attributes immutability' )
 
 
+# pylint: disable=bad-classmethod-argument,no-self-argument
+@__.typx.dataclass_transform( kw_only_default = True )
+class ProtocolDataclass( ProtocolClass ):
+    ''' Immutable protocol dataclass factory. '''
+    def __new__( # pylint: disable=too-many-arguments
+        clscls: type[ ProtocolDataclass ],
+        name: str,
+        bases: tuple[ type, ... ],
+        namespace: dict[ str, __.typx.Any ], *,
+        decorators: ClassDecorators = ( ),
+        docstring: __.Absential[ __.typx.Optional[ str ] ] = __.absent,
+        mutables: __.cabc.Collection[ str ] = ( ),
+        **args: __.typx.Any
+    ) -> ProtocolDataclass:
+        decorators_ = (
+            __.dcls.dataclass( kw_only = True, slots = True ),
+            *decorators )
+        return ProtocolClass.__new__( # pyright: ignore
+            clscls, name, bases, namespace,
+            decorators = decorators_,
+            docstring = docstring,
+            mutables = mutables,
+            **args )
+# pylint: enable=bad-classmethod-argument,no-self-argument
+
+ProtocolDataclass.__doc__ = __.generate_docstring(
+    ProtocolDataclass,
+    'description of class factory class',
+    'class attributes immutability' )
+
+
+# pylint: disable=bad-classmethod-argument,no-self-argument
+@__.typx.dataclass_transform( frozen_default = True, kw_only_default = True )
+class CompleteProtocolDataclass( ProtocolClass ):
+    ''' Immutable protocol dataclass factory.
+
+        Dataclasses from this factory produce immutable instances. '''
+    def __new__( # pylint: disable=too-many-arguments
+        clscls: type[ CompleteProtocolDataclass ],
+        name: str,
+        bases: tuple[ type, ... ],
+        namespace: dict[ str, __.typx.Any ], *,
+        decorators: ClassDecorators = ( ),
+        docstring: __.Absential[ __.typx.Optional[ str ] ] = __.absent,
+        mutables: __.cabc.Collection[ str ] = ( ),
+        **args: __.typx.Any
+    ) -> CompleteProtocolDataclass:
+        decorators_ = (
+            __.dcls.dataclass( frozen = True, kw_only = True, slots = True ),
+            *decorators )
+        return ProtocolClass.__new__( # pyright: ignore
+            clscls, name, bases, namespace,
+            decorators = decorators_,
+            docstring = docstring,
+            mutables = mutables,
+            **args )
+# pylint: enable=bad-classmethod-argument,no-self-argument
+
+CompleteProtocolDataclass.__doc__ = __.generate_docstring(
+    CompleteProtocolDataclass,
+    'description of class factory class',
+    'class attributes immutability' )
+
+
 def _accumulate_mutables(
     class_: type, mutables: __.cabc.Collection[ str ]
 ) -> frozenset[ str ]:

{frigid-2.0 → frigid-3.0}/sources/frigid/dictionaries.py

@@ -82,8 +82,7 @@ class AbstractDictionary( __.cabc.Mapping[ __.H, __.V ] ):
         after creation. This provides a clean interface for dictionaries
         that should never change.
 
-        Implementations must provide:
-        - __getitem__, __iter__, __len__
+        Implementations must provide __getitem__, __iter__, __len__.
     '''
 
     @__.abc.abstractmethod
@@ -110,6 +109,8 @@ class AbstractDictionary( __.cabc.Mapping[ __.H, __.V ] ):
 class _DictionaryOperations( AbstractDictionary[ __.H, __.V ] ):
     ''' Mix-in providing additional dictionary operations. '''
 
+    # TODO? Common __init__.
+
     def __or__( self, other: __.cabc.Mapping[ __.H, __.V ] ) -> __.typx.Self:
         if not isinstance( other, __.cabc.Mapping ): return NotImplemented
         conflicts = set( self.keys( ) ) & set( other.keys( ) )
@@ -170,6 +171,7 @@ class Dictionary( # pylint: disable=eq-without-hash
     _objects.Object, _DictionaryOperations[ __.H, __.V ]
 ):
     ''' Immutable dictionary. '''
+    # TODO: version 2.0: Do not subclass from 'Object'.
 
     __slots__ = ( '_data_', )
 
@@ -251,10 +253,6 @@ class Dictionary( # pylint: disable=eq-without-hash
 
 Dictionary.__doc__ = __.generate_docstring(
     Dictionary, 'dictionary entries immutability' )
-# Register as subclass of Mapping rather than use it as mixin.
-# We directly implement, for the sake of efficiency, the methods which the
-# mixin would provide.
-__.cabc.Mapping.register( Dictionary )  # type: ignore
 
 
 class ValidatorDictionary( Dictionary[ __.H, __.V ] ):

{frigid-2.0 → frigid-3.0}/sources/frigid/exceptions.py

@@ -23,11 +23,6 @@
     Provides a hierarchy of exceptions that are raised when immutability is
     violated. The hierarchy is designed to allow both specific and general
     exception handling.
-
-    * ``Omniexception``: Base for all package exceptions
-    * ``Omnierror``: Base for all package errors
-    * ``AttributeImmutabilityError``: Raised for attribute modification
-    * ``EntryImmutabilityError``: Raised for dictionary entry modification
 '''
 
 
@@ -59,7 +54,7 @@ class DecoratorCompatibilityError( Omnierror, TypeError ):
     def __init__( self, class_name: str, method_name: str ) -> None:
         # TODO: Use helper function to extract class name from class.
         super( ).__init__(
-            f"Cannot apply immutable decorator to {class_name!r} "
+            f"Cannot apply immutability decorator to {class_name!r} "
             f"because it defines {method_name!r}.")
 
 
@@ -68,7 +63,7 @@ class EntryImmutabilityError( Omnierror, TypeError ):
 
     def __init__( self, key: __.cabc.Hashable ) -> None:
         super( ).__init__(
-            f"Cannot assign or delete entry for {key!r}." )
+            f"Cannot add, alter, or remove entry for {key!r}." )
 
 
 class EntryValidityError( Omnierror, ValueError ):
@@ -80,10 +75,3 @@ class EntryValidityError( Omnierror, ValueError ):
         super( ).__init__(
             f"Cannot add invalid entry with key, {indicator!r}, "
             f"and value, {value!r}, to dictionary." )
-
-
-class OperationInvalidity( Omnierror, RuntimeError, TypeError ):
-    ''' Attempt to perform invalid operation. '''
-
-    def __init__( self, name: str ) -> None:
-        super( ).__init__( f"Operation {name!r} is not valid on this object." )

{frigid-2.0 → frigid-3.0}/sources/frigid/modules.py

@@ -66,18 +66,15 @@ def reclassify_modules(
 ) -> None:
     ''' Reclassifies modules to be immutable.
 
-        This function converts existing modules to immutable modules, enforcing
-        attribute immutability after conversion. It can operate on individual
-        modules or entire package hierarchies.
+        Can operate on individual modules or entire package hierarchies.
 
         Notes
         -----
         * Only converts modules within the same package to prevent unintended
-          modifications to external modules
+          modifications to external modules.
         * When used with a dictionary, converts any module objects found as
-          values if they belong to the same package
-        * Module conversion is permanent for the runtime session
-        * Has no effect on already-immutable modules
+          values if they belong to the same package.
+        * Has no effect on already-immutable modules.
     '''
     from inspect import ismodule
     from sys import modules

frigid-3.0/sources/frigid/objects.py

@@ -0,0 +1,190 @@
+# 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.                                            #
+#                                                                            #
+#============================================================================#
+
+
+# ruff: noqa: F811
+
+
+# pylint: disable=line-too-long
+''' Immutable objects.
+
+    Provides a base class and decorator for creating objects with immutable
+    attributes. Once an object is initialized, its attributes cannot be modified
+    or deleted.
+
+    >>> from frigid import Object
+    >>> class Point( Object ):
+    ...     def __init__( self, x, y ):
+    ...         self.x = x
+    ...         self.y = y
+    ...         super( ).__init__( )
+    ...
+    >>> obj = Point( 1, 2 )  # Initialize with attributes
+    >>> obj.z = 3  # Attempt to add attribute
+    Traceback (most recent call last):
+    ...
+    frigid.exceptions.AttributeImmutabilityError: Cannot assign or delete attribute 'z'.
+    >>> obj.x = 4  # Attempt modification
+    Traceback (most recent call last):
+    ...
+    frigid.exceptions.AttributeImmutabilityError: Cannot assign or delete attribute 'x'.
+
+    The `immutable` decorator can be used to make any class immutable:
+
+    >>> from frigid import immutable
+    >>> @immutable
+    ... class Config:
+    ...     def __init__( self, verbose = False ):
+    ...         self.verbose  = verbose
+    ...
+    >>> config = Config( verbose = True )
+    >>> config.verbose = False  # Attempt to modify attribute
+    Traceback (most recent call last):
+        ...
+    frigid.exceptions.AttributeImmutabilityError: ...
+'''
+# pylint: enable=line-too-long
+
+
+from . import __
+
+
+_behavior = 'immutability'
+
+
+def _check_behavior( obj: object ) -> bool:
+    behaviors: __.cabc.MutableSet[ str ]
+    if _check_dict( obj ):
+        attributes = getattr( obj, '__dict__' )
+        behaviors = attributes.get( '_behaviors_', set( ) )
+    else: behaviors = getattr( obj, '_behaviors_', set( ) )
+    return _behavior in behaviors
+
+
+def _check_dict( obj: object ) -> bool:
+    # Return False even if '__dict__' in '__slots__'.
+    if hasattr( obj, '__slots__' ): return False
+    return hasattr( obj, '__dict__' )
+
+
+@__.typx.overload
+def immutable( # pragma: no branch
+    class_: type[ __.C ], *,
+    docstring: __.Absential[ __.typx.Optional[ str ] ] = __.absent,
+    mutables: __.cabc.Collection[ str ] = ( )
+) -> type[ __.C ]: ...
+
+
+@__.typx.overload
+def immutable( # pragma: no branch
+    class_: __.AbsentSingleton, *,
+    docstring: __.Absential[ __.typx.Optional[ str ] ] = __.absent,
+    mutables: __.cabc.Collection[ str ] = ( )
+) -> __.typx.Callable[ [ type[ __.C ] ], type[ __.C ] ]: ...
+
+
+def immutable( # pylint: disable=too-complex,too-many-statements
+    class_: __.Absential[ type[ __.C ] ] = __.absent, *,
+    docstring: __.Absential[ __.typx.Optional[ str ] ] = __.absent,
+    mutables: __.cabc.Collection[ str ] = ( )
+) -> __.typx.Union[
+    type[ __.C ], __.typx.Callable[ [ type[ __.C ] ], type[ __.C ] ]
+]:
+    ''' Decorator which makes class immutable after initialization.
+
+        Cannot be applied to classes which define their own __setattr__
+        or __delattr__ methods.
+
+        This decorator can be used in different ways:
+
+        1. Simple decorator:
+
+           >>> @immutable
+           ... class Config:
+           ...     pass
+
+        2. With parameters:
+
+           >>> @immutable( mutables = ( 'version', ) )
+           ... class Config:
+           ...     pass
+    '''
+    def decorator( cls: type[ __.C ] ) -> type[ __.C ]: # pylint: disable=too-many-statements
+        if not __.is_absent( docstring ): cls.__doc__ = docstring
+        for method in ( '__setattr__', '__delattr__' ):
+            if method in cls.__dict__:
+                from .exceptions import DecoratorCompatibilityError
+                raise DecoratorCompatibilityError( cls.__name__, method )
+        original_init = next(
+            base.__dict__[ '__init__' ] for base in cls.__mro__
+            if '__init__' in base.__dict__ ) # pylint: disable=magic-value-comparison
+        mutables_ = frozenset( mutables )
+
+        def __init__(
+            self: object, *posargs: __.typx.Any, **nomargs: __.typx.Any
+        ) -> None:
+            original_init( self, *posargs, **nomargs )
+            behaviors: __.cabc.MutableSet[ str ]
+            if _check_dict( self ):
+                attributes = getattr( self, '__dict__' )
+                behaviors = attributes.get( '_behaviors_', set( ) )
+                if not behaviors: attributes[ '_behaviors_' ] = behaviors
+            else:
+                behaviors = getattr( self, '_behaviors_', set( ) )
+                if not behaviors: setattr( self, '_behaviors_', behaviors )
+            behaviors.add( _behavior )
+
+        def __delattr__( self: object, name: str ) -> None:
+            if name in mutables_:
+                super( cls, self ).__delattr__( name )
+                return
+            if _check_behavior( self ): # pragma: no branch
+                from .exceptions import AttributeImmutabilityError
+                raise AttributeImmutabilityError( name )
+            super( cls, self ).__delattr__( name ) # pragma: no cover
+
+        def __setattr__( self: object, name: str, value: __.typx.Any ) -> None:
+            if name in mutables_:
+                super( cls, self ).__setattr__( name, value )
+                return
+            if _check_behavior( self ):
+                from .exceptions import AttributeImmutabilityError
+                raise AttributeImmutabilityError( name )
+            super( cls, self ).__setattr__( name, value )
+
+        cls.__init__ = __init__
+        cls.__delattr__ = __delattr__
+        cls.__setattr__ = __setattr__
+        return cls
+
+    if not __.is_absent( class_ ): return decorator( class_ )
+    return decorator # No class to decorate; keyword arguments only.
+
+
+@immutable
+class Object:
+    ''' Immutable objects. '''
+
+    __slots__ = ( '__dict__', '_behaviors_' )
+
+    def __repr__( self ) -> str:
+        return "{fqname}( )".format( fqname = __.calculate_fqname( self ) )
+
+Object.__doc__ = __.generate_docstring(
+    Object, 'instance attributes immutability' )

{frigid-2.0 → frigid-3.0}/sources/frigid/qaliases.py

@@ -42,9 +42,13 @@
 
 from . import __
 from .classes import (
-    ABCFactory as           ImmutableABCFactory,
-    Class as                ImmutableClass,
-    ProtocolClass as        ImmutableProtocolClass,
+    ABCFactory as                   ImmutableABCFactory,
+    Class as                        ImmutableClass,
+    CompleteDataclass as            ImmutableCompleteDataclass,
+    CompleteProtocolDataclass as    ImmutableCompleteProtocolDataclass,
+    Dataclass as                    ImmutableDataclass,
+    ProtocolClass as                ImmutableProtocolClass,
+    ProtocolDataclass as            ImmutableProtocolDataclass,
 )
 from .dictionaries import (
     AbstractDictionary as   AbstractImmutableDictionary,
@@ -60,5 +64,5 @@ from .namespaces import (
 )
 from .objects import (
     Object as               ImmutableObject,
-    immutable,
+                            immutable,
 )

frigid-2.0/sources/frigid/objects.py

@@ -1,129 +0,0 @@
-# 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.                                            #
-#                                                                            #
-#============================================================================#
-
-
-# pylint: disable=line-too-long
-''' Immutable objects.
-
-    Provides a base class and decorator for creating objects with immutable
-    attributes. Once an object is initialized, its attributes cannot be modified
-    or deleted.
-
-    The implementation uses a special dictionary type for attribute storage that
-    enforces immutability. This makes it suitable for:
-
-    * Configuration objects
-    * Value objects
-    * Immutable data containers
-    * Objects requiring attribute stability
-
-    >>> from frigid import Object
-    >>> class Point( Object ):
-    ...     def __init__( self, x, y ):
-    ...         self.x = x
-    ...         self.y = y
-    ...         super( ).__init__( )
-    ...
-    >>> obj = Point( 1, 2 )  # Initialize with attributes
-    >>> obj.z = 3  # Attempt to add attribute
-    Traceback (most recent call last):
-    ...
-    frigid.exceptions.AttributeImmutabilityError: Cannot assign or delete attribute 'z'.
-    >>> obj.x = 4  # Attempt modification
-    Traceback (most recent call last):
-    ...
-    frigid.exceptions.AttributeImmutabilityError: Cannot assign or delete attribute 'x'.
-'''
-# pylint: enable=line-too-long
-
-
-from . import __
-
-
-def _check_behavior( obj: object ) -> bool:
-    behaviors: __.cabc.MutableSet[ str ]
-    if _check_dict( obj ):
-        attributes = getattr( obj, '__dict__' )
-        behaviors = attributes.get( '_behaviors_', set( ) )
-    else: behaviors = getattr( obj, '_behaviors_', set( ) )
-    return __.behavior_label in behaviors
-
-
-def _check_dict( obj: object ) -> bool:
-    # Return False even if '__dict__' in '__slots__'.
-    if hasattr( obj, '__slots__' ): return False
-    return hasattr( obj, '__dict__' )
-
-
-def immutable( class_: type[ __.C ] ) -> type[ __.C ]: # pylint: disable=too-complex
-    ''' Decorator which makes class immutable after initialization.
-
-        Cannot be applied to classes which define their own __setattr__
-        or __delattr__ methods.
-    '''
-    for method in ( '__setattr__', '__delattr__' ):
-        if method in class_.__dict__:
-            from .exceptions import DecoratorCompatibilityError
-            raise DecoratorCompatibilityError( class_.__name__, method )
-    original_init = next(
-        base.__dict__[ '__init__' ] for base in class_.__mro__
-        if '__init__' in base.__dict__ ) # pylint: disable=magic-value-comparison
-
-    def __init__(
-        self: object, *posargs: __.typx.Any, **nomargs: __.typx.Any
-    ) -> None:
-        # TODO: Use accretive set for behaviors.
-        original_init( self, *posargs, **nomargs )
-        behaviors: __.cabc.MutableSet[ str ]
-        if _check_dict( self ):
-            attributes = getattr( self, '__dict__' )
-            behaviors = attributes.get( '_behaviors_', set( ) )
-            if not behaviors: attributes[ '_behaviors_' ] = behaviors
-            setattr( self, '__dict__', __.ImmutableDictionary( attributes ) )
-        else:
-            behaviors = getattr( self, '_behaviors_', set( ) )
-            if not behaviors: setattr( self, '_behaviors_', behaviors )
-        behaviors.add( __.behavior_label )
-
-    def __delattr__( self: object, name: str ) -> None:
-        if _check_behavior( self ):
-            from .exceptions import AttributeImmutabilityError
-            raise AttributeImmutabilityError( name )
-        super( class_, self ).__delattr__( name )
-
-    def __setattr__( self: object, name: str, value: __.typx.Any ) -> None:
-        if _check_behavior( self ):
-            from .exceptions import AttributeImmutabilityError
-            raise AttributeImmutabilityError( name )
-        super( class_, self ).__setattr__( name, value )
-
-    class_.__init__ = __init__
-    class_.__delattr__ = __delattr__
-    class_.__setattr__ = __setattr__
-    return class_
-
-
-@immutable
-class Object:
-    ''' Immutable objects. '''
-
-    __slots__ = ( '__dict__', '_behaviors_' )
-
-Object.__doc__ = __.generate_docstring(
-    Object, 'instance attributes immutability' )