Draft: WorkingPlane.py clean up imports and docstrings

Small spacing fixes like imports in separate lines
for more clarity, and the position of the license.

Cleaned up the class docstring, so it is in only one place
below the class definition. Also small fixes
in the docstrings of the class methods.

The class is now in upper case `Plane` to conform with Python
guidelines. An alias in lowercase `plane` is still provided
for compatibility purposes; this will be deprecated
in the future.

src/Mod/Draft/WorkingPlane.py

@@ -1,20 +1,3 @@
-## @package WorkingPlane
-#  \ingroup DRAFT
-#  \brief This module handles the Working Plane and grid of the Draft module.
-#
-#  This module provides the plane class which provides a virtual working plane
-#  in FreeCAD and a couple of utility functions.
-"""@package WorkingPlane
-\ingroup DRAFT
-\brief This module handles the working plane and grid of the Draft Workbench.
-
-This module provides the plane class which provides a virtual working plane
-in FreeCAD and a couple of utility functions.
-The working plane is mostly intended to be used in the Draft Workbench
-to draw 2D objects in various orientations, not only in the standard XY,
-YZ, and XZ planes.
-"""
-
 # ***************************************************************************
 # *   Copyright (c) 2009, 2010 Ken Cline <cline@frii.com>                   *
 # *                                                                         *
@@ -35,64 +18,87 @@
 # *   USA                                                                   *
 # *                                                                         *
 # ***************************************************************************
+"""Provide the working plane code and utilities for the Draft Workbench.
+
+This module provides the plane class which provides a virtual working plane
+in FreeCAD and a couple of utility functions.
+The working plane is mostly intended to be used in the Draft Workbench
+to draw 2D objects in various orientations, not only in the standard XY,
+YZ, and XZ planes.
+"""
+## @package WorkingPlane
+#  \ingroup DRAFT
+#  \brief This module handles the Working Plane and grid of the Draft module.
+#
+#  This module provides the plane class which provides a virtual working plane
+#  in FreeCAD and a couple of utility functions.
 
+import math
 
-import FreeCAD, math, DraftVecUtils
+import FreeCAD
+import DraftVecUtils
 from FreeCAD import Vector
-from FreeCAD import Console as FCC
 
 __title__ = "FreeCAD Working Plane utility"
 __author__ = "Ken Cline"
 __url__ = "https://www.freecadweb.org"
 
 
-class plane:
+class Plane:
     """A WorkPlane object.
 
+    Parameters
+    ----------
+    u: Base::Vector3, optional
+        An axis (vector) that helps define the working plane.
+        It defaults to `(1, 0, 0)`, or the +X axis.
+
+    v: Base::Vector3, optional
+        An axis (vector) that helps define the working plane.
+        It defaults to `(0, 1, 0)`, or the +Y axis.
+
+    w: Base::Vector3, optional
+        An axis that is supposed to be perpendicular to `u` and `v`;
+        it is redundant.
+        It defaults to `(0, 0, 1)`, or the +Z axis.
+
+    pos: Base::Vector3, optional
+        A point through which the plane goes through.
+        It defaults to the origin `(0, 0, 0)`.
+
     Attributes
     ----------
-    doc : App::Document
+    doc: App::Document
         The active document. Reset view when `doc` changes.
-    weak : bool
+
+    weak: bool
         It is `True` if the plane has been defined by `setup()`
         or has been reset. A weak plane can be changed
         (it is the "auto" mode), while a strong plane will keep
         its position until weakened (it is "locked")
-    u : Base::Vector3
+
+    u: Base::Vector3
         An axis (vector) that helps define the working plane.
-    v : Base::Vector3
+
+    v: Base::Vector3
         An axis (vector) that helps define the working plane.
-    axis : Base::Vector3
+
+    axis: Base::Vector3
         A vector that is supposed to be perpendicular to `u` and `v`;
         it is helpful although redundant.
-    position : Base::Vector3
+
+    position: Base::Vector3
         A point, which the plane goes through,
         that helps define the working plane.
-    stored : bool
+
+    stored: bool
         A placeholder for a stored state.
     """
 
     def __init__(self,
                  u=Vector(1, 0, 0), v=Vector(0, 1, 0), w=Vector(0, 0, 1),
                  pos=Vector(0, 0, 0)):
-        """Initialize the working plane.
 
-        Parameters
-        ----------
-        u : Base::Vector3, optional
-            An axis (vector) that helps define the working plane.
-            It defaults to `(1, 0, 0)`, or the +X axis.
-        v : Base::Vector3, optional
-            An axis (vector) that helps define the working plane.
-            It defaults to `(0, 1, 0)`, or the +Y axis.
-        w : Base::Vector3, optional
-            An axis that is supposed to be perpendicular to `u` and `v`;
-            it is redundant.
-            It defaults to `(0, 0, 1)`, or the +Z axis.
-        pos : Base::Vector3, optional
-            A point through which the plane goes through.
-            It defaults to the origin `(0, 0, 0)`.
-        """
         # keep track of active document.  Reset view when doc changes.
         self.doc = None
         self.weak = True
@@ -122,6 +128,7 @@ def offsetToPoint(self, p, direction=None):
         ----------
         p : Base::Vector3
             The external point to consider.
+
         direction : Base::Vector3, optional
             The unit vector that indicates the direction of the distance.
 
@@ -326,8 +333,8 @@ def alignToPointAndAxis(self, point, axis, offset=0, upvec=None):
         offsetVector.multiply(offset)
         self.position = point.add(offsetVector)
         self.weak = False
-        # FCC.PrintMessage("(position = " + str(self.position) + ")\n")
-        # FCC.PrintMessage(self.__repr__() + "\n")
+        # Console.PrintMessage("(position = " + str(self.position) + ")\n")
+        # Console.PrintMessage(self.__repr__() + "\n")
 
     def alignToPointAndAxis_SVG(self, point, axis, offset=0):
         """Align the working plane to a point and an axis (vector).
@@ -436,14 +443,14 @@ def alignToPointAndAxis_SVG(self, point, axis, offset=0):
 
         # spat_vec = self.u.cross(self.v)
         # spat_res = spat_vec.dot(axis)
-        # FCC.PrintMessage(projcase + " spat Prod = " + str(spat_res) + "\n")
+        # Console.PrintMessage(projcase + " spat Prod = " + str(spat_res) + "\n")
 
         offsetVector = Vector(axis)
         offsetVector.multiply(offset)
         self.position = point.add(offsetVector)
         self.weak = False
-        # FCC.PrintMessage("(position = " + str(self.position) + ")\n")
-        # FCC.PrintMessage(self.__repr__() + "\n")
+        # Console.PrintMessage("(position = " + str(self.position) + ")\n")
+        # Console.PrintMessage(self.__repr__() + "\n")
 
     def alignToCurve(self, shape, offset=0):
         """Align plane to curve. NOT YET IMPLEMENTED.
@@ -631,7 +638,7 @@ def alignToSelection(self, offset=0):
         When the interface is not loaded it should fail and print
         a message, `FreeCAD.Console.PrintError()`.
 
-        See also
+        See Also
         --------
         alignToFace, alignToCurve
         """
@@ -652,7 +659,7 @@ def alignToSelection(self, offset=0):
             return False
 
     def setup(self, direction=None, point=None, upvec=None, force=False):
-        """Setup the working plane if it exists but is undefined.
+        """Set up the working plane if it exists but is undefined.
 
         If `direction` and `point` are present,
         it calls `alignToPointAndAxis(point, direction, 0, upvec)`.
@@ -704,7 +711,7 @@ def setup(self, direction=None, point=None, upvec=None, force=False):
                         # perpendicular to the current view
                         self.alignToPointAndAxis(Vector(0, 0, 0),
                                                  vdir.negative(), 0, upvec)
-                except:
+                except Exception:
                     pass
             if force:
                 self.weak = False
@@ -878,7 +885,7 @@ def getLocalCoords(self, point):
         Base::Vector3
             The relative coordinates of the point from the plane.
 
-        See also
+        See Also
         --------
         getGlobalCoords, getLocalRot, getGlobalRot
 
@@ -944,7 +951,7 @@ def getGlobalCoords(self, point):
         Base::Vector3
             The coordinates of the point from the absolute origin.
 
-        See also
+        See Also
         --------
         getLocalCoords, getLocalRot, getGlobalRot
 
@@ -999,7 +1006,7 @@ def getLocalRot(self, point):
             The relative coordinates of the point from the plane,
             if the plane had its `position` at the global origin.
 
-        See also
+        See Also
         --------
         getLocalCoords, getGlobalCoords, getGlobalRot
         """
@@ -1039,7 +1046,7 @@ def getGlobalRot(self, point):
         Base::Vector3
             The coordinates of the point from the absolute origin.
 
-        See also
+        See Also
         --------
         getGlobalCoords, getLocalCoords, getLocalRot
         """
@@ -1144,7 +1151,7 @@ def getDeviation(self):
             Angle between the `u` vector, and a projected vector
             on the global horizontal plane.
 
-        See also
+        See Also
         --------
         DraftVecUtils.angle
         """
@@ -1156,6 +1163,9 @@ def getDeviation(self):
             return DraftVecUtils.angle(self.u, proj, norm)
 
 
+plane = Plane
+
+
 def getPlacementFromPoints(points):
     """Return a placement from a list of 3 or 4 points.
 
@@ -1185,7 +1195,7 @@ def getPlacementFromPoints(points):
         defined by `points`,
         or `None` is it fails to use the points.
 
-    See also
+    See Also
     --------
     getPlacement
     """
@@ -1198,7 +1208,7 @@ def getPlacementFromPoints(points):
             pl.axis = (points[3].sub(points[0]).normalize())
         else:
             pl.axis = ((pl.u).cross(pl.v)).normalize()
-    except:
+    except Exception:
         return None
     p = pl.getPlacement()
     del pl
@@ -1229,14 +1239,14 @@ def getPlacementFromFace(face, rotated=False):
         defined by `face`,
         or `None` if it fails to use `face`.
 
-    See also
+    See Also
     --------
     alignToFace, getPlacement
     """
     pl = plane()
     try:
         pl.alignToFace(face)
-    except:
+    except Exception:
         return None
     p = pl.getPlacement(rotated)
     del pl