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:

@@ -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.