diff --git a/README.rst b/README.rst index 5713861..12bd15b 100644 --- a/README.rst +++ b/README.rst @@ -39,23 +39,26 @@ An overview of Properties, November 2016. 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. +Properties 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. Scope ----- -The :code:`properties` package allows you to create **strongly typed** objects in a -consistent way. This allows you to hook into **notifications** and other libraries. +The :code:`properties` package enables the creation of **strongly typed** objects in a +consistent, declarative way. This allows **validation** of developer expectations and hooks +into **notifications** and other libraries. It provides **documentation** with +no extra work, and **serialization** for portability and reproducibility. Goals ----- -* Keep a clean name space so that it can be used easily by users +* Keep a clean namespace for easy interactive programming * Prioritize documentation -* Connect to other libraries for interactive visualizations +* Provide built-in serialization/deserialization +* Connect to other libraries for GUIs and visualizations Documentation ------------- @@ -65,14 +68,51 @@ API Documentation is available at `ReadTheDocs `_ is used by Enthought -* `traitlets `_ is used in the Jupyter project -* `mypy `_ and `PEP0484 `_ which document typing but do not include coercion or notifications +* `traitlets `_ (Jupyter project) and + `traits `_ (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 to properties (strong typing, validation, and notifications). + However, There are a few key areas where properties differs: + + 1. properties has a clean namespace - this (in addition to `?` docstrings) + allows for very easy discovery in an interactive programming environment. + 2. properties prioritizes documentation - this is not explicitly implemented + yet in traits or traitlets, but works out-of-the-box in properties. + 3. 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. + 4. 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 calls :code:`validate` + + Significant advantages of traitlets and traits over properties are + GUI interaction and the much larger suite of existing property types. + +* `param `_ - 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 builtin Python properties, and current development is + very slow. + +* `mypy `_ and `PEP0484 `_ - + This provides static typing for Python without coersion, notifications, etc. + It has a very different scope and implementation than traits-like libraries. + +* `builtin Python property `_ - + properties/traits-like behavior can be mostly recreated using :code:`@property`. + This requires significantly more work by the programmer, and results in + not-declarative, difficult-to-read code. Connections ----------- * `SimPEG `_ Simulation and Parameter Estimation in Geophysics +* `Steno3D `_ Python client for building and uploading 3D models Installation ------------