properties 0.2.0

properties

Why

Giving structure (and documentation!) to the properties you use in your classes avoids confusion and allows users to interact flexibly and provide multiple styles of input, have those inputs validated, and allow you as a developer to set expectations for what you want to work with.

Scope

The properties package allows you to create strongly typed objects in a consistent way. This allows you to hook into notifications and other libraries.

Goals

• Keep a clean name space so that it can be used easily by users

• Prioritize documentation

• Connect to other libraries for interactive visualizations

Alternatives

• traits is used by Enthought

• traitlets is used in the Jupyter project

• mypy and PEP0484 which document typing but do not include coercion or notifications

Connections

• steno3d for the client API

Installation

To install the repository, ensure that you have pip installed and run:

pip install properties

For the development version:

git clone https://github.com/3ptscience/properties.git
cd properties
pip install -e .

Examples

Lets start by making a class to organize your coffee habits.

import properties
class CoffeeProfile(properties.HasProperties):
    name = properties.String('What should I call you?', required=True)
    count = properties.Integer('number of coffees today')
    haz_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'])

The CoffeeProfile class has 4 properties, one of which is required (name). All of them are documented! At a minimum, we need to instantiate the class with a name.

profile = CoffeeProfile(name='Bob')
print profile.name
>> "Bob"

Since a default value was provided for haz_enough_coffee, the response is (naturally)

print profile.haz_enough_coffee
>> False

We can set Bob’s caffeine_choice, his default is coffee

profile.caffeine_choice = 'coffee'

He also likes macchiatos, so we try to set that, but that will error. Our caffeine_choice property has a select set of choices. Clearly, macchiatos fall into the 'something fancy' category.

Property Classes are auto-documented! When you ask for the docs of CoffeeProfile, you get

Init signature: CoffeeProfile(self, **kwargs)
Docstring:
Required:

:param name: What should I call you?
:type name: :class:`.String`

Optional:

:param count: number of coffees today
:type count: :class:`.Integer`
:param haz_enough_coffee: Have you had enough coffee today?
:type haz_enough_coffee: :class:`.Bool`
:param caffeine_choice: How do you take your caffeine?, Choices: something fancy, tea, coffee, cappuccino, latte
:type caffeine_choice: :class:`.String`
File:           ~/git/python_symlinks/properties/base.py
Type:           _PropertyMetaClass