feat: add updateAddon.py automated tool to complement existing#41
feat: add updateAddon.py automated tool to complement existing#41abdel792 wants to merge 8 commits into
Conversation
…ration merges for legacy add-ons. - Add tomlkit to project dependencies in pyproject.toml to support robust AST-aware TOML parsing. - Update updatingExistingAddons.md to provide clear instructions and prerequisites for the new automated tool. - Exclude the update script from ruff and pyright configurations to prevent strict environment linting conflicts.
|
Hi @nvdaes, I have just added you as a collaborator to this repository. If you have some time and interest, feel free to directly review and update the docstrings in Thank you so much for your help and guidance on this! |
|
Thanks @abdel792 . I've accepted your invitation as a collaborator, and I'll try to update the docstrings. |
|
@abdel792 , can we add a way to ignore files which shouldn't be merged? |
|
Thanks a lot @nvdaes for your quick commits and for improving the docstrings and file headers! Regarding your suggestions:
I'll let you know once I've drafted the file-ignoring feature so we can test it. Thanks again for your amazing collaboration! |
|
@abdel792 , I've reorganized the documentation so that info about the script is at the start. Perhaps the information about merge should be removed= |
- Remove trailing "Press Enter to exit..." prompt at successful script completion to allow seamless execution in automated environments. - Implement specific file/folder exclusion handling during synchronization, with full architecture setup requested by @CyrilleB79.
|
Hi @nvdaes, Thank you so much for updating the documentation! It looks great and makes using the automated tool very clear. Could you please do me a favor and also integrate the new feature requested by @CyrilleB79 that I just implemented in my latest commit? It allows developers to exclude specific template files during synchronization. Here is the markdown section that needs to be added to the documentation (you can place it right before the build verification step): ### Excluding specific template files
By default, the script synchronizes every infrastructure file provided by AddonTemplate.
If you want to preserve specific files from your repository (for example, a customized GitHub workflow), you can exclude them from synchronization.
Open `updateAddon.py` and locate the `IGNORED_FILES` set near the beginning of the `main()` function:
```python
IGNORED_FILES = {
os.path.join(".github", "workflows", "build_addon.yml").lower(),
}Add any relative path from the template root to this set to prevent that file from being synchronized. |
|
Hi @nvdaes, While looking closely at our documentation, I am considering a complete overhaul and restructuring of the documentation files to make everything cleaner, more cohesive, and easier to navigate for developers. Before diving into this, I wanted to open a discussion here to get your thoughts, ideas, or any suggestions you might have regarding how we should reorganize the content. Let me know what you think! |
- Completely restructure the guide to separate the recommended automated tool method from the manual Git merge workflow. - Integrate detailed instructions for the automated companion script (`updateAddon.py`). - Document the new template synchronization exclusions feature (`IGNORED_FILES`). - Improve overall clarity, formatting, and prerequisites for initial repository setup.
|
I have just committed a complete overhaul and reorganization of the update documentation ( In this update, I have:
Please let me know if you have any feedback or further suggestions. @nvdaes, please feel free to add, modify, or correct anything you see fit—you have the green light, of course! |
There was a problem hiding this comment.
Pull request overview
This PR introduces a developer-facing automation tool (updateAddon.py) intended to help migrate/update existing NVDA add-ons to the modern AddonTemplate structure, alongside documentation and dependency updates to support that workflow.
Changes:
- Added
updateAddon.pyto clone the latest AddonTemplate, sync infrastructure files, and mergebuildVars.py/pyproject.toml. - Updated
pyproject.tomldependencies (pyright bump + new tomlkit dependency) and excludedupdateAddon.pyfrom ruff/pyright checks. - Expanded
docs/managementFromGit/updatingExistingAddons.mdwith an “automated update” path plus revised manual instructions.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 11 comments.
| File | Description |
|---|---|
| updateAddon.py | New CLI tool that syncs template infrastructure and performs AST/TOML-based merges. |
| pyproject.toml | Adds tomlkit dependency and excludes the new script from lint/type-checking; bumps pyright. |
| docs/managementFromGit/updatingExistingAddons.md | Documents the new automated update workflow and revises the manual update steps. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| def deepMergeDicts(dictProj: dict[str, Any], dictTpl: dict[str, Any]) -> dict[str, Any]: | ||
| """Recursively merges dictTpl into dictProj. Supports both dict and tomlkit container types. | ||
|
|
||
| :param dictProj: The original dictionary to be updated. | ||
| :param dictTpl: The template dictionary whose values will be merged into dictProj. | ||
| :return: The updated dictProj with merged values from dictTpl. | ||
| """ | ||
| for key, value in dictTpl.items(): | ||
| if key in dictProj: | ||
| if isinstance(dictProj[key], dict) and isinstance(value, dict): | ||
| deepMergeDicts(dictProj[key], value) | ||
| elif isinstance(dictProj[key], list) and isinstance(value, list): | ||
| for item in value: | ||
| if item not in dictProj[key]: | ||
| dictProj[key].append(item) | ||
| else: | ||
| pass | ||
| else: | ||
| dictProj[key] = value | ||
| return dictProj |
| # Extract base package name (e.g. 'pyright' from 'pyright[nodejs]==1.1.407') | ||
| def get_base(s: str) -> str: | ||
| return s.split("[")[0].split("=")[0].split(">")[0].strip().lower() | ||
|
|
| if val is None: | ||
| formattedVal = "None" | ||
| elif isinstance(val, str): | ||
| is_multiline = key in ["addon_summary", "addon_description", "addon_changelog"] | ||
| formattedVal = f'_("""{val}""")' if is_multiline else f'"{val}"' | ||
| else: | ||
| formattedVal = str(val) |
| addonDirInput = args.addonDir if args.addonDir else os.getcwd() | ||
| addonDir = os.path.abspath(addonDirInput) | ||
|
|
||
| print("=== NVDA ADD-ON UPDATE TOOL ===") | ||
| print(f"[*] Target Directory: {addonDir}") | ||
|
|
||
| oldBuildvars = os.path.join(addonDir, "buildVars.py") | ||
| oldPyproject = os.path.join(addonDir, "pyproject.toml") | ||
|
|
||
| if not os.path.exists(oldBuildvars): | ||
| print(f"[-] Error: '{addonDir}' does not appear to be a valid NVDA Add-on (missing buildVars.py).") | ||
| input("\nPress Enter to exit...") | ||
| sys.exit(1) |
| print("[+] Backup created successfully.") | ||
| except Exception as e: | ||
| print(f"[-] Critical: Backup failed ({e}). Aborting update.") | ||
| input("\nPress Enter to exit...") |
| "pyright[nodejs]==1.1.407", | ||
| "pyright[nodejs]==1.1.411", | ||
| # Repository synchronization machinery | ||
| "tomlkit>=0.12.0", |
| ```sh | ||
| cd {repoFolder} | ||
| git clone https://github.com/{repoName}.git | ||
| ``` |
|
|
||
| Before running the tool, ensure your system meets the following requirements: | ||
|
|
||
| - **Python**: Version **3.11** or newer must be installed. |
| > [!NOTE] | ||
| > Before modifying any infrastructure files, the script creates an untracked `_bak_` directory containing backups of every file it updates. If necessary, you can restore these files manually. |
| Fetch the latest version of AddonTemplate: | ||
|
|
||
| ```sh | ||
| git fetch template | ||
| ``` | ||
|
|
||
| Run the update script: | ||
|
|
||
| ```sh | ||
| uv run updateAddon.py | ||
| ``` |
Link to issue number:
Close #37.
Summary of the issue:
Upgrading an existing add-on to follow the modern
addonTemplatestructure manually is a repetitive and error-prone process. Developers frequently encounter syntax issues or merge conflicts when manually porting old metadata into the newpyproject.tomlstructure.Description of developer facing changes:
Introduces an automated update workflow. Developers can now run a single command (
uv run updateAddon.py) from any directory on their PC to automatically migrate metadata, clean template placeholder data (like removingnvaccessfrom third-party authors lists), and merge project configurations while preserving custom formatting.Description of development approach
updateAddon.pyat the repository root. The script leverages an AST-aware (Abstract Syntax Tree) approach to perform safe, robust parsing and merging of TOML structures.tomlkit==0.13.0under the# Update machinerysection inpyproject.tomlto support programmatic, comment-preserving TOML modifications.updateAddon.pyto theexcludelists of both[tool.ruff]and[tool.pyright]withinpyproject.tomlto avoid unnecessary environmental or strict typing alerts during standard repository validation.updatingExistingAddons.mdto cleanly integrate prerequisites (Python 3.11+, Git available in PATH) and step-by-step instructions on how to use this new companion tool alongside the existing manual instructions.Testing strategy:
The script and documentation workflow have been tested locally:
git fetch templateto ensure local tracking branches were up to date.uv run updateAddon.pyfrom the repository root, and verified that a_bak_backup directory was safely generated.pyproject.tomlto ensure old custom metadata was correctly merged, template placeholder defaults were stripped, and file formatting/comments remained completely intact.uv syncfollowed byuv run sconsto ensure the final environment synchronized properly and the.nvda-addonbundle compiled successfully with zero errors.Known issues with pull request:
None.
Code Review Checklist
updatingExistingAddons.md) has been explicitly updated to reflect these changes.