Hide keyboard shortcuts

Hot-keys on this page

r m x p   toggle line displays

j k   next/prev highlighted chunk

0   (zero) top of page

1   (one) first highlighted chunk

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

37

38

39

40

41

42

43

44

45

46

47

48

49

50

51

52

53

54

55

56

57

58

59

60

61

62

63

64

65

66

67

68

69

70

71

72

73

74

75

76

77

78

79

80

81

82

83

84

85

86

87

88

89

90

91

92

93

94

95

96

97

98

99

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

# Copyright (C) 2015 Chintalagiri Shashank 

# 

# This file is part of Tendril. 

# 

# This program is free software: you can redistribute it and/or modify 

# it under the terms of the GNU Affero General Public License as published by 

# the Free Software Foundation, either version 3 of the License, or 

# (at your option) any later version. 

# 

# This program is distributed in the hope that it will be useful, 

# but WITHOUT ANY WARRANTY; without even the implied warranty of 

# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the 

# GNU Affero General Public License for more details. 

# 

# You should have received a copy of the GNU Affero General Public License 

# along with this program.  If not, see <http://www.gnu.org/licenses/>. 

""" 

The Types Package (:mod:`tendril.utils.types`) 

============================================== 

 

The :mod:`tendril.utils.types` package, like all the :mod:`tendril.utils` 

modules, includes code that ideally resides outside of Tendril itself, 

perhaps using some standard or third-party package. In the case of 

:mod:`tendril.utils.types`, this package provides various modules and 

consequently classes to handle special data types - usually data structures 

and units. These use cases are more thoroughly and effectively handled by 

various third-party packages, and its existence in Tendril is largely due 

to a combination of the *Not Invented Here* syndrome, as well as the 

overwhelming number of possible options available, none of which seem to 

be ideal drop in replacements for Tendril core's requirements. 

 

While you can use the units and data structures from 

:mod:`tendril.utils.types` independent of the rest of Tendril, you probably 

should not. The code itself should function, but it lacks the thoroughness 

of type-checking or the efficiency of more full fledged implementations. Even 

when using Tendril units to handle data generated by one of the Tendril 

submodules, I strongly recommend using a full-fledged unit package instead. 

If you'd like to use them anyway, well, you have been warned. 

 

Converters from Tendril types to other forms should be reasonably 

straightforward to write, and over time some these converters and/or 

re-implementations using an established types/units package will hopefully 

find their way into the classes defined within :mod:`tendril.utils.types`. 

 

The general principles of design used for the units defined within this 

package are as follows : 

 

- If there is an obvious good-fit python package available to provide the 

  units or data structures required, use that instead and simply proxy to that 

  package within this module. Data-structures are relatively more complex 

  beasts, so the remaining principles don't apply to them. They follow more 

  of a *use your best judgement* type of development principle. 

 

- Unit Type classes should, as far as possible, derive from 

  :class:`unitbase.UnitBase`. 

 

- The fundamental nature of unit instantiation must remain stable and 

  consistent within the various units defined. The underlying implementation 

  isn't important as long as it provides the functionality required via the 

  accessors Tendril expects. More importantly, changing the underlying 

  implementation should not change the way application code uses the units. 

 

- In most cases, primary unit instantiation is using a string containing the 

  value the object should hold as well as the unit. Units can also be 

  instantiated using a :class:`numbers.Number` instance, but application code 

  should avoid doing this. This interface is provided largely to support 

  arithmetic operations defined between units. 

 

- For each 'simple' unit class, unless provided by an external library, the 

  core information should be a number in the "canonical" unit of that class. 

  The class should also store the original string. 

 

- Wherever possible, the numbers stored should be :class:`decimal.Decimal` 

  instances and not floats. Number of significant digits should ideally be 

  tracked, but presently is not. 

 

- The unit classes should support the bare-minimum set of valid operations. 

  As far as possible, the simple mathematical operations performed with two 

  elements of the same unitclass should produce a valid result (if 

  physically meaningful) 

 

- The unit classes should not produce physically meaningless results. This is 

  not something that's tested all that much, so it's likely corner cases have 

  slipped through the cracks. 

 

- Be unafraid to throw exceptions. If application code misuses the units, the 

  application is asking to be penalized. 

 

.. warning:: 

  No effort is made to have a complete set of units, or even a complete set of 

  units of the same dimensionality as the supported units. Addition of new 

  types is done on a lazy basis, as are type conversions, inter-unit 

  arithmetic, and other ranges. This policy is likely to change only if this 

  module is pulled out of Tendril into it's own units library, and maintaining 

  that isn't something I'm likely to do alone. 

 

Types 

----- 

 

.. toctree:: 

 

   tendril.utils.types.currency 

   tendril.utils.types.lengths 

   tendril.utils.types.unitbase 

   tendril.utils.types.electromagnetic 

   tendril.utils.types.thermodynamic 

   tendril.utils.types.time 

 

Data Structures / Composite Types 

--------------------------------- 

 

.. toctree:: 

 

   tendril.utils.types.signalbase 

   tendril.utils.types.cartesian 

 

.. rubric:: Inheritance Diagram 

 

.. inheritance-diagram:: 

   tendril.utils.types 

   tendril.utils.types.cartesian 

   tendril.utils.types.currency 

   tendril.utils.types.electromagnetic 

   tendril.utils.types.thermodynamic 

   tendril.utils.types.lengths 

   tendril.utils.types.time 

   tendril.utils.types.signalbase 

   tendril.utils.types.unitbase 

 

"""