Running your first script

Now that we have WbW installed, it's time to start using it. Create a new Python file called wbw_test.py and type the following script into the file.

wbw_test.py

import whitebox_workflows as wbw

wbe = wbw.WbEnvironment()

print(wbe.version())

Notice the underscore in the WbW library name whitebox_workflows compared with the hyphen used in the pip package name whitebox-workflows.

This above script does a few things. First, it imports the whitebox_workflows library and gives it the shorter alias wbw. Next, we set up the Whitebox Environment, WbEnvrionment, which is one of the most important classes contained within the whitebox_workflows module. It's the class that is used to manipulate environmental settings, e.g. setting the current working directory. Importantly, all of the tools for processing spatial data are methods of the WbEnvironment class. Lastly, the version() method is called, printing information about our installed version of WbW.

When you run the above script, it should print something similar to this:

License activated for Trial License - Whitebox Workflows for Python. There are 0
seats remaining in the key. Please enjoy!

You can use Whitebox Workflows for Python for free over the next 3 days. After
that, you will need to purchase a license from
https://www.whiteboxgeo.com/whitebox-workflows-for-python/. Annual licenses are
about $10+tax.

The license for "Trial License - Whitebox Workflows for Python" will expire in 3
days. Please visit www.whiteboxgeo.com, or contact Whitebox Geospatial Inc. at
support@whiteboxgeo.com, to renew your license.

Whitebox Workflows for Python v0.9.8 by Whitebox Geospatial Inc. 
Developed by Dr. John B. Lindsay, (c) 2022

Description:
Whitebox Workflows for Python is an advanced geospatial data analysis platform 
and Python extension module.

That is a lot of information, so let's break it down. Because this is the first time that we've run WbW, the library looks for a valid license for the software. Finding no license, it activates a 3-day free trial license. After it installed the trial license, the script then continued to print the versioning information of our installed WbW. Between issuing the trial license and printing the versioning information, the script output the statement The license for "Trial License - Whitebox Workflows for Python" will expire in.... This warning reminds you that your license is soon to expire and that you should update. If the script runs without error, we can be assured that WbW has been installed correctly on our system.

Floating Licenses vs. Node-locked Licenses

A purchase of WbW comes with an equal number of node-locked and floating licenses. For example, if you've purchased two seats, you will be able to register two node-locked licenses on two computers, but you will also be able to check-out two silmutaneous floating licenses at any time from any computer.

The code above uses a node-locked WbW license, i.e., the license is tied to the machine that it was registered on. Sometimes, you will want to use WbW in other computing environments, e.g. on different computers within a network, or on cloud-based computing platforms like Google Colab. When this is the case, you need to use a floating license. If you've purchased a WbW license (and you aren't using a trial license), then you will have been provided a floating license ID in an email that was sent to you after registering your license activation code.

Your floating-license user ID is unique to you and you should keep this string private. Sharing your user ID with other people will result in the early termination of your license.

If you would instead like to use your floating license, simply provide your floating-license user ID as a parameter in the wbw.WbEnvironment() constructor, e.g. wbw.WbEnvironment('white-bolting-camel'). Here's an example of a script using a floating license:

wbw_test_floating_license.py

import whitebox_workflows as wbw

wbe = wbw.WbEnvironment('your-license-id')
try:
    print(wbe.version())
except Exception as e:
  print("The error raised is: ", e)
finally:
    print(wbe.check_in_license('your-license-id')) # print to confirm the successful check-in

A note on checking-in your license: Because the floating license uses a Check-out/Check-in model, you must remember to check-in your license after you have completed processing your script. The last thing you do in each script, therefore, should be to call the WbEnvironment.check_in_license method.

When we specify our floating-license user ID in the WbEnvironment initializer in the script above, the program, when run, will communicate with the Whitebox Geospatial Inc. remote license server web app. It will check to see if there is an available seat associated with the specified user ID. Importantly, while your script is running, and until you check-in your license, it will not be available for use again. This means that it is very important that the last thing you successfully check-in the license at the end of the script, which is why we call check_in_license within the finally block of a try-finally construct in the script above. This way, if the script throws an error, we can still be sure that the license will be checked back in and we'll be able to use it again in the future.

If all of the existing 'seats' of a license are unavailable because they are either in use, or haven't yet been checked back in, you will receive an error indicating that 'All floating licenses are currently in use'. The number of 'users' that you specified when you purchased your WbW license will indicate how many silmutaneous floating license seats you have to work with.

Sometimes a script may panic, which is an unrecoverable type of error. This happens for example, if you provide an unexpected input parameter to a function. When this is the case, our checked-out license may not be checked back in correctly. What do we do in this case? Well, after a certain amount of time (usually two hours), an un-checked-in license will be returned to the pool of available licenses. But, of course, that leaves us in a difficult situation for those hours wihtout being able to run further WbW scripts. When this occurs, we can call the check_in_license function associated directly with the whitebox_workflows module, i.e. whitebox_workflows.check_in_license('your-license-id'). Note, you should always prefer using WbEnvironment.check_in_license('your-license-id) over whitebox_workflows.check_in_license('your-license-id') because the latter will throw an error if there is no unchecked-in license to check-in. However, in the event that a script panic results in a 'zombie' floating license seat, this method is a usable solution to get you up-and-running with WbW geoprocessing once again.

import whitebox_workflows as wbw

print(wbw.check_in_license('your-license-id')) # print to confirm the successful check-in