Git commit messages and automatic changelog formatting

https://mokkapps.de/blog/how-to-automatically-generate-a-helpful-changelog-from-your-git-commit-messages/

https://www.conventionalcommits.org/en/v1.0.0/

Docstring format

I am using the sphinx docstring format. This is because it allows specifying the types of parameters when the types are known.

https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html

USGS Map API has changed

https://maps.waterdata.usgs.gov/mapper/ https://help.waterdata.usgs.gov/tutorials/overview/a-primer-on-downloading-data https://waterservices.usgs.gov/docs/portable_code.html https://help.waterdata.usgs.gov/faq/automated-retrievals#FAQ https://maps.waterdata.usgs.gov/mapper/help/sitetype.html https://maps.waterdata.usgs.gov/mapper/instructions.html

GEOCODE Nomination

This is a lookup service for converting addresses and other sites into latitude and longitude.

https://nominatim.org/release-docs/latest/develop/overview/

Catching Exceptions

In general only named exceptions should ever be caught. Catching bare exceptions, that is 'except:' or broad exceptions 'except Exception:' will hide programming errors or errors caused by API changes, and generally makes the code harder to debug.

So for the short term, I will be adding visible tracebacks and sometimes re-raise the exception to find out what specific exceptions need to be caught.

Some exceptions like have additional attributes like errno that should be checked to verify that it is an expected exception.

Raising exceptions

In general only locally created exceptions names should be raised.

In many cases instead of re-raising a python supplied module exception, a locally created exception can make the issue easier to understand.

Exceptions can inherit from other classes.

In general, there should be a base exception class for all d-rats exceptions.

For classes that are in files a directory tree, there should be a base exception class that inherits from the above class.

For each file in a class there should be an exception class that inherits from one of the above parent class.

If a routine raises more than one exception, those exceptions should probably have a common parent, usually named for the routine raising the exception.

Internationalization potential bugs

The _() function is set in the global namespace by the main module. The pylance wants it to be set in any module that uses the _(). But we only want to define _() if it is not already in the in locals(). I think I have this part right now, but every module will need to be checked.

We need to make sure that "()" is not being called on variables as that is not going to work. The "()" function looks up a string constant for substitution from a dictionary. String parameters are allowed.

Also look out for the same string constant being passed to _() in the same method or class multiple times. That is just going to slightly slow the program down.

Mysteries and potential bugs

main_message.py class MessageFolder

The create_msg method creates a message and makes sure that it is also stored in the configuration data for some reason

The delete method delete the message from the filesystem and removes it from the configuration data.

The rename message changes the filename, but does not update the configuration data.

This appears to cause a data inconsistency.

dplatform.py

class Platform

run_sync

Why is this returning a tuple with the first member always 0? What about the return status and stderr output?

class UnixPlatform

open_text_file open_html_file

We need a better message than this: "If after this your Linux box crashes, "

If there is any way D-Rats can actually crash a system, the OS has a big problem.

Lots of room for improvement, more browser choices, etc.

There is a TODO note to select these program as a config option.

os_version_string

This is apparently trying to open /etc/issue.net to get the os-version for Unix/Linux and giving up on that if it is not present.

There should be a way in python3 to get the version string for a platform. If not there are other commands and files to look for.

class Win32Platform

open_text_file and open_html_file

Need to be a config option, not sure current defaults are valid.