README.rst
1======================================================
2Traits: observable typed attributes for Python classes
3======================================================
4
5http://docs.enthought.com/traits
6
7The Traits project is at the center of all Enthought Tool Suite development
8and has changed the mental model used at Enthought for programming in the
9already extremely efficient Python programming language. We encourage everyone
10to join us in enjoying the productivity gains from using such a powerful
11approach.
12
13The Traits project allows Python programmers to use a special kind of type
14definition called a *trait*, which gives object attributes some additional
15characteristics:
16
17- **Initialization**: A trait has a *default value*, which is
18 automatically set as the initial value of an attribute before its
19 first use in a program.
20- **Validation**: The type of a trait attribute is *explicitly declared*. The
21 type is evident in the code, and only values that meet a
22 programmer-specified set of criteria (i.e., the trait definition) can
23 be assigned to that attribute.
24- **Delegation**: The value of a trait attribute can be contained either
25 in the defining object or in another object *delegated* to by the
26 trait.
27- **Notification**: Setting the value of a trait attribute can *notify*
28 other parts of the program that the value has changed.
29- **Visualization**: User interfaces that allow a user to *interactively
30 modify* the value of a trait attribute can be automatically
31 constructed using the trait's definition. (This feature requires that
32 a supported GUI toolkit be installed. If this feature is not used, the
33 Traits project does not otherwise require GUI support.)
34
35A class can freely mix trait-based attributes with normal Python attributes,
36or can opt to allow the use of only a fixed or open set of trait attributes
37within the class. Trait attributes defined by a class are automatically
38inherited by any subclass derived from the class.
39
40Dependencies
41------------
42
43Traits requires Python >= 3.6.
44
45Traits has the following optional dependencies:
46
47* `NumPy <http://pypi.python.org/pypi/numpy>`_ to support the trait types
48 for arrays.
49* `TraitsUI <https://pypi.python.org/pypi/traitsui>`_ to support GUI
50 Views.
51
52To build the full documentation one needs:
53
54* `Sphinx <https://pypi.org/project/Sphinx>`_ version 2.1 or later.
55* The `Enthought Sphinx Theme <https://pypi.org/project/enthought-sphinx-theme>`_.
56 (A version of the documentation can be built without this, but
57 some formatting may be incorrect.)
58