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.

attr_name: str¶

The name of the owning attribute.

New in version 3.3.

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.

Parameters:

instance (object) – The instance owning this property.

Returns:

The name of this property on the instance.

Return type:

str

__set_name__(owner: type, name: str) → None¶

Handle setting the attribute name for this property.

New in version 3.3.

Parameters:

• owner (type, unused) – The class that owns the property.

• name (str) – The attribute name for this property.

__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 of DeprecationWarning.

prop_name: str¶

The name of the property or attribute to read from and write to

deprecated: bool¶

Whether to emit a deprecation warning on access.

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.

Parameters:

• instance (object) – The instance owning this property.

• value (object) – The value being set.

__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.

Parameters:

• instance (object) – The instance owning this property.

• owner (type) – The instance’s class.

Returns:

The property value.

Return type:

object

__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.

Parameters:

• valid_types (list of type) – The types of values that are permitted to be set.

• default (object, optional) – The default value, if one is not set.

• allow_none (bool, optional) – Whether None values are allowed to be set.

valid_types: Tuple[Type[_SetT], ...]¶

The types that are valid for this property.

New values are checked against this at runtime.

default: Optional[_TypedPropertyGetT]¶

The default value for the property if one is not set.

allow_none: bool¶

Whether a None value is allowed to be set.

__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.

Parameters:

• instance (object) – The instance owning this property.

• value (object) – The value being set.

Raises:

TypeError – The value is not of a valid type.

__get__(instance: None, owner: Type[object]) → Self¶

__get__(instance: object, owner: Type[object]) → _TypedPropertyGetT

Return the value of the property.

Parameters:

• instance (object) – The instance owning this property.

• owner (type) – The instance’s class.

Returns:

The property value.

Return type:

object

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.

Parameters:

• descriptor (object) – The instance of the property/descriptor. For a proper value to be returned, this must exist on cls.

• cls (type) – The class owning the property.

Returns:

The name of the property/descriptor.

Return type:

str