From 5ea0bcc2e99e1d201e5eabe65e039fbbb6659366 Mon Sep 17 00:00:00 2001 From: Tom Keffer Date: Thu, 22 Dec 2016 16:00:47 -0800 Subject: [PATCH] Added notes about internationalization and about exceptions. --- docs/devnotes.htm | 57 +++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 48 insertions(+), 9 deletions(-) diff --git a/docs/devnotes.htm b/docs/devnotes.htm index a0761618..83ca84d4 100644 --- a/docs/devnotes.htm +++ b/docs/devnotes.htm @@ -16,12 +16,9 @@
- User's Guide
- Customization Guide
- Hardware Guide
- Utilities Guide
- Upgrade Guide
- Notes for Developers + User's Guide
Customization Guide
Hardware Guide
Utilities Guide
Upgrade Guide
Notes for Developers
@@ -52,7 +49,7 @@ Version: 3.6.1

Goals

-

The primary design goals of weewx are:

+

The primary design goals of weewx are:

  • Architectural simplicity. No semaphores, no named pipes, no inter-process communications, no complex multi-threading to manage. @@ -103,7 +100,7 @@ Version: 3.6.1 seems to be dead). Fortunately, Cheetah seems to be very robust, with only a few well-known bugs that are easiy worked around, so we will likely continue to use it for the foreseeable future.
    • -
  • Pure Python. The code base is 100% Python &mdash no underlying C libraries need be built to install +
  • Pure Python. The code base is 100% Python — no underlying C libraries need be built to install weewx. This also means no Makefiles are needed.
@@ -156,7 +153,11 @@ Version: 3.6.1

Value "None"

The Python special value None is used throughout to signal a missing data point. - All functions expect it.

+ All functions must be written to expect it.

+ +

Device drivers should be written to emit None if a data value is bad (perhaps + because of a failed checksum). If the hardware simply doesn't support it, then the driver should not emit a + value at all.

However, the time value must never be None. This is because it is used as the primary key in the SQL database.

@@ -187,6 +188,44 @@ next_dt = time_dt + delta next_ts = int(time.mktime(next_dt.timetuple()))

Other time conversion problems are handled in a similar manner.

+

Internationalization

+

Generally, weewx does not make much use of Unicode. This is because the Python 2.x libraries do not always + handle it correctly. In particular, the function time.strftime() completely fails + when handed a Unicode string with a non-ASCII character. As this function is often used by extensions, + working around this bug is an unfair expectation on extension writers. So, we generally avoid Unicode.

+

Instead, weewx mostly uses regular strings, with any non-ASCII characters encoded as UTF-8.

+

An exception to this general rule is the image generator, which holds labels internally in Unicode, because + that is the encoding expected by most fonts.

+

The document The + Absolute Minimum Every Software Developer Absolutely, Positively Must Know About Unicode and Character + Sets by Joel Spolsky, is highly recommended if you are just starting to work with UTF-8 and Unicode. +

+ +

Exceptions

+

In general, your code should not simply swallow an exception. For example, this is bad form:

+ 
+    try:
+        os.rename(oldname, newname)
+    except:
+        pass
+
+

While the odds are that if an exception happens it will be because the file oldname + does not exist, that is not guaranteed. It could be because of a keyboard interrupt, or a corrupted file + system, or something else. Instead, you should test explicitly for any expected exception, and let the rest + go by:

+ 
+    try:
+        os.rename(oldname, newname)
+    except OSError:
+        pass
+
+

Weewx has a few specialized exception types, used to rationalized all the different types of exceptions that + could be thrown by the underlying libraries. In particular, low-level I/O code can raise a myriad of + exceptions, such as USB errors, serial errors, network connectivity errors, etc. All device drivers + should catch these exceptions and convert them into an exception of type WeeWxIOError or one of its subclasses.

+

Glossary

This is a glossary of terminology used throughout the code.