Ykhjuy

When I show others how to use this module I have them make a PROJECT instance and then add other objects.

>>> from Abstracted import PROJECT



>>> project = PROJECT('bob', Y_factor=2, use_MQTT=True)

MQTT status: started

Yay, your new Project named "bob" has been created

They may do this from a terminal which does not show the docstring balloons the way IDLE and many other IDEs can. So instead I've found a way so that when they type the instance, a few lines only of helpful text appears. This is in contrast to help() which can generate dozens of lines and scroll their previous work right up off the top of the screen.

>>> project

PROJECT("bob")

  intantiate with p = PROJECT(name, Y_factor=None, use_MQTT=False)

  later use start_MQTT(), stop_MQTT(), and

  add THINGs with p.new_CARROT(name) or p.new_ONION(name, n_rings=None)

>>> carrot = project.new_CARROT('carrotte')

a CARROT was added!

>>> onion = project.new_ONION('onionne', n_rings=42)

an ONION was added!

Type the object, and a few lines with a few "main methods" and helpful hints shows up. This is the functionality that I am asking about

>>> carrot

CARROT("carrotte")

  instantiate with c = CARROT(project, name)

  change thread with c.change_thread_value(new_value)



>>> onion

ONION("onionne"), n_rings=42

  instantiate with o = ONION(project, name, n_rings=None)

  increase onionrings with o.multiply(factor)

Question: Am I re-inventing the wheel? Is this recreating something that python does naturally? I've only really learned about docstrings in the past 24 hours, so maybe there are better ways to do this?

Here is Abstracted.py, an abstracted version of a large module. All of the functionality I'm asking about is contained here.

import time, datetime, logging, socket, Queue

from threading import Thread, Lock, Event

#import paho.mqtt.client as mqtt 



important_lock = Lock()   # the rest of threading not shown



class PROJECT(object):

    """  intantiate with p = PROJECT(name, Y_factor=None, use_MQTT=False)

  later use start_MQTT(), stop_MQTT(), and

  add THINGs with p.new_CARROT(name, X) or p.new_ONION(name)"""

    def __init__(self, name, Y_factor=None, use_MQTT=False):



        self.name               = name

        self.use_MQTT           = use_MQTT

        self.things             = 

        if Y_factor == None:

            Y_factor = -1

        self.Y_factor           = Y_factor

        if self.use_MQTT:

            status = self.start_MQTT()

            print "MQTT status: {}".format(status)

        self.info = ('{self.__class__.__name__}("{self.name}")'

                .format(self=self))

        print 'Yay, your new Project named "{}" has been created'.format(self.name)



    def __repr__(self):

        return (self.info + 'n' + self.__doc__)



    def doc(self):

        print self.__doc__



    def start_MQTT(self, start_looping=False):

        """(start_looping=False) creates an MQTT client attribute and connects it"""

        # do stuff

        status = 'started'

        self.client = 'client instance'

        return status



    def stop_MQTT(self):

        """disconnects from MQTT"""

        # do stuff

        status = 'stopped'

        return status



    def new_ONION(self, name, n_rings=None):

        """def new_ONION"""



        onion = ONION(project=self, name=name, n_rings=n_rings)



        self.things.append(onion)

        print "an ONION was added!"

        return onion        



    def new_CARROT(self, name):

        """def new_CARROT"""



        carrot = CARROT(project=self, name=name)



        self.things.append(carrot)

        print "a CARROT was added!"

        return carrot



class THING(object):

    """THING!"""



    def __init__(self, project, name):

        """THING.__init__!"""



        self.project              = project

        self.name                 = name

        self.Y_factor             = self.project.Y_factor



    def __repr__(self):

        return (self.info + 'n' + self.__doc__)



class ONION(THING):

    """  instantiate with o = ONION(project, name, n_rings=None)

  increase onionrings with o.multiply(factor)"""

    def __init__(self, project, name, n_rings=None):

        """ONION.__init__!"""

        if n_rings==None:

            n_rings = 7

        self.n_rings = n_rings



        THING.__init__(self, project, name)



        self.info = ('{self.__class__.__name__}("{self.name}"), n_rings={self.n_rings}'

                .format(self=self))



    def multiply(self, factor):

        if type(factor) in (int, float):

            self.n_rings *= factor



class CARROT(THING):

    """  instantiate with c = CARROT(project, name)

  change thread with c.change_thread_value(new_value)"""

    def __init__(self, project, name):

        """CARROT.__init__!"""



        self.thread_value = 1



        THING.__init__(self, project, name)



        self.info = ('{self.__class__.__name__}("{self.name}")'

                .format(self=self))



    def change_thread_value(self, new_value):

        with important_lock:

            self.thread_value = new_value

I realize this is one of the central premises of your program, but printing help docstrings during normal use of the program is highly unusual behavior and likely to be annoying to users of your program. For example, a user might already know how to use your API, and doesn't need to be told how every time they invoke it; it would just clutter up the command line. Besides, you're solving a problem that doesn't really need to be solved: a class docstring may scroll the screen as described, but function and method docstrings do not, and the Python REPL interpreter already allows you to short circuit the scrolling.

Instead, I would recommend using more descriptive and helpful docstrings. For example, informing the user of the class calling conventions in isolation is not useful; explaining what the class's intended use is, and what the various parameters mean would be more useful. PEP 257 provides guidance on how to write good docstrings.