build(release): merge branch develop (release 0.1.8)

docs/source/cheat-sheet.rst

@@ -198,6 +198,18 @@ Getting the **Revitron** bounding box object of the first element in the selecti
     bbox = _(el).getBbox()
     print(bbox)
 
+Document Context
+----------------
+
+In order to filter elements and using ``revitron.Filter`` with any other model than the active one, 
+it is possible to temporarily change the document context as follows:
+
+.. code-block:: python
+
+    with revitron.Document(anyOtherDoc):
+        fltr = revitron.Filter().noTypes()
+        elements = fltr.getElements()
+
 Storing Configurations
 ----------------------
 

revitron/__init__.py

@@ -121,7 +121,7 @@
 DB = Autodesk.Revit.DB
 LIB_DIR = parent(parent(__file__))
 REVIT_VERSION = pyrevit.HOST_APP.uiapp.Application.VersionNumber
-REVITRON_VERSION = '0.1.7'
+REVITRON_VERSION = '0.1.8'
 
 
 def _(element):

revitron/document.py

@@ -9,12 +9,21 @@ class Document:
 	"""
 	A basic wrapper class for Revit documents.
 	
-	Examples::
+	Basic examples are::
 	
 		path = revitron.Document().getPath()
-		
 		if revitron.Document().isFamily():
 		    pass
+
+	In case you want to work with any other model than the active one, it is possible to change the context
+	to that model using the ``with`` statement. Changing the context to another model will internally redefine 
+	the ``revitron.DOC`` property within the scope of that ``with`` statement.
+	Therefore it is also possible to use a ``revitron.Filter`` instance on any model by just using a filter within a 
+	``with`` statement::
+
+		with revitron.Document(doc):
+		    fltr = revitron.Filter().noTypes()
+		    elements = fltr.getElements()
 	"""
 
 	def __init__(self, doc = None):
@@ -23,14 +32,38 @@ def __init__(self, doc = None):
 
 		Args:
 			doc (object, optional): Any document instead of the active one. Defaults to None.
-		"""        
+		"""
 		import revitron
 		if doc is not None:
 			self.doc = doc
 		else:
 			self.doc = revitron.DOC
 
 
+	def __enter__(self):
+		"""
+		Set ``revitron.DOC`` to the document of the current ``Document`` class instance. 
+
+		By default that will just be the active document and therefore ``revitron.DOC`` stays unchanged.
+		"""
+		import revitron
+		self.cache = revitron.DOC
+		revitron.DOC = self.doc
+
+
+	def __exit__(self, execType, execValue, traceback):
+		"""
+		Restore the original context.
+
+		Args:
+			execType (string): The execution type
+			execValue (string): The execution value
+			traceback (mixed): The traceback
+		"""
+		import revitron
+		revitron.DOC = self.cache
+
+
 	def getDuplicateInstances(self, preferOlderElement = False):
 		"""
 		Returns a list of duplicate family instances. 

revitron/filter.py

@@ -4,14 +4,30 @@
 complementing the standard **Revit API** ``FilteredElementCollector`` class with 
 the ability to filter collections by parameter values::
 
-	filter = revitron.Filter
-	ids = filter().byStringEquals('param', 'value').noTypes().getElementIds()
+	elements = (
+	    revitron.Filter
+	    .byStringEquals('param', 'value')
+	    .noTypes()
+	    .getElements()
+	)
 	
 Note that you can **invert** a filter by providing a the third argument for a string filter as follows::
 
-	filter = revitron.Filter
-	ids = filter().byStringEquals('param', 'value', True).noTypes().getElementIds()
-	
+	elements = (
+	    revitron.Filter
+	    .byStringEquals('param', 'value', True)
+	    .noTypes()
+	    .getElements()
+	)
+
+.. note:: In order to filter elements in another model instead of the active one, it is possible to change 
+	the document context using the ``with`` statement.
+
+The document context can be changed as follows::
+
+	with revitron.Document(anyOtherDoc):
+	    fltr = revitron.Filter().noTypes()
+	    elements = fltr.getElements()
 """
 import re
 from System.Collections.Generic import List
@@ -196,8 +212,8 @@ def byNumberIsGreater(self, paramName, value, invert = False):
 
 		Example::
 			
-			filter = revitron.Filter
-			ids = filter().byNumberIsGreater('Area', 5).noTypes().getElementIds()
+			fltr = revitron.Filter()
+			ids = fltr.byNumberIsGreater('Area', 5).noTypes().getElementIds()
 
 		Args:
 			paramName (string): The parameter name
@@ -224,8 +240,9 @@ def byNumberIsGreaterOrEqual(self, paramName, value, invert = False):
 
 		Example::
 			
-			filter = revitron.Filter().noTypes()
-			ids = filter.byNumberIsGreaterOrEqual('Area', 5).getElementIds()
+			fltr = revitron.Filter()
+			fltr = fltr.byNumberIsGreaterOrEqual('Area', 5).noTypes()
+			ids = fltr.getElementIds()
 
 		Args:
 			paramName (string): The parameter name
@@ -252,8 +269,8 @@ def byNumberIsEqual(self, paramName, value, invert = False):
 
 		Example::
 			
-			filter = revitron.Filter().noTypes()
-			ids = filter.byNumberIsEqual('Area', 5).getElementIds()
+			fltr = revitron.Filter()
+			ids = fltr.byNumberIsEqual('Area', 5).noTypes().getElementIds()
 
 		Args:
 			paramName (string): The parameter name
@@ -280,8 +297,8 @@ def byNumberIsLess(self, paramName, value, invert = False):
 
 		Example::
 			
-			filter = revitron.Filter().noTypes()
-			ids = filter.byNumberIsLess('Area', 5).getElementIds()
+			fltr = revitron.Filter()
+			ids = fltr.byNumberIsLess('Area', 5).noTypes().getElementIds()
 
 		Args:
 			paramName (string): The parameter name
@@ -308,8 +325,8 @@ def byNumberIsLessOrEqual(self, paramName, value, invert = False):
 
 		Example::
 			
-			filter = revitron.Filter().noTypes()
-			ids = filter.byNumberIsLessOrEqual('Area', 5).getElementIds()
+			fltr = revitron.Filter()
+			ids = fltr.byNumberIsLessOrEqual('Area', 5).noTypes().getElementIds()
 
 		Args:
 			paramName (string): The parameter name
@@ -334,10 +351,14 @@ def byOneInCsv(self, evaluatorName, paramName, csv, invert = False):
 		"""
 		Filters the collection by testing whether a string contains at lease one ot the items in a CSV list.
 
-		Note that by setting the ``invert`` to ``True``, all elements that match one of the items will be removed from the collection.
+		This method is the base method for the ``byStringContainsOneInCsv`` and ``byStringEqualsOneInCsv``
+		methods.
+
+		.. note:: that by setting ``invert`` to ``True``, all elements that match one of the items will be 
+			removed from the collection.
 
 		Args:
-			evaluatorName (class): The filter method to be used to filter
+			evaluatorName (method): The filter method to be used to filter
 			paramName (string): The name of the parameter 
 			csv (string): A comma separated list of items 
 			invert (bool, optional): Inverts the filter. Defaults to False.
@@ -376,8 +397,9 @@ def byStringContains(self, paramName, value, invert = False):
 
 		Example::
 			
-			filter = revitron.Filter
-			ids = filter().byStringContains('param', 'value').noTypes().getElementIds()
+			fltr = revitron.Filter()
+			fltr = fltr.byStringContains('param', 'value').noTypes()
+			ids = fltr.getElementIds()
 
 		Args:
 			paramName (string): The parameter name
@@ -401,7 +423,15 @@ def byStringContainsOneInCsv(self, paramName, csv, invert = False):
 		"""
 		Filters the collection by testing whether a string contains at lease one ot the items in a CSV list.
 
-		Note that by setting the ``invert`` to ``True``, all elements that match one of the items will be removed from the collection.
+		.. note:: that by setting ``invert`` to ``True``, all elements that match one of the items will be 
+			removed from the collection.
+
+		Example::
+
+			fltr = revitron.Filter()
+			fltr = fltr.byStringContainsOneInCsv('Family', 'some, words', False)
+			fltr = fltr.noTypes()
+			elements = fltr.getElements()
 
 		Args:
 			paramName (string): The name of the parameter 
@@ -420,8 +450,8 @@ def byStringEquals(self, paramName, value, invert = False):
 
 		Example::
 			
-			filter = revitron.Filter
-			ids = filter().byStringEquals('param', 'value').noTypes().getElementIds()
+			fltr = revitron.Filter()
+			ids = fltr.byStringEquals('param', 'value').noTypes().getElementIds()
 
 		Args:
 			paramName (string): The parameter name
@@ -446,7 +476,15 @@ def byStringEqualsOneInCsv(self, paramName, csv, invert = False):
 		"""
 		Filters the collection by testing whether a string equals at lease one ot the items in a CSV list.
 
-		Note that by setting the ``invert`` to ``True``, all elements that match one of the items will be removed from the collection.
+		.. note:: that by setting ``invert`` to ``True``, all elements that match one of the items will be 
+			removed from the collection.
+
+		Example::
+
+			fltr = revitron.Filter()
+			fltr = fltr.byStringEqualsOneInCsv('Family', 'some, words', False)
+			fltr = fltr.noTypes()
+			elements = fltr.getElements()
 
 		Args:
 			paramName (string): The name of the parameter 
@@ -463,6 +501,12 @@ def byStringBeginsWith(self, paramName, value, invert = False):
 		"""
 		Filters the collection by a string at the beginning of a parameter value.
 
+		Example::
+			
+			fltr = revitron.Filter()
+			fltr = fltr.byStringBeginsWith('param', 'value').noTypes()
+			ids = fltr.getElementIds()
+
 		Args:
 			paramName (string): The parameter name
 			value (string): The searched string
@@ -511,7 +555,7 @@ def getElements(self):
 
 		Returns:
 			list: The list of excluded elements
-		"""        
+		"""
 		try:
 			return self.collector.ToElements()
 		except: