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.

__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