sp2ts

A Python module for converting between the settlement periods used by GB electricity industry and Unix timestamps.

Latest Version: 1.0.0

About this repository

• Convert settlement date and settlement period to Unix timestamp and vice versa.
• Convert settlement date and settlement period to Python datetime object and vice versa.
• Convert Python datetime objects to Unix timestamp and vice versa.
• Developed and tested with Python 3.11, should work for 3.9+.

How do I get set up?

Run pip install sp2ts

(or make sure you have Git installed - Download Git - then run pip install git+https://github.com/SheffieldSolar/sp2ts/)

Check that the installation was successful by running the following command from terminal / command-line:

>> sp2ts -h

This will print the helper for the command line interface which can be useful for working interactively:

usage: sp2ts.py [-h] [-d <yyyy-mm-dd>] [-sp <[1..50]>]
                [-ts <seconds since epoch>] [-dt <yyyy-mm-ddTHH:MM:SS>]
                [-tz <Olson timezone string>]

This is a command line interface (CLI) for the sp2ts module.

optional arguments:
  -h, --help            show this help message and exit
  -d <yyyy-mm-dd>, --date <yyyy-mm-dd>
                        Specify a date (use only in conjuction with
                        -sp/--settlement-period).
  -sp <[1..50]>, --settlement-period <[1..50]>
                        Specify a settlement period (use only in conjuction
                        with -d/--date).
  -ts <seconds since epoch>, --timestamp <seconds since epoch>
                        Specify a timestamp (all other options will be
                        ignored).
  -dt <yyyy-mm-ddTHH:MM:SS>, --datetime <yyyy-mm-ddTHH:MM:SS>
                        Specify a datetime (optionally also specify
                        -tz/--timezone).
  -tz <Olson timezone string>, --timezone <Olson timezone string>
                        Specify a timezone (used only in conjunction with
                        -dt/--datetime, default is 'UTC').

Jamie Taylor, 2020-03-31

Usage

The module contains the following functions:

• to_unixtime(datetime, timezone=None)
  • Convert a Python datetime object to Unix timestamp. The datetime object must be timezone aware or else you must pass the timezone as an Olsen timezone string.
• from_unixtime(timestamp, timezone="UTC")
  • Convert a Unix timestamp to a (timezone-aware) Python datetime object
• sp2ts(date, sp, closed="right")
  • Convert a date and settlement period into a Unix timestamp. The closed parameter can be "left", "middle" or "right" (default), which will determine whether the timestamp returned is the start, middle or end of the settlement period respectively.
• sp2dt(date, sp, closed="right")
  • Convert a date and settlement period into a (timezone-aware) Python datetime object. The closed parameter can be "left", "middle" or "right" (default), which will determine whether the timestamp returned is the start, middle or end of the settlement period respectively.
• ts2sp(timestamp)
  • Convert a Unix timestamp into a date and settlement period. Settlement periods are considered to be "closed right" i.e. SP 1 refers to the interval 00:00:00 < t <= 00:30:00.
• dt2sp(datetime, timezone=None)
  • Convert a Python datetime object into a date and settlement period. The datetime must be timezone-aware, or else you must also pass the timezone as an Olsen timezone string. Settlement periods are considered to be "closed right" i.e. SP 1 refers to the interval 00:00:00 < t <= 00:30:00.

Example

from datetime import date

from sp2ts import sp2ts, ts2sp, from_unixtime

def main():
    # Converting date and SP to timestamp...
    mydate = date(2020, 3, 28)
    mysp = 24
    mytimestamp = sp2ts(mydate, mysp)
    print(f"{mydate} SP{mysp}  -->  {mytimestamp} ({from_unixtime(mytimestamp)})")
    # Converting timestamp to date and SP...
    mytimestamp = 1585396800 # SP ending 2020-03-28T12:00:00Z
    mydate, mysp = ts2sp(mytimestamp)
    print(f"{mytimestamp} ({from_unixtime(mytimestamp)})  -->  {mydate} SP{mysp}")

if __name__ == "__main__":
    main()

2020-03-28 SP24 --> 1585396800 (2020-03-28 12:00:00+00:00)

1585396800 (2020-03-28 12:00:00+00:00) --> 2020-03-28 SP24

How do I update?

Run pip install --upgrade sp2ts.

How do I run tests?

Clone the repo locally, then run the following command from the repo's root:

>> python -m Tests.test_sp2ts

Who do I talk to?

• Jamie Taylor - jamie.taylor@sheffield.ac.uk - SheffieldSolar

Authors

• Jamie Taylor - SheffieldSolar