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