Add calculate_age_group

[mjtamlyn]

This utility function works out the age group under AGB rules, given a year of birth and the year the event takes place in.

I've written this (or something like it) more than once, and it seems like a "core" utility function for AGB applications, usable in records code, entry systems, rankings etc.

I think I've done most of the docstrings, testing, type checks etc in roughly the right way, but let me know if htere's things missing.

[mjtamlyn]

The failing test on python 3.10 relates to the use of typing.NotRequired for the optional keys min_age and max_age. It doesn't look like this has an obvious polyfill, and I don't think I know enough about python typing to know how to work around it.

[jatkinson1000]

Thanks for this @mjtamlyn I think it's a really useful utility

Did some slight restructuring and added null to the json to satisfy Python 3.10 with all ages having a max/min which could be None. Also relocated the tests to follow the current structure.

Hopefully this all still works for the situations in which you envisage using this in your code, but let me know if not!

My only comment would be whether it is worth renaming the function to calculate_agb_age_group()? This would match the call signs for the agb classifications and leave open to implementing other schemes in future.
Edit: I'm currently implementing Archery Australia classifications - I wonder if passing an optional argument for rules (like with handicaps) might be useful. e.g. "AGB" vs "AA".

[mjtamlyn]

Thanks for the updates to make it work with the strict typing.

I'm happy for now to look at just renaming to calculate_agb_age_group as that's going to cover the majority of use cases for now. However, we should think about different "age group schemes" in more detail. Some use cases include:

• Archery Australia as you mentioned
• Strict WA age groups, which is technically a subset of AGB age groups
• Extended age groups, for example some events might run U10s, or the AGB 50+ event runs 65+
  I agree I was only have way there with providing alternate JSON, so you'd also need to provide an alternate enum.

Even if we factor this out in the long term, it's reasonable to expose calculate_agb_age_group with the current API, and then to implement a more generic function in the future that this uses.

So I reckon just rename the fn and we're good to go?

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.31%. Comparing base (31c74ca) to head (eef1291).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #134      +/-   ##
==========================================
+ Coverage   98.28%   98.31%   +0.03%     
==========================================
  Files          34       36       +2     
  Lines        2326     2380      +54     
==========================================
+ Hits         2286     2340      +54     
  Misses         40       40              

Files with missing lines	Coverage Δ
archeryutils/classifications/__init__.py	100.00% <100.00%> (ø)
archeryutils/classifications/age_calculator.py	100.00% <100.00%> (ø)
...cheryutils/classifications/classification_utils.py	78.46% <ø> (ø)
tests/unit/classifications/test_age_calculator.py	100.00% <100.00%> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[jatkinson1000]

@mjtamlyn I just rebased, updated to use the new ages enum, and renamed the function.

I believe this is good to go if you can take a quick look and are happy.

My final thought is whether this should be in the classifications module or a new module (rules, ages, governing_bodies?), as it could be used for a whole bunch of things besides classifications?

Let me know your thoughts and approval and then I'll look to merge.

[mjtamlyn]

PR in its current form looks great. I'm indifferent about its location.