Installation Guide
Before you can use Scout, you’ll need to install a few things that Scout relies upon to run. Preparing for and using Scout requires interacting a bit with the command line, but these instructions will walk through each step in the set up process with the specific commands required. While the basic prerequisites are the same for Mac and Windows users, because the details and order of the steps are somewhat different, separate instructions are provided. Before beginning, you’ll need to be using a computer where you have administrator-level privileges so that you can install new software. The first step is to download or clone the latest version of Scout to a local directory.
If you’re comfortable at the command line, install or set up everything in this list of prerequisites and then skip straight to step 2 of the Quick Start Guide.
Prerequisites
Python 3
Scout Python package:
pip install .from your Scout install directoryA text editor of your choice
The installation instructions for Mac and Windows assume that none of these prerequisite programs or distributions are installed on your system. Please follow the instructions as appropriate, given what might already installed on your system and checking for updates if appropriate.
Warning
Please use due care and take appropriate security precautions to ensure that your system is not compromised when installing the programs and distributions identified below. It is your responsibility to protect the integrity of your system. Caveat utilitor.
Mac OS
0. (Optional) Install a package manager
The Mac OS ships with Python already installed. Installing and using a package manager will make it easy to ensure that any additional installations of Python do not interfere with the version of Python included with the operating system. Homebrew is a popular package manager, but there are other options, such as MacPorts and Fink.
Note
While this step is optional, subsequent instructions are written with the assumption that you have installed Homebrew as your package manager.
To install Homebrew, open Terminal (found in Applications/Utilities, or trigger Spotlight with ⌘-space and type “Terminal”). Visit the Homebrew website and copy the installation command text on the page. Paste the text into the Terminal application window and press Return. If you encounter problems with the installation, return to the Homebrew website for help or search online for troubleshooting assistance.
If you are using a package manager other than Homebrew, follow the documentation for that package manager to install Python 3. If you have chosen to not install a package manager, you may use the Python Software Foundation installer for the latest version of Python 3.
1. Install Python 3
In a Terminal window, at the command prompt (a line terminated with a $ character and a flashing cursor), type:
brew install python3
2. Install Scout Python package
Once Python 3 is fully installed, pip3 [1] is the tool you will use to install add-ons specific to Python 3. We recommend using a virtual environment, such as venv, vitualenv, or conda to run Scout. Create and activate an environment and run the following from your Scout installation directory to install the Scout package:
pip3 install .
Note
For developers: if you intend on editing files within the Scout package directory, such as scout/supporting_data or .py modules, run pip3 install -e ".[dev]" to install in editable mode with developer depedendencies.
The Python packages Scout needs are listed under “dependencies” in the pyproject.toml file. If you’d like to confirm that the dependencies were installed successfully, you can run the command below to review the dependencies installed to your environment.
pip3 list
3. Install a text editor
A third-party text editor will make it easier to change Scout files. There are many different text editors available for the Mac. Mac OS X ships with two command line interface editors, vim and emacs. You may use one of these or install and use another graphical or command line interface editor of your choice. Whatever editor you choose should have support for syntax-specific code coloring and syntax-specific formatting and there should be linting for Python and JSON built-in or available through add-on packages. Python code linting should include checking for compliance with PEP 8 (using the pycodestyle package) and pyflakes, at a minimum.
For the purposes of this documentation, the following instructions will step through how to install Sublime Text, an easy to use text editor with a graphical interface that can be configured to satisfy the specified requirements. These instructions are provided to illustrate the steps required to configure a text editor for viewing and modifying Python and JSON files and should not be construed as an endorsement or promotion of Sublime Text.
1. Download Sublime Text
To set up Sublime Text for working with Scout, download Sublime Text 4, open the downloaded disk image, and drag the application file to the Applications folder using the shortcut provided.
After installing Sublime Text, there are several additional configuration steps that will help get the editor ready for viewing and editing Python and JSON files.
2. Install Package Control
First, open Sublime Text and, following the directions provided by the developer, install Package Control.
Once installed, Package Control is opened via the Command Palette (Tools > Command Palette or ⌘⌥P). Begin typing “Package Control” into the Command Palette. If a list of options beginning with “Package Control” appear, then the installation was successful. If not, refer back to the Package Control website for troubleshooting help.
We will use Package Control to install the additional features needed for checking Python files.
3. Install SublimeLinter prerequisites
Before proceeding further, open a Terminal window and at the command prompt, use pip3 to install the pycodestyle and pyflakes packages:
pip3 install pycodestyle
pip3 install pyflakes
4. Install SublimeLinter
Return to Sublime Text and open Package Control using the Command Palette (Tools > Command Palette or ⌘⌥P). Begin typing “Package Control: Install Package” in the Command Palette and click that option once it appears in the list. (Arrow keys can also be used to move up and down in the list.) In the search field that appears, begin typing “SublimeLinter” and click the package when it appears in the list to install the package. If installation was successful for this (or any other) package, the package name will appear in the Preferences > Package Settings sub-menu.
5. Install specific code linters
Open the Command Palette and select “Package Control: Install Package” again to install new packages following the same steps. Install the “SublimeLinter-pycodestyle,” “SublimeLinter-json,” and “SublimeLinter-pyflakes” packages.
6. Configure Python syntax-specific preferences
Finally, the Python-specific settings for Sublime Text need to be updated. Open a new file in Sublime Text and save it with the file name asdf.py. (asdf.py will be deleted later.) Open the Python syntax-specific settings (Sublime Text > Preferences > Settings – Syntax Specific) and between the braces, paste:
"spell_check": true,
"tab_size": 4,
"translate_tabs_to_spaces": true,
"rulers": [80]
Save the modified file and close the window. Once complete, delete asdf.py.
Quit and reopen Sublime Text to apply all of the settings changes and new packages that have been installed.
Windows
0. Determine whether you have 32-bit or 64-bit Windows installed
Some of the software prerequisites for Scout have different versions for 32-bit and 64-bit installations of Windows. If you are unsure of whether your computer is running 32-bit or 64-bit Windows, you can follow these instructions from Microsoft to find out.
1. Install Python 3
Tip
If you have 64-bit Windows installed on your computer, downloading and installing the 64-bit version of Python is recommended.
Download the executable installer for Windows available on the Python Software Foundation downloads page. Run the installer and follow the on-screen prompts as you would with any other software installer. Be sure that the option in the installer “Add Python 3.x to PATH,” where x denotes the current version of Python 3, is checked.
2. Install Scout Python package
Once Python 3 installation is complete, the Scout package and its dependencies can be installed. pip [1] is the tool you will use to install add-ons specific to Python 3. Begin by opening a command prompt window. We recommend using a virtual environment, such as venv, vitualenv, or conda to run Scout. Create and activate an environment and run the following from your Scout installation directory to install the Scout package:
py -3 -m pip install .
Note
For developers: if you intend on editing files within the Scout package directory, such as scout/supporting_data or .py modules, run py -3 -m pip install -e ".[dev]" to install in editable mode with developer depedendencies.
The Python packages Scout needs are listed under “dependencies” in the pyproject.toml file. If you’d like to confirm that the dependencies were installed successfully, you can run the command below to review the dependencies installed to your environment.
py -3 -m pip list
3. Install a text editor
While Windows comes with a plain text editor, Notepad, there are many different text editors available for Windows that will make it much easier to view and change Scout files. You are welcome to use the editor of your choice, but whatever you choose should have support for syntax-specific code coloring and syntax-specific formatting and there should be linting for Python and JSON built-in or available through add-on packages. Python code linting should include checking for compliance with PEP 8 (using the pycodestyle package) and pyflakes, at a minimum.
Sublime Text is an easy to use cross-platform text editor that can be configured to have the necessary features for authoring Python and JSON files. The following instructions are provided to illustrate the steps required to configure a text editor for viewing and modifying Python and JSON files and should not be construed as an endorsement or promotion of Sublime Text.
1. Install Sublime Text
To set up Sublime Text for working with Scout, download Sublime Text 4 and run the installer. The installer will automatically place the application and supporting files in the appropriate locations on your system.
After installing Sublime Text, there are several additional configuration steps that will help get the editor ready for viewing and editing Python and JSON files.
2. Install Package Control
First, open Sublime Text and, following the directions provided by the developer, install Package Control.
Once installed, Package Control is opened via the Command Palette (Tools > Command Palette or Ctrl+Shift+P). Begin typing “Package Control” into the Command Palette. If a list of options beginning with “Package Control” appear, then the installation was successful. If not, refer back to the Package Control website for troubleshooting help.
We will use Package Control to install the additional features needed for checking Python files.
3. Install SublimeLinter prerequisites
Before proceeding further, open a command prompt window and type the following commands to use pip to install the pycodestyle and pyflakes packages:
py -3 -m pip install pycodestyle
py -3 -m pip install pyflakes
Once you have
4. Install SublimeLinter
Return to Sublime Text and open Package Control using the Command Palette (Tools > Command Palette or Ctrl+Shift+P). Begin typing “Package Control: Install Package” in the Command Palette and click that option once it appears in the list. (Arrow keys can also be used to move up and down in the list.) In the search field that appears, begin typing “SublimeLinter” and click the package name when it appears in the list to install the package. If installation was successful for this (or any other) package, the package name will appear in Preferences > Package Settings.
5. Install specific code linters
Open the Command Palette and select “Package Control: Install Package” again to install new packages following the same steps. Install the “SublimeLinter-pycodestyle,” “SublimeLinter-json,” and “SublimeLinter-pyflakes” packages.
6. Configure Python syntax-specific preferences
Finally, the Python-specific settings for Sublime Text need to be updated. Open a new file in Sublime Text and save it with the file name asdf.py. (asdf.py will be deleted later.) Open the Python syntax-specific settings (Preferences > Settings – Syntax Specific) and between the braces, paste:
"spell_check": true,
"tab_size": 4,
"translate_tabs_to_spaces": true,
"rulers": [80]
Save the modified file and close the window, then delete asdf.py.
Quit and reopen Sublime Text to apply all of the settings changes and new packages that have been installed.
Footnotes