djblets.util.properties¶
Specialized descriptors/properties for classes.
- class BaseProperty¶
Bases:
Generic
[_StoredT
]Base class for a custom property for a class.
This is an optional base class that provides handy utilities that properties may need. For instance, being able to determine the name of the property’s attribute on a class.
Changed in version 3.3: This now supports generics for typing, taking the type of the stored content.
- get_attr_name(instance: object) str ¶
Return the name of this property’s attribute.
Deprecated since version 3.3: This has been replaced with
attr_name
, and will be removed in Djblets 5.0.
- __set_name__(owner: type, name: str) None ¶
Handle setting the attribute name for this property.
New in version 3.3.
- __annotations__ = {'attr_name': 'str'}¶
- __orig_bases__ = (typing.Generic[~_StoredT],)¶
- __parameters__ = (~_StoredT,)¶
- class AliasProperty(prop_name: str, *, convert_to_func: ~typing.Optional[~typing.Callable[[~djblets.util.properties._AliasPropertySetT], ~typing.Any]] = None, convert_from_func: ~typing.Optional[~typing.Callable[[~typing.Any], ~djblets.util.properties._GetT]] = None, deprecated: bool = False, deprecation_warning: ~typing.Type[DeprecationWarning] = <class 'DeprecationWarning'>)¶
Bases:
Generic
[_GetT
,_AliasPropertySetT
],BaseProperty
[Any
]A property that aliases to another property or attribute.
Alias properties are used to automatically retrieve from another property on access, or to set a value on another property. It’s useful when wanting to rename an attribute but continue to provide a deprecated version, or when creating an object that provides a set of compatibility attributes for use with legacy code.
Alias properties can optionally emit a deprecation warning on use, in order to help in the process of migrating legacy code.
Changed in version 3.3: This now supports generics for typing, taking the types to return on access, and types that can be set.
Example
class MyClass: new_prop: str old_prop: AliasProperty[int, str] = AliasProperty[int, str]( 'new_prop', convert_to_func=str, convert_from_func=int)
Note that the explicit type declaration is important. Without it, type checkers may allow constructors to override the type.
- __init__(prop_name: str, *, convert_to_func: ~typing.Optional[~typing.Callable[[~djblets.util.properties._AliasPropertySetT], ~typing.Any]] = None, convert_from_func: ~typing.Optional[~typing.Callable[[~typing.Any], ~djblets.util.properties._GetT]] = None, deprecated: bool = False, deprecation_warning: ~typing.Type[DeprecationWarning] = <class 'DeprecationWarning'>) None ¶
Initialize the property.
Changed in version 3.3: All arguments but
prop_name
must be provided as keyword arguments. This will be enforced in Djblets 5.0.- Parameters:
prop_name (
str
) – The name of the property or attribute to read from and write to.convert_to_func (
callable
, optional) – An optional function to call on a value before setting it on the aliased property name. This must take in the value as a parameter and return a value to set.convert_from_func (
callable
, optional) – An optional function to call on a value after accessing it on the aliased property name and before returning to the caller. This must take in the value from the aliased property and return a value to return to the caller.deprecated (
bool
, optional) – Whether to emit a deprecation warning when setting or accessing the property.deprecation_warning (
type
) – The type of class to use for the deprecation warning. This should be a subclass ofDeprecationWarning
.
- deprecation_warning: Type[DeprecationWarning]¶
The type of class to use for the deprecation warning.
- __set__(instance: object, value: _AliasPropertySetT) None ¶
Set a value on the property.
This will convert the value (if
convert_to_func
was provided to this property) and set it on the aliased property.If this is a deprecated property, this will emit a warning.
- __get__(instance: None, owner: Type[object]) Self ¶
- __get__(instance: object, owner: Type[object]) _GetT
Return the value of the property.
This will retrieve the value from the aliased property, converting it (if
convert_from_func
was provided to this property), and return it.If this is a deprecated property, this will emit a warning.
- __annotations__ = {'attr_name': 'str', 'deprecated': 'bool', 'deprecation_warning': 'Type[DeprecationWarning]', 'prop_name': 'str'}¶
- __orig_bases__ = (typing.Generic[~_GetT, ~_AliasPropertySetT], djblets.util.properties.BaseProperty[typing.Any])¶
- __parameters__ = (~_GetT, ~_AliasPropertySetT)¶
- class TypedProperty(valid_types: Union[Type[_SetT], Sequence[Type[_SetT]]], *, default: Optional[_TypedPropertyGetT] = None, allow_none: bool = True)¶
Bases:
Generic
[_TypedPropertyGetT
,_SetT
],BaseProperty
[_TypedPropertyGetT
]A property that enforces type safety.
This property will ensure that only values that are compatible with a given type can be set. This ensures type safety and helps catch errors early.
Changed in version 3.3: This now supports generics for typing, taking the types to return on access, and types that can be set.
Example
class MyClass: optional_prop: TypedProperty[Optional[str], Optional[str]] = TypedProperty(str) required_to_set_prop: TypedProperty[Optional[int], int] = TypedProperty(int, default=None allow_none=False) never_none_prop: TypedProperty[int, int] = TypedProperty(int, default=42, allow_none=False)
Note that the explicit type declaration is important. Without it, type checkers may allow constructors to override the type.
- __annotations__ = {'allow_none': 'bool', 'default': 'Optional[_TypedPropertyGetT]', 'valid_types': 'Tuple[Type[_SetT], ...]'}¶
- __orig_bases__ = (typing.Generic[~_TypedPropertyGetT, ~_SetT], djblets.util.properties.BaseProperty[~_TypedPropertyGetT])¶
- __parameters__ = (~_TypedPropertyGetT, ~_SetT)¶
- __init__(valid_types: Union[Type[_SetT], Sequence[Type[_SetT]]], *, default: Optional[_TypedPropertyGetT] = None, allow_none: bool = True) None ¶
Initialize the property.
Changed in version 3.3: All arguments but
prop_name
must be provided as keyword arguments. This will be enforced in Djblets 5.0.
- valid_types: Tuple[Type[_SetT], ...]¶
The types that are valid for this property.
New values are checked against this at runtime.
- __set__(instance: object, value: _SetT) None ¶
Set a value on the property.
This will check if the value is of a valid type, and then set it on the instance.
- get_descriptor_attr_name(descriptor, cls)¶
Return the name of a property/descriptor instance on a class.
This will go through the class and all parent classes, looking for the property, and returning its attribute name. This is primarily intended to help with providing better error messages.
Deprecated since version 3.3: This will be removed in Djblets 5.0. Callers should define a
__set_name__()
method on the descriptor instead.