Maintenance updates

.editorconfig

@@ -0,0 +1,16 @@
+# EditorConfig is awesome: https://EditorConfig.org
+
+# top-most EditorConfig file
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+end_of_line = crlf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.{yml,yaml}]
+indent_style = space
+indent_size = 2

.github/workflows/_build_and_publish_documentation.yml

@@ -13,7 +13,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout active branch
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           fetch-depth: 1
           lfs: true

.github/workflows/_build_package.yml

@@ -7,7 +7,7 @@ jobs:
     name: Build source distribution
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           fetch-depth: 1
           lfs: true
@@ -37,7 +37,7 @@ jobs:
   #     matrix:
   #       platform: [ubuntu-latest, macos-latest, windows-latest]
   #   steps:
-  #     - uses: actions/checkout@v3
+  #     - uses: actions/checkout@v4
   #       with:
   #         fetch-depth: 1
   #         lfs: true
@@ -46,7 +46,7 @@ jobs:
   #         python-version: '3.11'
   #         cache: 'pip' # cache pip dependencies
   #     - name: Install cibuildwheel
-  #       run: python -m pip install cibuildwheel==2.3.1
+  #       run: python -m pip install cibuildwheel==2.16
   #     - name: Build wheels
   #       run: python -m cibuildwheel --output-dir wheels
   #     - uses: actions/upload-artifact@v3

.github/workflows/_code_quality.yml

@@ -13,7 +13,7 @@ jobs:
           options: '--check --diff'
           src: '.'
           jupyter: true
-          version: '>=23.9'
+          version: '==23.11'
 
   ruff:
     runs-on: ubuntu-latest
@@ -27,7 +27,7 @@ jobs:
       - name: Install dependencies
         run: pip install -r requirements.txt
       - name: Install ruff
-        run: pip install ruff>=0.0.290
+        run: pip install ruff==0.1.6
       - name: Run ruff
         run: ruff .
 
@@ -45,6 +45,6 @@ jobs:
           pip install -r requirements.txt
           pip install pytest
       - name: Install pyright
-        run: pip install pyright>=1.1.325
+        run: pip install pyright==1.1.336
       - name: Run pyright
         run: pyright .

.github/workflows/_merge_into_release.yml

@@ -12,7 +12,7 @@ jobs:
     runs-on: ubuntu-latest
     environment: release
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           # Fetch the whole history to prevent unrelated history errors
           fetch-depth: 0

.gitignore

@@ -3,18 +3,6 @@ __pycache__/
 *.py[cod]
 *$py.class
 
-#vi & emacs
-*~
-'#'*
-
-#packaging
-*.whl
-*.tar.gz
-
-
-#doxygen
-html/
-
 # C extensions
 *.so
 
@@ -140,10 +128,17 @@ dmypy.json
 # Pyre type checker
 .pyre/
 
+# PyCharm
+.idea
+
+# modules
+modules.txt
+
 # VS Code Settings
 .vscode/*
 !.vscode/settings.json
 !.vscode/tasks.json
 !.vscode/launch.json
 !.vscode/extensions.json
 !.vscode/*.code-snippets
+

.vscode/extensions.json

@@ -10,6 +10,7 @@
         "charliermarsh.ruff",
         "sourcery.sourcery",
         "njpwerner.autodocstring",
+        "editorconfig.editorconfig",
     ],
     // List of extensions recommended by VS Code that should not be recommended for users of this workspace.
     "unwantedRecommendations": []

.vscode/launch.json

@@ -7,31 +7,35 @@
         {
             "name": "Debug Unit Test",
             "type": "python",
-            "request": "test",
+            "request": "launch",
             "justMyCode": false,
+            "program": "${file}"
         },
         {
-            "name": "Python: Current File",
+            "name": "Python: Current File, cwd = file dir, envFile",
             "type": "python",
             "request": "launch",
-            "cwd": "${fileDirname}",
+            "cwd": "${fileDirname}", // working dir = dir where current file is
             "program": "${file}",
             "console": "integratedTerminal",
-            "justMyCode": true,
             "autoReload": {
                 "enable": true
-            }
+            },
+            "justMyCode": false,
+            "envFile": "${workspaceFolder}/.env" // specify where .env file is
         },
         {
-            "name": "Python: Current File, cwd = workspace root folder",
+            "name": "Python: Current File, cwd = workspace root folder, envFile",
             "type": "python",
             "request": "launch",
-            "cwd": "${workspaceFolder}",
+            "cwd": "${workspaceFolder}", // working dir = workspace (mvx) dir
             "program": "${file}",
             "console": "integratedTerminal",
             "autoReload": {
                 "enable": true
-            }
+            },
+            "justMyCode": false,
+            "envFile": "${workspaceFolder}/.env" // specify where .env file is
         },
         {
             "name": "dictParser test_dict",
@@ -46,7 +50,9 @@
             "console": "integratedTerminal",
             "autoReload": {
                 "enable": true
-            }
+            },
+            "justMyCode": false,
+            "envFile": "${workspaceFolder}/.env" // specify where .env file is
         },
         {
             "name": "dictParser include\\initialConditions",
@@ -61,13 +67,14 @@
             "console": "integratedTerminal",
             "autoReload": {
                 "enable": true
-            }
+            },
+            "justMyCode": false,
+            "envFile": "${workspaceFolder}/.env" // specify where .env file is
         },
         {
             "name": "dictParser test_dict .env",
             "type": "python",
             "request": "launch",
-            "envFile": "${workspaceFolder}\\.env",
             "cwd": "${workspaceFolder}\\tests",
             "program": "${workspaceFolder}\\src\\dictIO\\cli\\dictParser.py",
             "args": [
@@ -77,7 +84,9 @@
             "console": "integratedTerminal",
             "autoReload": {
                 "enable": true
-            }
+            },
+            "justMyCode": false,
+            "envFile": "${workspaceFolder}/.env" // specify where .env file is
         },
     ]
 }

.vscode/settings.json

@@ -1,4 +1,7 @@
 {
+    "terminal.integrated.env.windows": {
+        "PYTHONPATH": "${workspaceFolder}/src"
+    },
     "python.terminal.activateEnvInCurrentTerminal": true,
     "python.languageServer": "Pylance",
     "ruff.importStrategy": "fromEnvironment",
@@ -19,7 +22,9 @@
     "python.analysis.diagnosticSeverityOverrides": {},
     "python.analysis.indexing": true,
     "python.analysis.autoImportCompletions": true,
+    "python.analysis.autoImportUserSymbols": true,
     "python.analysis.inlayHints.variableTypes": false,
     "python.analysis.inlayHints.functionReturnTypes": false,
     "python.analysis.inlayHints.pytestParameters": true,
+    "python.terminal.executeInFileDir": true,
 }

README.md

@@ -13,36 +13,37 @@ Further, dictIO
 * can read and write also JSON, XML and OpenFOAM (with some limitations)
 
 ## Installation
+
 ```sh
 pip install dictIO
 ```
 
 ## Usage Example
 
 dictIO provides a simple, high level API that allows reading and writing Python dicts from/to dict files:
-~~~py
+```py
 from dictIO import DictReader, DictWriter
 
 my_dict = DictReader.read('myDict')
 DictWriter.write(my_dict, 'parsed.myDict')
-~~~
+```
 
 The above example reads a dict file, merges any (sub-)dicts included through #include directives, evaluates expressions contained in the dict,
 and finally saves the read and evaluated dict with prefix 'parsed' as 'parsed.myDict'.
 
 This sequence of reading, evaluating and writing a dict is also called 'parsing' in dictIO.
 Because this task is so common, dictIO provides a convenience class for it:
 Using DictParser.parse() the above task can be accomplished in one line of code:
-~~~py
+```py
 from dictIO import DictParser
 
 DictParser.parse('myDict')
-~~~
+```
 
 The above task can also be invoked from the command line, using the 'dictParser' command line script installed with dictIO:
-~~~sh
+```sh
 dictParser myDict
-~~~
+```
 
 _For more examples and usage, please refer to dictIO's [documentation][dictIO_docs]._
 
@@ -56,43 +57,72 @@ _For a detailed documentation of the dict file format used by dictIO, see [File
 
 ## Development Setup
 
-1. Install Python 3.9 or higher, i.e. [Python 3.9](https://www.python.org/downloads/release/python-3912/) or [Python 3.10](https://www.python.org/downloads/release/python-3104/)
+1. Install Python 3.9 or higher, i.e. [Python 3.10](https://www.python.org/downloads/release/python-3104/) or [Python 3.11](https://www.python.org/downloads/release/python-3114/)
 
 2. Update pip and setuptools:
 
-    ~~~sh
-    $ python -m pip install --upgrade pip setuptools
-    ~~~
+    ```sh
+    python -m pip install --upgrade pip setuptools
+    ```
 
 3. git clone the dictIO repository into your local development directory:
 
-    ~~~sh
+    ```sh
     git clone https://github.com/dnv-opensource/dictIO path/to/your/dev/dictIO
-    ~~~
+    ```
 
 4. In the dictIO root folder:
 
     Create a Python virtual environment:
-    ~~~sh
-    $ python -m venv .venv
-    ~~~
-    Activate the virtual environment: <br>
+
+    ```sh
+    python -m venv .venv
+    ```
+
+    Activate the virtual environment:
+
     ..on Windows:
-    ~~~sh
+
+    ```sh
     > .venv\Scripts\activate.bat
-    ~~~
+    ```
+
     ..on Linux:
-    ~~~sh
-    $ source .venv/bin/activate
-    ~~~
+
+    ```sh
+    source .venv/bin/activate
+    ```
+
     Update pip and setuptools:
-    ~~~sh
-    $ python -m pip install --upgrade pip setuptools
-    ~~~
+
+    ```sh
+    (.venv) $ python -m pip install --upgrade pip setuptools
+    ```
+
     Install dictIO's dependencies:
-    ~~~sh
-    $ pip install -r requirements-dev.txt
-    ~~~
+    ```sh
+    (.venv) $ pip install -r requirements-dev.txt
+    ```
+
+    This should return without errors.
+
+5. Setup your development environment to locate Python source codes:
+
+    For example, Visual Studio Code on Windows assumes the Python environment is specified in a `.env` file. <br>
+    If you are developing and running the Python code from VSCode, make sure to create a `.env` file in the mypackage root folder with below content. <br>
+    Set the path for `PROJ_DIR` to where your mypackage folder is on your system. <br>
+    _Note_: `.env` is part of `.gitignore`, such that you do not commit your `.env` file to the repository.
+
+    ```ini
+    PROJ_DIR=<path-to-dictIO-root-dir>
+    PYTHONPATH=${PROJ_DIR}/src
+    ```
+
+6. Test that the installation works (in the mypackage root folder):
+
+    ```sh
+    (.venv) $ pytest .
+    ```
 
 ## Meta
 
@@ -112,9 +142,9 @@ Distributed under the MIT license. See [LICENSE](LICENSE.md) for more informatio
 
 1. Fork it (<https://github.com/dnv-opensource/dictIO/fork>)
 2. Create your branch (`git checkout -b myBranchName`)
-3. Commit your changes (`git commit -am 'place your commit message here'`)
-4. Push to the branch (`git push origin myBranchName`)
-5. Create a new Pull Request
+3. Commit your changes (e.g. `git commit -m 'place a descriptive commit message here'`)
+4. Push to the branch (e.g. `git push origin myBranchName`)
+5. Create a new Pull Request in GitHub
 
 For your contribution, please make sure you follow the [STYLEGUIDE](STYLEGUIDE.md) before creating the Pull Request.