First steps in addon development
Hi,
Although each add-on is different, I standardize around the following:
- Setup: no integrated development environment (IDE), relying on Notepad++ for all coding activities, along with using command-line tools. I would have suggested Cygwin/PowerShell/Command Prompt if the question was asked seven years ago, but Windows Subsystem for Linux (WSL) changed everything as I can use Linux tools such as Grep for certain tasks. Besides, all the tools I need to write and package add-ons are either included with Ubuntu (the WSL distribution I use) or can be fetched from elsewhere. I keep latest versions of various NVDA development builds (channels) so I can replicate user environments.
- Documentation: I’m sure others will recommend it, but I use what I wrote initially – NVDA add-on development guide. I work with NVDA source code directly (see below as to why and how), but if I do employ third-party packages, I read its documentation and experiment with it in Python interpreter (both Windows and Linux) before employing the package in my add-on in its entirety (that is, I include the complete package as part of my add-on).
- Folder structure: while I use a dedicated folder structure for managing add-ons, I sometimes develop add-ons directly from their install location. That way I can test things immediately after writing code and experience bugs firsthand.
- Coding and debugging: I either call print function or ask add-on code to play tones for debugging purposes. While quite advanced, I disassemble Python bytecode as part of optimization work from time to time (a topic that requires a dedicated thread to discuss as it is quite advanced).
Specifically, my add-on development environment resembles that of NVDA screen reader development setup, complete with Visual Studio 2022 Community, Python 3.7 (3.10 in WSL), and tools to run system and unit tests if required. Part of this has to do with my desire to unify the development environment across NVDA itself and add-ons, but also to mirror how NV Access folks and code contributors prepare their systems for NVDA development (I and several others both contribute code to NVDA project and publish add-ons). Due to the requirement of one particular add-on, I require that my development computer run a Windows Insider Preview build, specifically either release preview or beta builds (until last year I also used a touchscreen computer as I was actively maintaining an add-on that uses touch capabilities). My setup is not as automated to Noelia’s environment, but I can perform tests if needed.
Because I sometimes contribute code to NVDA project (not as often as I used to these days), I use the same set of software as NV Access folks, including Git, Flake8 (linter), among others.
As for the overall folder structure of my add-ons, it can range from a single Python file that houses a global plugin to a structure resembling a mini NVDA, complete with a global plugin, several app modules, and an install tasks module. Most of my add-ons are in between these extremes. Here are four example add-ons to showcase them:
- Enhanced Touch Gestures: consists of a single global plugin module. After installing it, you may notice additional folders used for documentation and localization data.
- Add-on Updater: the actual global plugin is stored as a package with multiple Python files.
- Windows App Essentials: this add-on consists of a global plugin and multiple app modules.
- StationPlaylist: lots of folders and files, organized into a global plugin, two app module packages, and individual app module files.
Add-ons from other authors may have more complex structure.
As for my code structure, it is a hybrid of the style used in NVDA project and other Python projects. The code uses tabs for indentation just like NVDA, but also include type hints, lint results, and lots of source code comments.
As for my add-on development methodology, I tend to follow agile, iterative development method. I use iterative method in many places, especially when testing add-ons, knowing that users should be given a chance to shape an add-on with me by giving feedback. It takes me between hours to weeks to write an add-on depending on the add-on’s purpose (the problem(s) the add-on needs to solve); of course it takes more time as I go through requirements analysis, design, coding and prototyping, testing, and review and publishing steps. Although rare, I did publish a complete add-on within minutes but if and only if I know exactly what the problem is and know the solution, but typically it takes hours to come up with a seriously usable add-on.
I can offer three tips for beginning add-on writers:
- Read and write a lot: first and foremost, remember that you are effectively writing code, so treat writing add-ons as though you are writing an important essay or an impactful story. In other words, you must read and write a lot to succeed as an NVDA add-on author. Unless you are a genius, you will do lots of reading and writing while writing a small add-on.
- Have clear and reasonable set of goals: unless you are a genius, you will find that you can’t write add-ons in one programming session. Therefore, work on dividing up the problem the add-on seeks to solve into smaller pieces so you can set clear and reasonable goals to work on while developing add-ons. Of these goals, the first goal should always be, “rephrase the problem in my own words” – if you are talking to a user, restating the problem in your own words will let the user know that you have at least some understanding of the problem at hand. One common thing I notice from beginning developers is telling the world that their first add-on can solve everything. Unless you are a proven genius, that’s a big no-no.
- Test and test again: the best stories require many edits. Do not fall into temptation of saying your add-on is stable unless you’ve tested it several times.
One more tip, mostly for folks with some add-on development experience: learn to remove color from pictures. In other words, learn to walk backwards and retrace steps – picture (imagine) what the final version of the add-on would look (sound) like to users, then come up with ways to arrive at the final picture. For example, if you are writing an app module that adds new functionality for NVDA users, imagine how the user would use your app module and work backwards so you can come up with needed functions, classes, commands, messages, and other components to complete the add-on. This is sometimes applicable to NVDA screen reader contributors.
Cheers,
Joseph
Sent: Sunday, August 14, 2022 3:14 PM
To: nvda-addons (mailing list) <nvda-addons@nvda-addons.groups.io>
Subject: [nvda-addons] First steps in addon development
Hello everyone,
I'm new -writing- to this list, so firstly I will introduce myself... My name is Ramón and I'm a freelance accessibility consultant based in Asturias, north of Spain. I also do some Python programming, and I'm starting to play with NVDA code and Addons
For the moment I've developed some toy code and played with basic functionalities, but I have some ideas for more complex experiments and I would like to know your experiences developing addons. Mostly how you plan, develop and debug your code, especially for "big" addons. I've asked this before in the Spanish lists and obtained very good answers and advice; now I finally found the time for translating these questions to English and will love to learn from this great community.
You'll see that there are many questions, I've tried to be exhaustive and cover all the development process, but of course feel fre to ignore my script and share any ideas that you consider useful when developing addons / NVDA features.
1. What is your development environment setup?
- NVDA setup (installed, portable, source...). Do you consider different development scenarios (for example, reverting NVDA source to an older version)?
- Additional addons or other tools to help with debug...
- System Python installed, if any. Virtual environments?
- Code/markdown editor/IDE, linting, useful extensions, automation...
2. Documentation
- Beyond directly reading NVDA's source code, do you use any library/API references, guides, etc.?
- Any recommendations of books, blogs or other learning resources? (better if they are especific to NVDA/Screen readers/TTS,Braille, etc.)
3. Files, directories, code structure
- Apart from using the Addon Template, how do you organize addon's code, modules/packages, public/private parts, functions, classes, configurations...?
- Working directory: do you write code in a "draft" directory or directly in the scratchpad directory? Is it safe to work in the scratchpad if there are errors in the code, for example?
- Third-party dependencies: do you include their full code or just the needed code (if possible), have you faced compatibility issues with other addons? What about executables/DLLs/database engines...?
- Version control: do you follow a "standardized" workflow or methodology? do you have an issues/PR policy for contributing? Do you use Github actions or automation?
4. Coding and debugging
- Do you use coding aids like autocompletion, linting, text espansion, code suggestions/copilot...?
- How do you test and debug your code? How do you log or trace variables/errors?
- Do you include tests in your code? Do you follow a methodology like TDD or similar?
- Do you use Github Actions or similar to automate things like basic PR checking, building of releases, etc.?
I know that most of the above questions are not necessary for small addons, but I would like to start building my house with the best foundations that I can afford 😉
Thanks in advance!
Ramón.
Hello everyone,I'm new -writing- to this list, so firstly I will introduce myself... My name is Ramón and I'm a freelance accessibility consultant based in Asturias, north of Spain. I also do some Python programming, and I'm starting to play with NVDA code and AddonsFor the moment I've developed some toy code and played with basic functionalities, but I have some ideas for more complex experiments and I would like to know your experiences developing addons. Mostly how you plan, develop and debug your code, especially for "big" addons. I've asked this before in the Spanish lists and obtained very good answers and advice; now I finally found the time for translating these questions to English and will love to learn from this great community.You'll see that there are many questions, I've tried to be exhaustive and cover all the development process, but of course feel fre to ignore my script and share any ideas that you consider useful when developing addons / NVDA features.1. What is your development environment setup?- NVDA setup (installed, portable, source...). Do you consider different development scenarios (for example, reverting NVDA source to an older version)?- Additional addons or other tools to help with debug...- System Python installed, if any. Virtual environments?- Code/markdown editor/IDE, linting, useful extensions, automation...2. Documentation- Beyond directly reading NVDA's source code, do you use any library/API references, guides, etc.?- Any recommendations of books, blogs or other learning resources? (better if they are especific to NVDA/Screen readers/TTS,Braille, etc.)3. Files, directories, code structure- Apart from using the Addon Template, how do you organize addon's code, modules/packages, public/private parts, functions, classes, configurations...?- Working directory: do you write code in a "draft" directory or directly in the scratchpad directory? Is it safe to work in the scratchpad if there are errors in the code, for example?- Third-party dependencies: do you include their full code or just the needed code (if possible), have you faced compatibility issues with other addons? What about executables/DLLs/database engines...?- Version control: do you follow a "standardized" workflow or methodology? do you have an issues/PR policy for contributing? Do you use Github actions or automation?4. Coding and debugging- Do you use coding aids like autocompletion, linting, text espansion, code suggestions/copilot...?- How do you test and debug your code? How do you log or trace variables/errors?- Do you include tests in your code? Do you follow a methodology like TDD or similar?- Do you use Github Actions or similar to automate things like basic PR checking, building of releases, etc.?I know that most of the above questions are not necessary for small addons, but I would like to start building my house with the best foundations that I can afford 😉Thanks in advance!Ramón.
Hi Ramon,
I too was planning to get started with addon development and you asked almost same questions as I was planning to ask.
Really thanks for this.
Joseph and Samuel,
Really thanks, your advice is quite good.
I have 1 more question though,
As Joseph said that he uses just Notepad++ for his addon development, so I want to ask, that do you write everything by hand or rely on autocompletion?
May be I'm missing something, but when I last checked, Auto completion was not accessible in Notepad++
If you don't rely on Auto completion, then isn't too tedious and boring to type everything by hand and verify everything to avoid syntax errors or other linting errors?
I want to know that is there any way by which we can get proper and robust auto completion support for addon development? I think that if we install python extension in VS code and start developing, then we won't get auto completion for NVDA related stuff, is it true?
Or is there any way to integrate VS Code/Visual Studio with NVDA's source so that we can get code completion for NVDA related classes, method, pydoc support etc?
1 More thing which I want to ask is:
Usually I code in ReactJS and C# .NET and I use architecture patterns, for example MVVM for my Desktop based C# apps and MVC for web apps.
Do you guys follow any such pattern for your addons? If yes, then
which?
Help will be very appreciated.
And really thanks for bringing this topic Ramon,
I think it will be very useful for everybody who so ever is planning to start addon development in near future.
Hi Ramon,
welcome to the list.
I think for lots of the questions you will receive much of the same answers, but I will tell you about what I do for my working directory, since I am not sure if others also use this so I wanted to share .
I have a normal directory where I store the addon project in a special workspace folder. So each addon is something like C:\Users\Sam\workspace\<addon name>
I also use the scratchpad for testing the addon, but what I do is I create symbollic links to the addon file from my project directory to the scratchpad using the mklink command. This way I don't need to move files back and forth between my scratchpad and project folder. I can just edit my addon file, hit ctrl + S in VS code, and reload my addons, test the change, and finally if all is good create a git commit of the change.
Hope that helps. Other than that I would recommend VS code together with the official python extension as well as pylance, especially if you are blind yourself. For the most part, you will just want to learn general programming and project management skills, which you can in much bigger communities than ours. Definitely learn git and hot to use versioning to your advantage. Having granular logical commits can make understanding your code much easier and make it a hell of a lot easier for tracking down a bug.
Anyway good luck and looking forward to seeing your progress :)
On Sun, Aug 14, 2022 at 11:19 PM Ramón Corominas <ramon@...> wrote:
Hello everyone,I'm new -writing- to this list, so firstly I will introduce myself... My name is Ramón and I'm a freelance accessibility consultant based in Asturias, north of Spain. I also do some Python programming, and I'm starting to play with NVDA code and AddonsFor the moment I've developed some toy code and played with basic functionalities, but I have some ideas for more complex experiments and I would like to know your experiences developing addons. Mostly how you plan, develop and debug your code, especially for "big" addons. I've asked this before in the Spanish lists and obtained very good answers and advice; now I finally found the time for translating these questions to English and will love to learn from this great community.You'll see that there are many questions, I've tried to be exhaustive and cover all the development process, but of course feel fre to ignore my script and share any ideas that you consider useful when developing addons / NVDA features.1. What is your development environment setup?- NVDA setup (installed, portable, source...). Do you consider different development scenarios (for example, reverting NVDA source to an older version)?- Additional addons or other tools to help with debug...- System Python installed, if any. Virtual environments?- Code/markdown editor/IDE, linting, useful extensions, automation...2. Documentation- Beyond directly reading NVDA's source code, do you use any library/API references, guides, etc.?- Any recommendations of books, blogs or other learning resources? (better if they are especific to NVDA/Screen readers/TTS,Braille, etc.)3. Files, directories, code structure- Apart from using the Addon Template, how do you organize addon's code, modules/packages, public/private parts, functions, classes, configurations...?- Working directory: do you write code in a "draft" directory or directly in the scratchpad directory? Is it safe to work in the scratchpad if there are errors in the code, for example?- Third-party dependencies: do you include their full code or just the needed code (if possible), have you faced compatibility issues with other addons? What about executables/DLLs/database engines...?- Version control: do you follow a "standardized" workflow or methodology? do you have an issues/PR policy for contributing? Do you use Github actions or automation?4. Coding and debugging- Do you use coding aids like autocompletion, linting, text espansion, code suggestions/copilot...?- How do you test and debug your code? How do you log or trace variables/errors?- Do you include tests in your code? Do you follow a methodology like TDD or similar?- Do you use Github Actions or similar to automate things like basic PR checking, building of releases, etc.?I know that most of the above questions are not necessary for small addons, but I would like to start building my house with the best foundations that I can afford 😉Thanks in advance!Ramón.
About patterns, I started developing plugins for NVDA when add-on
packages system didn't exist yet, in 2011 or so. Previously I had
developed JAWS scripts, even naming scripts with words in Spanish and
of course without using version controls. This work was saved
partially by a friend, but it's almost lost and not useful yet.
What I try to explain is that this topic is really great since, though
I love flexibility and not to be restricted by prefixed methods or
patterns, they can be useful, specially for future maintenance and
reviews, or if a project needs to be transfered to other maintainer.
I try to consider using SOLID principles for add-ons, and if I had
tried this before some bug probably was been avoided.
For example, recently I was informed privately about a duplicate
message in clipContentsDesigner add-on, and this was produced since a
function whose responsibility should be just to return some text
included a message, also provided in a script.
This guide explain SOLID:
https://www.freecodecamp.org/news/solid-principles-explained-in-plain-english/
2022-08-15 8:41 GMT+02:00, Akash Kakkar <akash.diverse@...>:
Hi Ramon,
I too was planning to get started with addon development and you asked
almost same questions as I was planning to ask.
Really thanks for this.
Joseph and Samuel,
Really thanks, your advice is quite good.
I have 1 more question though,
As Joseph said that he uses just Notepad++ for his addon development, so
I want to ask, that do you write everything by hand or rely on
autocompletion?
May be I'm missing something, but when I last checked, Auto completion
was not accessible in Notepad++
If you don't rely on Auto completion, then isn't too tedious and boring
to type everything by hand and verify everything to avoid syntax errors
or other linting errors?
I want to know that is there any way by which we can get proper and
robust auto completion support for addon development? I think that if we
install python extension in VS code and start developing, then we won't
get auto completion for NVDA related stuff, is it true?
Or is there any way to integrate VS Code/Visual Studio with NVDA's
source so that we can get code completion for NVDA related classes,
method, pydoc support etc?
1 More thing which I want to ask is:
Usually I code in ReactJS and C# .NET and I use architecture patterns,
for example MVVM for my Desktop based C# apps and MVC for web apps.
Do you guys follow any such pattern for your addons? If yes, then which?
Help will be very appreciated.
And really thanks for bringing this topic Ramon,
I think it will be very useful for everybody who so ever is planning to
start addon development in near future.
On 8/15/2022 11:45 AM, Samuel Kacer wrote:Hi Ramon,
welcome to the list.
I think for lots of the questions you will receive much of the same
answers, but I will tell you about what I do for my working directory,
since I am not sure if others also use this so I wanted to share .
I have a normal directory where I store the addon project in a special
workspace folder. So each addon is something like
C:\Users\Sam\workspace\<addon name>
I also use the scratchpad for testing the addon, but what I do is I
create symbollic links to the addon file from my project directory to
the scratchpad using the mklink command. This way I don't need to move
files back and forth between my scratchpad and project folder. I can
just edit my addon file, hit ctrl + S in VS code, and reload my
addons, test the change, and finally if all is good create a git
commit of the change.
Hope that helps. Other than that I would recommend VS code together
with the official python extension as well as pylance, especially if
you are blind yourself. For the most part, you will just want to learn
general programming and project management skills, which you can in
much bigger communities than ours. Definitely learn git and hot to use
versioning to your advantage. Having granular logical commits can make
understanding your code much easier and make it a hell of a lot easier
for tracking down a bug.
Anyway good luck and looking forward to seeing your progress :)
On Sun, Aug 14, 2022 at 11:19 PM Ramón Corominas
<ramon@...> wrote:
Hello everyone,
I'm new -writing- to this list, so firstly I will introduce
myself... My name is Ramón and I'm a freelance accessibility
consultant based in Asturias, north of Spain. I also do some
Python programming, and I'm starting to play with NVDA code and
Addons
For the moment I've developed some toy code and played with basic
functionalities, but I have some ideas for more complex
experiments and I would like to know your experiences developing
addons. Mostly how you plan, develop and debug your code,
especially for "big" addons. I've asked this before in the Spanish
lists and obtained very good answers and advice; now I finally
found the time for translating these questions to English and will
love to learn from this great community.
You'll see that there are many questions, I've tried to be
exhaustive and cover all the development process, but of course
feel fre to ignore my script and share any ideas that you consider
useful when developing addons / NVDA features.
1. What is your development environment setup?
- NVDA setup (installed, portable, source...). Do you consider
different development scenarios (for example, reverting NVDA
source to an older version)?
- Additional addons or other tools to help with debug...
- System Python installed, if any. Virtual environments?
- Code/markdown editor/IDE, linting, useful extensions,
automation...
2. Documentation
- Beyond directly reading NVDA's source code, do you use any
library/API references, guides, etc.?
- Any recommendations of books, blogs or other learning
resources? (better if they are especific to NVDA/Screen
readers/TTS,Braille, etc.)
3. Files, directories, code structure
- Apart from using the Addon Template, how do you organize
addon's code, modules/packages, public/private parts, functions,
classes, configurations...?
- Working directory: do you write code in a "draft" directory
or directly in the scratchpad directory? Is it safe to work in the
scratchpad if there are errors in the code, for example?
- Third-party dependencies: do you include their full code or
just the needed code (if possible), have you faced compatibility
issues with other addons? What about executables/DLLs/database
engines...?
- Version control: do you follow a "standardized" workflow or
methodology? do you have an issues/PR policy for contributing? Do
you use Github actions or automation?
4. Coding and debugging
- Do you use coding aids like autocompletion, linting, text
espansion, code suggestions/copilot...?
- How do you test and debug your code? How do you log or trace
variables/errors?
- Do you include tests in your code? Do you follow a
methodology like TDD or similar?
- Do you use Github Actions or similar to automate things like
basic PR checking, building of releases, etc.?
I know that most of the above questions are not necessary for
small addons, but I would like to start building my house with the
best foundations that I can afford 😉
Thanks in advance!
Ramón.
Hello:
About patterns, I started developing plugins for NVDA when add-on
packages system didn't exist yet, in 2011 or so. Previously I had
developed JAWS scripts, even naming scripts with words in Spanish and
of course without using version controls. This work was saved
partially by a friend, but it's almost lost and not useful yet.
What I try to explain is that this topic is really great since, though
I love flexibility and not to be restricted by prefixed methods or
patterns, they can be useful, specially for future maintenance and
reviews, or if a project needs to be transfered to other maintainer.
I try to consider using SOLID principles for add-ons, and if I had
tried this before some bug probably was been avoided.
For example, recently I was informed privately about a duplicate
message in clipContentsDesigner add-on, and this was produced since a
function whose responsibility should be just to return some text
included a message, also provided in a script.
This guide explain SOLID:
https://www.freecodecamp.org/news/solid-principles-explained-in-plain-english/
2022-08-15 8:41 GMT+02:00, Akash Kakkar <akash.diverse@...>:Hi Ramon,
I too was planning to get started with addon development and you asked
almost same questions as I was planning to ask.
Really thanks for this.
Joseph and Samuel,
Really thanks, your advice is quite good.
I have 1 more question though,
As Joseph said that he uses just Notepad++ for his addon development, so
I want to ask, that do you write everything by hand or rely on
autocompletion?
May be I'm missing something, but when I last checked, Auto completion
was not accessible in Notepad++
If you don't rely on Auto completion, then isn't too tedious and boring
to type everything by hand and verify everything to avoid syntax errors
or other linting errors?
I want to know that is there any way by which we can get proper and
robust auto completion support for addon development? I think that if we
install python extension in VS code and start developing, then we won't
get auto completion for NVDA related stuff, is it true?
Or is there any way to integrate VS Code/Visual Studio with NVDA's
source so that we can get code completion for NVDA related classes,
method, pydoc support etc?
1 More thing which I want to ask is:
Usually I code in ReactJS and C# .NET and I use architecture patterns,
for example MVVM for my Desktop based C# apps and MVC for web apps.
Do you guys follow any such pattern for your addons? If yes, then which?
Help will be very appreciated.
And really thanks for bringing this topic Ramon,
I think it will be very useful for everybody who so ever is planning to
start addon development in near future.
On 8/15/2022 11:45 AM, Samuel Kacer wrote:Hi Ramon,
welcome to the list.
I think for lots of the questions you will receive much of the same
answers, but I will tell you about what I do for my working directory,
since I am not sure if others also use this so I wanted to share .
I have a normal directory where I store the addon project in a special
workspace folder. So each addon is something like
C:\Users\Sam\workspace\<addon name>
I also use the scratchpad for testing the addon, but what I do is I
create symbollic links to the addon file from my project directory to
the scratchpad using the mklink command. This way I don't need to move
files back and forth between my scratchpad and project folder. I can
just edit my addon file, hit ctrl + S in VS code, and reload my
addons, test the change, and finally if all is good create a git
commit of the change.
Hope that helps. Other than that I would recommend VS code together
with the official python extension as well as pylance, especially if
you are blind yourself. For the most part, you will just want to learn
general programming and project management skills, which you can in
much bigger communities than ours. Definitely learn git and hot to use
versioning to your advantage. Having granular logical commits can make
understanding your code much easier and make it a hell of a lot easier
for tracking down a bug.
Anyway good luck and looking forward to seeing your progress :)
On Sun, Aug 14, 2022 at 11:19 PM Ramón Corominas
<ramon@...> wrote:
Hello everyone,
I'm new -writing- to this list, so firstly I will introduce
myself... My name is Ramón and I'm a freelance accessibility
consultant based in Asturias, north of Spain. I also do some
Python programming, and I'm starting to play with NVDA code and
Addons
For the moment I've developed some toy code and played with basic
functionalities, but I have some ideas for more complex
experiments and I would like to know your experiences developing
addons. Mostly how you plan, develop and debug your code,
especially for "big" addons. I've asked this before in the Spanish
lists and obtained very good answers and advice; now I finally
found the time for translating these questions to English and will
love to learn from this great community.
You'll see that there are many questions, I've tried to be
exhaustive and cover all the development process, but of course
feel fre to ignore my script and share any ideas that you consider
useful when developing addons / NVDA features.
1. What is your development environment setup?
- NVDA setup (installed, portable, source...). Do you consider
different development scenarios (for example, reverting NVDA
source to an older version)?
- Additional addons or other tools to help with debug...
- System Python installed, if any. Virtual environments?
- Code/markdown editor/IDE, linting, useful extensions,
automation...
2. Documentation
- Beyond directly reading NVDA's source code, do you use any
library/API references, guides, etc.?
- Any recommendations of books, blogs or other learning
resources? (better if they are especific to NVDA/Screen
readers/TTS,Braille, etc.)
3. Files, directories, code structure
- Apart from using the Addon Template, how do you organize
addon's code, modules/packages, public/private parts, functions,
classes, configurations...?
- Working directory: do you write code in a "draft" directory
or directly in the scratchpad directory? Is it safe to work in the
scratchpad if there are errors in the code, for example?
- Third-party dependencies: do you include their full code or
just the needed code (if possible), have you faced compatibility
issues with other addons? What about executables/DLLs/database
engines...?
- Version control: do you follow a "standardized" workflow or
methodology? do you have an issues/PR policy for contributing? Do
you use Github actions or automation?
4. Coding and debugging
- Do you use coding aids like autocompletion, linting, text
espansion, code suggestions/copilot...?
- How do you test and debug your code? How do you log or trace
variables/errors?
- Do you include tests in your code? Do you follow a
methodology like TDD or similar?
- Do you use Github Actions or similar to automate things like
basic PR checking, building of releases, etc.?
I know that most of the above questions are not necessary for
small addons, but I would like to start building my house with the
best foundations that I can afford 😉
Thanks in advance!
Ramón.
Hi,
I don’t use auto-complete in Notepad++ at all (I know that Derek’s Notepad++ add-on does support this feature).
As for looking up NVDA functions and classes, I use Python Console’s auto-complete feature, or if I need to, consult the screen reader source code directly.
Cheers,
Joseph
Sent: Sunday, August 14, 2022 11:42 PM
To: nvda-addons@nvda-addons.groups.io
Subject: Re: [nvda-addons] First steps in addon development
Hi Ramon,
I too was planning to get started with addon development and you asked almost same questions as I was planning to ask.
Really thanks for this.
Joseph and Samuel,
Really thanks, your advice is quite good.
I have 1 more question though,
As Joseph said that he uses just Notepad++ for his addon development, so I want to ask, that do you write everything by hand or rely on autocompletion?
May be I'm missing something, but when I last checked, Auto completion was not accessible in Notepad++
If you don't rely on Auto completion, then isn't too tedious and boring to type everything by hand and verify everything to avoid syntax errors or other linting errors?
I want to know that is there any way by which we can get proper and robust auto completion support for addon development? I think that if we install python extension in VS code and start developing, then we won't get auto completion for NVDA related stuff, is it true?
Or is there any way to integrate VS Code/Visual Studio with NVDA's source so that we can get code completion for NVDA related classes, method, pydoc support etc?
1 More thing which I want to ask is:
Usually I code in ReactJS and C# .NET and I use architecture patterns, for example MVVM for my Desktop based C# apps and MVC for web apps.
Do you guys follow any such pattern for your addons? If yes, then which?
Help will be very appreciated.
And really thanks for bringing this topic Ramon,
I think it will be very useful for everybody who so ever is planning to start addon development in near future.
On 8/15/2022 11:45 AM, Samuel Kacer wrote:
Hi Ramon,
welcome to the list.
I think for lots of the questions you will receive much of the same answers, but I will tell you about what I do for my working directory, since I am not sure if others also use this so I wanted to share .
I have a normal directory where I store the addon project in a special workspace folder. So each addon is something like C:\Users\Sam\workspace\<addon name>
I also use the scratchpad for testing the addon, but what I do is I create symbollic links to the addon file from my project directory to the scratchpad using the mklink command. This way I don't need to move files back and forth between my scratchpad and project folder. I can just edit my addon file, hit ctrl + S in VS code, and reload my addons, test the change, and finally if all is good create a git commit of the change.
Hope that helps. Other than that I would recommend VS code together with the official python extension as well as pylance, especially if you are blind yourself. For the most part, you will just want to learn general programming and project management skills, which you can in much bigger communities than ours. Definitely learn git and hot to use versioning to your advantage. Having granular logical commits can make understanding your code much easier and make it a hell of a lot easier for tracking down a bug.
Anyway good luck and looking forward to seeing your progress :)
On Sun, Aug 14, 2022 at 11:19 PM Ramón Corominas <ramon@...> wrote:
Hello everyone,
I'm new -writing- to this list, so firstly I will introduce myself... My name is Ramón and I'm a freelance accessibility consultant based in Asturias, north of Spain. I also do some Python programming, and I'm starting to play with NVDA code and Addons
For the moment I've developed some toy code and played with basic functionalities, but I have some ideas for more complex experiments and I would like to know your experiences developing addons. Mostly how you plan, develop and debug your code, especially for "big" addons. I've asked this before in the Spanish lists and obtained very good answers and advice; now I finally found the time for translating these questions to English and will love to learn from this great community.
You'll see that there are many questions, I've tried to be exhaustive and cover all the development process, but of course feel fre to ignore my script and share any ideas that you consider useful when developing addons / NVDA features.
1. What is your development environment setup?
- NVDA setup (installed, portable, source...). Do you consider different development scenarios (for example, reverting NVDA source to an older version)?
- Additional addons or other tools to help with debug...
- System Python installed, if any. Virtual environments?
- Code/markdown editor/IDE, linting, useful extensions, automation...
2. Documentation
- Beyond directly reading NVDA's source code, do you use any library/API references, guides, etc.?
- Any recommendations of books, blogs or other learning resources? (better if they are especific to NVDA/Screen readers/TTS,Braille, etc.)
3. Files, directories, code structure
- Apart from using the Addon Template, how do you organize addon's code, modules/packages, public/private parts, functions, classes, configurations...?
- Working directory: do you write code in a "draft" directory or directly in the scratchpad directory? Is it safe to work in the scratchpad if there are errors in the code, for example?
- Third-party dependencies: do you include their full code or just the needed code (if possible), have you faced compatibility issues with other addons? What about executables/DLLs/database engines...?
- Version control: do you follow a "standardized" workflow or methodology? do you have an issues/PR policy for contributing? Do you use Github actions or automation?
4. Coding and debugging
- Do you use coding aids like autocompletion, linting, text espansion, code suggestions/copilot...?
- How do you test and debug your code? How do you log or trace variables/errors?
- Do you include tests in your code? Do you follow a methodology like TDD or similar?
- Do you use Github Actions or similar to automate things like basic PR checking, building of releases, etc.?
I know that most of the above questions are not necessary for small addons, but I would like to start building my house with the best foundations that I can afford 😉
Thanks in advance!
Ramón.
From my part, I tried to use autocomplete function in Notepad++ with
Derek and Tuukka0s add-on, and also use VS Code, but generally this
results in confusions for me since it's needed to pay attention to
insert the right code. So generally I use Joseph's approach and prefer
Notepad++ instead of VS Code, except for .json files if I want to
search for problems.
2022-08-15 14:50 GMT+02:00, Joseph Lee <joseph.lee22590@...>:
Hi,
I don’t use auto-complete in Notepad++ at all (I know that Derek’s Notepad++
add-on does support this feature).
As for looking up NVDA functions and classes, I use Python Console’s
auto-complete feature, or if I need to, consult the screen reader source
code directly.
Cheers,
Joseph
From: nvda-addons@nvda-addons.groups.io <nvda-addons@nvda-addons.groups.io>
On Behalf Of Akash Kakkar
Sent: Sunday, August 14, 2022 11:42 PM
To: nvda-addons@nvda-addons.groups.io
Subject: Re: [nvda-addons] First steps in addon development
Hi Ramon,
I too was planning to get started with addon development and you asked
almost same questions as I was planning to ask.
Really thanks for this.
Joseph and Samuel,
Really thanks, your advice is quite good.
I have 1 more question though,
As Joseph said that he uses just Notepad++ for his addon development, so I
want to ask, that do you write everything by hand or rely on
autocompletion?
May be I'm missing something, but when I last checked, Auto completion was
not accessible in Notepad++
If you don't rely on Auto completion, then isn't too tedious and boring to
type everything by hand and verify everything to avoid syntax errors or
other linting errors?
I want to know that is there any way by which we can get proper and robust
auto completion support for addon development? I think that if we install
python extension in VS code and start developing, then we won't get auto
completion for NVDA related stuff, is it true?
Or is there any way to integrate VS Code/Visual Studio with NVDA's source so
that we can get code completion for NVDA related classes, method, pydoc
support etc?
1 More thing which I want to ask is:
Usually I code in ReactJS and C# .NET and I use architecture patterns, for
example MVVM for my Desktop based C# apps and MVC for web apps.
Do you guys follow any such pattern for your addons? If yes, then which?
Help will be very appreciated.
And really thanks for bringing this topic Ramon,
I think it will be very useful for everybody who so ever is planning to
start addon development in near future.
On 8/15/2022 11:45 AM, Samuel Kacer wrote:
Hi Ramon,
welcome to the list.
I think for lots of the questions you will receive much of the same answers,
but I will tell you about what I do for my working directory, since I am not
sure if others also use this so I wanted to share .
I have a normal directory where I store the addon project in a special
workspace folder. So each addon is something like
C:\Users\Sam\workspace\<addon name>
I also use the scratchpad for testing the addon, but what I do is I create
symbollic links to the addon file from my project directory to the
scratchpad using the mklink command. This way I don't need to move files
back and forth between my scratchpad and project folder. I can just edit my
addon file, hit ctrl + S in VS code, and reload my addons, test the change,
and finally if all is good create a git commit of the change.
Hope that helps. Other than that I would recommend VS code together with the
official python extension as well as pylance, especially if you are blind
yourself. For the most part, you will just want to learn general programming
and project management skills, which you can in much bigger communities than
ours. Definitely learn git and hot to use versioning to your advantage.
Having granular logical commits can make understanding your code much easier
and make it a hell of a lot easier for tracking down a bug.
Anyway good luck and looking forward to seeing your progress :)
On Sun, Aug 14, 2022 at 11:19 PM Ramón Corominas <ramon@...
<mailto:ramon@...> > wrote:
Hello everyone,
I'm new -writing- to this list, so firstly I will introduce myself... My
name is Ramón and I'm a freelance accessibility consultant based in
Asturias, north of Spain. I also do some Python programming, and I'm
starting to play with NVDA code and Addons
For the moment I've developed some toy code and played with basic
functionalities, but I have some ideas for more complex experiments and I
would like to know your experiences developing addons. Mostly how you plan,
develop and debug your code, especially for "big" addons. I've asked this
before in the Spanish lists and obtained very good answers and advice; now I
finally found the time for translating these questions to English and will
love to learn from this great community.
You'll see that there are many questions, I've tried to be exhaustive and
cover all the development process, but of course feel fre to ignore my
script and share any ideas that you consider useful when developing addons /
NVDA features.
1. What is your development environment setup?
- NVDA setup (installed, portable, source...). Do you consider different
development scenarios (for example, reverting NVDA source to an older
version)?
- Additional addons or other tools to help with debug...
- System Python installed, if any. Virtual environments?
- Code/markdown editor/IDE, linting, useful extensions, automation...
2. Documentation
- Beyond directly reading NVDA's source code, do you use any library/API
references, guides, etc.?
- Any recommendations of books, blogs or other learning resources?
(better if they are especific to NVDA/Screen readers/TTS,Braille, etc.)
3. Files, directories, code structure
- Apart from using the Addon Template, how do you organize addon's code,
modules/packages, public/private parts, functions, classes,
configurations...?
- Working directory: do you write code in a "draft" directory or
directly in the scratchpad directory? Is it safe to work in the scratchpad
if there are errors in the code, for example?
- Third-party dependencies: do you include their full code or just the
needed code (if possible), have you faced compatibility issues with other
addons? What about executables/DLLs/database engines...?
- Version control: do you follow a "standardized" workflow or
methodology? do you have an issues/PR policy for contributing? Do you use
Github actions or automation?
4. Coding and debugging
- Do you use coding aids like autocompletion, linting, text espansion,
code suggestions/copilot...?
- How do you test and debug your code? How do you log or trace
variables/errors?
- Do you include tests in your code? Do you follow a methodology like
TDD or similar?
- Do you use Github Actions or similar to automate things like basic PR
checking, building of releases, etc.?
I know that most of the above questions are not necessary for small addons,
but I would like to start building my house with the best foundations that I
can afford 😉
Thanks in advance!
Ramón.
No IDE, just Notepad++ & command-line toolsWell, I'm now in my transition to using VSCode as my primary editor after years of coding using Ultraedit and I'm interested in any experiences with different editors. I tried Notepad++ some time ago but I had some accessibility problems with it, maybe I can give it a second chance...
I keep latest versions of various NVDA development builds (channels)so I can replicate user environments.
Could you please elaborate this? I'm not sure of having understood it. Anyway, I assume this is because some of your addons are somwhat complex or interact with the system and you need to test them very well, isn't it?
I use what I wrote initially – NVDA add-on development guideYes, I've read that and it's great for understanding the basics of how NVDA addons work . Regarding that guide, I'm curious about the remote python console that is mentioned in the last part of that guide... Do you know how it works? I've managed to launch it and I see that the port is listening, but I don't know how to connect to it to send python commands and obtain the results, if possible.
I disassemble Python bytecode as part of optimization work from timeto time (a topic that requires a dedicated thread to discuss as it is quite advanced).
I didn't know that this was even possible... It would be great if you could elaborate a bit more, I'm now intrigued 😉
NVDA screen reader development setup, complete with Visual Studio2022 Community ...
You mentioned that for editing code you use Notepad++, I suppose you use Visual Studio Community just for builds and not for coding, isn't it?
Flake8 (linter)Is this a command-line tool? I've seen some settings in VSCode to use flake8, but I don't have much experience with linters and I guess that it will need some setup. Is there a particular setup for NVDA's code?
Here are four example add-ons to showcase them:Thank you very much for these examples, they will be great for my learning. I also did a quick read of your articles about specific addons you developed and I'm sure I will learn a lot from them! ☺
I also include type hints, lint results, and lots of source codecomments.
I also try to use type hints, but sometimes I find it difficult to define the arguments' types when they are not native or accept multiple types, any hints on type hints will be appreciated 😉. I don't know what are those "lint results", could you please elaborate on this?
As for my add-on development methodology, I tend to follow agile,iterative development method
Hopefully I'll understand agile... Someday... 😂
1. Read and write a lotAlthough I'm not new to programming, I am a complete newbie to NVDA's code and I think these are three of the best tips on programming that I've ever received! In particular, the second one is a very good reminder, everytime I learn something new I feel so excited that tend to explode on ideas for "solving" everything 😂
2. Have clear and reasonable set of goals
3. Test and test again
learn to remove color from pictures.Great tip, too, as developers we tend to forget that we are working for users and that we need to know how they will use our apps... Thanks!
Cheers,
Ramón.
what I do is I create symbollic links to the addon file from myproject directory to the scratchpad using the mklink command. This way I don't need to move files back and forth between my scratchpad and project folder
Good idea, I was using some symlinks as "shortcuts" to quickly access my working directories, but didn't realize that they could also work this way, thanks!
good luck and looking forward to seeing your progress :)Thanks! I'm learning a lot and hope to start contributing soon, although it will bbe after my holidays, which are starting next weekend! 😉
Cheers,
Ramón.
On Sun, Aug 14, 2022 at 11:19 PM Ramón Corominas <ramon@...> wrote:
Hello everyone,
I'm new -writing- to this list, so firstly I will introduce myself... My name is Ramón and I'm a freelance accessibility consultant based in Asturias, north of Spain. I also do some Python programming, and I'm starting to play with NVDA code and Addons
For the moment I've developed some toy code and played with basic functionalities, but I have some ideas for more complex experiments and I would like to know your experiences developing addons. Mostly how you plan, develop and debug your code, especially for "big" addons. I've asked this before in the Spanish lists and obtained very good answers and advice; now I finally found the time for translating these questions to English and will love to learn from this great community.
You'll see that there are many questions, I've tried to be exhaustive and cover all the development process, but of course feel fre to ignore my script and share any ideas that you consider useful when developing addons / NVDA features.
1. What is your development environment setup?
- NVDA setup (installed, portable, source...). Do you consider different development scenarios (for example, reverting NVDA source to an older version)?
- Additional addons or other tools to help with debug...
- System Python installed, if any. Virtual environments?
- Code/markdown editor/IDE, linting, useful extensions, automation...
2. Documentation
- Beyond directly reading NVDA's source code, do you use any library/API references, guides, etc.?
- Any recommendations of books, blogs or other learning resources? (better if they are especific to NVDA/Screen readers/TTS,Braille, etc.)
3. Files, directories, code structure
- Apart from using the Addon Template, how do you organize addon's code, modules/packages, public/private parts, functions, classes, configurations...?
- Working directory: do you write code in a "draft" directory or directly in the scratchpad directory? Is it safe to work in the scratchpad if there are errors in the code, for example?
- Third-party dependencies: do you include their full code or just the needed code (if possible), have you faced compatibility issues with other addons? What about executables/DLLs/database engines...?
- Version control: do you follow a "standardized" workflow or methodology? do you have an issues/PR policy for contributing? Do you use Github actions or automation?
4. Coding and debugging
- Do you use coding aids like autocompletion, linting, text espansion, code suggestions/copilot...?
- How do you test and debug your code? How do you log or trace variables/errors?
- Do you include tests in your code? Do you follow a methodology like TDD or similar?
- Do you use Github Actions or similar to automate things like basic PR checking, building of releases, etc.?
I know that most of the above questions are not necessary for small addons, but I would like to start building my house with the best foundations that I can afford 😉
Thanks in advance!
Ramón.
NVDA versions and user environments: while I have NVDA alpha builds installed on my computer, I have several portable copies designed to test add-ons under beta, stable, and portable alpha releases.
As for code disassembly, don't do it as part of the first add-on. Only if you really wish to know the internals of Python execution model and/or need to optimize add-ons for size and/or speed should you learn about the "dis" module.
Regarding lint results, mostly comments and/or trying to keep statements under line length limit (110 characters per line if using NVDA's lint configuration).
Type hints are useful (you may come across these while looking at NVDA source code), and more so as running tools such as Mypy will find bugs after annotating code with component from typing module.
As for the add-on development guide: I think you might be thinking about NVDA's own development guide. The one I'm talking about is:
https://github.com/nvdaaddons/DevGuide/wiki/NVDA-Add-on-Development-Guide
Cheers,
Joseph
From: nvda-addons@nvda-addons.groups.io <nvda-addons@nvda-addons.groups.io> On Behalf Of Ramón Corominas
Sent: Monday, August 15, 2022 7:19 AM
To: nvda-addons@nvda-addons.groups.io
Subject: Re: [nvda-addons] First steps in addon development
Hi Joseph, thank you very much for your quick and detailed answer!
> No IDE, just Notepad++ & command-line tools
Well, I'm now in my transition to using VSCode as my primary editor after years of coding using Ultraedit and I'm interested in any experiences with different editors. I tried Notepad++ some time ago but I had some accessibility problems with it, maybe I can give it a second chance...
> I keep latest versions of various NVDA development builds (channels) so I can replicate user environments.
Could you please elaborate this? I'm not sure of having understood it.
Anyway, I assume this is because some of your addons are somwhat complex or interact with the system and you need to test them very well, isn't it?
> I use what I wrote initially – NVDA add-on development guide
Yes, I've read that and it's great for understanding the basics of how
NVDA addons work . Regarding that guide, I'm curious about the remote
python console that is mentioned in the last part of that guide... Do
you know how it works? I've managed to launch it and I see that the port
is listening, but I don't know how to connect to it to send python
commands and obtain the results, if possible.
> I disassemble Python bytecode as part of optimization work from time
to time (a topic that requires a dedicated thread to discuss as it is
quite advanced).
I didn't know that this was even possible... It would be great if you
could elaborate a bit more, I'm now intrigued 😉
> NVDA screen reader development setup, complete with Visual Studio
2022 Community ...
You mentioned that for editing code you use Notepad++, I suppose you use
Visual Studio Community just for builds and not for coding, isn't it?
> Flake8 (linter)
Is this a command-line tool? I've seen some settings in VSCode to use
flake8, but I don't have much experience with linters and I guess that
it will need some setup. Is there a particular setup for NVDA's code?
> Here are four example add-ons to showcase them:
Thank you very much for these examples, they will be great for my
learning. I also did a quick read of your articles about specific addons
you developed and I'm sure I will learn a lot from them! ☺
> I also include type hints, lint results, and lots of source code
comments.
I also try to use type hints, but sometimes I find it difficult to
define the arguments' types when they are not native or accept multiple
types, any hints on type hints will be appreciated 😉. I don't know what
are those "lint results", could you please elaborate on this?
> As for my add-on development methodology, I tend to follow agile,
iterative development method
Hopefully I'll understand agile... Someday... 😂
> 1. Read and write a lot
> 2. Have clear and reasonable set of goals
> 3. Test and test again
Although I'm not new to programming, I am a complete newbie to NVDA's
code and I think these are three of the best tips on programming that
I've ever received! In particular, the second one is a very good
reminder, everytime I learn something new I feel so excited that tend to
explode on ideas for "solving" everything 😂
> learn to remove color from pictures.
Great tip, too, as developers we tend to forget that we are working for
users and that we need to know how they will use our apps... Thanks!
Cheers,
Ramón.
Regarding autocompletion, I'm getting used to it in VSCode and I find it really useful, especially if the programmer has included type hints and docstrings. It was certainly confusing at the beginning, but with time and patience I'm now more or less confident using it. Nevertheless, I still have to fix its results sometimes, but using Control+shift+M to detect syntax errors is usually enough to solve them.
As for the NVDA's code autocompletion, you can achieve it if you work directly with the NVDA's source code, as Joseph mentioned. I had some trouble building it due to missing dependencies in Visual Studio, but I think you don't need to build anything to obtain the advantages of autocompletion.
Cheers!
Ramón.
Appreciate it
Hi Akash, thank you for your message, I'm happy to know that there are others walking this way with me ☺
Regarding autocompletion, I'm getting used to it in VSCode and I find it really useful, especially if the programmer has included type hints and docstrings. It was certainly confusing at the beginning, but with time and patience I'm now more or less confident using it. Nevertheless, I still have to fix its results sometimes, but using Control+shift+M to detect syntax errors is usually enough to solve them.
As for the NVDA's code autocompletion, you can achieve it if you work directly with the NVDA's source code, as Joseph mentioned. I had some trouble building it due to missing dependencies in Visual Studio, but I think you don't need to build anything to obtain the advantages of autocompletion.
Cheers!
Ramón.