[Python] Implement new Concept Exercise: numbers

[BethanyG]

This issue describes how to implement the numbers concept exercise for the Python track.

Getting started

Please please please read the docs before starting. Posting PRs without reading these docs will be a lot more frustrating for you during the review cycle, and exhaust Exercism's maintainers' time. So, before diving into the implementation, please read up on the following documents:

• The features of v3.
• Rationale for v3.
• What are concept exercise and how they are structured?

Please also watch the following video:

• The Anatomy of a Concept Exercise.

Goal

The goal of this exercise is to teach the basics of theint , float , and complex numeric types (numbers) in Python.

Learning objectives

• understand the difference between int, float and complex numbers in Python
• understand that Python uses j to represent the square root of -1. appending j to a number defines it as imaginary. (e.g.3j is equivalent of 3(sqrt(-1)) -- IF Pythons math module allowed negative square roots...it doesn't).
• understand that a decimal (.) preceeded or followed by a number creates a float literal
• create an imaginary literal via appending j to an int or float (e.g. 3.4j or 5j)
• create a float by casting an int and an int by casting a float, using the int() and float() constructors.
• create complex numbers by casting int and float to complex using the complex() constructor.
• create a complex number by adding a float and an imaginary literal (e.g. 3.0 + 6j)
• understand when and how Python uses arithmetic conversions to apply arithmetic operators between these numeric types.
• apply the arithmetic operators to each/between each of the number types (where applicable)
• perform integer (floor) division and "regular" (float) division and see how they differ.
• changing precision of a float, using round(<float>, <digits>)

Out of scope

• Special values for Infinity and NaN
• Special math functions for complex numbers contained in cmath
• Bitwise operations on ints
• round numbers using math.floor() and math.ceiling()
• Issues with precision limits & sys.float_info -- but maybe we should note these in passing, or link to them in links.
• Numpy and the numeric types defined by Numpy -- again, something for links/notes.
• Checking strings to see if they are floats. This means any test input to this exercise should not require a student to (a) catch or raise an Exception if a non-float string is passed, or (b) check to see if the string is a float. Only pass valid float strings, i.e. "1.032".

Concepts

• numbers
• arithmetic operations

Prerequisites

• basics

Resources to refer to

• Python numeric type documentation
• Documentation for int() built in
• Documentation for complex() built in
• Documentation for float() built in
• Documentation for builtin function round()
• Pythons Integer Implementation
• Arithmetic conversions
• Arithmetic Operations (see table and notes on the same page as numeric types.)
• Operator Precedence in Python

Hints

Hints can link to the builtin function docs mentioned above, with appropriate prompts.

Concept Description

(a variant of this can be used for the v3/languages/python/concepts/<concept>/about.md doc and this exercises introduction.md doc.)

Python has three different types of built-in numbers: integers (int), floating-point (float, and complex (complex). Fractions (fractions.Fraction) and Decimals (decimal.Decimal) are also available via import from the standard library.

Whole numbers (including hex, octals and binary numbers) without decimal places are identified as ints:

#whole number
>>> 1234
1234
>>> type(1234)
<class 'int'>

>>> -12
-12

#hex number
>>> 0x17
23
>>> type(0x17)
<class 'int'>

#octal number
>>> 0o446
294
>>> type(0o446)
<class 'int'>

#binary number
>>> 0b1100110
102
>>> type(0b1100110)
<class 'int'>

Numbers containing a decimal point are identified as floats:

>>> 3.45
3.45
>>> type(3.45)
<class 'float'>

Appending j or J to a number creates a imaginary number -- a complex number with a zero real part. Integers or floats can then be added to an imaginary number to create a complex number with both real and imaginary parts:

>>> 3j
3j
>>> type(3j)
<class 'complex'>

>>> 3.5+4j
(3.5+4j)

Arithmetic

Python fully supports arithmetic between these different number types, and will convert narrower numbers to match their less narrow counterparts when used with binary arithmetic operators (+, -, *, /, and %). ints are narrower than floats, which are considered narrower than complex. Comparisons between different number types behaves as as if the exact values of those numbers were being compared:

#the int is widened to a float here, and a float is returned
>>> 3 + 4.0
7.0

#the int is widened to a complex number, and a complex number is returned
>>> 6/(3+2j)
(2+2j)

#division always returns a float, even if integers are used
>>> 6/2
3.0

#if an int result is needed, you can use floor division to truncate the result
>>> 6//2
3

#when comparing, exact values are used
>>> 23 == 0x17
True

>>> 0b10111 == 0x17
True

>>> 6 == (6+0j)
True

All numbers (except complex) support the same general arithmetic operations, evaluated according to operator precedence.

Precision & Representation

Integers in Python have arbitrary precision -- the amount of digits is limited only by the available memory of the host system.

Floating point numbers are usually implemented using a double in C (15 decimal places of precision), but will vary in representation based on the host system. Complex numbers have a real and an imaginary part, both of which are represented by floating point numbers.

For a more detailed discussion of the issues and limitations of floating point arithmetic, take a look at The Python Tutorial.

Representer

TBD.

Analyzer

TBD.

Implementing

Tests should be written using unittest.TestCase, and the test file named numbers_test.py.

Code in the .meta/example.py file should only use syntax & concepts introduced in this exercise or one of its prerequisites.
Please do not use comprehensions, generator expressions, or other syntax not previously covered. Please also follow PEP8 guidelines.

Help

If you have any questions while implementing the exercise, please post the questions as comments in this issue.

[BethanyG]

@mohanrajanr will be taking this on! 🎉 (thank you Mohan!), you are a 🌟

[BethanyG]

Note: I linked #2875 as a PR that can close this issue. We can re-open or re-work this issue for a follow-on complex numbers focused exercise when the time comes. 😄