Modules

1. Introduction

In Python a 'module' is a single file that may contain classes, functions and variables. It has to be imported to make these things accessible and those things are then referred to using the module name or the alias defined in the import statement and the dot operator '.'.

'Packages' are collections of modules structured using a directory tree.

A code 'library' is a generic name for a collection of code. So, a Python library might contain a single module, or multiple packages.

2. Importing

The Python Module Index is a useful look up for Python Standard Library modules. These modules can be readily imported and used without needing to customise the environment.

There are two types of import statement, those that begin with the keyword 'import' and others that begin with the keyword 'from' and also contain the keyword 'import'.

The following code imports a module called 'agentframework' and then constructs an instance of the 'Agent' class as defined in the 'agentframework' module:

import agentframework
a = agentframework.Agent()

This is a very explicit style. There is little ambiguity about which 'Agent' class is used - it is the one from the 'agentframework' module.

Another way to create instances of the 'Agent' class is as follows:

from agentframework import Agent
a = Agent()

The advantage of this is that it is less verbose when it comes to lines of code that instantiate instances of the Agent class. Also this is more memory efficent as it only makes available that specific class from the 'agentframework' module rather than keeping the entire module available.

You may see imports of everything in a module using the star operator '*', for example:

from agentframework import *

This saves having to import multiple classes, but it can be problematic as what gets imported can replace things imported before that have the same name. It is good practise to be explicit and import individually only those things that are used and to check if an identifier is already in use and if so use aliases.

The keyword 'as' can be used to alias a module or class on import. This can also abbreviate a name, for example the following are alternatives for creating 'agentframework' 'Agent' class instances:

import agentframework as af
a = af.Agent()

from agentframework import Agent as A
a = A()

The Python interpreter parses modules on import initialising variables and making functions and classes available for use. Within the module, any code not in a function or a class is run when the module is imported as is any code within a class that is not in a method. This means that sometimes there can be side effects of importing modules. It can be argued that the less code that is run when the module is imported the better!

It is good practise to set up a module so that any code not in functions is isolated and is not run when the module is imported. This can be done by ensuring all code not in functions is within an 'if statement' that has a condition that tests if the global '__name__' variable equals "__main__":

if __name__ == "__main__":
    # All code in this is only run when the module is run as a script.
    # It is not run if the module is imported.

3. Packages

Consider the following package file structure:

/abm
    __init__.py
    __main__.py
    /models
        __init__.py
        model.py
    /my_modules
        __init__.py
        agentframework.py

The '__init__.py' files can be empty, but they must exist so the Python interpreter recognises these subdirectories as subpackages and allows import statements to work as follows:

import abm.my_modules.agentframework.Agent

This import statement will work so long as there is an 'Agent' class within the 'agentframework' module

The base '__init__.py' file in the 'abm' directory can also include a text representation of a specially named list which will import specific subpackages if a star import statement is used. For example, if the following were the contents of '/abm/__init__.py':

__all__ = ["models", "my_modules"]

Then, the following import statement would import both the 'models' and 'my_modules' subpackages:

from abm import *

Packages are set to run as applications by placing startup code in a file called '__main__.py'. The following command would then run the application when issued at the prompt:

python -m packagename

4. Third Party Libraries

Anaconda comes bundled with numerous third party libraries.

Exactly what Anaconda comes with varies with the version and underlying operating system. Details can be found via the following URL: https://docs.anaconda.com/anaconda/packages/pkg-docs/

There are many additional libraries that might be useful for geographical data processing or whatever you may be doing.

Many Python libraries are made available via PyPI - the Python Package Index (PyPi) including:

• ArcPY - ArcGIS Pro API.
• beautiful-soup - for parsing HTML and XML files.
• celery - useful for distributed computing (splitting up programs and running them on multiple computers).
• Contextily - for retrieving tile maps from the Internet, then adding them to matplotlib figures or writing them to files.
• Fiona - reads and writes geographic data files.
• Folium - for visualising data on an interactive javascript map.
• Geopandas - extends the data types used by 'pandas' to include geometry (and has support for many geometry operations).
• GeoPy - a client for several popular geocoding web services.
• matplotlib - a comprehensive library for creating static, animated, and interactive visualizations.
• nltk - a Natural Language Toolkit for parsing and analysing text.
• numpy - useful for mathematics and statistics, especially multi-dimensional array manipulation.
• pandas - useful for a range of other things including time series analysis.
• PyQGIS - QGIS API.
• scikit-learn - useful for scientific analysis and machine learning.

For details on installing packages see: Python Packages and Environment Management.