Variable naming suggestion (contains time boundary)

This question is just about a single object attribute naming. I hope it is not off-topic since important aspect of Python is readability of code. :slight_smile:

The application I am writing performs actions on firewall rules. The actions depend on the last time the rule matched a connection (it is called rule hit). The class RuleMetainfo contains information for a single rule.

I had a mental block for naming the attribute how_to_name_this_time_boundary (and my English is lousy). Do you have any ideas? Do you know about any article which would help with the process of inventing variable names in general?

class RuleMetainfo:
    """Store single rule meta information controlling cppolc actions.

    Meta information for a single rule is obtained from statements in a specially
    formatted part of the rule's comment. Additional meta information comes from rule's
    dedicated meta information fields and all is combined with default values from the
    application configuration.
    """

    ...
    statements: dict[str, Any]
    """Extracted and parsed statements with their arguments."""
    thresholds: metainfo_thresholds.RuleThresholds
    """Thresholds for the rule (time period thresholds)."""
    how_to_name_this_time_boundary: datetime.datetime
    """Date boundary after which the rule hits are relevant for planning actions."""

During writing of this question I came up with the first variant below (probably the Rubber duck debugging - Wikipedia effect). I think the variant is OK but since I wrote almost all this I think possible discussion could be beneficial for others.

My variants:

  • hits_relevant_since
  • last_modification_effective - because the boundary comes from the rule’s last modification datetime, I find this rather long and too oriented to the source of the information.

Can define it a bit more, Václav? Is it…

  • the time passed since the last hit?
  • the time between the last hit and a recent hit?
  • an absolute time? (such as the date the rule was last hit)
  • …or a relative time? (how much time has passed since the rule was last hit)

rule_active_date
rule_active_thresh [abbreviations are generally not a best practice]
rule_time_boundary
rule_relevant_boundary
rule_relevant_date
rule_dormancy
rule_latency (works well for “was dormant but had a recent hit”. Could be confused with “network latency”, though)
rule_idle_time
rule_inact_time (another abbreviation…) :frowning_face:
rule_quiet_time

Thanks for your help! (I fixed a mistake I made: it is an object attribute, not a class attribute)

The attribute is going to be used to store a point in time. The value is derived from the rule’s last modification time but ignoring modifications made by the application itself. The application does not change the executive content of the rule, it changes just the rule’s comment or placement. The application is to be executed in phases in intervals of multiple weeks or months.

Rule hits before this point in time (i.e. in the previous executive form of the rule) will not be significant for the application’s actions because we are interested only in what happened with the rule in its current/latest form.

I thinks it is redundant to repeat the word rule in the attribute name because the whole class RuleMetainfo is about a rule and objects created will also have rule in their name: rule_metainfo = RuleMetainfo().

I think the name I came up with during writing of my question is OK: hits_relevant_since

  • explains that the value can be used to filter out irrelevant hits (hits_relevant…)
  • says that it is a point in time (since)
  • conveys the time interval: from the point in time till now (since)

Edit: Now I see a possible problem: The noun in the variable name (hits) can suggest that the variable will very closely relate to rule hits (i.e. hit count, list of hits etc.). Which meaning do you see first when you see the variable name?

  • hits_relevant_since_time ? this starts to be too long :slight_smile:

In English, the ‘time’ is strongest since the subject of a sentence usually comes first. This is for subject-verb-object sentence grammar. For adjective-adjective-noun grammar (like “little red car” and a bit like hit_relevance_time), the time at the end end is strongest but `hits_relevant_since’ is closer to sentence grammar (subject-verb-object).

This is perfectly sensible. The context provides the ‘rule’ part of the variable’s function/purpose/significance.

I’m still not following your use case 100% but it sounds like the variable is time_since_…something.

What else changes the rule’s comment or placement in addition to the application?

time_since_update
time_since_revised
time_since_mod
brozolator_mod_time
`brozolator_mod_point’

This brings up the term period, but you’ve been describing a “point in time”, not a period.

What about effective_time (as in, the time at which the rule goes into effect)?

activation_time?

Other have made various reasonable name suggestions.

I’m just wondering:

how_to_name_this_time_boundary: datetime.datetime
"""Date boundary after which the rule hits are relevant for planning actions."""

Are you sure you don’t just want a UNIX time here, as from
time.time()? I tend to use datetime just for presentation.

Cheers,
Cameron Simpson cs@cskk.id.au

1 Like

Thank you all for your suggestions!

Yes this is a good suggestions, thanks. UNIX time is certainly in orders of magnitude more effective both in storage space and speed. I will reconsider it for the future. Here are my reasons for datetime:

  • Used in an older code which makes part of this one.
  • The problem that the epoch (time 0) can differ between platforms!
  • Typing distinction from int / float. I would probably use NewType for UNIX time.
    • Also everyone (knowing the standard library) at first sight recognizes the datetime type and knows what to expect from it.
  • Existing methods for computations with time units (minutes, hours, days…).
    • I prefer to take these common things from the standard library instead of copying them again and again to my programs or installing my tiny utility library with very unstable interface.
  • Existing methods for a limited (but almost completely sufficient) subset of ISO 86601 format.
  • Completely unsure how leap seconds work in UNIX time.
  • I think almost all tutorials and presentations show the datetime type as the new and preferred way of working with date and time in Python.

By Václav Brožík via Discussions on Python.org at 14Jun2022 21:43:

  • The problem that the epoch (time 0) can differ between platforms!

time.time() should be a UNIX time on Windows and UNIX (seconds since
start of 1970-01-01 UTC). I guess there is gmtime(0) as the docs say
should you ever care.

One can go quite a long way by treating it as opaque, anyway. I normally
only care about whether a time is in the future or the past, or the time
between two other times. When I care about the absolute number I’m
often in a domain where a datetime is also meaningful. Maybe - this is
rare for me.

  • Typing distinction from int / float for free. I would probably use NewType for UNIX time.

I think it returns a float on all platforms, even if the OS time call
returns an int. (I’m not sure any current Python platform has a clock
that coarse anyway.)

  • Existing methods for computations with time units (minutes, hours, days…).

True, though timezones and leap seconds etc make “days” upwards a
fuzzier concept that you might like.

If I need to compute, say, “a month in the future” I’ll convert to
datetime-in-local-timezone, add a month with timedelta, back convert.
That lets the calendar complexities be handled by datetime, and leaves
me with a reliable point-in-time UNIX time for the real work.

  • I prefer to take these common things from the standard library instead of copying them again and again to my programs or installing my tiny utility library with very unstable interface.

I prefer my tiny utility library :slight_smile: At least it means I do things the
same way all the time, and solve problems just once. (Well, of course I
re-solve problems in a better way as I trip over limitations and bugs,
but I want to solve just once.)

  • Existing methods for a limited ISO 86601 (but almost completely sufficient) format.

Aye. But again, this is presentation.

  • Completely unsure how leap seconds work in UNIX time.

There’s no such thing in UNIX time. It is elapsed time. Like there are
no timezones. That is one of the nice things about it.

Cheers,
Cameron Simpson cs@cskk.id.au