💻 iMarina-load (Developer guide)

Prerequisites

You need Python 3.12.3 (or higher) version and git installed. To install them on Ubuntu, run this command:

 sudo apt install python3.12-venv gcc build-essential git -y

Installation

1.Clone repository of iMarina:

 git clone https://github.com/ICIQ-DMP/iMarina-load.git

Enter to folder of iMarina

 cd iMarina-load

2.Initialize a virtual environment (venv)

 python3 -m venv venv

3.Upgrade pip and install dependencies and requirements

 ./venv/bin/pip install --upgrade pip
 ./venv/bin/pip install -r requirements.txt

💻🧑‍💻 IDE Setup — PyCharm

🧩 1. Download and Install PyCharm

You can install PyCharm Community Edition (free) or Professional Edition (paid).

For manual installation on Linux using the .tar.gz package:

# Download the latest version from JetBrains community
wget https://download.jetbrains.com/python/pycharm-community-2024.2.tar.gz

Extract the file

 tar -xzf pycharm-community-2024.2.tar.gz

Move to /opt (recommended for global access)

sudo mv pycharm-community-2024.2 /opt/pycharm

2. Create a Shortcut (Alias)

To launch PyCharm quickly from any terminal, create an alias:

 echo "alias pycharm='/opt/pycharm/bin/pycharm.sh &'" >> ~/.bashrc
 source ~/.bashrc

Now you can open it by simply typing:

 pycharm

The alias will remain available even after restarting your terminal.

🌿 3. Clone the Project Repository (iMarina-load)

 cd /home/username/Desktop

 git clone https://github.com/ICIQ-DMP/iMarina-load.git

 cd iMarina-load

Then open the project directly in PyCharm:

 pycharm .
 pycharm
# all forms is correct

💡 iMarina-load Usage

Obtaining translations excels

By default, they are read from the input/ folder but you can change the location of these expected files with the following arguments:

--imarina-input /path/to/iMarina.xlsx      
--a3-input /path/to/A3.xlsx  
--countries-dict /path/to/countries.xlsx    
--jobs-dict /app/input/Job_Descriptions.xlsx

To start the program execute this command with argument –imarina-input:

./venv/bin/python src/main.py --step build --imarina-input ./input/iMarina.xlsx

You can either Download them manually from Sharepoint, or you can use the Dockerized OneDrive service to sync files from Sharepoint to your host computer automatically in the background.

💻 OneDrive service

The program will display a link and ask you to authenticate and paste the answered URL into the terminal.

  cd services/onedrive
  bash run.sh

After following the steps, OneDrive will be syncing the folder
Institutional Strengthening/_Projects/iMarina_load_automation/input
from Sharepoint into services/onedrive/data.

Add or change the necessary arguments to read from this new source, instead of input/, so that data consumed by the program is always updated.

You can leave OneDrive running so that the files are always in sync.

🐳 Docker basic info

Access the container shell:

 docker-compose run --rm app sh

🧪 Testing section

All tests are managed using pytest and are located in the tests/ directory.
The testing process ensures that all core functionalities work as expected before deployment.
For detailed testing setup, configuration, and automation through Docker or GitHub Actions, refer to the Programming standard document.

🧭 Git Branching Model

The project uses a two-branch model based on Git best practices:

• master → stable, production-ready branch
• develop → main branch for integrating and testing new features

🌱 Workflow

1. Pull the latest version of develop:

   git checkout develop
   git pull origin develop
   

2. Create a new branch for your feature or fix:

    git checkout -b feature/my-feature
   

3. After finishing your changes:

    git add .
    git commit -m "feat: add ......"
   

4. Push your branch to GitHub:

     git push --set-upstream origin feature/my-feature
   

5. Open a Pull Request (PR) (if necessary) on GitHub to merge into develop.
6. Once tested and approved, develop can be merged into master for release.

🛠️ Useful Commands

• List all branches

   git branch -a
  

• Switch between branches

   git checkout branch_name   
  

• Delete a local branch

   git branch -d branch_name
  #or
   git branch -D branch_name
  

• Visualize branch history

   gitk --all &
  

• Discard local changes

    git reset --hard
  

• Update your branch with the latest develop

   git pull origin develop --no-ff
  

More info in Programming standard

Additions from the readme of iMarina load

Initialize PYTHONPATH

This initialization adds the project path to Python’s module search path, so that it can find our tests.

With pytest.ini

To use the library correctly and find our tests, we must create the following file and place it in the same root directory as Desktop/iMarina-load. If it is already present

Create the pytest.ini file with the following content if not present:

[pytest]
pythonpath = .

Pytest uses the pytest.ini file to define global settings. The option pythonpath = . tells pytest to add the project root folder (.) to PYTHONPATH.

The test file must be in the project root (same folder as src/ and tests/).

With environment variable

To ensure that Python sees the project root, you can manually add it to PYTHONPATH running this command:

export PYTHONPATH=$PYTHONPATH:/home/your_usersystem/Desktop/iMarina-load

---

Creating tests

Test functions are written that begin with test_ in files with the same name.

Test Folder

Folder test for example test_main.py.

All the tests that we implement must be stored in this folder called tests.

Folder Location

And the tests folder must be located in the root directory of your project: Marina-load/tests.

In the file called test_main.py, you must first import the classes needed for the test For example:

from src.main import Researcher, is_visitor

---

Table of contents

• Programming Standard