Python Refactoring (#103)

Author: simonkurtz-MSFT

.devcontainer/README.md

@@ -160,22 +160,22 @@ Our devcontainer uses two key lifecycle commands optimized for prebuild:
 #### `onCreateCommand` (Container Creation)
 ```bash
 # Creates Python virtual environment and registers Jupyter kernel
-echo '🚀 Creating Python virtual environment in workspace...' && 
-/usr/local/bin/python3.12 -m venv /workspaces/Apim-Samples/.venv --copies && 
-source /workspaces/Apim-Samples/.venv/bin/activate && 
-pip install --upgrade pip setuptools wheel ipykernel && 
+echo '🚀 Creating Python virtual environment in workspace...' &&
+/usr/local/bin/python3.12 -m venv /workspaces/Apim-Samples/.venv --copies &&
+source /workspaces/Apim-Samples/.venv/bin/activate &&
+pip install --upgrade pip setuptools wheel ipykernel &&
 python -m ipykernel install --user --name=apim-samples --display-name='APIM Samples Python 3.12'
 ```
 
 #### `updateContentCommand` (Content Updates)
 ```bash
 # Installs Python packages and configures environment
-source /workspaces/Apim-Samples/.venv/bin/activate && 
-pip install -r requirements.txt && 
-pip install pytest pytest-cov coverage && 
-python setup/setup_python_path.py --generate-env && 
-az config set core.login_experience_v2=off && 
-az extension add --name containerapp --only-show-errors && 
+source /workspaces/Apim-Samples/.venv/bin/activate &&
+pip install -r requirements.txt &&
+pip install pytest pytest-cov coverage &&
+python setup/setup_python_path.py --generate-env &&
+az config set core.login_experience_v2=off &&
+az extension add --name containerapp --only-show-errors &&
 az extension add --name front-door --only-show-errors
 ```
 

.devcontainer/devcontainer.json

@@ -157,4 +157,4 @@
   "runArgs": [
     "--init"
   ]
-}
+}

.devcontainer/post-start-setup.sh

@@ -77,7 +77,7 @@ echo "        - Wait for all extensions to install"
 echo "        --> ✅ (.venv) prefix will appear when you open a new terminal"
 echo ""
 echo "   3. Start using the infrastructures and samples!"
-echo "        - You may initially need to select the kernel (top-right above the" 
+echo "        - You may initially need to select the kernel (top-right above the"
 echo "          Jupyter notebook). If so, select the '.venv' Python environment."
 echo ""
 echo "============================================================================"

.gitattributes

@@ -26,6 +26,9 @@
 # Markdown files should use LF
 *.md text eol=lf
 
+# Python files should use LF
+*.py text eol=lf
+
 # Windows batch files should use CRLF
 *.bat text eol=crlf
 *.cmd text eol=crlf

.github/copilot-instructions.bicep.md

@@ -0,0 +1,51 @@
+---
+applyTo: "**/*.bicep"
+---
+
+# Copilot Instructions (Bicep)
+
+## Goals
+
+- Prefer modern Bicep syntax and patterns.
+- Keep templates readable and easy to extend.
+- Keep deployments cross-platform (Windows, Linux, macOS).
+
+## Conventions
+
+- Use `@description` for all parameters and variables.
+- Prefer consistent naming:
+  - Enums: `SNAKE_CASE` + uppercase.
+  - Resources/variables: `camelCase`.
+- Use the repo's standard top parameters when authoring standalone Bicep files:
+
+```bicep
+@description('Location to be used for resources. Defaults to the resource group location')
+param location string = resourceGroup().location
+
+@description('The unique suffix to append. Defaults to a unique string based on subscription and resource group IDs.')
+param resourceSuffix string = uniqueString(subscription().id, resourceGroup().id)
+```
+
+## Structure
+
+- Prefer visible section headers:
+
+```bicep
+// ------------------------------
+//    PARAMETERS
+// ------------------------------
+```
+
+- Keep two blank lines before a section header and one blank line after.
+- Suggested order (when applicable): Parameters, Constants, Variables, Resources, Outputs.
+
+## Docs
+
+- Add a Microsoft Learn template reference comment above each resource, e.g.:
+
+```bicep
+// https://learn.microsoft.com/azure/templates/microsoft.network/virtualnetworks
+resource vnet 'Microsoft.Network/virtualNetworks@<apiVersion>' = {
+  ...
+}
+```

.github/copilot-instructions.md

@@ -64,6 +64,11 @@ In case of any conflicting instructions, the following hierarchy shall apply. If
     - `shared/`: Shared resources, such as Bicep modules, Python libraries, and other reusable components.
     - `tests/`: Contains unit tests for Python code and Bicep modules. This folder should contain all tests for all code in the repository.
 
+  ## Language-specific Instructions
+
+  - Python: see `.github/copilot-instructions.python.md`
+  - Bicep: see `.github/copilot-instructions.bicep.md`
+
 ## Formatting and Style
 
 - Maintain consistent indentation and whitespace but consider Editor Config settings, etc, for the repository.
@@ -85,110 +90,7 @@ In case of any conflicting instructions, the following hierarchy shall apply. If
 - Ensure that Jupyter notebooks do not contain any cell output.
 - Ensure that Jupyter notebooks have `index` assigned to `1` in the first cell.
 
-## Language-specific Instructions
-
-### Bicep Instructions
-- Prefer latest Bicep syntax and features.
-- Generated Bicep files should work with Windows, Linux, and macOS.
-- Reference latest available module versions. These may be newer than what you were trained on.
-- Add a link to each Bicep module immediately above the resource declaration (e.g., // https://learn.microsoft.com/azure/templates/microsoft.network/virtualnetworks)
-- Use `@description` for all parameters and variables.
-- Use snake-case and uppercase for all enum declarations.
-- Use camel care for resource and variables names.
-- `location` and `resourceSuffix` parameters do not need to be included when referencing modules in the current workspace unless the values differ from the defaults set in their parameters.
-- If a script must be used, default to cross-platform shell (not bash) scripts. Avoid PowerShell scripts.
-- Always add these two parameters at the top of Bicep files:
-
-```Bicep
-@description('Location to be used for resources. Defaults to the resource group location')
-param location string = resourceGroup().location
-
-@description('The unique suffix to append. Defaults to a unique string based on subscription and resource group IDs.')
-param resourceSuffix string = uniqueString(subscription().id, resourceGroup().id)
-```
-
-- Overall layout of a Bicep file should be:
-    - Visible sections of code with the following format should be used:
-
-        ```bicep
-        // ------------------------------
-        //    <SECTION HEADER>
-        // ------------------------------
-        ```
-
-    - <SECTION HEADER> should be indented three spaces and be in all caps.
-    - Section headers should have only two blank lines before and only one blank line after.
-    - Top-to-bottom, the following comma-separated section headers should be inserted unless the section is empty:
-        - Parameters
-        - Constants
-        - Variables
-        - Resources
-        - Outputs
-
-### Python Instructions
-
-- Prefer Python 3.12+ syntax and features unless otherwise specified.
-- Respect the repository's `.pylintrc` file for linting rules. The file is found in the `tests/python/` folder.
-- When inserting a comment to describe a method, insert a blank line after the comment section.
-- Never leave a blank line at the very top of a Python file. The file must start immediately with the module docstring or code. Always remove any leading blank line at the top.
-- Do not have imports such as `from shared.python import Foo`. The /shared/python directory is covered by a root `.env` file. Just use `import Foo` or `from Foo import Bar` as appropriate.
-- After the module docstring, all import statements must come before any section headers (e.g., CONSTANTS, VARIABLES, etc.). Section headers should only appear after the imports. Here is a more explicit example:
-
-    ```python
-    """
-    Module docstring.
-    """
-
-    import ...
-    ...
-
-
-    # ------------------------------
-    #    CONSTANTS
-    # ------------------------------
-    ...
-    ```
-
-- Overall layout of a Python file should be:
-    - Visible sections of code with the following format should be used:
-
-        ```python
-        # ------------------------------
-        #    <SECTION HEADER>
-        # ------------------------------
-        ```
-
-    - <SECTION HEADER> should be indented three spaces and be in all caps.
-    - Section headers should have only two blank lines before and only one blank line after.
-    - Top-to-bottom, the following comma-separated section headers should be inserted unless the section is empty:
-        - Constants
-        - Variables
-        - Private Methods
-        - Public Methods
-
-    - If using classes, the following section headers should be used:
-        - Classes
-            - Constants
-            - Variables
-            - Constructor
-            - Private Methods
-            - Public Methods
-
-- Python Docstring/Class Formatting Rule:
-    - Always insert a single blank line after a class docstring and before any class attributes or methods.
-    - Never place class attributes or decorators on the same line as the docstring. Example:
-
-        ```python
-        class MyClass:
-            """
-            This is the class docstring.
-            """
-
-            attribute: str
-            ...
-        ```
-
-### Jupyter Notebook Instructions
+## Jupyter Notebook Instructions
 
 - Use these [configuration settings](https://github.com/microsoft/vscode-jupyter/blob/dd568fde/package.nls.json) as a reference for the VS Code Jupyter extension configuration.
 

.github/copilot-instructions.python.md

@@ -0,0 +1,64 @@
+---
+applyTo: "**/*.py"
+---
+
+# Copilot Instructions (Python)
+
+## Goals
+
+- Make changes that are easy to review, test, and maintain.
+- Keep scripts cross-platform (Windows, Linux, macOS).
+- Prefer minimal, working implementations (MVP), then iterate.
+
+## Project Context
+
+- Python code lives primarily under `shared/python/`, `setup/`, `infrastructure/`, and `tests/python/`.
+- The repository uses Azure CLI from Python for many operations.
+
+## Style and Conventions
+
+- Prefer Python 3.12+ features unless otherwise required.
+- Keep all imports at the top of the file.
+- Use type hints and concise docstrings (PEP 257).
+- Use 4-space indentation and PEP 8 conventions.
+- Use only straight quotes (U+0027 and U+0022), not typographic quotes.
+- Use whitespace to separate logical sections and add a blank line before `return` statements.
+
+## Import Style Guidelines
+
+- Imports from this repo should be grouped, be imported last, and have a group header called `# APIM Samples imports`
+- Only use multi-line imports when a single-line is too long
+- Avoid mixing patterns: Don't use both `import module` and `from module import ...` for the same module
+- Parentheses in imports: Only use parentheses for multi-line imports, not for single-line imports:
+  - Good: `from console import print_error, print_val`
+  - Bad: `from console import (print_error, print_val)`
+  - Good (multi-line):
+    ```python
+    from console import (
+        print_error,
+        print_info,
+        print_ok
+    )
+    ```
+- Order within APIM Samples imports section:
+  1. Module imports with aliases (e.g., `import azure_resources as az`)
+  2. Specific type/constant imports (e.g., `from apimtypes import INFRASTRUCTURE`)
+  3. Specific function imports (e.g., `from console import print_error`)
+
+## Linting (pylint)
+
+- Respect the repository pylint configuration at `tests/python/.pylintrc`.
+- When changing Python code, run pylint and ensure changes do not worsen the pylint rating unexpectedly.
+- Prefer fixing root causes (e.g., import structure, error handling) over suppressions.
+
+## Testing
+
+- Add or update pytest unit tests when changing behavior.
+- Prefer focused tests for the code being changed.
+- Avoid tests that require live Azure access; mock Azure CLI interactions and `azure_resources` helpers.
+
+## Azure Helper Imports
+
+- Prefer calling Azure resource helper functions via `import azure_resources as az`.
+- Avoid calling Azure-resource helpers through `utils` re-exports in new code.
+- When patching in tests, patch the symbol actually used by the module under test (e.g., `module.az.does_resource_group_exist`).

.gitignore

@@ -36,4 +36,7 @@ tests/python/$TextReport
 shared/bicep/modules/**/*.json
 main.json
 
-Test-Matrix.html
+Test-Matrix.html
+
+$JsonReport
+$TextReport

.vscode/settings.json

@@ -13,10 +13,18 @@
     "files.trimTrailingWhitespace": true,
     "files.insertFinalNewline": true,
     "files.trimFinalNewlines": true,
+    "files.eol": "\n",
     "editor.renderWhitespace": "trailing",
     "python.defaultInterpreterPath": "./.venv/Scripts/python.exe",
     "python.pythonPath": "./.venv/Scripts/python.exe",
     "python.envFile": "${workspaceFolder}/.env",
+    "[python]": {
+        "editor.codeActionsOnSave": {
+            "source.organizeImports": "explicit",
+            "source.unusedImports": "explicit"
+        },
+        "editor.formatOnSave": true
+    },
     "notebook.defaultLanguage": "python",
     "notebook.kernelPickerType": "mru",
     "terminal.integrated.defaultProfile.windows": "PowerShell",