Standard Classes¶
Introduction¶
The standard subpackage provides base classes, decorators, and class
factories (metaclasses) to imbue classes, and the instances which they produce,
with attributes concealment and immutability.
>>> import classcore.standard as ccstd
Inheriting from a standard base class:
>>> class Point2d( ccstd.Object ):
... def __init__( self, x: float, y: float ) -> None:
... self.x = x
... self.y = y
...
>>> point = Point2d( 3, 4 )
>>> type( Point2d )
<class 'classcore.standard.classes.Class'>
is essentially equivalent to producing a new class with a standard metaclass:
>>> class Point2d( metaclass = ccstd.Class ):
... def __init__( self, x: float, y: float ) -> None:
... self.x = x
... self.y = y
...
>>> point = Point2d( 5, 12 )
Concealment and Immutability¶
Both classes have immutable attributes. For example, we cannot delete the
__init__ method that we defined:
>>> del Point2d.__init__
Traceback (most recent call last):
...
classcore.exceptions.AttributeImmutability: Could not assign or delete attribute '__init__' on class ...
Nor, for example, can we add a default value for x:
>>> Point2d.x = 3
Traceback (most recent call last):
...
classcore.exceptions.AttributeImmutability: Could not assign or delete attribute 'x' on class ...
Also, all non-public attributes on the class are concealed from dir():
>>> dir( Point2d )
[]
The instances of these classes also have immutable attributes:
>>> point.x = 3
Traceback (most recent call last):
...
classcore.exceptions.AttributeImmutability: Could not assign or delete attribute 'x' on instance of class ...
And concealed non-public attributes:
>>> dir( point )
['x', 'y']
Decoration versus Production¶
By contrast, if we decorate an existing class, then it retains the default Python behavior (full mutability and visibility) with respect to its class attributes:
>>> @ccstd.with_standard_behaviors( )
... class Point2d:
... def __init__( self, x: float, y: float ) -> None:
... self.x = x
... self.y = y
...
>>> point = Point2d( 8, 15 )
>>> type( Point2d )
<class 'type'>
>>> '__init__' in dir( Point2d )
True
>>> del Point2d.__init__
However, attributes on its instances are immutable and concealed, which is the same behavior as for the classes we produced:
>>> dir( point )
['x', 'y']
>>> point.x = 5
Traceback (most recent call last):
...
classcore.exceptions.AttributeImmutability: Could not assign or delete attribute 'x' on instance of class ...
Thus, if you do not desire class attributes concealment and immutability, you can choose to decorate classes rather than produce them.
Mutable Instances¶
To produce classes with immutable attributes but instances with mutable
attributes, there is a convenience class, ObjectMutable.
>>> class Point2d( ccstd.ObjectMutable ):
... def __init__( self, x: float, y: float ) -> None:
... self.x = x
... self.y = y
...
>>> point = Point2d( 7, 24 )
>>> point.x, point.y = 20, 21
>>> point.x, point.y
(20, 21)
Attribute Preallocations¶
You can preallocate attributes using the standard Python __slots__
mechanism. In addition to potential performance gains for attribute lookups,
this can be useful if you are making a namespace class and want to keep the
namespace dictionary free of record-keeping attributes. You cannot inherit a
standard base class, such as Object, for this purpose, as it is
__dict__-based. However, you can create the namespace class via metaclass.
>>> class Namespace( metaclass = ccstd.Class ):
... __slots__ = ( '__dict__', )
... def __init__( self, **arguments: float ) -> None:
... self.__dict__.update( arguments )
...
>>> ns = Namespace( x = 20, y = 21 )
>>> ns.__slots__
('__dict__', '_classcore_instance_behaviors_')
>>> 'x' in ns.__dict__
True
>>> '_classcore_instance_behaviors_' in ns.__dict__
False
>>> ns.x, ns.y
(20, 21)
The mapping form of __slots__ is also supported.
>>> class Namespace( metaclass = ccstd.Class ):
... __slots__ = { '__dict__': 'Namespace attributes.' }
... def __init__( self, **arguments: float ):
... self.__dict__.update( arguments )
...
>>> ns = Namespace( x = 20, y = 21 )
>>> ns.__slots__[ '__dict__' ]
'Namespace attributes.'
Suppression of Initialization Arguments¶
In some cases, you may inherit from classes which process their instance
construction arguments via __new__ rather than __init__. This is
experienced, for example, where tuple and other immutable builtins
are subclassed. To prevent the construction arguments from being applied to the
__init__ call chain, you can set instances_ignore_init_arguments to
True as a class argument.
>>> from urllib.parse import ParseResult, urlparse
>>> class Url( ccstd.Object, ParseResult, instances_ignore_init_arguments = True ):
... pass
...
>>> u = Url( *urlparse( 'https://python.org' ) )
Or as ignore_init_arguments as True to a decorator.
>>> @ccstd.with_standard_behaviors( ignore_init_arguments = True )
... class Url( ParseResult ): pass
...
>>> u = Url( *urlparse( 'https://python.org' ) )
Integrations with Custom Behaviors¶
You can define dunder methods, like __delattr__, __setattr__, and
__dir__, and they will be automatically wrapped by the decorators which
setup attributes concealment and immutability enforcement on classes.
>>> class Point2d( ccstd.ObjectMutable ):
... def __init__( self, x: float, y: float ) -> None:
... super( ).__init__( )
... self.x = x
... self.y = y
... def __delattr__( self, name: str ) -> None:
... if not name.startswith( '_' ): print( name )
... super( ).__delattr__( name )
... def __setattr__( self, name: str, value ) -> None:
... if not name.startswith( '_' ): print( f"{name} = {value!r}" )
... super( ).__setattr__( name, value )
... def __dir__( self ):
... print( 'called dir' )
... return super( ).__dir__( )
...
>>> point = Point2d( 3, 4 )
x = 3
y = 4
>>> point.x, point.y = 5, 12
x = 5
y = 12
>>> del point.y
y
>>> 'x' in dir( point )
called dir
True
The integration points work correctly with inheritance. Furthermore, the standard behaviors (concealment and immutability) are idempotent, which improves their performance in class hierarchies.
>>> class Point3d( Point2d ):
... def __init__( self, x: float, y: float, z: float ) -> None:
... super( ).__init__( x, y )
... self.z = z
... def __delattr__( self, name: str ) -> None:
... if name == 'z': print( 'Z!' )
... super( ).__delattr__( name )
... def __setattr__( self, name: str, value ) -> None:
... if name == 'z': print( 'Z!' )
... super( ).__setattr__( name, value )
... def __dir__( self ):
... print( 'called dir in 3D' )
... return super( ).__dir__( )
...
>>> point3 = Point3d( 5, 12, 17 )
x = 5
y = 12
Z!
z = 17
>>> point3.z = 60
Z!
z = 60
>>> del point3.z
Z!
z
>>> 'z' not in dir( point3 )
called dir in 3D
called dir
True