Package: properties
Overview VideoAn overview of Properties, November 2016.WhyProperties provides structure to aid development in an interactive programming
environment while allowing for an easy transition to production code.
It emphasizes usability and reproducibility for developers and users at
every stage of the code life cycle.ScopeThepropertiespackage enables the creation ofstrongly typedobjects in a
consistent, declarative way. This allowsvalidationof developer expectations and hooks
intonotificationsand other libraries. It providesdocumentationwith
no extra work, andserializationfor portability and reproducibility.GoalsKeep a clean namespace for easy interactive programmingPrioritize documentationProvide built-in serialization/deserializationConnect to other libraries for GUIs and visualizationsDocumentationAPI Documentation is available atReadTheDocs.Alternativesattrs- “Python Classes Without
Boilerplate” - This is a popular, actively developed library that aims to
simplify class creation, especially around object protocols (i.e. dunder
methods), with concise, declarative code.Similarities to Properties include type-checking, defaults, validation, and
coercion. There are a number of differences:attrs acts somewhat like anamedtuple, whereas properties acts
more like adictor mutable object.as a result, attrs is able to tackle hashing, comparison methods,
string representation, etc.attrs does not suffer runtime performance penalties as much as propertieson the other hand, properties focuses on interactivity, with
notifications, serialization/deserialization, and mutable,
possibly invalid states.properties has many built-in types with existing, complex validation
already in place. This includes recursive validation of container
and instance properties. attrs only allows attribute type to be specified.properties is more prescriptive and detailed around auto-generated
class documentation, for better or worse.traitlets(Jupyter project) andtraits(Enthought) - These libraries
are driven by GUI development (much of the Jupyter environment is built
on traitlets; traits has automatic GUI generation) which leads to many
similar features as properties such as strong typing, validation, and
notifications. Also, some Properties features and aspects of the API take
heavy inspiration from traitlets.However, There are a few key areas where properties differs:properties has a clean namespace - this (in addition to?docstrings)
allows for very easy discovery in an interactive programming environment.properties prioritizes documentation - this is not explicitly implemented
yet in traits or traitlets, but works out-of-the-box in properties.properties prioritizes serialization - this is present in traits with
pickling (but difficult to customize) and in traitlets with configuration
files (which require extra work beyond standard class definition); in
properties, serialization works out of the box but is also highly
customizable.properties allows invalid object states - the GUI focus of traits/traitlets
means an invalid object state at any time is never ok; without that constraint,
properties allows interactive object building and experimentation.
Validation then occurs when the user is ready and callsvalidateSignificant advantages of traitlets and traits over properties are
GUI interaction and larger suites of existing property types.
Besides numerous types built-in to these libraries, some other examples aretrait types that support unit conversionandNumPy/SciPy trait types(note: properties has a NumPy array property type).Noteproperties provides alinkobject which inter-operates with
traitlets and follows the same API as traitlets linksparam- This library also provides
type-checking, validation, and notification. It has a few unique features
and parameter types (possibly of note is the ability to provide dynamic
values for parameters at any time, not just as the default). This was first
introduced before built-in Python properties, and current development is
very slow.built-in Python dataclass decorator-
provides “mutable named tuples with defaults” - this provides similar functionality
to the attrs by adding several object protocol dunder methods to a class. Data
Classes are clean, lightweight and included with Python 3.7. However, they
don’t provide as much builtin functionality or customization as the above
libraries.built-in Python property-
properties/traits-like behavior can be mostly recreated using@property.
This requires significantly more work by the programmer, and results in
not-declarative, difficult-to-read code.mypy,PEP 484,
andPEP 526-
This provides static typing for Python without coersion, notifications, etc.
It has a very different scope and implementation than traits-like libraries.ConnectionscasingSimulations- Research repository for
electromagnetic simulations in the presence of well casingOMF- Open Mining Format API and file serializationSimPEG- Simulation and Parameter Estimation in GeophysicsSteno3D- Python client for building and uploading 3D modelsInstallationTo install the repository, ensure that you havepip installedand run:pip install propertiesFor the development version:git clone https://github.com/seequent/properties.git
cd properties
pip install -e .ExamplesLets start by making a class to organize your coffee habits.importpropertiesclassCoffeeProfile(properties.HasProperties):name=properties.String('What should I call you?')count=properties.Integer('How many coffees have you had today?',default=0)had_enough_coffee=properties.Bool('Have you had enough coffee today?',default=False)caffeine_choice=properties.StringChoice('How do you take your caffeine?',choices=['coffee','tea','latte','cappuccino','something fancy'],required=False)TheCoffeeProfileclass has 4 properties, all of which are documented!
These can be set on class instantiation:profile=CoffeeProfile(name='Bob')print(profile.name)Out[1]:BobSince a default value was provided forhad_enough_coffee, the response is (naturally)print(profile.had_enough_coffee)Out[2]:FalseWe can set Bob’scaffeine_choiceto one of the available choices; he likes coffeeprofile.caffeine_choice='coffee'Also, Bob is half way through his fourth cup of coffee today:profile.count=3.5Out[3]:ValueError:The'count'propertyofaCoffeeProfileinstancemustbeaninteger.Ok, Bob, chug that coffee:profile.count=4Now that Bob’sCoffeeProfileis established,propertiescan
check that it is valid:profile.validate()Out[4]:TrueProperty Classes are auto-documented in Sphinx-style reStructuredText!
When you ask for the doc string ofCoffeeProfile, you get**Required Properties:*****count**(:class:`Integer <properties.basic.Integer>`): How many coffees have you had today?, an integer, Default: 0***had_enough_coffee**(:class:`Bool <properties.basic.Bool>`): Have you had enough coffee today?, a boolean, Default: False***name**(:class:`String <properties.basic.String>`): What should I call you?, a unicode string**Optional Properties:*****caffeine_choice**(:class:`StringChoice <properties.basic.StringChoice>`): How do you take your caffeine?, any of "coffee", "tea", "latte", "cappuccino", "something fancy"