Last Chance To Claim LIFETIME ACCESS. (Only ~50 Seats Left)

Last Chance To Claim LIFETIME ACCESS.

15k+ already joined

Get Full Access

Next Lesson is Coming Soon!

Lesson 5: My pyRevit Script Template and pyRevit Anatomy

We are almost ready to start creating Revit Add-ins, but let's understand pyRevit anatomy and prepare your own pyRevit template, so you never start from scratch.

Summary

Welcome to the Fifth Lesson

Today, we're diving into something really important: pyRevit script anatomy.

In this lesson, I'll walk you through some pre-made templates that I've prepared for you and explain you pyRevit's meta tags.

These templates will be a huge time saver in all your future projects, so you don't have to start with a blank page every time.

Open the Templates

Here are the buttons to open up the pyRevit templates I've prepared.

pyRevit Template.min

pyRevit Template.full

  • min Version is the regular template you will be using where you put only the most essential imports, variables and other things.

full Version is more an educational examples, where I've placed all pyRevit meta tags, and tried to leave as many comments as possible.

πŸ’‘No matter what version you begin with,
make sure you adjust it to your own needs over time.

Let's break down these templates and I will explain each part.

UTF-8 Encoding

You will notice in both themplate the first line defines UTF-8 encoding.

If you are not familiar, in IronPython, we need to explicitly declare encoding. UTF-8 is the standard which will allow you to use non standard ASCII characters like German, Russian, Chinese and other special characters.

You can get away without specifying it, but eventually you might get an error like this πŸ‘‰


πŸ‘‡pyCharm will also point it out to you:

πŸ’‘If you will use CPython engine, you won't need to define UTF-8 encoding, but keep in mind that it's still under development and not as stable.

__title__ and __doc__

Next up are title and doc pyRevit meta tags. These are used to define your button's name and tooltip.

__title__ = 'Your Button Name'

# Multi-Language
__title__  = {
  "en_us": "English Button Name",
  "de_de": "Deutscher Beispiel-Knopf"
}

Usually people keep tooltip information short, but I like to break it down into multiple sections and provide more information like this:

This way users can get used to this, and always know that they can learn what is the button, how to use it and other upcoming or updated features.

__doc__ = """Version = 1.0
Date    = 15.07.2024
_____________________________________________________________________
Description:
This is a template file for pyRevit Scripts.
_____________________________________________________________________
How-to:
-> Click on the button
-> ...
_____________________________________________________________________
Last update:
- [16.07.2024] - 1.1 Fixed an issue...
- [15.07.2024] - 1.0 RELEASE
_____________________________________________________________________
To-Do:
- Describe Next Features
_____________________________________________________________________
Author: Erik Frits"""

pyRevit also provides you an option to specify different names for different Revit versions. Here is a list of locale codes.

Common Imports

Next we need to import classes for our script. This includes Autodesk, pyrevit and even .NET imports.

# Regular + Autodesk
from Autodesk.Revit.DB import *
from Autodesk.Revit.DB.Architecture import *
from Autodesk.Revit.DB.Structure    import StructuralType

# pyRevit
from pyrevit import revit, forms

# .NET Imports (You often need List import)
import clr
clr.AddReference("System")
from System.Collections.Generic import List

It's best to only include only the most used imports in your template to keep it neat. So feel free to remove what you don't need.

But as a beginner, you can also put everything here so you don't have to remember where something comes from. And then slowly adjust to only most essential imports.

But I strongly recommend you to leave .NET List import, because it's hard to remember by heart where it comes from. And while you won't need it in every script, it's very often required as an argument in Revit API methods.

πŸ’‘Also keep in mind that there are many classes that can be located in discipline specific namespaces like Architecture, Structure, Mechanical, Electrical and many others…

You can always check in Revit API Docs where they come from

Variables

Now, let's talk about the three common variables you'll need:

  • doc - Document, representing open projects. (used to relate to projects)

  • uidoc - UIDocument, representing projects in Revit UI (used for selection and other interaction with the UI)

  • app - Application, representing the Revit application iself (used for application-wide settings like Background color, Revit Year, Revit Language, Path to Shared Parameter File and so on…

doc   = __revit__.ActiveUIDocument.Document
uidoc = __revit__.ActiveUIDocument
app   = __revit__.Application

πŸ’‘Pro Tip: Specify type hinting using the following syntax so your IDE can give you auto-suggestions by knowing what type of an object it is.

doc   = __revit__.ActiveUIDocument.Document #type: Document

Structuring Your Code

The more readable you can make your code, the easier it is to maintain it.

Personally, I like to organize my code with large ASCI-Art text blocks to separate into sections like Imports, Variables, Functions and so on. And on smaller scripts I use emojis.

This is purely personal preference, and not a python standard at all. Python experts are probably going to go against it, but I know that many beginners love it, because it makes it so much easier to navigate, especially when you watch my tutorials.

# ╦╔╦╗╔═╗╔═╗╦═╗╔╦╗╔═╗
# ║║║║╠═╝║ ║╠╦╝ β•‘ β•šβ•β•—
# β•©β•© β•©β•©  β•šβ•β•β•©β•šβ• β•© β•šβ•β• IMPORTS
#==================================================


# ╦  ╦╔═╗╦═╗╦╔═╗╔╗ ╦  ╔═╗╔═╗
# β•šβ•—β•”β•β• β•β•£β• β•¦β•β•‘β• β•β•£β• β•©β•—β•‘  β•‘β•£ β•šβ•β•—
#  β•šβ• β•© β•©β•©β•šβ•β•©β•© β•©β•šβ•β•β•©β•β•β•šβ•β•β•šβ•β• VARIABLES
#==================================================


# ╔═╗╦ ╦╔╗╔╔═╗╔╦╗╦╔═╗╔╗╔╔═╗
# β• β•£ β•‘ β•‘β•‘β•‘β•‘β•‘   β•‘ β•‘β•‘ β•‘β•‘β•‘β•‘β•šβ•β•—
# β•š  β•šβ•β•β•β•šβ•β•šβ•β• β•© β•©β•šβ•β•β•β•šβ•β•šβ•β•
#==================================================

# ╔╦╗╔═╗╦╔╗╔
# ║║║╠═╣║║║║
# β•© β•©β•© β•©β•©β•β•šβ• MAIN
#==================================================

To create these ASCI-Art blocks, you need to install pyCharm/VS Code plugin called - FigLET or use online generators.

Once you have the plugin you can select your text and click on [ALT] + [Insert] Keys and select FigLet plugin. Then select Calvis S font for ASCII-Art.

Honestly, I haven't seen anyone use it like that, but I like it for some reason.

#⬇️ IMPORTS
#------------------------------

#πŸ“¦ VARIABLES
#------------------------------

#🧬 FUNCTIONS
#------------------------------

#🎯 MAIN
#------------------------------

To create Emojis anywhere on windows, you can hold [WIN-Key] + [Dot] and it will open Emoji browser to choose from.

You can start typing something like 'arrow', 'box', 'target' to find what you need quicker.

pyRevit Meta Tags

We've covered everything in the Template.min, now let's focus on the full template and explore pyRevit Meta tags.

I won't go in much detail, because you can read mroe in the pyRevit Docs: IronPython Anatomy

But here are the most useful ones:

__author__ = "Erik Frits"                                       # Script's Author
__helpurl__ = "https://www.youtube.com/watch?v=YhL_iOKH-1M"     # Link that can be opened with F1 when hovered over the tool in Revit UI.
# __highlight__ = "new"                                           # Button will have an orange dot + Description in Revit UI
__min_revit_ver__ = 2019                                        # Limit your Scripts to certain Revit versions if it's not compatible due to RevitAPI Changes.
__max_revit_ver = 2022                                          # Limit your Scripts to certain Revit versions if it's not compatible due to RevitAPI Changes.
#__context__     = 'selection'                                  # Make your button available only when certain categories are selected. Or Revit/View Types.

Context

Context is a unique feature in pyRevit that allows you to set the criteria for the button before it can be used.

There is a whole page in pyRevit Dev Docs where you can find more about all possible criteria.

But in general you can force users to:

  • Select certain categories

  • Ensure Active Document is Project/Cloud/Family/Worksharing

  • Open certain ViewType (FloorPlan, Section…)

  • Combine multiple criteria together


Also you will notice that examples are all for bundle.yaml file. This is an optional file that can be placed in the folder of a button, where you can define all your metatags like:

  • doc

  • title

  • min_revit-ver

  • context

  • …

Personally, I don't using bundle.yaml, and I prefer to define all metatags inside of my python files. It's easier to find, modify and I get less errors, because bundle.yaml might give you some errors sometimes if you fill something wrong.

Check the video for more information about context and bundle.yaml.

What's Next?

Alright, and now you have your pyRevit Template and you know about pyRevit metatags. You are ready now to create your first Revit Add-in and that's what we will do in the next lesson.

HomeWork

Prepare your own pyRevit Template.

You can take my existing template and feel free to modify anything to your own needs. You might not want to change anything, because you are just starting.

But make sure you adjust it to your needs over time when you understand Revit API better.

⌨️ Happy Coding!

πŸ™‹β€β™‚οΈ See you in the next lesson.
- EF

πŸ™‹β€β™‚οΈ See you in the next lesson.
- EF

Questions:

Do you always start with a template?

Do you always start with a template?

πŸ”’ Online Discord Chats are available only to Course members.

Join Here.

πŸ”’ Online Discord Chats are available only to Course members.

Join Here.

πŸ”’ Online Discord Chats are available only to Course members.

Join Here.