Coverage for sources/classcore/standard/__.py: 100%
24 statements
« prev ^ index » next coverage.py v7.16.2, created at 2026-10-15 18:04 +0000
« prev ^ index » next coverage.py v7.16.2, created at 2026-10-15 18:04 +0000
1# vim: set filetype=python fileencoding=utf-8:
2# -*- coding: utf-8 -*-
4#============================================================================#
5# #
6# Licensed under the Apache License, Version 2.0 (the "License"); #
7# you may not use this file except in compliance with the License. #
8# You may obtain a copy of the License at #
9# #
10# http://www.apache.org/licenses/LICENSE-2.0 #
11# #
12# Unless required by applicable law or agreed to in writing, software #
13# distributed under the License is distributed on an "AS IS" BASIS, #
14# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. #
15# See the License for the specific language governing permissions and #
16# limitations under the License. #
17# #
18#============================================================================#
21''' Common constants, imports, and utilities. '''
23# ruff: noqa: F403, F405
26from ..__ import *
27from ..nomina import is_public_identifier
30def provide_error_class( name: str ) -> type[ Exception ]:
31 ''' Produces error class for this package. '''
32 match name:
33 case 'AttributeImmutability':
34 from ..exceptions import AttributeImmutability as error
35 case _:
36 from ..exceptions import ErrorProvideFailure
37 raise ErrorProvideFailure( name, reason = 'Does not exist.' )
38 return error
41mutables_default = ( )
42visibles_default = ( is_public_identifier, )
44# Standard library ABC machinery attribute names which the class-level
45# immutability behavior permits. The C _abc implementation writes these
46# cache attributes through direct dict access, so they must remain
47# assignable on standard classes. Also used to mark such names as
48# internal in attribute explanations.
49abc_class_mutables = (
50 '_abc_cache',
51 '_abc_negative_cache',
52 '_abc_negative_cache_version',
53 '_abc_registry',
54)
55# Standard library typing machinery attribute names which the
56# class-level immutability behavior permits on protocol classes.
57# 'typing' sets these protocol bookkeeping attributes during class
58# decoration: '_is_runtime_protocol' and '__non_callable_proto_members__'
59# in the 'runtime_checkable' decorator, and
60# '__typing_is_deprecated_inherited_runtime_protocol__' (CPython 3.15+)
61# during class decoration and in 'runtime_checkable'. Without this
62# exemption, decorating a runtime protocol which inherits runtime
63# checkability fails. Also used to mark such names as internal in
64# attribute explanations.
65typing_class_mutables = (
66 '_is_runtime_protocol',
67 '__non_callable_proto_members__',
68 '__typing_is_deprecated_inherited_runtime_protocol__', # Python 3.15+
69)
72def is_same_detector(
73 detector: cabc.Callable[ [ str ], bool ],
74 other: cabc.Callable[ [ str ], bool ], /,
75) -> bool:
76 ''' Returns whether two detector references are the same detector.
78 Bound methods are the same detector only when both the
79 underlying function and the bound instance are identical, so
80 distinct namer instances with distinct configured behavior keep
81 separate contributions. Plain callables compare by identity.
82 '''
83 if detector is other: return True
84 function = getattr( detector, '__func__', None )
85 other_function = getattr( other, '__func__', None )
86 if function is None or other_function is None: return False
87 return (
88 function is other_function
89 and getattr( detector, '__self__', None )
90 is getattr( other, '__self__', None ) )
93def augment_internal_names(
94 cls: type, /, detector: cabc.Callable[ [ str ], bool ]
95) -> None:
96 ''' Adds an internal-name detector to existing contributions.
98 Private wiring point for machinery mixins: the abstract-base
99 metaclass adds the stdlib machinery set after factory
100 decoration, without expanding public factory arguments.
101 '''
102 detectors = getattr( cls, calculate_contribution_name( ), ( ) )
103 if any( is_same_detector( detector, d ) for d in detectors ): return
104 setattr(
105 cls, calculate_contribution_name( ),
106 ( *detectors, detector ) )