(Expecting the Mac OS Actions test jobs to fail, as there are issues in the dependency setup on master I need to sort out. Test suite does pass locally at this stage.)

@davidhassell: (for after the long weekend if you have started yours) I thought I'd let you see this at this nearly-done stage in case you have any comments on the implementation & approach, etc., & so you can become familiar with how the logging will work in code terms. If you want to do a formal code review, that's fine too, in which case just assign yourself.

Hi Sadie, I wonder if the verbose keyword should either be None or an int (rather than a bool), so that the control can be fine-tuned at the function level. I.e. verbose can be one of None, 0, 1, 2, 3, 4, 5, where None, the default, means "use the setting of cfdm.LOG_SEVERITY_LEVEL, 0 means "disable logging" and a +ve integer sets that log level. For backwards compatibility (and not documented), the old setting of False would map to 0;andTrue` could map to the most appropiate +ve int.

What do you think?

Should we take this opportunity to rename the package level functions to lower case: ATOL, RTOL, LOG_SEVERITY_LEVEL (but not cfdm.CF)? The upper case versions of ATOL, RTOL would remain as aliases.

That said, these functions do have something in common, which the other package level functions don't have, in that they are all about the setting of global constants.

I don't mind either way - what do you think?

Thanks for your feedback comments @davidhassell. In response:

I wonder if the verbose keyword should either be None or an int (rather than a bool), so that the control can be fine-tuned at the function level.

Ah yes, that's a very good idea!

There were a few methods you mentioned &/or I noticed have some levelling aspect already (e.g. construct_verbose = (verbose > 1) in constructs._equals_coordinate_reference()) where I was at this point relying on the value equivalence of True & 1 (1 == True) until allowing such levels by subsuming any such kwargs (I forgot to add that to the TODO checklist), but it is definitely better as you suggest to allow full configurability for all methods having the verbose kwarg. For:

the old setting of False would map to 0; and True could map to the most appropiate +ve int.

I can change from value to identity check so True is distinguished, & False has value 0 anyway so a value comparison can manage that equivalency.

I'll implement it as you suggest in your comment.

Should we take this opportunity to rename the package level functions to lower case: ATOL, RTOL, LOG_SEVERITY_LEVEL (but not cfdm.CF)? The upper case versions of ATOL, RTOL would remain as aliases.

It would be good to do this, & I am happy to here, but maybe to avoid cluttering this PR I can do this as follow-on work? I was thinking of the cf-python Issue NCAS-CMS/cf-python#70 which would be an ideal place to do the renaming for cf-python, but best do that after the logging is in so that can be included. And best do the renaming on cfdm & cf-python together. Either way, I think I can get all that in for the next release set.

Now I am back from leave I will prioritise getting this PR done including to extend it according to your feedback, but that shouldn't be too difficult or time-consuming since the bulk of the code is there & just needs tweaking.

Also looking at my changes afresh after my break, I am thinking maybe I should create a test case (unittest.TestCase) subclass to manage setting the logging in the test classes, instead of adding in the configuration to each setUp (see 792d2fd). However, that would make it more cumbersome to change it on a per-test-module basis, & hide away the comment about how to change it for given lines. Not sure what to do there, so if you have thoughts or a preference please let me know.

Reviewing aids:

• I have just updated the opening comment to reflect changes in approach from the earlier feedback suggestion & as discussed yesterday after seeing the outputs logging in practice. It is not up to date to summarise the key points.
• Additionally, the new agreed log & verbosity level schema, with integer mapping, is summarised here in what will become (part of) a new section in the documentation.

Tests added & including these the local test suite passes, both when running the relevant tests individually & as part of the full test suite, which is notable because I had to make a few tweaks mainly to the assertLogs setup for test_decorators as otherwise with naive setup one but not the other would pass (mainly relating to logger naming by __name__ which of course varies according to the origin executable).

I want to check the GH Actions suite results. The Mac OS jobs may fail due to platform-specific unrelated issues that have been cropping up and I need to look into, so just looking for an Ubuntu job pass. The Actions workflow would have triggered itself as far as I know, not sure why it isn't running the checks. I'll try a close & re-open to force the triggering.

One conflict present has been resolved, so ready to merge once the Actions test suite job passes.

All test jobs passed 🎉! It looks like the previously-observed Mac OS job issues are intermittent. I will investigate them in due course, but I'm glad they haven't cropped up here so I can be confident everything does as it should on that platform.

@davidhassell I am merging this now. Thanks for your comments. As you suggest, levels attached to certain messages may not be the most appropriate but we can easily tweak the levels of any message as we attune to the logging system & outputs. It is just a case of changing a call from, e.g, logging.info(...) to logging.detail(...) now.

I will move the noted follow-in work (see 'Post-PR work' in the opening comment) to its own Issue, but it should wait at least until the equivalent basic logging has been added to cf-python, which may be a few weeks at least due to other priorities.

Great - thank you! I shall update my my fork.