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

README.md

@@ -9,15 +9,15 @@ Revitron is a [Revit API](https://www.revitapidocs.com/) wrapper written in Pyth
 ![GitHub top language](https://img.shields.io/github/languages/top/revitron/revitron?color=222222)
 ![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/revitron/revitron?color=222222)
 ![Read the Docs](https://img.shields.io/readthedocs/revitron?color=222222)
-![](https://img.shields.io/badge/Revit-2017--2021-222222)
+![](https://img.shields.io/badge/Revit-2017--2022-222222)
 
 ## Docs
 
 An installation guide, the API reference and the UI docs can be found [here](https://revitron.readthedocs.io).     
 
 ## Unit Tests
 
-> :point_up: Note that this extension is only tested on Revit `2017`, `2019.1`, `2020.2` and `2021.1`, but may as well work on other versions.
+> :point_up: Note that this extension is only tested on Revit `2017`, `2019`, `2020`, `2021` and `2022`, but may as well work on other versions.
 
 Revitron unit tests need their own pyRevit UI to run. Since they are only needed to develop the library extension and would only bother normal users, all unit tests are located in a [separate repository](https://github.com/revitron/revitron-tests) and can be installed as an independent UI extension if required.
 

docs/source/cheat-sheet.rst

@@ -117,6 +117,15 @@ Getting all elements of a certain category, specified by a string, for example "
     for room in rooms:
         print(_(room).get('Name'))
 
+Instead of the *natural* category name, it is also valid to use the string representation of 
+a built-in category as filter argument:
+
+.. code-block:: python
+
+    rooms = revitron.Filter().byCategory('OST_Rooms').getElements()
+
+.. note:: A full list of natural category names and their corresponding built-in categories can be found `here <https://docs.google.com/spreadsheets/d/1uNa77XYLjeN-1c63gsX6C5D5Pvn_3ZB4B0QMgPeloTw/edit#gid=1549586957>`_.
+
 Filtering those rooms by filtering the ``Name`` *"beginning with the word Room"* can be done as follows. 
 Note the flexible way of breaking down the filtering into multiple line for better readability:
 

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.6'
+REVITRON_VERSION = '0.1.7'
 
 
 def _(element):

revitron/category.py

@@ -1,17 +1,18 @@
 """ 
 To simplify the interaction with **Revit** categories, the ``category`` 
-submodule provides the ``Category`` class to be able to access **Revit** category objects by name.
+submodule provides the ``Category`` and ``BuiltInCategory`` classes in order
+to access **Revit** category objects as well as builtin categories by name.
 """
 
 class Category:
 	"""
-	A wrapper class for category objects which can be instantiated by a catergory name.
+	A wrapper class for category objects which can be instantiated by a category name.
 	
 	You can get the Revit Category class object by providing a name as follows::
 	
 		category = revitron.Category('name').get()
 	"""
-	
+
 	def __init__(self, name):
 		"""
 		Init a new Category by name.
@@ -24,8 +25,8 @@ def __init__(self, name):
 			if cat.Name == name:
 				self.category = cat
 				break
-		
-		
+
+
 	def get(self):
 		"""
 		Returns the category object.
@@ -42,12 +43,72 @@ def getBic(self):
 
 		Returns:
 			object: The built-in category
-		"""    
-		import revitron    
+		"""
+		import revitron
 		for item in dir(revitron.DB.BuiltInCategory):
 			try:
 				bic = getattr(revitron.DB.BuiltInCategory, item)
 				if int(bic) == self.category.Id.IntegerValue:
 					return bic
 			except:
-				pass  
+				pass
+
+
+class BuiltInCategory:
+	"""
+	A wrapper class for builtin category objects which can be instantiated by name.
+	
+	You can get the Revit BuitlInCategory class object by providing a name as follows::
+	
+		bic = revitron.BuiltInCategory('OST_Walls').get()
+
+	For convenience reasons, it is also valid to skip the ``OST_`` prefix and simply do::
+
+		bic = revitron.BuiltInCategory('Walls').get()
+
+	In case you only know the *natural* category name and want to get the BuiltInCategory instead,
+	you can also use that one. For example to get the ``OST_BeamAnalyticalTags`` BuiltInCategory, you
+	can do simply::
+
+		bic = revitron.BuiltInCategory('Analytical Beam Tags').get()
+
+	A full list of category names can be found `here <https://docs.google.com/spreadsheets/d/1uNa77XYLjeN-1c63gsX6C5D5Pvn_3ZB4B0QMgPeloTw/edit#gid=1549586957>`_.
+	"""
+
+	def __init__(self, name):
+		"""
+		Get the BuiltInCategory by its name, its name without the ``OST_`` prefix 
+		or even its natural category name. A full list of category names can be found `here <https://docs.google.com/spreadsheets/d/1uNa77XYLjeN-1c63gsX6C5D5Pvn_3ZB4B0QMgPeloTw/edit#gid=1549586957>`_.
+
+		Example::
+
+			bic = revitron.BuiltInCategory('OST_Walls').get()
+			bic = revitron.BuiltInCategory('Walls').get()
+
+		Use the natural name to get for example ``OST_BeamAnalyticalTags``::
+
+			bic = revitron.BuiltInCategory('Analytical Beam Tags').get()
+
+		Args:
+			name (name): The name, the name without the ``OST_`` prefix or even the 
+				`natural <https://docs.google.com/spreadsheets/d/1uNa77XYLjeN-1c63gsX6C5D5Pvn_3ZB4B0QMgPeloTw/edit#gid=1549586957>`_ category name
+		"""
+		import revitron
+		cat = Category(name)
+		self.bic = cat.getBic()
+		if not self.bic:
+			try:
+				name = 'OST_{}'.format(name.replace('OST_', ''))
+				self.bic = getattr(revitron.DB.BuiltInCategory, name)
+			except:
+				pass
+
+
+	def get(self):
+		"""
+		Return the BuiltInCategory class.
+
+		Returns:
+			class: The BuiltInCategory class
+		"""
+		return self.bic

revitron/filter.py

@@ -152,17 +152,30 @@ def byRegex(self, paramName, regex, invert = False):
 
 	def byCategory(self, name):
 		"""
-		Filters the collection by a category name - not a built-in category.
+		Filters the collection by a category name or a built-in category name.
+		
+		Note that there are basically three valid types that can be used as the filter argument. 
+		The first two use the name of a built-in category (with or without the ``OST_`` prefix)::
+
+			fltr = revitron.Filter().byCategory('Walls')
+			fltr = revitron.Filter().byCategory('OST_Walls')
+
+		The third type uses a `natural <https://docs.google.com/spreadsheets/d/1uNa77XYLjeN-1c63gsX6C5D5Pvn_3ZB4B0QMgPeloTw/edit#gid=1549586957>`_ 
+		category name to find a corresponding built-in category to filter, here ``OST_BeamAnalyticalTags``::
+
+			fltr = revitron.Filter().byCategory('Analytical Beam Tags')
 
 		Args:
-			name (string): The category name
+			name (string): A category or built-in category name
 
 		Returns:
 			object: The Filter instance
-		"""   
+		"""
 		import revitron
-
-		self.collector = self.collector.OfCategory(revitron.Category(name).getBic())
+		try:
+			self.collector = self.collector.OfCategory(revitron.BuiltInCategory(name).get())
+		except:
+			pass
 		return self