Skip to content

Latest commit

 

History

History
112 lines (71 loc) · 5.85 KB

DEVELOPMENT_SETUP.adoc

File metadata and controls

112 lines (71 loc) · 5.85 KB
Raw

Notes on Setting Up a Development Environment

The Makefile

This project has a makefile. With it, several tasks are automated:

  • Setting up a virtual environment (.venv)

  • Installing all required modules (into that .venv)

  • Running all of the unit tests

  • Standardizing all of the .py code (format, import order, and de-linting)

  • Preparing for a new release

Note
 Again, this library was developed on Windows 10. Thus, the makefile uses DOS commands, not bash. Just be aware (and feel free to contribute an alternate makefile).

Installing Make (Windows)

The make command is standard with linux, but it must be manually installed in Windows.

  1. Download the "Complete package, except sources" (Setup) from http://gnuwin32.sourceforge.net/packages/make.htm. (Yes, it hasn’t needed any updates since 25 November 2006 — version 3.81. That’s the one.)

  2. Run the installer with all of the default settings.

  3. Open a command terminal and type make --version to ensure that it’s in the path.

Using Make

To invoke make from the command prompt, type make -f name-of-the-makefile goal. If the makefile name is makefile, which it is in this case, then you can just say make goal. If you do not specify a specific goal (just make), then the default goal will be targeted. In our case, the default goal is help, which lists all of the other goals available (according to this file: /doc_technical/makefile_help.txt)

Note
 In the case of make examples, there is currently only one example, automate_notepad_control_panel.py, so that is what will run. In the future, there will be a table-of-contents app that, in turn, runs the examples.

Installing the GruntWurk Core for Python Source Code

Instead of the normal pip install gwpycore, do this:

  1. Fork this GitHub repository.

  2. Clone it to your hard drive.

python38 -m pip install -e /path/to/gwpycore

The advantage of using the -e flag is that any changes that you make to your copy of the gwpycore source are directly available to your projects that use gwpycore.

Installing Visual Studio Code (Windows, Mac OS, or Linux), If Desired

Microsoft Visual Studio Code (we’ll call it "VSCode" from now on) is a free IDE (integrated development environment) that runs on Windows, Mac OS, and Linux.

Note
 "Visual Studio Code" is different than full-fledged "Visual Studio." VSCode is slimmed down. You can work on Python code in either, but VSCode is preferred.
Note
 At some point after getting started, be sure to see /doc_technical/VSCODE_TIPS.adoc.

Official documentation on editing Python with VSCode is at: https://code.visualstudio.com/docs/languages/python. Here is a bare-bones summary:

  1. Install Python, if not already. (TIP: The Python installer defaults to placing it in your user-folder’s appdata subfolder. You’ll save yourself a world of hurt if you change it to something simpler, e.g. C:\Python38).

  2. Download VSCode from https://code.visualstudio.com/ and install.

  3. In the Welcome tab…​

  4. Under Help, click on "Printable keyboard cheatsheet" and print it.

  5. Under Customize, click on "Tools and Languages"

  6. Select Python and click Install.

  7. Open the Command Palette (Ctrl-Shift-P) and type "py" to jump down to the Python commands. Scroll down to "Python: Select Interpreter" and hit enter. It will take a second to find all versions of Python installed on your machine. Select the one you want to use. (If there is only one, it will automatically select it for you.)

  8. Unit Testing for Python in VSCode is disabled by default. To enable testing, open the Command Palette and use "Python: Configure Tests". (We recommend selecting the PyTest framework for new projects.) Then, tell it that the unit tests are in the "tests" folder.

  9. Open the Command Palette (Ctrl-Shift-P) and type "pref" to jump down to the preferences. Scroll down to "Preferences: Configure Language Specific Settings" and hit enter. Select Python. This will open your settings.json file and add a [Python] section. Start typing "indent" until editor.detectIndentation is selected. Hit enter. From now on, when you open a file in VSCode, it will scan to see if the file uses tabs or spaces and then continue in whatever style it finds.

Using Visual Studio Code with GruntWurk Core for Python

  1. To open the GruntWurk Core for Python project, use File | Open Folder and select the root folder for the project (where you cloned it to).

  2. To run the examples, open any of the .py scripts in the examples folder and click the run button (Ctrl-Shift-D).

  3. The first time you open the Run view, it will suggest that you "create a launch.json file." Go ahead and click on that suggestion. Select Python, then select "Python: Current File." A tab will open up with a 14 line default configuration. Just save it as is and close the tab.

  4. To actually run the program, click on the green "play" button.

  5. The first time you run a Python program, VSCode will prompt you to install Linter. Go ahead and install it.

Running the Unit Tests (assuming pytest)

PyUnit is the original unit testing library that’s part of Python, but PyTest is more advanced and simpler to use.

pip install pytest

Running all of the unit tests from the command line:

pytest

Running a specific unit test from the command line:

pytest tests/test_x.py

Running the unit tests from within Visual Studio Code (VSCode):

  1. (The VSCode install instructions above include how to configure it for PyTest.)

  2. Click on the flask icon (far left) to bring up the Test Explorer.

  3. Click on the circular arrow (refresh) icon at the top to discover all of the tests.

  4. Click on the green double-play icon at the top to run all of the tests.

  5. Or, navigate to a particular test and click the green play icon to the right of it.

See the PyTest documentation for how to write the tests: https://docs.pytest.org/en/latest/

Next Topic: VSCode Tips