Package: oep-client
OEP ClientThis tool eases data sharing with the Open Energy Platform (OEP). Common tasks on the OEP are:creating a tableuploading dataupdating a table's metadatadownloading dataretrieving a table's metadatadeleting a table (that you created)You can also always just use the API(TODO: link to documentation)directly if your tasks are more complex.Notes for Windows UsersAll the example commands below usepython3, because we need python 3. Under Windows, it's most likely to bepython.exeor justpython.InstallationInstall packageoep-clientfrom python package index with pip:python3-mpipinstall--upgradeoep-clientAuthentificationYou need to beregistered on the OEP platformand have a valid API token.
You can find your token in your user profile on the OEP underYour Security Information.TestThere is a short test script that creates a table on the platform, uploads data and metadata, downloads them again
and finally deletes the table.You can run it either directly from the command prompt usingoep-client -t OEP_API_TOKEN testNotes on Data and MetadataSupported filetypes that the client can work with are are: xslx, csv, json.
Your metadata must be a json file that complies with themetadata specification of the OEP.Notes on UsageAll tasks can be executed either directly as a comand line script (CLI)oep-clientthat comes with this package, or in a python environment.The CLI is very handy for standardized tasks as it requires just one command line, but is somewhat limited when for instance your input data is not in a very specific format.
To see avaiblabe command line options, useoep-client --helpIn a python environment, you have more flexibility to prepare / clean your data before uploading it.Using the CLICreating a tableRequires a valid metadata file.You need to specify names and data types of your columns in the metadata, which also must be validpostgres data types.metadata.json{
  "resources": [
    {
      "schema": {
        "fields": [
          {
            "name": "id",
            "type": "bigserial"
          },
          {
            "name": "field_1",
            "type": "varchar(32)",
            "description": "column description",
            "unit": "unit name"
          }
        ]
      }
    }
  ]
}oep-client-tOEP_API_TOKENcreateTABLE_NAMEmetadata.jsonUploading dataoep-client-tOEP_API_TOKENinsertTABLE_NAMEFILENAMEifFILENAMEis axlsx, youhave toalso specify--sheet SHEETNAMEcsv, youmayalso specify--delimiter DELIMITERand or--encoding ENCODINGUpdating a table's metadataThis of course requires a valid metadata file.oep-client-tOEP_API_TOKENmetadatasetTABLE_NAMEmetadata.jsonDownloading dataNote: you do not need an API_TOKEN to downlad data. Also, the table might not be in themodel_draftschema, in which case you can specify the table name asschema_name.table_name. ->List of schemas.oep-client-tOEP_API_TOKENselectTABLE_NAMEFILENAMEifFILENAMEis axlsx, youhave toalso specify--sheet SHEETNAMEcsv, youmayalso specify--delimiter DELIMITERand or--encoding ENCODINGRetrieving a table's metadataNote: you do not need an API_TOKEN to downlad metadata. Also, the table might not be in themodel_draftschema, in which case you can specify the table name asschema_name.table_name. ->List of schemas.oep-client-tOEP_API_TOKENmetadatagetTABLE_NAMEFILENAMEDeleting a table (that you created)oep-client-tOEP_API_TOKENdropTABLE_NAMEUsing the Package in PythonAll examples assume that you import the package and create a client instance first:from oep_client import OepClient
cl = OepClient(token='API_TOKEN', ...)... TODOMore Information - Use the API without the oep-clientThis section describes how to upload data to theOEPusing Python and the REST-API.Create and upload data table(s)The REST-API can be used with any language than can make HTTP(s) requests.Most requests require you to add an authorization header:
Authorization:Token API_TOKEN, where you substituteAPI_TOKENwith your token.All requests (and most responses) will use json data as payload. A paylpad is the actual data content of the request.An example is provided below. For it, we use python and therequests package. All requests will use a requests session with the authorization header.import requests
API_URL = 'https://openenergy-platform.org/api/v0'
session = requests.Session()
session.headers = {'Authorization': 'Token %s' % API_TOKEN}The requests in the following sections use roughly the same pattern:Prepare your request payload as a json objectPrepare your request urlSend your request using the correct verb (get, post, put, delete)Check if the request was successfulCreate a new tableYou will create the tables at first in themodel_draftschema. After a successful review later, the table will be moved to the final target schema.You need to specify the name of the new table (TABLE_NAME), which should be a valid
post-gresql table name, without spaces, ideally only containing lower case letters, numbers and underscores.make request and check using PUTres = session.put(url, json=data)
res.raise_for_status() # check: throws exception if not successful### Upload data
* To upload data, you must first load it into a json structure as a [list](https://www.w3schools.com/python/python_lists.asp "python lists") representing data rows, each of which is a [dictionary](https://www.w3schools.com/python/python_dictionaries.asp "python dictionary") mapping column names to values.

* In the example, we will use [pandas](https://pypi.org/project/pandas/ "pandas") to read data from an Excel workbook (`WORKBOOK, WORKSHEET`) into a [data frame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html "data frame") which we will then convert into a json object. Please note that this step will most likely require some modification to accommodate the specifics of your in-put data.

* In addition to that, at the end, you need to load your data into the specified json structure.

* After that, the data can be uploaded making a request to the API:load data into dataframe, convert into jsondf = pd.read_excel(WORKBOOK, WORKSHEET)
records = df.to_json(orient='records')
records = json.loads(records)prepare request payloaddata = {'query': records}prepare api urlurl = API_URL + '/schema/model_draft/tables/' + TABLE_NAME + '/rows/new'make requestres = session.post(url, json=data)
res.raise_for_status() # check