Scripting Reference
Last updated
Last updated
This reference page extends the best practices covered in Scripting Strategies with greater detail on code libraries, labeling, and styling. We will be using Python to illustrate the concepts below, but the same principles would apply in Python and C#(Zerotouch) but in different syntax.
Standard libraries are external to Dynamo and are present in the programming languages Python and C# (Zerotouch). Dynamo also has its own set of libraries that directly correspond to it's node hierarchy, enabling the user to build anything in code that could be made with nodes and wires. The following is a guide for what each Dynamo library gives access to and when to use a standard one.
Standard Libraries and Dynamo Libraries
Standard libraries from Python and C# can be used to build advanced data and flow structures in the Dynamo environment.
Dynamo libraries directly correspond to the node hierarchy for creating geometry and other Dynamo objects.
Dynamo Libraries
ProtoGeometry*
Functionality: Arc, Bounding Box, Circle, Cone, Coordinate System, Cuboid, Curve, Cylinder, Edge, Ellipse, Ellipse Arc ,Face, Geometry, Helix, Index Group, Line, Mesh, Nurbs Curve, Nurbs Surface, Plane, Point, Polygon, Rectangle, Solid, Sphere, Surface, Topology, TSpline, UV, Vector, Vertex.
How to import: import Autodesk.DesignScript.Geometry
``
DSCoreNodes
Functionality: Color, Color Range 2D, Date Time, Time Span, IO, Formula, Logic, List, Math, Quadtree, String, Thread.
How to import: import DSCore
Tessellation
Functionality: Convex Hull, Delaunay, Voronoi.
How to import: import Tessellation
DSOffice
Functionality: Excel.
How to import: import DSOffice
*Note: When using ProtoGeometry through Python or C#, you are creating unmanaged objects, which need have their memory managed manually - please see section below: Unmanaged Objects, for more info.
While scripting, we are constantly using identifiers to denote things like variables, types, functions, and other entities. Through this system of symbolic notation, while building algorithms we can conveniently refer to information by way of labels --usually made up of a sequence of characters. Naming things well plays a significant role in writing code that can be easily read and understood by others as well as your future self! Here are some tips to keep in mind while naming things in your script:
It´s OK to use abbreviations, but explain the abbreviation with a comment:
Avoid redundant labeling:
Use positive logic for your variable names instead of negative logic:
Prefer “reverse notation”:
It’s more sensible, in structural terms.
Aliases should be used to shorten overly long and often repeated chains:
Aliasing can quickly lead to very confusing and non-standard programs.
Only use necessary words:
“Everything should be made as simple as possible, but not simpler.” – Albert Einstein
Generally speaking there is more than one way to program just about anything, therefore your “personal style” of scripting is the result of the countless small decisions you choose to make (or not make) along the way. That said, the readability and maintainability of your code is a direct result of its internal consistency as well as its adherence to general stylistic conventions. As a rule of thumb, code that looks the same in two places should work the same, too. Here are a few tips for writing clear and consistent code.
Naming conventions: (Choose one of the conventions below for each type of entity in your code and stick to it!)
Variables, functions, methods, packages, modules:
lower_case_with_underscores
Classes and Exceptions:
CapWords
Protected methods and internal functions:
_single_leading_underscore(self, ...)
Private methods:
__double_leading_underscore(self, ...)
Constants:
ALL_CAPS_WITH_UNDERSCORES
Tip: Avoid one-letter variables (esp. l, O, I) except in very short blocks, when the meaning is clearly visible from the immediate context.
Use of blank lines:
Surround top-level function and class definitions with two blank lines.
Method definitions inside a class are surrounded by a single blank line.
Extra blank lines may be used (sparingly) to separate groups of related functions.
Avoid extraneous whitespace:
Immediately inside parentheses, brackets or braces:
Immediately before a comma, semicolon, or colon:
Immediately before the open parenthesis that starts the argument list of a function call:
Immediately before the open parenthesis that starts an indexing or slicing:
Always surround these binary operators with a single space on either side:
Watch line length:
Don't stress over it ~ 79 characters.
Limiting the required editor window width makes it possible to have several files open side-by-side, and works well when using code review tools that present the two versions in adjacent columns.
Long lines can be broken over multiple lines by wrapping expressions in parentheses:
Avoid obvious and redundant comments:
Sometimes fewer comments makes for more readable code. Especially if it forces you to use meaningful symbol names instead.
Adopting good coding habits reduces dependence on comments:
Tip: Comments tell you why, Code tells you how.
Check out open source code:
Open Source projects are built on the collaborative efforts of many developers. These projects need to maintain a high level of code readability so that the team can work together as efficiently as possible. Therefore, it is a good idea to browse through the source code of these projects to observe what these developers are doing.
Improve your conventions:
Question whether or not each convention is working for the needs at hand.
Is functionality/efficiency being compromised?
Check out these wiki pages for guidance on writing C# for Zerotouch and contributing to Dynamo:
Unmanaged Objects:
You only need to dispose unmanaged resources that you don't return into the graph or store a reference to. For the rest of this section, we'll refer to these objects as intermediate geometry. You can see an example of this class of object in the code example below. This zero touch C# function singleCube returns a single cube, but creates 10000 extra cubes during its execution. We can pretend this other geometry was used as some intermediate construction geometry.
This zero touch function will most likely crash Dynamo. Since we created 10000 solids, but only stored one of them, and only returned that one. We should instead, dispose all of our intermediate cubes, except the one that we return. We don't want to dispose what we return, as it will be propogated into the graph and used by other nodes.
The fixed code would look something like:
In general you only need to dispose geometry like Surfaces, Curves, and Solids. To be safe though, you can dispose all geometry types (Vectors, Points, CoordinateSystems).
This wiki covers some general coding standards for documenting and testing your code:
This wiki specifically covers naming standards for libraries, categories, node names, port names, and abbreviations:
When using Dynamo's Geometry library (ProtoGeometry) from Python or C# geometry objects that you create will not be managed by the virtual machine, and the memory of many of these objects will need to be cleaned up manually. To cleanup native or unmanaged objects you can use the Dispose method or the using keyword. See this wiki entry for an overview: .
