djblets.util.properties¶

Specialized descriptors/properties for classes.

class BaseProperty[source]¶

Bases: object

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.

get_attr_name(instance)[source]¶

Return the name of this property’s attribute.

The value will be computed only once per property instance.

Parameters

instance (object) – The instance owning this property.

Returns

The name of this property on the instance.

Return type

str

class AliasProperty(prop_name, convert_to_func=None, convert_from_func=None, deprecated=False, deprecation_warning=<class 'DeprecationWarning'>)[source]¶

Bases: djblets.util.properties.BaseProperty

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.

__init__(prop_name, convert_to_func=None, convert_from_func=None, deprecated=False, deprecation_warning=<class 'DeprecationWarning'>)[source]¶

Initialize the property.

Parameters

• prop_name (str) – The name of the property or attribute to read from and write it.

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

__set__(instance, value)[source]¶

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, owner)[source]¶

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__ = {}¶

class TypedProperty(valid_types, default=None, allow_none=True)[source]¶

Bases: djblets.util.properties.BaseProperty

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.

__init__(valid_types, default=None, allow_none=True)[source]¶

Initialize the property.

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.

__set__(instance, value)[source]¶

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, owner)[source]¶

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

__annotations__ = {}¶

get_descriptor_attr_name(descriptor, cls)[source]¶

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.

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