Skip to content
Snippets Groups Projects
Commit 0c954510 authored by s-roscher's avatar s-roscher
Browse files

Update python-modularization.md:

- Changed emojis from "\emoji wink" to :wink:
- Changed note/warning syntax from @note/warning to:

!!! note
        Text.
parent c154ee51
No related branches found
No related tags found
Loading
Pipeline #1515683 waiting for manual action
# How to Python in UNICADO
# How to Python in UNICADO :snake:
This documentation provides a detailed overview of helpful guidelines and conventions for the use/implementation of Python code in the UNICADO framework.
@note The content below is valid for UNICADO release v2.0.
!!! note
The content below is valid for UNICADO release v2.0.
# Content
- [Introduction](#introduction)
......@@ -20,7 +21,7 @@ This documentation provides a detailed overview of helpful guidelines and conven
2. Start an interactive Python console.
3. Type `import this`.
4. Congrats! You found the _Zen of Python_.
5. Take a few deep breaths and let the spiritual outpourings of Tim Peters work their magic on you ... \emoji lotus_position (For the less spiritual souls among us, awesome work! Allow yourself a short break before we dive deeper into the topic.)
5. Take a few deep breaths and let the spiritual outpourings of Tim Peters work their magic on you ... 🧘 (For the less spiritual souls among us, awesome work! Allow yourself a short break before we dive deeper into the topic.)
# Introduction {#introduction}
The UNICADO Python Library is designed to streamline and standardize Python-based code development. The library consists of multiple packages within a central repository, each containing individual modules grouped by functionality. These modules house functions that perform related tasks, creating a highly modular, scalable, and manageable structure.
......@@ -35,12 +36,12 @@ Let's start with an obvious question ... [What is a PEP?](https://peps.python.or
> PEP stands for Python Enhancement Proposal. A PEP is a design document providing information to the Python community, or describing a new feature for Python or its processes or environment. The PEP should provide a concise technical specification of the feature and a rationale for the feature.
There are numerous PEPs, one of which is PEP 20 (which you have already encountered as _Zen of Python_), but probably the most beautiful is ... \emoji drum
There are numerous PEPs, one of which is PEP 20 (which you have already encountered as _Zen of Python_), but probably the most beautiful is ... :drum:
... PEP 8.
Wondering why?
Great, I will tell you... [PEP 8 - Style Guide for Python Code](https://peps.python.org/pep-0008/) gives us conventions on how to write beautiful Python code. And beautiful is better than ugly, right? \emoji wink
Great, I will tell you... [PEP 8 - Style Guide for Python Code](https://peps.python.org/pep-0008/) gives us conventions on how to write beautiful Python code. And beautiful is better than ugly, right? :wink:
No, seriously... PEP 8 is considered a common and official Python style guide. To improve readability and ensure consistency as well as maintainability when writing new Python code, we decided to follow this recommendation and choose PEP 8 as our **Python coding standard**.
......@@ -138,9 +139,12 @@ This means, for example:
In the following, the modularized structure of a Python module is explained using the `cost_estimation` module. The according folder structure is shown in the following picture. It is also available for download.
![](../../assets/images/developer/style/python-modularization_01_code-modularity.png)
@warning Check, if images displayed correctly here!
@warning Insert files here!
@warning {F216186}
!!! warning
Check, if images displayed correctly here!
!!! warning
Insert files here! {F216186}
## Layer example
The following **layers** are selected for cost calculation:
......@@ -148,10 +152,12 @@ The following **layers** are selected for cost calculation:
1. Aircraft configuration (e.g., `blended_wing_body` or `tube_and_wing`, golden folder)
2. Fidelity of the calculation method (e.g., `empirical`, red folder)
3. Calculation method (e.g., `operating_cost_estimation_tu_berlin`, green folder)
4. Energy carrier (e.g., `kerosene` or `liquid_hydrogen`, grey folder) - **USER LAYER** (This is where the magic happens! \emoji mage)
4. Energy carrier (e.g., `kerosene` or `liquid_hydrogen`, grey folder) - **USER LAYER** (This is where the magic happens! :dizzy:)
![](../../assets/images/developer/style/python-modularization_02_example-folder.png)
@warning Check, if images displayed correctly here!
!!! warning
Check, if images displayed correctly here!
## File structure
......@@ -163,7 +169,7 @@ rAircraftDesign
| | |- blended_wing_body: Folder and files for blended wing body configurations (see [2])
| | |- tube_and_wing: Folder and files for tube and wing configurations (see [2])
| | | | - empirical: Folder and files for empirical calculation methods (see [3])
| | | | | - operating_cost_estimation_tu_berlin: Files and folders necessary for calculating operating costs based on the TU Berlin method ([J. Thorbeck's Documentation](https://unicado.ilr.rwth-aachen.de/w/micado_descriptions/doc_estimation/)) (see [4])
| | | | | - operating_cost_estimation_tu_berlin: Files and folders necessary for calculating operating costs (see [4])
| | | | | | - general: [user layer] Files with functionalities independent of layer 4 value
| | | | | | | - methodhtmlreport.py: Functionalities for data export to "cost_estimation.html" file (located in '...')
| | | | | | | - methodplot.py: Plotting functionalities (plots saved to 'projects/CSR/CSR-02/reporting/plots')
......@@ -185,16 +191,20 @@ rAircraftDesign
|- unicado_python_library: Contains UNICADO-specific Python packages
```
<br>
@note [1] At the top level, the example structure distinguishes between aircraft configurations with two branches: **blended wing body** and **tube and wing**.
@note [2] These folders are subdivided according to **layer 2** and may contain various calculation method fidelities.
@note [3] This folder is subdivided according to **layer 3** and may contain various calculation methods.
@note [4] This folder is subdivided according to **layer 4** and may contain various fuel types.
!!! note
[1] At the top level, the example structure distinguishes between aircraft configurations with two branches: **blended wing body** and **tube and wing**.
[2] These folders are subdivided according to **layer 2** and may contain various calculation method fidelities.
[3] This folder is subdivided according to **layer 3** and may contain various calculation methods.
[4] This folder is subdivided according to **layer 4** and may contain various fuel types.
## Files that require changes by the module manager
The code is designed to be highly generalized, meaning that only a few files need changes by the module manager. These files are shown in the following image and are discussed below in more detail. In some parts of the code, dynamic import commands and function names are generated, with examples provided at relevant points to illustrate how these commands work.
![](../../assets/images/developer/style/python-modularization_03_example-folder-changes-module-manager.png)
@warning Check, if images displayed correctly here!
!!! warning
Check, if images displayed correctly here!
### The `main()`
- Update the module name in two places within the docString
......@@ -203,7 +213,9 @@ The code is designed to be highly generalized, meaning that only a few files nee
![](../../assets/images/developer/style/python-modularization_04_main-01.png)
![](../../assets/images/developer/style/python-modularization_05_main-02.png)
@warning Check, if images displayed correctly here!
!!! warning
Check, if images displayed correctly here!
### The `data_preprocessing` (`datapreprocessing.py`)
- Update the layer description in the docString
......@@ -211,7 +223,9 @@ The code is designed to be highly generalized, meaning that only a few files nee
![](../../assets/images/developer/style/python-modularization_06_datapreprocessing-01.png)
![](../../assets/images/developer/style/python-modularization_07_datapreprocessing-02.png)
@warning Check, if images displayed correctly here!
!!! warning
Check, if images displayed correctly here!
**Example for `module_import_name`**
In this example, `module_import_name` at line 68 would be: `src.tube_and_wing.empirical.operating_cost_estimation_tu_berlin`.
......@@ -226,7 +240,9 @@ To import a module from `usermethoddatapreparation.py` at line 74, the command i
![](../../assets/images/developer/style/python-modularization_08_datapostprocessing-01.png)
![](../../assets/images/developer/style/python-modularization_09_datapostprocessing-02.png)
@warning Check, if images displayed correctly here!
!!! warning
Check, if images displayed correctly here!
## Files that require changes by the user
Similarly, the code is structured so that only a few files require modifications by the user. These files are highlighted in the following image.
......@@ -243,7 +259,9 @@ Users are free to structure the code within these files but must ensure that all
More detailed instructions for required changes are available within the docStrings of each corresponding file.
![](../../assets/images/developer/style/python-modularization_10_example-folder-changes-user.png)
@warning Check, if images displayed correctly here!
!!! warning
Check, if images displayed correctly here!
# Logging and printing {#logging-and-printing}
The Python framework in this project has a customized logging function, which builds on Python’s [logging facility](https://docs.python.org/3/library/logging.html). The following logging levels are available:
......@@ -286,7 +304,9 @@ The necessary steps are listed below. Please ensure to read the respective expla
2. Navigate to the `AircraftDesign/unicado_python_library` folder (illustrated below) to set up the required folder structure.
![](../../assets/images/developer/style/python-modularization_11_unicado-python-library.png)
@warning Check, if images displayed correctly here!
!!! warning
Check, if images displayed correctly here!
## Step 1: Create the package subfolder
In `unicado_python_library`, create a new subfolder for the package. Follow this naming convention:
......@@ -300,8 +320,8 @@ The `pyproject.toml` file contains information on the build backend (`[build-sys
Please download the sample `pyproject.toml` file and complete the **highlighted fields** with package-specific information, without modifying build system details.
@warning Upload files/images here!
@warning {F204735}
!!! warning
Upload files/images here! {F204735}
**Further resources:**
- [PEP 621: Project metadata](https://peps.python.org/pep-0621/)
......@@ -310,18 +330,18 @@ Please download the sample `pyproject.toml` file and complete the **highlighted
## Step 3: Create a `LICENSE` file
Add a `LICENSE` file to define usage rights. You can download this directly here:
@warning Upload files/images here!
@warning {F204736}
@warning Add: This file only needs to be downloaded from the repository.
!!! warning
Upload files/images here! {F204736}
Add: This file only needs to be downloaded from the repository.
The [GPL-3.0 license](https://choosealicense.com/licenses/gpl-3.0/#) text is used in this example.
## Step 4: Create a `README.md` file
Download and fill out the sample `README.md` file with details about your package. This file can also be obtained from the repository.
@warning Upload files/images here!
@warning {F204737}
@warning Add: This file only needs to be downloaded from the repository.
!!! warning
Upload files/images here! {F204737}
Add: This file only needs to be downloaded from the repository.
## Step 5: Create `src` subfolder
Inside the package folder, create a `src` subfolder to hold the `.py` files (modules).
......@@ -352,4 +372,4 @@ The modules should now be ready to use. You can import the functions from the m
`from datapostprocessingmodule import paths_and_names`
# Testing with Python {#testing-with-python}
tbd. \emoji construction
\ No newline at end of file
tbd. :construction:
\ No newline at end of file
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment