Docstrings – Handling Subclass Method Documentation

documentationinheritance

I have an abstract class structured somewhat like this:

class AbstractQuery(object, zip_code):
    def execute(self):
        """
        Retrieve information about a zip code
        The information returned will depend on the subclass
        """
        url, params = self._build_query(zip_code)
        response = requests.get(url, params=params)
        if self._is_valid(response):
            # etc.

    def _build_query(self, zip_code):
        """
        Returns a tuple (url, params) where
        url is the url of the API to query and
        params are the query params for the API call
        """
        raise NotImplementedError

    def _is_valid(self, response):
        """
        Returns True if response contains information necessary
        to continue processing
        """
        raise NotImplementedError

_build_query for example is always going to do the same thing, there's just going to be minor implementation differences. Do I just keep the docstring in the base class? Or copy/paste it down and violate DRY? What would a user or maintainer of these classes want to see?

Best Answer

From PEP 257:

The docstring for a class should summarize its behavior and list the public methods and instance variables. If the class is intended to be subclassed, and has an additional interface for subclasses, this interface should be listed separately (in the docstring). The class constructor should be documented in the docstring for its __init__ method. Individual methods should be documented by their own docstring.

If a class subclasses another class and its behavior is mostly inherited from that class, its docstring should mention this and summarize the differences. Use the verb "override" to indicate that a subclass method replaces a superclass method and does not call the superclass method; use the verb "extend" to indicate that a subclass method calls the superclass method (in addition to its own behavior).

So if you want to follow Python standards, use language indicating that the method is overriden in your subclass docstring.

Related Solutions

Python Documentation – How to Split Between Docstrings and Sphinx

The Python standard library keeps all of its Sphinx documentation separate, forgoing the autodoc feature entirely, and uses much more brief docstrings in the source files. Thus, the following practice is perhaps best:

Docstrings in source code should not use Sphinx directives, using only light reST formatting for readability. Because (good) Python code is quite clear on its own, keep docstrings informative but simple. These should be primarily for project devs and anyone digging into the source code.
Actual end-user (or developers for libraries) documentation should be taken care of by Sphinx. Use autodoc when suitable, adhering to the above.

Design Patterns: Subclass with Methods Only, No Variables

Having three separate classes might make sense if you know you're going to add some special members to some of these subclasses and you just haven't gotten around to it yet (but you're going to really soon, right?).

Normally, I'd agree with the senior developer: This seems like an unecessary complication. Could you create an enumeration called Frequency and use that to determine which type of Medication you're dealing with, something like this pseudo-code:

Enum MedicationFrequency{MONTHLY, DAILY, WEEKLY, HOURLY}

class Medication
{
    private MedicationFrequency frequency;
    ...
}

I suppose if you really want to keep the different implementations completely separate, you could try to inject specific algorithms into the Medication instances. Maybe something like this:

Interface MedicationProcess
{
   public void doSomething();
   public String getWhen();
   public MedicationFrequency getFreq();
}

class WeeklyMedProcess implements MedicationProcess
{
   String weekdays;
   public MedicationFrequency getFreqy() { return MedicationFrequency.WEEKLY;}
   public String getWhen() { return weekdays; }
   //...
}

class DailyMedProcess implements MedicationProcess
{
   public MedicationFrequency getFreqy() { return MedicationFrequency.DAILY;}
   //...
}

class MonthlyMedProcessimplements MedicationProcess
{
   String monthdays;
   public MedicationFrequency getFreqy() { return MedicationFrequency.MONTHLY;}
   public String getWhen() { return monthdays; }
   //...
}

class Medication
{
    private MedicationProcess someProcess;
    private String updateColumnName;

    public void setUpdateColumnName(String s)
    {
        this.updateColumnName= s;
    }

    public void setProcess(MedicationProcess p)
    {
        this.someProcess = p;
    }

    public doMedicationThing()
    {
        this.someProcess.doSomething();
    }
}

Doing this in Java, You'd have a Spring configuration that might look like this:

<bean id="dailyMedProc" class="DailyMedProcess/>
<bean id="weeklyMedProc" class="WeeklyMedProcess/>

<bean id="medication1" class="Medication">
    <property name="process" ref="dailyMedProc/>
    <property name="updateColumnName" value="weekdays"/>
</bean>

<bean id="medication" class="Medication">
    <property name="process" ref="weeklyMedProc/>
    <property name="updateColumnName" value="monthdays"/>
</bean>

To answer your quesion about weekdays and monthdays, there are many ways to do this and it's not very clear from your question just what weekdays and monthdays are. Since you show them to be single variables, I'll assume they are just comma-separate strings.

It sounds like you also have columns in some table named weekdays and monthdays which need to be set to null if there is no value. Since you already know the frequency of the Medication (via its someProcess.getFreq), you know which field to set to null. The implementors of MedicationProcess can be required to implement getWhen, which will return the comma-separated list of days/month-days. With these two pieces of information, you can easily update the correct columns.

Having Medication have knowledge over what to do when specific MedicationFrequencies are encountered does break the design pattern a little bit. It's not great, but it's a simple solution.

If you don't like that, you could include the column name that should be updated for a specific instance of Medication. Only slightly better - I don't like mixing that sort of low-level data access into such classes, but I haven't seen the rest of your design, so maybe it's OK here...

Another option would be to have the MedicationProcess do its own database insert/update. This is a little trickier and I can't really give any concrete examples of how to do this without knowing the details about your schema, though I think this would be the best solution, if you can implement it.

There are other ways to implement the strategy pattern, depending on the tools and frameworks available to you.

Also, see: https://stackoverflow.com/questions/17721623/advantages-of-using-strategy-pattern-in-php The question is PHP-specific, but the answer is not.

Best Answer

Related Solutions

Python Documentation – How to Split Between Docstrings and Sphinx

Design Patterns: Subclass with Methods Only, No Variables

Related Topic