Allplan Python Environment

All the following information is not required if you just want to use the allpy package, which hopefully has an usable installer! But if you want to write your own PythonParts this Information may be of interest for you. This section shows my personal experience I gathered by writing the allpy package and as time goes by, they may be not true anymore!

The Python Environment provided by Allplan is only determined to run PythonParts inside of Allplan, if you launch the Python interpreter in PRG\Python, you get an error message about the missing python35.dll which is located in the parent PRG folder. You can run the Allplan Python interpreter if you copy the python35.dll into the folder of python35.exe.

But this is not the only problem, the Allplan Python interpreter started inside of Allplan strips the sys.path (locations where to search for additional modules and packages), especially the user’s site-packages folder will be removed, if you want to use “pip” to install packages from Python Package Index (PyPI), you can only install this packages into the Allplan site-packages directory (PRG\Python\lib\site-packages), which is in the write protected program installation path. This requires to run the Allplan Python interpreter within a command shell with admin rigthts.

This were the point I choose not to touch the Allplan Python Environment at all and it is nevertheless possible to add your own packages and also using “pip” to install packages from PyPI.

Installing Python 3.5 64-bit

Install a regular Python 3.5 64-bit Environment from www.Python.org.

At the time of writing this document (25.12.2016) Python 3.6 was just released, but you have to use same Python version as provided by your Allplan release to use the Allplan libs in your development environment to run/test your PythonParts outside of the Allplan environment:

• Allplan 2016: has an older API, with less features, don’t use it for PythonPart development
• Allplan 2017: Windows x86-64 Python 3.5 installer
• Later versions of Allplan may have other requirements, I will try to keep this list updated.

Learn Python!

Python is for much more useful than just PythonParts, so learn Python the proper way, read some (free) books:

• Free books linked at OnlineProgrammingBooks.com (english)
• Free books linked at Python.org (english)
• Free books linked at Python.org (german)

Extending Allplan Python

The strategy is to extend the sys.path at runtime, because I don’t know how to add paths permanently to the Allplan Python environment (Status 25.12.2016), and Allplan removes some standard search paths from sys.path, I decided to use a special python module exendsyspath.py, located in one of the Allplan Python standard search paths: STD\PythonPartsScripts (ETC\PythonPartsScripts would also work), from this location it is available from all PythonParts launched by the Allplan application.

Extending sys.path the Awkward Way

The module exendsyspath.py is simple:

import sys

PATHS = [
    # replace <username> with your user name, this is the location of
    # the user's site packages, so every package installed with
    # 'py -m pip install --user <packagename>' is available inside of Allplan
    r"C:\users\<username>\AppData\Python\Python35\site-packages",
    # I would not recommend to add the system wide site-packages directory

    # location of my allpy package in development status
    r"D:\Source\PythonParts",
]

for path in PATHS:
    if path not in sys.path:
        print("Extending sys.path: {}".format(path))
        sys.path.append(path)

In the main PythonPartsScript you just have to import this module:

try:
    import extendsyspath
except ImportError:
    print('Module extendsyspath.py not available.')  # just available when called from Allplan

Extending sys.path the Standard Way

By adding the Allplan PRG path to the standard Python environment, it is possible to run/test your PythonPartsScripts from outside of Allplan. But some API objects need a running Allplan application to work properly.

You can add the PRG path in your development environment (VS 2015 or PyCharm), or crate a *.pth file in your user site package folder, this is the universal solution, because it works for every IDE, Editor or just the plain command line.

The file location should look like this (replace <username>): C:\users\<username>\AppData\Python\Python35\site-packages, if “site-packages” does not exist, create a new folder. Add a file with a unique name and the ending .pth, I would suggest extrapaths.pth. Every line in this file represents an additional search path for sys.path, but this way the Python interpreter adds this location automatically to sys.path. The Python interpreter launched within Allplan prevents this standard mechanism actively, therefore I needed the awkward solution with extendsyspath.py as shown above.

Example extrapaths.pth:

# first add path to the Allplan libs, this allows you to
# import the Allplan libs from every Python environment
C:\Program Files\Allplan\Allplan 2017\Prg
# every following line can define an import path to your
# own custom packages, like the location of my allpy package
# in development status - not necessary if you use an IDE
D:\Source\PythonParts

Setup for PyCharm as Development Environment

If you choose Visual Studio as your development environment, please follow the instruction provided by Allplan.

This section shows how to setup PyCharm as developing environment for PythonParts.

Setup a new PyCharm Project.

The Allplan python environment installed in C:\Program Files\Allplan\Allplan 2017\Prg\Python will not recognised as full functional Python environment by PyCharm, it is not worth to repair the Allplan Python environment (see introduction). If you haven’t already installed a regular Python 3.5 64-bit environment, do it now.

Warning

It is not recommend to run the 32-bit and the 64-bit environment of the same Python version on the same machine.

Set the standard project interpreter:

1. Open the settings dialog: File -> Settings -> Project Interpreter
2. Choose the system wide 64-bit version of Python 3.5 - you can also use a virtual environment, but on Windows I don’t like them, inside of PyCharm you will not recognize many differences, but on the command line VENV are no fun.
3. If you haven’t created the extrapaths.pth file in your site packages folder, you can add the lib path to the Python environment, in the settings menu (wheel beside the env name), choose menu “more”, select your python environment, click on “Show path for the selected interpreter” (last icon from above), and add (+ symbol) the Allplan PRG path, the path to PRG should look like this C:\\Program Files\\Allplan\\Allplan 2017\\Prg.
4. PyCharm has to update its project skeleton, this may take a while.

Running the Allplan Unit Tests with PyCharm

Download the unit test from the Allplan site, and unzip the tests into your PyCharm project directory.

Create a new test runner with Edit -> Edit Configurations ....

Add a test suite (green +) -> Python tests -> Unittests

Name the test suite, in Unittests select “All in folder”, select the folder containing the test files, as Pattern set *.py, and use the standard Python 3.5 interpreter.

Because I use PyCharm, I don’t need PyLint and therefore I haven’t installed it, and the test TestPyLint.py breaks the test suite, I just deleted this file.

Now you can run the unit tests provided by Allplan. But in Allplan 2017 some of the available tests from 2016-03-07 and 2016-06-24 fail, because of a change of the API.

Install Additional Packages

This chapter shows how to install new package in C:\users\<username>\AppData\Python\Python35\site-packages. Installing the packages into the user’s site-packages directory is very important, because the Allplan PythonParts can only access the packages installed in the user site-packages folder, if you follow my way as shown in Extending sys.path the Awkward Way.

Installing packages with PyCharm

When installing packages with the PyCharm package dialog, check the option “install packages into user’s site-packages directory”, if the packages should be available for PythonPartsScripts started by Allplan.

Installing from the command line into the regular Python environment

If you have a system wide (means not a virtual environment) Python environment, just type:

py -m pip install --user <package-name or package-path>

• option –user is important to install the packages in the user’s site-packages directory.
• use <package-name> to install packages from the official Python Package Index (PyPI)
• use a <package-path> to install downloaded packages from .zip or .whl files

Adding Packages without Installation

Add an additional line with the package file path to the extrapaths.pth as shown in Extending sys.path the Standard Way, and also add this line to exendsyspath.py as shown in Extending sys.path the Awkward Way, this is my preferred way to add my packages in development status.

PyCharm Configuration

To get syntax high lightning for PYP files (this are plain XML files), register the file extension *.pyp:

Menu: File -> Settings -> Editor -> File Types

In dialog field “Recognised File Types” select “XML”, and in the field “Registered Pattern” add “*.pyp”.

Project Configuration

For easy access to all PythonPartsScripts, I added my STDPythonParts directory as additional content root: Settings -> Project -> Project Structure -> Add Content Root

And to quickly look into the Building Framework, I also added ETC\PythonPartsScripts\GeneralScripts as content root. You find ETC in C:\\ProgramData\\Nemetschek\\Allplan\\2017 or use the Allmenu application (Service -> Windows Explorer).