Debian Codegraph @

examples/tutorials/traits_4.0/interfaces/interfaces.py

raw
1 # (C) Copyright 2005-2023 Enthought, Inc., Austin, TX
2 # All rights reserved.
3 #
4 # This software is provided without warranty under the terms of the BSD
5 # license included in LICENSE.txt and may be redistributed only under
6 # the conditions described in the aforementioned license. The license
7 # is also available online at http://www.enthought.com/licenses/BSD.txt
8 #
9 # Thanks for using Enthought open source!
10
11 # --(Interfaces)---------------------------------------------------------------
12 """
13 Interfaces
14 ==========
15
16 In Traits 3.0, the ability to define, implement and use *interfaces* has been
17 added to the package.
18
19 Defining Interfaces
20 -------------------
21
22 Interfaces are defined by subclassing from the **Interface** class, as shown
23 in the example below::
24
25 from traits.api import Interface
26
27 class IName(Interface):
28
29 def get_name(self):
30 " Returns the name of an object. "
31
32 This same code is shown in the **IName Interface** tab of the code.
33
34 Interface classes are intended mainly as documentation of the methods and
35 traits that the interface defines, and should not contain any actual
36 implementation code, although no check is performed to enforce this currently.
37
38 Implementing Interfaces
39 -----------------------
40
41 A class declares that it implements one or more interfaces using the
42 **provides** decorator, which has the form::
43
44 @provides(interface [, interface2, ..., interfacen])
45
46 The decorator declares that the decorated class implements each of the
47 *interfaces* specified as an argument to **provides**. For example::
48
49 from traits.api import HasTraits, provides
50
51 @provides(IName)
52 class Person(HasTraits):
53
54 def get_name(self):
55 ...
56
57
58 Note that in the current version, traits does not check to ensure that the
59 class decorated with **provides** actually implements the interfaces
60 it says it does.
61
62 Using Interfaces
63 ----------------
64
65 Being able to define and implement interfaces would be of little use without
66 the ability to *use* interfaces in your code. In traits, using an interface is
67 accomplished using the **Instance** trait, as shown in the following example::
68
69 from traits.api import HasTraits, Instance
70
71 class Apartment(HasTraits):
72
73 renter = Instance(IName)
74
75 Using an interface class in an **Instance** trait definition declares that the
76 trait only accepts values which implement the specified interface.
77
78 As before, the **Instance** trait can also be used with classes that are not
79 interfaces, such as::
80
81 from traits.api import HasTraits, Instance
82
83 class Apartment(HasTraits):
84
85 renter = Instance(Person)
86
87 In this case, the value of the trait must be an object which is an instance of
88 the specified class or one of its subclasses.
89 """
90 # --<Imports>------------------------------------------------------------------
91 from traits.api import HasTraits, Instance, Interface, provides, Str
92
93
94 # --[IName Interface]----------------------------------------------------------
95 # Define the 'IName' interface:
96 class IName(Interface):
97 def get_name(self):
98 """ Returns the name of an object. """
99
100
101 # --[Person Class]-------------------------------------------------------------
102 @provides(IName)
103 class Person(HasTraits):
104
105 first_name = Str("John")
106 last_name = Str("Doe")
107
108 # Implementation of the 'IName' interface:
109 def get_name(self):
110 """ Returns the name of an object. """
111 return "%s %s" % (self.first_name, self.last_name)
112
113
114 # --[Apartment Class]----------------------------------------------------------
115 # Define a class using an object that implements the 'IName' interface:
116 class Apartment(HasTraits):
117
118 renter = Instance(IName)
119
120
121 # --[Example*]-----------------------------------------------------------------
122 # Create an object implementing the 'IName' interface:
123 william = Person(first_name="William", last_name="Adams")
124
125 # Create an apartment, and assign 'renter' an object implementing 'IName':
126 apt = Apartment(renter=william)
127
128 # Verify that the object works correctly:
129 print("Renter is:", apt.renter.get_name())