Feat: enrollments can expire

[angela-tran]

Closes #1877

This PR refactors the enrollment phase so that we no longer catch a 409 error to detect existing enrollments. Instead we see if the enrollment already exists for the group. This also allows us to inspect the expiration date of any existing enrollment.

So this PR also introduces support for enrollments that expire. See the table below for expected behavior.

Combinations of states and their expected outcomes

copied directly from our dev meeting notes

Expand to view table

Eligibility state	Enrollment state	Expiration state	Expected enrollment outcome	Expected end page for user
Supports expiration	Not enrolled	No expiration	User can enroll, expiration date set	Enrollment success
Supports expiration	Not enrolled	Future expiration	This state should not be possible	N/A
Supports expiration	Not enrolled	Re-enrollment window expiration	This state should not be possible	N/A
Supports expiration	Not enrolled	Past expiration	This state should not be possible	N/A
Supports expiration	Enrolled	No expiration	Update expiration of existing enrollment	Enrollment success
Supports expiration	Enrolled	Future expiration	Re-enrollment error	Enrollment error with expiration
Supports expiration	Enrolled	Re-enrollment window expiration	Update expiration of existing enrollment	Enrollment success
Supports expiration	Enrolled	Past expiration	Update expiration of existing enrollment	Enrollment success
Does not support expiration	Not enrolled	No expiration	User can enroll, no expiration date set	Enrollment success
Does not support expiration	Not enrolled	Future expiration	This state should not be possible	N/A
Does not support expiration	Not enrolled	Re-enrollment window expiration	This state should not be possible	N/A
Does not support expiration	Not enrolled	Past expiration	This state should not be possible	N/A
Does not support expiration	Enrolled	No expiration	No action	Enrollment success
Does not support expiration	Enrolled	Future expiration	Remove expiration date	Enrollment success
Does not support expiration	Enrolled	Re-enrollment window expiration	Remove expiration date	Enrollment success
Does not support expiration	Enrolled	Past expiration	Remove expiration date	Enrollment success

Some functions to be familiar with

In Python 3.9+, the standard library includes zoneinfo for working with time zones.

Django has a django.utils.timezone module that exposes convenience methods for working with the built-in Python datetime module and incorporates its own USES_TZ and TIMEZONE settings. Because of that, I did not need to use zoneinfo (or pytz which was a popular option before zoneinfo was a thing).

I thought it might be helpful to write out brief summaries of how the functions below are useful in this PR.

Used in application code

django.utils.timezone.now()

This function creates a standard Python datetime.datetime object representing the current point in time.

More importantly, if USE_TZ is True, timezone.now() will return an aware datetime with UTC as its timezone.

Benefits has USE_TZ set to True, so we can rely on this as an easy way to make an aware "now" datetime , for example in _is_expired and _is_within_reenrollment_date.

django.utils.timezone.localtime(value=None, timezone=None)

This function lets you give it an aware datetime and converts it to the timezone that you pass in.

If you don't give it a value, it will use timezone.now() for value.

This was useful for calculating the expiration date since we want to make sure the expiration time is midnight Pacific Time.

django.utils.timezone.get_default_timezone()

This function returns what you set the TIME_ZONE setting to, which Django refers to as the "default time zone".

In this PR, we set Benefits's default timezone to America/Los_Angeles. This means we can call timezone.get_default_timezone and give it to timezone.localtime to create an aware datetime that is in Pacific Time.

Aside: "current time zone" is initially the same as the default time zone. If you call timezone.activate with some other time zone, that's when they'd be different. The way I think about this is that it's for cases like, for example, if we gave the user a drop-down of timezones and set their selection as the "current time zone" for their requests to the server. With that understanding, we can see that we don't want to use "current time zone" to calculate the expiration date.

Used only in test code

django.utils.timezone.make_aware(value, timezone=None)

This function lets you give it a naive datetime and a timezone to make an aware datetime. This is useful when you need a specific datetime, which I needed for testing. If there is a more succinct way to do this, I'm open to it.

[github-actions]

Coverage report

Click to see where and how coverage changed

File	Statements	Missing	Coverage	Coverage (new stmts)	Lines missing
benefits
settings.py
benefits/enrollment
views.py
Project Total

This report was generated by python-coverage-comment-action

[thekaveman]

Good progress on this!

I have a few suggestions for cleaning up the code flow, and noticed a few bugs in the enrollment logic.

[thekaveman]

Just a minor change but this is looking great.

I can't add a line comment, but I think we can drop a few log statements that aren't very useful (trying to reduce noise and also reduce code in this file!):

Line 76

logger.debug(f"Session contains an {models.EligibilityType.__name__}")

And Line 78

logger.debug("Read tokenized card")

[angela-tran]

I can't add a line comment, but I think we can drop a few log statements that aren't very useful (trying to reduce noise and also reduce code in this file!):

Removed the log statements in e65d076

[angela-tran]

Rebased this to resolve merge conflicts 😄