File Structure
==============

First some definitions:

<name>
  is a placeholder for your PythonPart name

<xxx.prj>
  is a placeholder for your current Allplan project folder

parameter
  file means the PythonPart (\*.pyp) file

script
  means the PythonPartsScript (\*.py) python script file

PythonPart
  means the PythonPart as a whole thing, all to this PythonPart related files: parameter file,
  script file, preview image, translation files

PythonPart Files
----------------

For running a PythonPart in Allplan, you need at least two files:

  - <name>.pyp – the parameter file can be placed anywhere, but for easy access by the Allplan library manager, it is
    necessary placing it in one of Allplan library folders, else you have to drag and drop the parameter file into the
    Allplan application window. It is a plain text/XML file, you can edit it with any text editor.
    I recommend `Notepad++`_.

  - <name>.py – has to be placed in one of Allplan PythonPartsScripts folders. This is the python script file, also
    a plain text file, you can edit it with any text editor. I recommend the `Notepad++`_ editor or a
    Python IDE (Integrated Development Environment) like Visual Studio 2015 (Community Edition) or PyCharm, but there
    are many other free IDEs available, just do a `Google search <http://lmgtfy.com/?q=python+ide>`_.

.. hint::

   Always save your files with UTF-8 encoding, especially if you use none ASCII 7-bit characters (like ÄÖÜß)

In addition, there are some optional files:

  - <name>.png – preview image (128x128 px) for the Allplan library manager, has to be placed next to the
    parameter <name>.pyp file.

  - <name>_deu.xml – localisation xml file for each Allplan language (deu, eng, fr, …). The file contains the
    translations for each TextId used in the <name>.pyp file

.. _python_part_parameter_folders:

Library Folders
---------------

These folders contain the parameter files (\*.pyp).

Use the Allmenu application to find the Allplan ETC and STD folders: Service -> Windows Explorer

  - ETC\\Library - Allplan standard
  - STD\\Library - Office standard
  - <xxx.prj>\\Library  - Project

.. _python_part_scripts_folders:

PythonPartScripts Folders
-------------------------

These folders contain the script files (\*.py).

  - ETC\\PythonPartsScripts - Allplan standard
  - STD\\PythonPartsScripts - Office standard
  - <xxx.prj>\\PythonPartsScripts - Project

Allplan will **not** create the PythonPartsScripts folders in STD and <xxx.prj> path, **you** have to create them.

You can import every *script* placed in one of this folders into one of your PythonPart scripts. Especially from ETC
and STD, the project related scripts are only available if this project is currently opened in Allplan.

It is possible and useful to structure your PythonParts in subfolders. It is recommend to structure the parameter files
and the *script* files in the same way:

  - \\Library\\MyFirstPart\\<name>.pyp - the parameter file

  - \\PythonpartsScripts\\MyFirstPart\\<name>.py - the python script

Where to place your PythonParts? In ETC, STD or <xxx>.prj, there is no recommendation from Nemetschek/Allplan.

I put my PythonParts into the STD path, so they are available to all my projects, ETC is the vendor path, here applies
the vendor policy: "Just look, don't touch!". I use the <xxx.prj> path just for project adapted PythonParts.

.. _just_look_do_not_touch_policy:

Just Look, Don't Touch Policy in ETC
------------------------------------

.. warning::

    The "Just look, don't touch" policy is not a joke:

    In ETC\\PythonPartsScripts\\GeneralScripts resides the PythonParts Building Framework, which is used by **ALL**
    PythonParts, if you damage one of these files, no PythonPart will ever work, until you restore a proper status.

.. _Notepad++: https://notepad-plus-plus.org/