Development: Source Files

Source File Types

We have source-files separated into two types:

1. Source files with generic tools
   These files contains the main systems for the playground, and can be borrowed and used by anyone who likes the tools, for example for student projects, startups etc.
   They reside in AI_playground/src/
2. Source files with content for notebooks
   These files only contain methods and classes used by the notebooks and are thus very specifically developed for teaching and visualization. They are not particularly handy for other projects, but may of course also be used if wanted.
   They reside in AI_playground/notebooks/src/

Source Files Design

All source files should follow the following design guidelines:

1. Follow the PEP8 Style Guide. Developers are advised to use IDEs with automated tools for following this style.

2. All source code is encapsulated into classes and methods for ease of use.

3. Any runnable script must have the scripted part within the standard main scope check of Python (see below for an example of a source-file). We encourage developers to include a main scope check at the bottom of most source files, containing simple tests or exemplary usage of the code of the file.

4. It is recommended to develop features and tools in normal Python files and them integrate them with notebooks afterwards. All general tools should be usable outside of Jupyter as well.

5. All classes and functions follow the general structure of the existing repository and have useful documentation strings. The doc-strings can follow the PEP257 Docstring Conventions or the styles of the used IDE, but should be easily readable by other developers.

6. Make doc-strings for your classes and methods, but avoid doc-string for files. Eg. do not specify author, python-path, encoding, creation date (we use VS) and other fun stuff at the top of the files.

7. All imports at top of files and no starred imports.

8. When working with paths, use Path-object from pathlib. All path-operations can be handled in an object-oriented manner and integrates with all operating systems.
   Runnable example:

   from pathlib import Path
   
   working_directory = Path.cwd()
   relative_path = Path("relative", "path", "to", "a", "file.txt")  # This path is relative
   absolute_path = relative_path.resolve()  # This path is absolute
   print(working_directory)
   print(absolute_path)

Source File Example

import numpy as np  # Imports at top


class SomeClass:  # Class that can be used throughout project
    def __init__(self, var1):
        """
        Description of class.
        :param list var1: Description of parameter.
        """
        self.var1 = np.array(var1)


def some_method(x, y, z):  # Method that can be used throughout project
    """
    Description of method.
    :param int x: Description of parameter.
    :param int y: Description of parameter.
    :param int z: Description of parameter.
    """
    return x + y + z 


if __name__ == "__main__":  # This is the script-part of the file.
    test = some_method(1, 2, 3)
    test2 = SomeClass([1, 2, 3])