.. _pythonPrimerLibraries:

Python Primer - Libraries
=========================

In this chapter, you will learn about a very powerful and usefull tool: **libraries**! 

You know libraries from school, right? A room filled with a **collection** of books that you can borrow and use for you school projects. Well, here we are talking about something very similar, but instead of books, we will borrow **functions** or **variables** or **constants**, etc. Basically, all the stuff we already learned. :)

The "turtle" Library
^^^^^^^^^^^^^^^^^^^^

Actually, you have been using libraries all this time, but withoug knowing it! Have a look of the first line of this code example from :any:`pythonPrimerPart1`: 

.. literalinclude:: ../examples/turtle/triangle.py 
         :language: python

Let us have a closer look::

        from turtle import fd, lt, exitonclick

Do you remember how we called **fd**, **lt** and **exitonclick**? Yes, exactly, functions! ;)

.. important:: We import **functions** from a **library** in order to use them in our code.  
        
        In the example above, the library is "turtle" and the functions "fd", "lt" and "exitonclick". 


Try the following exercises in the :any:`pythonShell`!

Example 1
---------

.. image:: _static/img/from_turtle_import_fd.gif
   :align: center

.. note:: It is good practice to import only the functions we really need in our code, like we did above. However, while developping, it could usefull to import them all, with:

        "from turtle import *  "


Example 2
---------

**What happens if you try to use the function "fd" before importing it?**


.. image:: _static/img/fd_before_import.gif
   :align: center


Example 3
---------

**What happens if you try to import a function that does not exist in the library?**


.. image:: _static/img/from_turtle_import_hello.gif
   :align: center


.. note:: If you do not know whether a function is in the library, you can check the documentation online, for instance for the "turtle" library:

        https://docs.python.org/2/library/turtle.html


"Import turtle" versus "from turtle import ..."
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Until now, after important a function from a library, we could use it by simply typing its name. 

**What happens when you import two functions with the same name, but from different libraries?** 

Well, to tackle this problem, another way to import a library, is to use:: 

        import turtle 

To use a function for this library, you will have to specify from which library you want to use the function::

        turtle.fd(100) 

.. image:: _static/img/import_turtle.gif
   :align: center



The "time" Library 
^^^^^^^^^^^^^^^^^^ 

Imagine that for some reason, you would like to make your turtle draw a square, but it should **wait two seconds** at each corner before continuing. It would look like: 

.. image:: _static/img/turtle_sleep.gif
   :align: center

**What do you need to make the turtle stop?**

Have a look at the code behind the example above. **What libraries are used?** 

**Which function tells the turtle to wait two seconds?**

.. literalinclude:: ../examples/turtle/time_sleep.py 
        :language: python

.. important:: The library **time** contains many very useful time-related functions. A few examples are: 

        - **time.sleep(secs)** : suspends the execution of the programm for the given number of seconds 
        - **time.ctime()** : gives current local time and date
        - **time.time()** : returns the time in seconds since the epoch as a floating point number


**What is the difference between "ctime()" and "time()"?** 

.. image:: _static/img/time.gif
   :align: center

.. note:: **ctime()** returns the time and date so that a human can easily read it. **time()** returns a number of seconds, which does not make a lot of sense for a human, but is much easier to store and use for a computer! 

Measuring time with "time.time()" 
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Let us take the example of the square above.

.. image:: _static/img/turtle_sleep.gif
   :align: center

**If you were asked to calculate how long the turtle needs, to draw the square, how would you do it?** 

Have a look at the following code and try to understand how time is measured: 

.. literalinclude:: ../examples/turtle/time_measure.py 
        :language: python

     
.. important:: To compute the elapsed time, store the current time with **time.time()** at two places in the code and **calculate the difference**. 


.. image:: _static/img/time_measure.gif
   :align: center