v0.3.5 - Revert length conditionals

Bug Fixes

• v0.3.4 attempted to clean up some code that looked like if len(val) > 0: to just if val:. This works for lists, but not np.ndarrays since they have a different way of determining truth. This release reverts these changes back to checking length.

v0.3.4 - ARANZ Branding

Minor Changes

• Properties has been moved under ARANZ Geo Limited branding
• auto_create on Instance property has been deprecated (to be removed in a future release)
  • Instead of using auto_create, the instance class should be specified as default. This will maintain identical behavior.

v0.3.3 - Modifications to equal and new copy function

Major Features

• New properties.copy function that returns a copy of a HasProperties instance. This method uses serialize and deserialize to create the new instance. (see #147)
• HasProperties.equal has been moved to properties.equal (see #147)
  • This function determines if all property values on two HasProperties instances are equal
  • The movement to a top-level function from HasProperties method sets a precedent for keeping the HasProperties class namespace clean

Minor Changes

• Constraints placed on equal input so None and properties.undefined never reach equal (see #151)
• Backwards-compatibility warning - For consistency, in the change notification dictionary previous is now properties.undefined rather than None if the property value is not defined. This now matches the existing behavior of value in the change notification dictionary being properties.undefined rather than None if the value is deleted. (see #151)

Bug Fixes

• properties.Property.equal could return an iterator rather than a boolean given certain inputs (eg numpy arrays). This method now ensures iterators are reduced to a single boolean. (see #151)

v0.3.2 - Fix intersphinx class links

Bug Fixes

• Fix links in autogenerated docstrings so they point correctly to the new docs introduced in v0.3.1 (see #145)

v0.3.1 - Many New Features: DynamicProperty, Set/Tuple, equal method, etc.

Major Features

New Property types

• File Property - New Property validated as a file or file name. May provide mode to use for opening a file - if None, file must already be open. Also may provide valid_modes for files that are already open - if None, any mode (or file-like objects without mode like BytesIO) will be valid. (see #100)
  • ImagePNG Property is now a subclass of File. (see #118)
• DynamicProperty - New Property created when another property wraps a method. Behaves much like @property, where you can register setters and deleters that use other Properties. DynamicPropertys are never saved to the class. (see #108)
• Set and Tuple Properties - New Properties with set and tuple underlying data structures. (see #125)
• Renamed Property - for aiding backwards compatibility. (see #126)

Other features

• equal method on Property classes and HasProperties
  • This determines if two valid Property values are equal. It is used with HasProperties validation to ensure values have been set and validated correctly. (see #124)
  • Backwards-Compatibility Warning - HasProperties validate is now more strict. Rather than simply confirming properties are valid, it confirms that they are valid AND equal to their validated value. This difference is subtle and unlikely to be a problem under normal use. It provides one extra layer of checking that everything was set properly.
  • New observer handler that only fires on change, rather than set. use kwarg change_only=True. (see #125)
• regex attribute for String Property - If regex is specified, re.search on the input string must match the regular expression. (see #117)
• Modifications to StringChoiceProperty (see #120):
  • descriptions attribute - set this to a dictionary with choice keys and description values for improved documentation
  • case_sensitive attribute - determines if choice case should be enforced or just coerced
  • order of choices is now preserved (if applicable)
• coerce attribute for container properties (List, Tuple, Set) that if True, allows other container types or individual values (not in a container) as inputs, all of which are coerced to the appropriate container. (see #125)
• observe_mutations attribute for List and Set Properties (see #127)
  • This uses custom container classes that HasProperties change notifications when mutated
  • Pros: more reliable notifications, Cons: containers are repeatedly copied (bad for large lists/sets)
• New method decorator to stop_recursion_with a specified value if a method gets called recursively on the same HasProperties instance. (see #121)
• New listeners_disabled/observers_disabled/validators_disabled context managers for disabling validate and observe handlers. (see #123, #125)
• Enormous overhaul to sphinx docs and docstrings to make the online documentation much more useful. (see #136)
  • Backwards-Compatibility Warning - Intersphinx-linked documentation for projects implementing HasProperties will need to rebuild their documentation for links to be correct.

Minor Changes

• Backwards-Compatibility Warning - info_text and info() have been modified to class_info and info respectively. HasProperties with the former attributes will raise a FutureWarning but still work for now. (see #116)
• Tasks now have a built-in status report callback (see #122)
• Improved error messaging when instance is None and validation of Property attributes. (see #116)
• Improved automatic docstring formatting - no longer dependent on Sphinx formatting. (see #119)
• Instance Properties now support old-style classes. (see #116)
• _defaults may now contain properties.undefined to override previous default values with no default value. (see #136)

Bug Fixes

• Fixed bug where array validation was not raising an error if the array.type.kind was not 'i', 'f', or 'b' (see #107)

v0.3.0 - Major update: Serialization, Defaults, Metadata, etc.

Major Features

• Serialization:
  • Note: as_json has been renamed to_json for better parallels between from_json and to_json
  • Currently serialization/deserialization uses JSON. This can be overridden by registering custom serializers and deserializers to Property instances, and possibly overriding serialize in a HasProperties subclass. All the serialization methods pass around any kwargs they receive. This allows more flexibility in custom serializers (for example, an open file can be passed around).
  • In HasProperties:
    • serialize creates a JSON dictionary of all the properties using the property serialize functions. This dictionary may have a __class__ key that stores the HasProperties class for smart deserialization.
    • deserialize takes a dictionary and creates a new instance of theHasProperties class using valid property keywords in the dictionary. If deserialize is used on trusted JSON, it will use the _REGISTRY to find the correct __class__ to construct. If the JSON is not trusted, deserialize constructs an instance of the class it is called on.
  • In Property classes and subclasses:
    • to_json is a static method that takes a valid property value and converts it to JSON-serializable version. If the value cannot be converted statically (ie a Property instance is required), this errors.
    • from_json is a static method that takes a JSON-serializable value and converts it to the a valid property value. Again, if a Property instance is required, this errors.
    • serialize takes a property value and serializes it using either the registered serializer, to_json, or Property-subclass-specific serialization logic.
    • deserialize takes a JSON value and deserializes it to a valid property value using either the registered deserializer, from_json, or Property-subclass-specific deserialization logic.
• Defaults:
  • defaults wrapper has been removed. To implement dynamic defaults, specify a callable in the _defaults dictionary - this can no longer depend on self.
  • _defaults dictionary is now inherited. Any defaults not specified in a class will be inherited from parent classes.
    • This differs from old behaviour where _defaults overwrote parent class values for _defaults
  • default values are set before __init__ or with new function _reset. Deleting a property sets it to undefined.
    • This differs from old behavior where defaults were set on first get and deleting a property set it to default.
  • On init, defaults do not fire change notifications, kwargs do.
  • Additional validation of handlers and defaults in the metaclass.
• Metadata tagging:
  • Properties can be tagged with additional arbitrary metadata. This is stored on the property in meta
  • e.g. properties.String('password').tag(encrypt=True)
• Dependencies have been reduced for the base properties functionality. As a result, installation from PyPI has changed.
  • pip install properties only installs properties and the basic requirement six
  • pip install propreties[math] gets numpy and vectormath for the math properties (Array is now a math property)
  • pip install properties[image] gets image dependencies (ImagePNG is now native toproperties;properties_image` is no longer needed)
  • pip install properties[full] gets everything
• Beta release support

Minor Changes

• Overriding __init__ has been simplified by moving some instance setup to PropertyMetaclass __call__
  • By default __init__ now only sets kwargs (and fires change notifications)
• Float, Integer, and Complex validation has been changed to be more leniant. In try/except, values are coerced then equality is checked. If both of those pass with no exceptions, the value is valid.
  • Notably, this allows numpy.float16 and other similar numpy classes that are not subclasses of float/int/complex to pass validation.
  • This does not apply for Bool - values here must be type bool to pass (eg. numpy.bool8 does not pass.
• New task module for defining for implementing callable HasProperties Tasks
• Array properties may now be of dtype bool in addition to int or float
• Exception types:
  • Note: changing exception types may introduce backwards-incompatibility in error handling
  • No more AssertionErrors or KeyErrors are raised. Now properties raises three types of errors:
    • AttributeErrors on assignment to nonexistent properties/attributes
    • TypeErrors when Property attributes (e.g. required) are set to invalid values
    • ValueErrors when property values are invalid (i.e. validation on set fails)
• Terms used to construct properties are now stored on the property for recreating a (possibly modified) version of the property. The terms attribute is an instance of a PropertyTerms namedtuple, which contains fields: name, cls, args, kwargs and meta.
• StringChoice properties now allow sets as input. There is also additional validation to ensure no duplicates are present.
• filter_props now has an option to exclude immutable properties
• Minor improvements to doc strings and sphinx docs
  • Properties are now alphabetized in the docs (or the order can be customized by setting _doc_order to a list of the property names in the desired order).
• Property attributes help and helpdoc were renamed doc to remove the name conflict with builtin help this change is not backwards compatible but it is unlikely these attributes are referenced externally anywhere.
• Expanded testing
• Video added to README

Bug Fixes

• String properties now can handle unicode because casting to str was removed.
  • There is now a unicode attribute. If True (default) all strings are coerced to unicode; if False the input string type is maintained.
• Property validators (observers that fire on set, before the change) may now coerce the value by modifying the change dictionary. Previously they were allowed to have a coerced return value, but this value was never used.
• Array dtype validation previously allowed bad types to pass as long as 1+ good type was present. Now only good types (int, float, and bool) are allowed.

v0.2.3 - New default behaviour, updated vectormath compatibility

Major Features

• New default behaviour:
  • default values are validated but the underlying value is unchanged. This is mostly important when documenting (so, for example, if a Color property has a default value 'random', "random" shows up in the docs, rather than some coerced RGB triple).
  • startup() has been removed. This was used mainly to instantiate new instances in Instance properties and lists in List properties. Now, if a default value is callable, it is called when accessed.
  • _class_default is used much more sparingly. Basic properties (ie Integers and Bools) no longer have a class default (other than undefined). This is only used in List and Instance classes but may be defined in other Property subclasses.
  • Improved determination of default values from nested property classes like List and Union including warnings if unused defaults are defined.
• Updated vectormath:
  • Now dependent on vectormath >= 0.1.0 (see release notes)
  • The separation of individual Vector classes vs. VectorArray classes is mirrored in properties
    • The old Vector2 and Vector3 are now Vector2Array and Vector3Array properties and individual vector properties named Vector2 and Vector3 have been introduced.

Minor Changes

• required is now True by default - This assumes most properties you add to a HasProperties class are there for a reason.
• _exclusive_kwargs has been removed from HasProperties in favour of separate filter_props util function
• Immutable GettableProperties are now documented in sphinx as attributes rather than properties.
• Extensive cleanup to allow pylint tests to pass
• Minor improvements to README and docs

Bug Fixes

• Class validator functions were not callable on their own; now they are.

v0.2.2 - Sphinx AutoDoc; Improved List, Union, and Instance Properties

New Features

• Sphinx documentation generated for HasProperties classes in the metaclass based on the class's properties

Minor Changes:

• required properties may now have default values. On validate, a required property cannot be None or undefined
• assert_valid ensures HasProperty classes are valid
• List:
  • List properties are now lists of a given property type. A HasProperties class can also be provided - this is coerced into an instance property of that class.
  • validation errors raise list errors rather than errors of the property type
  • assert_valid validates HasProperties instances only
  • list now has min/max length property
• Union:
  • Similar to list, Union now allows HasProperties classes, coercing them into Instance properties
  • Union was moved to base from basic
• Uid:
  • assert_valid ensures the uid has not been tampered with
• Additional testing of the new features
• Improved docstrings

v0.2.1 - Validators

New features:

• @properties.validator wrapper for methods of HasProperties classes.
  • If this wrapper is used without arguments, the wrapped function becomes a ClassValidator that is called on has_props_instance.validate()
  • If this wrapper is given property name(s) like the @properties.observer wrapper, then the wrapped function is called on property change. validator functions are called before the change; observer functions are called after the change.
• @properties.observe => @properties.observer rename to match validator

Minor changes:

• choices is now required on StringChoices __init__ - this fixes problems with validation of default values (ie trying to set and validate default before the choices are set)

v0.2.0 - Clean API

This is almost a complete rewrite that is more inline with traitlets except that the class namespace is much cleaner. This is quite important as these classes are exposed to interactive use.

This version includes:

• observers
• class _REGISTRY for all subclasses
• better defaults and validators