mirror of
https://git.ianrenton.com/ian/spothole.git
synced 2026-08-08 19:41:41 +00:00
69 lines
3.5 KiB
Markdown
69 lines
3.5 KiB
Markdown
## Modifying the source code
|
|
|
|
Spothole is Public Domain licenced, so you can grab the source code and start modifying it for your own needs.
|
|
Contributions of code back to the main repository are encouraged, but completely optional.
|
|
|
|
### Code structure
|
|
|
|
To navigate your way around the source code, this list may help.
|
|
|
|
*Python back-end code*
|
|
|
|
* `/core` - Core classes and scripts
|
|
* `/data` - Data storage classes
|
|
* `/spotproviders` - Classes providing spots by accessing the APIs of other services
|
|
* `/alertproviders` - Classes providing alerts by accessing the APIs of other services
|
|
* `/solarconditionsproviders` - Classes providing solar and propagation by accessing the APIs of other services
|
|
* `/server` - Classes for running Spothole's own web server
|
|
|
|
*Templates*
|
|
|
|
* `/templates` - Templates used for constructing Spothole's user-targeted HTML pages
|
|
|
|
*HTML/JS/CSS front-end code*
|
|
|
|
* `/static` - Root for static files served by the web server. These are all served from a path starting `/static/`.
|
|
* `/static/apidocs` - Contains the OpenAPI spec (`openapi.yml`)
|
|
* `/static/css` - CSS files used by the web front-end
|
|
* `/static/img` - image files used by the web front-end
|
|
* `/static/js` - JavaScript used by the web front-end
|
|
* `/static/vendor` - Third-party libraries (CSS, JS, fonts and images)
|
|
|
|
*Miscellaneous*
|
|
|
|
* `/` - Main script (`spothole.py`), pip `requirements.txt`, config, README, etc.
|
|
* `/docs` - Documentation
|
|
* `/images` - Image sources
|
|
* `/datafiles` - Local data sources (differentiated from the majority of data files which are loaded from URLs and
|
|
cached in `/cache`)
|
|
* `/cache` - Directory where static-ish data downloaded from the internet is cached to avoid rapid re-requests, and
|
|
where spot/alert data is cached so that it survives a software restart. Created on first run.
|
|
|
|
### Extending the server
|
|
|
|
Spothole is designed to be easily extensible. If you want to write your own spot provider, for example, simply add a
|
|
module to the `spotproviders` package containing your class. (Currently, in order to be loaded correctly, the module (
|
|
file) name should be the same as the class name, but lower case.)
|
|
|
|
Your class should extend "SpotProvider"; if it operates by polling an HTTP Server on a timer, it can instead extend "
|
|
HTTPSpotProvider" where some of the work is done for you.
|
|
|
|
The class will need to implement a constructor that takes in the `provider_config` and provides it to the superclass
|
|
constructor, while also taking any other config parameters it needs.
|
|
|
|
If you're extending the base `SpotProvider` class, you will need to implement `start()` and `stop()` methods that start
|
|
and stop a separate thread which handles the provider's processing needs. The thread should call `submit()` or
|
|
`submit_batch()` when it has one or more spots to report.
|
|
|
|
If you're extending the `HTTPSpotProvider` class, you will need to provide a URI to query and an interval to the
|
|
superclass constructor. You'll then need to implement the `http_response_to_spots()` method which is called when new
|
|
data is retrieved. Your implementation should then call `submit()` or `submit_batch()` when it has one or more spots to
|
|
report.
|
|
|
|
When constructing spots, use the comments in the Spot class and the existing implementations as an example. All
|
|
parameters are optional, but you will at least want to provide a `time` (which must be timezone-aware) and a `dx_call`.
|
|
|
|
Finally, simply add the appropriate config to the `spot_providers` section of `config.yml`, and your provider should be
|
|
instantiated on startup.
|
|
|
|
The same approach as above is also used for alert providers. |