[Tutor] CONSTANTS -- Is it appropriate to use uppercase names within a function or method?

[boB Stepp]

On Tue, Nov 12, 2019 at 1:08 PM Mats Wichmann <mats at wichmann.us> wrote:
>
> On 11/12/19 10:43 AM, boB Stepp wrote:

> ...You can
> also configure pylint not to issue that particular warning - describing
> how is a bit out of scope for this message.

A pity.  Trying to determine how to configure pylint is what I am
currently struggling with.  I am not finding its official
documentation easy to comprehend.

> >     def get_days_to_goal(goal_date_obj, start_date_obj=None):
> > --    """Given a start date object and a goal date object, return the
> > number of
> >        days it will take to attain a goal, counting the start date as
> > one of these
> >        days.
> >
> >        start_date_obj:  A date object giving the start date for further
> >            calculations.
> >
> >        goal_date_obj:  A date object giving the date by which the goal
> > should be
> >            attained.
> >
> >        days_to_goal:  An integer giving the number of days to achieve the goal,
> >            counting today as one of those days.
> >        """

> Your function signature has two parameters, your docstring has three,
> which hints at a mismatch. Since you're playing with tools anyway, you
> could let the tools generate the initial docstring, then you can fill it
> in.  Many editors have some way to generate a template docstring (often
> with a selector to pick the style of docstring markup you prefer), and
> for those that don't, the external Pyment tool could do that. I pasted
> just the function signature (followed by pass) into a file and it
> generated this:

A good thought.  I suppose over time I would save a fair amount of the same.

> # Patch generated by Pyment v0.3.3
>
> --- a/x.py
> +++ b/x.py
> @@ -1,3 +1,9 @@
>
>   def get_days_to_goal(goal_date_obj, start_date_obj=None):
> +    """
> +
> +    :param goal_date_obj:
> +    :param start_date_obj:  (Default value = None)
> +
> +    """
>       pass
>
>
> or if you prefer the more human-readable Google style:
>
> # Patch generated by Pyment v0.3.3
>
> --- a/x.py
> +++ b/x.py
> @@ -1,3 +1,12 @@
>
>   def get_days_to_goal(goal_date_obj, start_date_obj=None):
> +    """
> +
> +    Args:
> +      goal_date_obj:
> +      start_date_obj:  (Default value = None)
> +
> +    Returns:
> +
> +    """
>       pass
>
> Don't document days_to_goal in the docstring - it's just a variable (an
> obvious one at that) internal to the function, which then is immediately
> returned.

I just finished rereading PEP 257.  I had forgotten that the intent is
to help someone to understand the function's use, so what you say
makes sense in that context.

> ===
>
> Since this function has a very specific expectation of the types of the
> arguments, you could add type hints to say so, and your tooling should
> warn you if there are mismatches.  e.g.,  assuming you've done
>
> from datetime import date

Yes.

> so that date is a known symbol, you can rewrite your signature annotated
> like so:
>
> def get_days_to_goal(goal_date_obj: date, start_date_obj: date = None)
> -> int:

I have enabled MyPy linting in my editor, but as I have not yet read
up on type hints/annotations, I currently have none to lint.

>
> I'm not (yet?) a "use type hints everywhere" guy, but this seems like a
> good place for it - your function would blow up if sent parameters of
> different types than a datetime.date, so it's useful to provide a way
> for at least some tooling to detect that - or else program the function
> a bit more defensively.

The program from which I drew today's posting was meant to be a
simple, throw-away script to inspire me to actually read and study to
the end the BIG BOOK OF PYTHON, i.e., "Learning Python, 5th ed." by
Lutz.  Alas!  Its inspiration proved to be short-lived.  However, in
typical boB style, I could not resist toying around with it to apply
things to it as I learned them.

IF I were to use type annotations as you suggest, would there be any
point to the more expansive docstring?  The combination of type
annotations with already very descriptive variable names seems to make
any more description superfluous.

-- 
boB