-
Notifications
You must be signed in to change notification settings - Fork 297
Version 5
To be able to do a complete WeeWX install using pip
.
Future-proof the install. Right now, we depend heavily on custom commands in
setup.py
. However, the imperative approach of setup.py
is being phased out
in favor of a more declarative approach, using pyproject.toml
(see PEP
621 and PEP
631). As an alternative, we could use
setup.cfg
, but it's clear that pyproject.toml
is the future.
Python 3.7 or greater. Python 3.7 was released over four years ago (on 27 June
2018), so it should be ubiquitous by now. Python 3.7 is necessary to support
importing resources.
Note that a backport of
importlib.resources
is available for earlier versions of Python, so we may be
able to relax this restriction and allow Python 3.5 and 3.6.
Support for Python 2.7 will be dropped. All references to six
and other
compatibility shims will be removed.
Stretch goal: introduce asynchronous drivers, which would allow more than one driver to be active at the same time. This feature would probably involve lots of breaking changes, but it would be a lot more elegant than the present pattern of using a WeeWX service to add data to the data pipeline.
There are many tools that were considered to manage the Python distribution
build process including setuptools,
pdm, flit, and
poetry. We have chosen poetry to manage
dependencies and to build the packages. It is mature, simple to use, depends on
pyproject.toml
, and very popular. Poetry can also be used to do an in situ
install, but that's not the intended use case. Most users will use pip
.
The ubiquitous setuptools was considered, but
poetry is easier to use and its implementation of pyproject.toml
is more
mature. NB: this only affects the distribution build process. Either way, pip
is used to install.
Applications will be invoked using an entry
point.
This is a small shim, installed by pip
, that invokes a function within a
module or package.
The old distutils
supported a
data_files
option that could be used to install miscellaneous resources such as
documentation or configuration files into the final installation target.
However, option data_files
is being deprecated for a variety of reasons (see
this
post
for a summary). Instead, resources must now be included as "package data", that
is, as part of a Python package. That means it will live deep in the target
site-packages
, where is is difficult to find and even more difficult to
modify.
Furthermore, package data must be regarded as "read only". For example, it's
possible that WeeWX could be installed as a zipfile or Python egg, so, even if a
user was willing to find its resources deep in site-packages
somewhere, s/he
could not edit them.
Both weewx.conf
and the skins are essential for the proper operation of
WeeWX, so they must be included in the distribution. For reasons outlined above,
they will be put in a dedicated wee_resources
package as package data.
Old | New |
---|---|
skins |
wee_resources/skins |
weewx.conf |
wee_resources/weewx.conf |
Once installed, these resources would be copied into position using a utility
(or, possibly, a repurposed wee_config
).
Unlike previous versions of WeeWX, weewx.conf
and the skins
directory would be updated with every upgrade. This is possible because the
production versions are in a separate location. The production version would
only be touched if the user requests it by using a utility.
There is no obvious place to install the documentation and examples using
pip
. Instead, they could be distributed in a separate tarball, which could
then be downloaded and expanded in a location of the user's choosing.
Generally, we expect WeeWX to be installed in a virtual envirornment, where the
names of its modules and packages would not collide with another application.
Nevertheless, it is possible that the user would install to the system's
sys.exec
, and we should be prepared for this.
Most packages used by WeeWX already start with the prefix wee_
, which is a
reasonable claim to a namespace. However, there are two problem areas:
Old | New |
---|---|
user |
wee_user |
schemas |
wee_schemas |
Note that these will break a lot of code, particularly the renaming of user
.
Fortunately, all references to the user
or schemas
packages are dynamic,
that is, they are in the form of string options in weewx.conf
or skin.conf
.
The actual instantiation is done by the WeeWX function weeutil.get_object()
.
This makes it straightforward to maintain backwards compatibility by having
get_object()
remap references from user
to wee_user
at runtime. In a
similar manner, references to schemas
would get remapped to wee_schemas
. All
of this would be transparent to the user.
Through the years, WeeWX has built up an extensive ecosystem of 3rd party extensions. It is essential that we not lose backwards compatibility with them. For this reason, they should continue to be installed directly into the target installation directories, and not indirectly through package resources.
Presently, we have 7 different utilities. Version 5 will combine these into one
utility called, simply, weectl
, with different subcommands. By having a single
utility, we make it easier to find the appropriate command: the user can simply
run weectl --help
.
Name | Definition |
---|---|
package resource | A resource, such as weewx.conf or skins , included in a distribution as a Python package. Read-only.Must be accessed using importlib.resources . |
package resource location | Location of the package resource, typically somewhere under site-packages . May or may not be a file. |
resource root | Final, installed, location of the resources, particularly the configuration file and skins. Typically, /etc/weewx , or /home/weewx
|
station | Unique piece of hardware, which requires a driver. This is equivalent to a "stanza" such as [Vantage] . |
driver | Software that interacts directly with the hardware. More than one station can use the same driver. |
station type | The currently active station, specified with option station_type . A corresponding station must exist. |
Create a new copy of the configuration file, using the copy of weewx.conf
in
the package resource as a template. The default location of the new file will
be /home/weewx/weewx.conf
.
If the configuration file already exists, then an error will be raised.
If they do not already exist, then the skins are also copied over from the package resource location to the resource root.
The following are set:
Name | What | Default |
---|---|---|
WEEWX_ROOT |
The resource_root. | /home/weewx |
HTML_ROOT |
Where the generated HTML files and images will be put, relative to $WEEWX_ROOT
|
public_html |
SKIN_ROOT |
The directory of the skins, relative to $HTML_ROOT . |
skins |
SQLITE_ROOT |
The directory of the SQLite database, relative to $HTML_ROOT . |
archive |
station_type |
The active station. | Simulator |
Optional path to the configuration file. The value for HTML_ROOT
will be set
to its directory.
The default is /home/weewx/weewx.conf
.
Optional path to where the skins will be installed, relative to $WEEWX_ROOT
.
Default is skins
.
Optional path to where the generated HTML files and plots will be placed,
relative to $WEEWX_ROOT
.
Default is public_html
.
The device driver to use.
Default is simulator
.
This will be the name of a dedicated stanza (e.g., [Vantage]
) that describes
the hardware characteristics of the station. The option station_type
will be
set to the stanza name.
Default is whatever is returned as attribute DRIVER_NAME
of the nominated
driver
.
This command provides an opportunity to reprovision an existing configuration file.
If necessary, upgrade an existing configuration file. The old version will be saved as a timestamped copy.
Optional path to the configuration file.
Default is /home/weewx/weewx.conf
Set the currently active station. This sets option station_type
.
Optional path to the configuration file.
Default is /home/weewx/weewx.conf
The skins will be copied over from the package resource location to the
resource root ($WEEWX_ROOT
). The old version will be saved under a
timestamp.
Optional path to the configuration file.
Default is /home/weewx/weewx.conf
|
# Create a new weewx.conf, using the vantage driver. The station stanza will be [House]:
weectl create-station --driver=vantage --driver-name=House
# Same as above, but use a custom configuration file name
weectl create-station --driver=vantage --driver-name=House --config=/home/weewx/house.conf
# Reconfigure it:
weectl reconfigure-station --config=/home/weewx/house.conf
# Upgrade its configuration file
weewx upgrade-config --config=/home/weewx/house.conf
Install utility files to run as a daemon.
Command | Flags | Functionality |
---|---|---|
weectl install-daemon |
--init |
Install /etc/init.d/weewx
|
weectl install-daemon |
--systemd |
Install /etc/systemd/system/weewx.service
|