On docstrings, here are some considerations to make. 1. Is there a convention I need to follow? (e.g. within the company, previous or related code you have written etc.) 2. Do I need/want automatic generation of documentation?
On 2, if you write your docstring in a particular way, then there are parsers out there (primarily Sphinx) capable of interpreting this and produce HTML documentation, similar to Python’s own documentation <https://docs.python.org/2/library/functions.html#file>. Personally, I’ve found that I rarely generate documentation, but still follow the syntax. That way, I don’t have to come up with my own syntax, and can benefit from the experience from others, linters and other goodies you get from sticking to standards. If one day the requirement came about that I *do* need documentation, well hey, that’s a neat bonus too. On docstrings conventions, these are the most common that I know of. - Sphinx <https://pythonhosted.org/an_example_pypi_project/sphinx.html#function-definitions> - Google Docstring <https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html> I personally stick with Google’s approach because I found it a good balance between readability in the generated HTML pages, and the code itself. But I see a lot of Sphinx out there as well, and have no trouble understanding that either. Hope it helps! On 27 October 2016 at 04:07, Alok Gandhi <[email protected]> wrote: > Most of what I wanted to comment is already covered by Justin and Marcus. > Here are my very very minor comments (consider them as extras): > > 1. self._state instead self.state (~ by convention, self.state should be > used only if `state` is public. From your code, and I presume, `state` is > not public. I usually start with ALL attributes - (methods, properties) as > private (starting with an '_') and then make them public, further down the > development as the need arises. > > 2. > >> # Documenting states >> STATE_ROOT_SELS = "root_sels" >> STATE_USER_SELS = "user_sels" >> > > are just enums and just can be alternatively written as, which are more > convenient to use > > ( > STATE_ROOT_SELS, > STATE_USER_SELS,) = range(2) > > > > This way you can add huge number of states, (though not required in your > case), simply by adding another line, without having to worry about the > corresponding strings. The bonus is more protection from potential bugs > when you accidentally assign "same string val" to different attrs. > > The above code can be made more procedural (although a bit convoluted), > and can be used at module level - > > from collections import namedtuple > > ALLOWED_STATES = [ > 'ROOT_SELS', > 'USER_SELS', > # Feel free to add more states here > ] > > SELECTION_STATES = (namedtuple('SELECTION_STATES', ALLOWED_STATES) > (*range(len(ALLOWED_STATES)))) > > > Enums became a part of python standard library as of 3.4, here is the PEP > <https://www.python.org/dev/peps/pep-0435/>, > > In the light of all of the above, the code becomes: > > from collections import namedtuple > > ALLOWED_STATES = [ > 'ROOT_SELS', > 'USER_SELS', > # Feel free to add more state here > ] > > SELECTION_STATES = ( > namedtuple('SELECTION_STATES', > ALLOWED_STATES)(*range(len(ALLOWED_STATES)))) > > class HierarchyDialog(QtGui.QDialog): > def __init__(self, state, parent=None): > super(HierarchyDialog, self).__init(parent=parent) > > self.setWindowTitle('Hierarchy Dialog') > self.setModal(False) > > self._state = state > > if self._state == SELECTION_STATE.ROOT_SELS: > # Run function_A() > pass > elif self._state == SELECTION_STATES.USER_SELS: > # Run function_B() > pass > else: > cmds.warning("Please check your selections." > " Either select some nodes or a root node") > > def run_dialog(): > selection = cmds.ls(selection=True) > if not selection: > cmds.warning("Please select a Stack or some nodes") > return > > state = None > if len(selection) == 1 and cmds.nodeType(selection) == 'nurbsSurface': > state = SELECTION_STATES.ROOT_SELS > elif len(selection) >= 1: > for items in selection: > if not cmds.nodeType(selection) == 'nurbsSurface' in items: > state = SELECTION_STATES.USER_SELS > > dialog = HierarchyDialog(state) > dialog.show() > return dialog > > > > On Thu, Oct 27, 2016 at 9:44 AM, Justin Israel <[email protected]> > wrote: > >> >> >> On Thu, Oct 27, 2016 at 2:16 PM likage <[email protected]> wrote: >> >>> >>> 2. Is there any chance that I will need to add in an `else` statement >>> should the self.state not conform to either `self.STATE_ROOT_SELS` or >>> `self.STATE_USER_SELS`? Otherwise, I suppose I can stopped such from >>> happening in the run_dialog function, right? >>> >>> >>> Can you raise a ValueError if they don't pass a valid constant? >>> >>> >>> Hey Justin, was wondering if you could give me an example scenario as to >>> when this will occurs? >>> I asked because I tried selecting objects of other node types etc, I am >>> getting errors (need to rewrite my logic here) but only within the >>> `run_dialog` and it does not seems to pass in this `else` statement.. >>> >> >> In your run_dialog() function, it looks like there is the potential for >> "state" to be an empty string, and passed to your dialog constructor. If it >> is not acceptable for your dialog to operate without a valid state value, >> then your dialog should raise a ValueError. If it can operate with an >> invalid state value, then don't raise an exception. >> >> So in your run_dialog(), what does it mean for your dialog to receive an >> empty string for state? Can the dialog still be useful? >> >>> -- >>> You received this message because you are subscribed to the Google >>> Groups "Python Programming for Autodesk Maya" group. >>> To unsubscribe from this group and stop receiving emails from it, send >>> an email to [email protected]. >>> To view this discussion on the web visit https://groups.google.com/d/ms >>> gid/python_inside_maya/2cd81c76-93f9-4837-81b8-be04c5d90bb4% >>> 40googlegroups.com >>> <https://groups.google.com/d/msgid/python_inside_maya/2cd81c76-93f9-4837-81b8-be04c5d90bb4%40googlegroups.com?utm_medium=email&utm_source=footer> >>> . >>> For more options, visit https://groups.google.com/d/optout. >>> >> -- >> You received this message because you are subscribed to the Google Groups >> "Python Programming for Autodesk Maya" group. >> To unsubscribe from this group and stop receiving emails from it, send an >> email to [email protected]. >> To view this discussion on the web visit https://groups.google.com/d/ms >> gid/python_inside_maya/CAPGFgA1EGuYDhMYN4LDGb%2BR3uX8D% >> 3D3Aiom_3KUz9uv85jDBK9Q%40mail.gmail.com >> <https://groups.google.com/d/msgid/python_inside_maya/CAPGFgA1EGuYDhMYN4LDGb%2BR3uX8D%3D3Aiom_3KUz9uv85jDBK9Q%40mail.gmail.com?utm_medium=email&utm_source=footer> >> . >> >> For more options, visit https://groups.google.com/d/optout. >> > > > > -- > > -- > You received this message because you are subscribed to the Google Groups > "Python Programming for Autodesk Maya" group. > To unsubscribe from this group and stop receiving emails from it, send an > email to [email protected]. > To view this discussion on the web visit https://groups.google.com/d/ > msgid/python_inside_maya/CAPaTLMR43Z3VwmknqEN91HTuNM7bt > 1Kb_BM%2BsSrQdPrNmp6j-A%40mail.gmail.com > <https://groups.google.com/d/msgid/python_inside_maya/CAPaTLMR43Z3VwmknqEN91HTuNM7bt1Kb_BM%2BsSrQdPrNmp6j-A%40mail.gmail.com?utm_medium=email&utm_source=footer> > . > > For more options, visit https://groups.google.com/d/optout. > -- *Marcus Ottosson* [email protected] -- You received this message because you are subscribed to the Google Groups "Python Programming for Autodesk Maya" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To view this discussion on the web visit https://groups.google.com/d/msgid/python_inside_maya/CAFRtmOBc3iir%3DtjJ-M1q3pW%2BcmMfYki-VJeJOtoz858nJ-Ma%3Dg%40mail.gmail.com. For more options, visit https://groups.google.com/d/optout.
