Merge pull request #1896 from sanzoghenzo/docstrings

docs: add docstrings

Pipfile

@@ -15,6 +15,7 @@ pygount = "*"
 pyyaml = ">=5.4"
 black = "*"
 setuptools = "==65.5.1"
+ruff = "*"
 
 [requires]
 python_version = "3.10"
@@ -24,3 +25,4 @@ allow_prereleases = true
 
 [scripts]
 pyrevit = "python ./dev/pyrevit.py"
+check-docstrings = "ruff check --fix pyrevitlib/pyrevit"

README.md

@@ -6,7 +6,7 @@
 [![GitHub forks](https://img.shields.io/github/forks/eirannejad/pyRevit.svg?style=for-the-badge)](https://github.com/eirannejad/pyRevit/network)
 [![GitHub stars](https://img.shields.io/github/stars/eirannejad/pyRevit.svg?style=for-the-badge&colorB=red)](https://github.com/eirannejad/pyRevit/stargazers)
 [![License: GPL v3](https://img.shields.io/badge/License-GPL%20v3-blue.svg?style=for-the-badge)](http://www.gnu.org/licenses/gpl-3.0)
-[![madewithloveinportland](https://img.shields.io/badge/%3C%2F%3E%20with%20%3C3-Portland%2C%20OR-green.svg?style=for-the-badge)](https://en.wikipedia.org/wiki/Portland,_Oregon)
+[![made with love in portland](https://img.shields.io/badge/%3C%2F%3E%20with%20%3C3-Portland%2C%20OR-green.svg?style=for-the-badge)](https://en.wikipedia.org/wiki/Portland,_Oregon)
 
  
 
@@ -120,13 +120,12 @@ Check the list of [Currently Open](https://github.com/eirannejad/pyRevit/issues)
 
 ## Share Your Coins
 
-**↓** Help making pyRevit financially stronger 
+**↓** Help making pyRevit financially stronger
 
 [Support on Patreon](https://www.notion.so/Support-on-Patreon-cdf92ba547154f7a85d32b526dc5e59b)
 
 [Supporters](https://www.notion.so/Supporters-4f3350243ba24dcd8228df6262723629)
 
-
 # Contributors
 
 Made with [contrib.rocks](https://contrib.rocks)

pyproject.toml

@@ -0,0 +1,6 @@
+[tool.ruff]
+select = ["D"]
+ignore = ["D107", "D105"]
+
+[tool.ruff.pydocstyle]
+convention = "google"

pyrevitlib/pyrevit/__init__.py

@@ -18,7 +18,7 @@
 import traceback
 import re
 
-import clr  #pylint: disable=E0401
+import clr  # pylint: disable=E0401
 
 from pyrevit import compat
 
@@ -141,7 +141,7 @@ class PyRevitIOError(PyRevitException):
 
 
 class PyRevitCPythonNotSupported(PyRevitException):
-    """Common base class for all pyRevit io-related exceptions."""
+    """Exception for features not supported under CPython."""
     def __init__(self, feature_name):
         super(PyRevitCPythonNotSupported, self).__init__()
         self.feature_name = feature_name
@@ -179,10 +179,7 @@ class _HostApplication(object):
     info on the active screen, active document and ui-document, available
     postable commands, and other functionality.
 
-    Args:
-        host_uiapp (``UIApplication``): Instance of running host.
-
-    Example:
+    Examples:
         >>> hostapp = _HostApplication()
         >>> hostapp.is_newer_than(2017)
     """
@@ -211,7 +208,7 @@ def addin_id(self):
 
     @property
     def has_api_context(self):
-        """Determine if host application is in API context"""
+        """Determine if host application is in API context."""
         return self.app.ActiveAddInId is not None
 
     @property
@@ -278,8 +275,13 @@ def serial_no(self):
 
     @property
     def pretty_name(self):
-        """str: Pretty name of the host
-        (e.g. 'Autodesk Revit 2019.2 build: 20190808_0900(x64)')
+        """Returns the pretty name of the host.
+
+        Examples:
+            Autodesk Revit 2019.2 build: 20190808_0900(x64)
+
+        Returns:
+            (str): Pretty name of the host
         """
         host_name = self.version_name
         if self.is_newer_than(2017):
@@ -359,6 +361,7 @@ def is_newer_than(self, version, or_equal=False):
 
         Args:
             version (str or int): version to check against.
+            or_equal (bool): Whether to include `version` in the comparison
         """
         if or_equal:
             return int(self.version) >= int(version)
@@ -385,7 +388,7 @@ def get_postable_commands(self):
         """Return list of postable commands.
 
         Returns:
-            :obj:`list` of :obj:`_HostAppPostableCommand`
+            (list[_HostAppPostableCommand]): postable commands.
         """
         # if list of postable commands is _not_ already created
         # make the list and store in instance parameter
@@ -408,7 +411,7 @@ def get_postable_commands(self):
         return self._postable_cmds
 
     def post_command(self, command_id):
-        """Request Revit to run a command
+        """Request Revit to run a command.
 
         Args:
             command_id (str): command identifier e.g. ID_REVIT_SAVE_AS_TEMPLATE
@@ -435,23 +438,23 @@ class _ExecutorParams(object):
 
     @property   # read-only
     def exec_id(self):
-        """Return execution unique id"""
+        """Return execution unique id."""
         try:
             return __execid__
         except NameError:
             pass
 
     @property   # read-only
     def exec_timestamp(self):
-        """Return execution timestamp"""
+        """Return execution timestamp."""
         try:
             return __timestamp__
         except NameError:
             pass
 
     @property   # read-only
     def engine_id(self):
-        """Return engine id"""
+        """Return engine id."""
         try:
             return __cachedengineid__
         except NameError:
@@ -488,25 +491,25 @@ def script_runtime(self):
 
     @property   # read-only
     def output_stream(self):
-        """Return ScriptIO"""
+        """Return ScriptIO."""
         if self.script_runtime:
             return self.script_runtime.OutputStream
 
     @property   # read-only
     def script_data(self):
-        """Return ScriptRuntime.ScriptData"""
+        """Return ScriptRuntime.ScriptData."""
         if self.script_runtime:
             return self.script_runtime.ScriptData
 
     @property   # read-only
     def script_runtime_cfgs(self):
-        """Return ScriptRuntime.ScriptRuntimeConfigs"""
+        """Return ScriptRuntime.ScriptRuntimeConfigs."""
         if self.script_runtime:
             return self.script_runtime.ScriptRuntimeConfigs
 
     @property   # read-only
     def engine_cfgs(self):
-        """Return ScriptRuntime.ScriptRuntimeConfigs"""
+        """Return ScriptRuntime.ScriptRuntimeConfigs."""
         if self.script_runtime:
             return self.script_runtime.EngineConfigs
 
@@ -598,15 +601,13 @@ def needs_persistent_engine(self):
 
     @property   # read
     def window_handle(self):
-        """``PyRevitLabs.PyRevit.Runtime.ScriptConsole``:
-                Return output window. handle
-        """
+        """Output window handle."""
         if self.script_runtime:
             return self.script_runtime.OutputWindow
 
     @property
     def command_data(self):
-        """``ExternalCommandData``: Return current command data."""
+        """ExternalCommandData: Return current command data."""
         if self.script_runtime_cfgs:
             return self.script_runtime_cfgs.CommandData
 
@@ -710,16 +711,16 @@ def result_dict(self):
 # -----------------------------------------------------------------------------
 
 class _DocsGetter(object):
-    """Instance to safely get document from HOST_APP instance or EXEC_PARAMS"""
+    """Instance to safely get document from HOST_APP instance or EXEC_PARAMS."""
 
     @property
     def doc(self):
-        """Active document"""
+        """Active document."""
         return HOST_APP.doc or EXEC_PARAMS.event_doc
 
     @property
     def docs(self):
-        """List of active documents"""
+        """List of active documents."""
         return HOST_APP.docs
 
 

pyrevitlib/pyrevit/api.py

@@ -1,6 +1,6 @@
 """Provide access to Revit API.
 
-Example:
+Examples:
     >>> from pyrevit.api import AdWindows
 """
 import os.path as op
@@ -30,16 +30,31 @@
 
 
 def get_product_serial_number():
-    """Return serial number of running host instance."""
+    """Return serial number of running host instance.
+
+    Returns:
+        (str): Serial number
+    """
     return UIFrameworkServices.InfoCenterService.ProductSerialNumber
 
 
 def is_product_demo():
-    """Determine if product is using demo license"""
+    """Determine if product is using demo license.
+
+    Returns:
+        (bool): True if product is using demo license
+    """
     return get_product_serial_number() == '000-00000000'
 
 
 def is_api_object(data_type):
-    """Check if given object belongs to Revit API"""
+    """Check if given object belongs to Revit API.
+
+    Args:
+        data_type (object): Object to check
+
+    Returns:
+        (bool): True if object belongs to Revit API
+    """
     if hasattr(data_type, 'GetType'):
         return 'Autodesk.Revit.' in data_type.GetType().Namespace

pyrevitlib/pyrevit/compat.py

@@ -1,6 +1,6 @@
 """python engine compatibility module.
 
-Example:
+Examples:
     >>> from pyrevit.compat import IRONPY277
     >>> from pyrevit.compat import safe_strtype
 """
@@ -42,14 +42,24 @@
 
 
 def urlopen(url):
-    """urlopen wrapper"""
+    """Urlopen wrapper.
+
+    Args:
+        url (str): request url
+    """
     if PY3:
         return urllib.request.urlopen(url)
     return urllib2.urlopen(url)
 
 
 def make_request(url, headers, data):
-    """urlopen wrapper to create and send a request"""
+    """Urlopen wrapper to create and send a request.
+
+    Args:
+        url (str): request url
+        headers (dict[str, str]): headers
+        data (bytes | None): request data
+    """
     if PY3:
         req = urllib.request.Request(url, headers, data)
         urllib.request.urlopen(req).close()