Python code coverage for Lib/numbers.py

#	count	content
1	n/a	# Copyright 2007 Google, Inc. All Rights Reserved.
2	n/a	# Licensed to PSF under a Contributor Agreement.
3	n/a
4	n/a	"""Abstract Base Classes (ABCs) for numbers, according to PEP 3141.
5	n/a
6	n/a	TODO: Fill out more detailed documentation on the operators."""
7	n/a
8	n/a	from abc import ABCMeta, abstractmethod
9	n/a
10	n/a	__all__ = ["Number", "Complex", "Real", "Rational", "Integral"]
11	n/a
12	n/a	class Number(metaclass=ABCMeta):
13	n/a	"""All numbers inherit from this class.
14	n/a
15	n/a	If you just want to check if an argument x is a number, without
16	n/a	caring what kind, use isinstance(x, Number).
17	n/a	"""
18	n/a	__slots__ = ()
19	n/a
20	n/a	# Concrete numeric types must provide their own hash implementation
21	n/a	__hash__ = None
22	n/a
23	n/a
24	n/a	## Notes on Decimal
25	n/a	## ----------------
26	n/a	## Decimal has all of the methods specified by the Real abc, but it should
27	n/a	## not be registered as a Real because decimals do not interoperate with
28	n/a	## binary floats (i.e. Decimal('3.14') + 2.71828 is undefined). But,
29	n/a	## abstract reals are expected to interoperate (i.e. R1 + R2 should be
30	n/a	## expected to work if R1 and R2 are both Reals).
31	n/a
32	n/a	class Complex(Number):
33	n/a	"""Complex defines the operations that work on the builtin complex type.
34	n/a
35	n/a	In short, those are: a conversion to complex, .real, .imag, +, -,
36	n/a	*, /, abs(), .conjugate, ==, and !=.
37	n/a
38	n/a	If it is given heterogenous arguments, and doesn't have special
39	n/a	knowledge about them, it should fall back to the builtin complex
40	n/a	type as described below.
41	n/a	"""
42	n/a
43	n/a	__slots__ = ()
44	n/a
45	n/a	@abstractmethod
46	n/a	def __complex__(self):
47	n/a	"""Return a builtin complex instance. Called for complex(self)."""
48	n/a
49	n/a	def __bool__(self):
50	n/a	"""True if self != 0. Called for bool(self)."""
51	n/a	return self != 0
52	n/a
53	n/a	@property
54	n/a	@abstractmethod
55	n/a	def real(self):
56	n/a	"""Retrieve the real component of this number.
57	n/a
58	n/a	This should subclass Real.
59	n/a	"""
60	n/a	raise NotImplementedError
61	n/a
62	n/a	@property
63	n/a	@abstractmethod
64	n/a	def imag(self):
65	n/a	"""Retrieve the imaginary component of this number.
66	n/a
67	n/a	This should subclass Real.
68	n/a	"""
69	n/a	raise NotImplementedError
70	n/a
71	n/a	@abstractmethod
72	n/a	def __add__(self, other):
73	n/a	"""self + other"""
74	n/a	raise NotImplementedError
75	n/a
76	n/a	@abstractmethod
77	n/a	def __radd__(self, other):
78	n/a	"""other + self"""
79	n/a	raise NotImplementedError
80	n/a
81	n/a	@abstractmethod
82	n/a	def __neg__(self):
83	n/a	"""-self"""
84	n/a	raise NotImplementedError
85	n/a
86	n/a	@abstractmethod
87	n/a	def __pos__(self):
88	n/a	"""+self"""
89	n/a	raise NotImplementedError
90	n/a
91	n/a	def __sub__(self, other):
92	n/a	"""self - other"""
93	n/a	return self + -other
94	n/a
95	n/a	def __rsub__(self, other):
96	n/a	"""other - self"""
97	n/a	return -self + other
98	n/a
99	n/a	@abstractmethod
100	n/a	def __mul__(self, other):
101	n/a	"""self * other"""
102	n/a	raise NotImplementedError
103	n/a
104	n/a	@abstractmethod
105	n/a	def __rmul__(self, other):
106	n/a	"""other * self"""
107	n/a	raise NotImplementedError
108	n/a
109	n/a	@abstractmethod
110	n/a	def __truediv__(self, other):
111	n/a	"""self / other: Should promote to float when necessary."""
112	n/a	raise NotImplementedError
113	n/a
114	n/a	@abstractmethod
115	n/a	def __rtruediv__(self, other):
116	n/a	"""other / self"""
117	n/a	raise NotImplementedError
118	n/a
119	n/a	@abstractmethod
120	n/a	def __pow__(self, exponent):
121	n/a	"""self**exponent; should promote to float or complex when necessary."""
122	n/a	raise NotImplementedError
123	n/a
124	n/a	@abstractmethod
125	n/a	def __rpow__(self, base):
126	n/a	"""base ** self"""
127	n/a	raise NotImplementedError
128	n/a
129	n/a	@abstractmethod
130	n/a	def __abs__(self):
131	n/a	"""Returns the Real distance from 0. Called for abs(self)."""
132	n/a	raise NotImplementedError
133	n/a
134	n/a	@abstractmethod
135	n/a	def conjugate(self):
136	n/a	"""(x+yi).conjugate() returns (x-yi)."""
137	n/a	raise NotImplementedError
138	n/a
139	n/a	@abstractmethod
140	n/a	def __eq__(self, other):
141	n/a	"""self == other"""
142	n/a	raise NotImplementedError
143	n/a
144	n/a	Complex.register(complex)
145	n/a
146	n/a
147	n/a	class Real(Complex):
148	n/a	"""To Complex, Real adds the operations that work on real numbers.
149	n/a
150	n/a	In short, those are: a conversion to float, trunc(), divmod,
151	n/a	%, <, <=, >, and >=.
152	n/a
153	n/a	Real also provides defaults for the derived operations.
154	n/a	"""
155	n/a
156	n/a	__slots__ = ()
157	n/a
158	n/a	@abstractmethod
159	n/a	def __float__(self):
160	n/a	"""Any Real can be converted to a native float object.
161	n/a
162	n/a	Called for float(self)."""
163	n/a	raise NotImplementedError
164	n/a
165	n/a	@abstractmethod
166	n/a	def __trunc__(self):
167	n/a	"""trunc(self): Truncates self to an Integral.
168	n/a
169	n/a	Returns an Integral i such that:
170	n/a	* i>0 iff self>0;
171	n/a	* abs(i) <= abs(self);
172	n/a	* for any Integral j satisfying the first two conditions,
173	n/a	abs(i) >= abs(j) [i.e. i has "maximal" abs among those].
174	n/a	i.e. "truncate towards 0".
175	n/a	"""
176	n/a	raise NotImplementedError
177	n/a
178	n/a	@abstractmethod
179	n/a	def __floor__(self):
180	n/a	"""Finds the greatest Integral <= self."""
181	n/a	raise NotImplementedError
182	n/a
183	n/a	@abstractmethod
184	n/a	def __ceil__(self):
185	n/a	"""Finds the least Integral >= self."""
186	n/a	raise NotImplementedError
187	n/a
188	n/a	@abstractmethod
189	n/a	def __round__(self, ndigits=None):
190	n/a	"""Rounds self to ndigits decimal places, defaulting to 0.
191	n/a
192	n/a	If ndigits is omitted or None, returns an Integral, otherwise
193	n/a	returns a Real. Rounds half toward even.
194	n/a	"""
195	n/a	raise NotImplementedError
196	n/a
197	n/a	def __divmod__(self, other):
198	n/a	"""divmod(self, other): The pair (self // other, self % other).
199	n/a
200	n/a	Sometimes this can be computed faster than the pair of
201	n/a	operations.
202	n/a	"""
203	n/a	return (self // other, self % other)
204	n/a
205	n/a	def __rdivmod__(self, other):
206	n/a	"""divmod(other, self): The pair (self // other, self % other).
207	n/a
208	n/a	Sometimes this can be computed faster than the pair of
209	n/a	operations.
210	n/a	"""
211	n/a	return (other // self, other % self)
212	n/a
213	n/a	@abstractmethod
214	n/a	def __floordiv__(self, other):
215	n/a	"""self // other: The floor() of self/other."""
216	n/a	raise NotImplementedError
217	n/a
218	n/a	@abstractmethod
219	n/a	def __rfloordiv__(self, other):
220	n/a	"""other // self: The floor() of other/self."""
221	n/a	raise NotImplementedError
222	n/a
223	n/a	@abstractmethod
224	n/a	def __mod__(self, other):
225	n/a	"""self % other"""
226	n/a	raise NotImplementedError
227	n/a
228	n/a	@abstractmethod
229	n/a	def __rmod__(self, other):
230	n/a	"""other % self"""
231	n/a	raise NotImplementedError
232	n/a
233	n/a	@abstractmethod
234	n/a	def __lt__(self, other):
235	n/a	"""self < other
236	n/a
237	n/a	< on Reals defines a total ordering, except perhaps for NaN."""
238	n/a	raise NotImplementedError
239	n/a
240	n/a	@abstractmethod
241	n/a	def __le__(self, other):
242	n/a	"""self <= other"""
243	n/a	raise NotImplementedError
244	n/a
245	n/a	# Concrete implementations of Complex abstract methods.
246	n/a	def __complex__(self):
247	n/a	"""complex(self) == complex(float(self), 0)"""
248	n/a	return complex(float(self))
249	n/a
250	n/a	@property
251	n/a	def real(self):
252	n/a	"""Real numbers are their real component."""
253	n/a	return +self
254	n/a
255	n/a	@property
256	n/a	def imag(self):
257	n/a	"""Real numbers have no imaginary component."""
258	n/a	return 0
259	n/a
260	n/a	def conjugate(self):
261	n/a	"""Conjugate is a no-op for Reals."""
262	n/a	return +self
263	n/a
264	n/a	Real.register(float)
265	n/a
266	n/a
267	n/a	class Rational(Real):
268	n/a	""".numerator and .denominator should be in lowest terms."""
269	n/a
270	n/a	__slots__ = ()
271	n/a
272	n/a	@property
273	n/a	@abstractmethod
274	n/a	def numerator(self):
275	n/a	raise NotImplementedError
276	n/a
277	n/a	@property
278	n/a	@abstractmethod
279	n/a	def denominator(self):
280	n/a	raise NotImplementedError
281	n/a
282	n/a	# Concrete implementation of Real's conversion to float.
283	n/a	def __float__(self):
284	n/a	"""float(self) = self.numerator / self.denominator
285	n/a
286	n/a	It's important that this conversion use the integer's "true"
287	n/a	division rather than casting one side to float before dividing
288	n/a	so that ratios of huge integers convert without overflowing.
289	n/a
290	n/a	"""
291	n/a	return self.numerator / self.denominator
292	n/a
293	n/a
294	n/a	class Integral(Rational):
295	n/a	"""Integral adds a conversion to int and the bit-string operations."""
296	n/a
297	n/a	__slots__ = ()
298	n/a
299	n/a	@abstractmethod
300	n/a	def __int__(self):
301	n/a	"""int(self)"""
302	n/a	raise NotImplementedError
303	n/a
304	n/a	def __index__(self):
305	n/a	"""Called whenever an index is needed, such as in slicing"""
306	n/a	return int(self)
307	n/a
308	n/a	@abstractmethod
309	n/a	def __pow__(self, exponent, modulus=None):
310	n/a	"""self ** exponent % modulus, but maybe faster.
311	n/a
312	n/a	Accept the modulus argument if you want to support the
313	n/a	3-argument version of pow(). Raise a TypeError if exponent < 0
314	n/a	or any argument isn't Integral. Otherwise, just implement the
315	n/a	2-argument version described in Complex.
316	n/a	"""
317	n/a	raise NotImplementedError
318	n/a
319	n/a	@abstractmethod
320	n/a	def __lshift__(self, other):
321	n/a	"""self << other"""
322	n/a	raise NotImplementedError
323	n/a
324	n/a	@abstractmethod
325	n/a	def __rlshift__(self, other):
326	n/a	"""other << self"""
327	n/a	raise NotImplementedError
328	n/a
329	n/a	@abstractmethod
330	n/a	def __rshift__(self, other):
331	n/a	"""self >> other"""
332	n/a	raise NotImplementedError
333	n/a
334	n/a	@abstractmethod
335	n/a	def __rrshift__(self, other):
336	n/a	"""other >> self"""
337	n/a	raise NotImplementedError
338	n/a
339	n/a	@abstractmethod
340	n/a	def __and__(self, other):
341	n/a	"""self & other"""
342	n/a	raise NotImplementedError
343	n/a
344	n/a	@abstractmethod
345	n/a	def __rand__(self, other):
346	n/a	"""other & self"""
347	n/a	raise NotImplementedError
348	n/a
349	n/a	@abstractmethod
350	n/a	def __xor__(self, other):
351	n/a	"""self ^ other"""
352	n/a	raise NotImplementedError
353	n/a
354	n/a	@abstractmethod
355	n/a	def __rxor__(self, other):
356	n/a	"""other ^ self"""
357	n/a	raise NotImplementedError
358	n/a
359	n/a	@abstractmethod
360	n/a	def __or__(self, other):
361	n/a	"""self \| other"""
362	n/a	raise NotImplementedError
363	n/a
364	n/a	@abstractmethod
365	n/a	def __ror__(self, other):
366	n/a	"""other \| self"""
367	n/a	raise NotImplementedError
368	n/a
369	n/a	@abstractmethod
370	n/a	def __invert__(self):
371	n/a	"""~self"""
372	n/a	raise NotImplementedError
373	n/a
374	n/a	# Concrete implementations of Rational and Real abstract methods.
375	n/a	def __float__(self):
376	n/a	"""float(self) == float(int(self))"""
377	n/a	return float(int(self))
378	n/a
379	n/a	@property
380	n/a	def numerator(self):
381	n/a	"""Integers are their own numerators."""
382	n/a	return +self
383	n/a
384	n/a	@property
385	n/a	def denominator(self):
386	n/a	"""Integers have a denominator of 1."""
387	n/a	return 1
388	n/a
389	n/a	Integral.register(int)