py-SEED
===========
.. image:: https://github.com/seed-platform/py-seed/actions/workflows/ci.yml/badge.svg?branch=develop
:target: https://github.com/seed-platform/py-seed/actions/workflows/ci.yml/badge.svg
.. image:: https://badge.fury.io/py/py-seed.svg
:target: https://pypi.python.org/pypi/py-seed/
py-SEED serves as a Python client for the SEED Platform API. This library is purpose-built for Python applications, enabling interaction with the SEED Platform API to access property lists, create properties, establish connections, and retrieve data from ENERGY STAR(R) Portfolio Manager, BETTER, and other sources. The SEED Platform has a robust API, granting users access to every front-end feature seamlessly via the API. Currently, this library exposes the most commonly used SEED API endpoints and will undergo continuous updates tailored to the community's evolving needs. py-SEED offers two interaction levels: a high-level API providing familiar endpoints for easy connectivity to SEED's API, and a low-level API that allows read-write access to any SEED API, demanding a deeper understanding of the SEED API architecture
py-SEED is compatible with the latest version of the SEED Platform (>2.17.4) and only support SEED API Version 3.
More information can be found here:
* https://seed-platform.org
* https://energy.gov/eere/buildings/standard-energy-efficiency-data-platform
* https://github.com/SEED-platform
* https://buildingdata.energy.gov/#/seed
* https://github.com/SEED-platform/pyseed-examples
Compatibility Matrix
--------------------
.. list-table::
:widths: 50 50
:header-rows: 1
* - py-SEED Version
- SEED Version
* - 0.5.0
- 3.1.0
* - 0.4.3
- 2.21.0 - 3.0.0
Stakeholders
-------------
The following list of stakeholders should be considered when making changes to this module
* 179D Tax Deduction Web Application
* Earth Advantage Green Building Registry
* User scripts for managing building data
* ECAM
Documentation
-------------
The SEED client is a read-write client. To install the client run:
.. code-block:: bash
pip install py-seed
Within Python you can use the client like this:
.. code-block:: python
from pathlib import Path
from pyseed.seed_client import SeedClient
# The seed-config.json file defines the hosting location and credentials for your SEED instance.
# If running SEED locally for testing, then you can run the following from your SEED root directory:
# ./manage.py create_test_user_json --username user@seed-platform.org --host http://localhost:8000 --file ./seed-config.json --pyseed
config_file = Path('seed-config.json')
organization_id = 1
seed_client = SeedClient(organization_id, connection_config_filepath=config_file)
# Get/create the new cycle and upload the data. Make sure to set the cycle ID so that the
# data end up in the correct cycle
cycle = seed_client.get_or_create_cycle(
'pyseed-api-test', date(2021, 6, 1), date(2022, 6, 1), set_cycle_id=True
)
seed_client.upload_and_match_datafile(
'pyseed-properties-test',
'tests/data/test-seed-data.xlsx',
'Single Step Column Mappings',
'tests/data/test-seed-data-mappings.csv'
)
# See the projects unit tests for more examples. https://github.com/SEED-platform/py-seed/blob/develop/tests/test_seed_client.py
# Or look at the py-SEED examples repository: https://github.com/SEED-platform/pyseed-examples
Low-Level Documentation
-----------------------
This client has access to the lower level API client by accessing `seed_client_base.SEEDOAuthReadOnlyClient`, `seed_client_base.SEEDOAuthReadWriteClient`, `seed_client_base.SEEDReadOnlyClient`, and `seed_client_base.SEEDReadWriteClient`. This provides two user authentication based Python clients and two authentication methods, basic and `OAuth2 <https://github.com/GreenBuildingRegistry/jwt_oauth2>`_. More information on authentication can be seen in the following py-SEED classes:
.. code-block:: bash
SEEDOAuthReadOnlyClient
SEEDOAuthReadWriteClient
SEEDReadOnlyClient
SEEDReadWriteClient
Note the clients do not provide per api-call methods, but does provide the standard CRUD methods: get, list, put, post, patch, delete. The intended use of these clients is to be further subclassed or wrapped in functions to provide the desired functionality. The CRUD methods are provided via mixins so its possible to create a client for example without the ability to delete by subclassing SEEDUserAuthBaseClient, or SEEDOAuthBaseClient, and adding only the mixins that provided the Create, Read and Update capabilities. Basic usage for the provided low-level clients is as follows:
.. code-block:: python
from pyseed import SEEDReadWriteClient
seed_client = SEEDReadWriteClient(
your_org_id,
username=your_username,
password=your_password,
base_url=url_of_your_seed_host,
)
# list all properties
seed_client.list(endpoint='properties')
# get a single property
seed_client.get(property_pk, endpoint='properties')
Testing
-------
Tests can be run via the `pytest` command.
You will need to export environment variables for a test portfolio manager account to test integration. Environment variables should be named:
.. code-block:: bash
SEED_PM_UN
SEED_PM_PW
SEED Platform
-------------
SEED (Standard Energy Efficiency Data Platform™) is an open source "web-based application that helps organizations easily manage data on the energy performance of large groups of buildings" funded by the United States Department of Energy.
License
-------
Full details in LICENSE file.
Releasing
---------
This project is configured with GitHub Actions to automatically release to PyPi when a new tag is created. To release a new version:
* Create a branch with the prepared release change log
* Merge branch to develop
* To release, from the command line run merge develop into main `git merge --ff-only origin main`. This will point the HEAD of main to latest develop. Then push the main branch to GitHub, which may require a developer with elevated privileges to push to main.
* Back in GitHub create a new tag in GitHub against main and copy the change log notes into the tag description.
* GitHub Actions will automatically prepare the release the new version to PyPi
* Go to GitHub actions to approve the release
The GitHub Action required updates to the GitHub repo to only release on tags (https://github.com/SEED-platform/py-seed/settings/environments) after approval and on PyPi to add an authorized publisher (https://pypi.org/manage/project/py-SEED/settings/publishing/).
Raw data
{
"_id": null,
"home_page": "https://github.com/SEED-platform/py-seed",
"name": "py-SEED",
"maintainer": "NREL",
"docs_url": null,
"requires_python": null,
"maintainer_email": "nicholas.long@nrel.gov",
"keywords": "seed, api",
"author": "Nicholas Long, Katherine Fleming, Fable Turas, Paul Munday",
"author_email": "nicholas.long@nrel.gov, katherine.fleming@nrel.gov, fable@raintechpdx.com, paul@paulmunday.net",
"download_url": "https://files.pythonhosted.org/packages/ec/15/e069c3fd3c38e3e7cbb8a56556866c09ad567b4f487be7f220ca8a5d53c8/py_seed-0.5.1.tar.gz",
"platform": null,
"description": "py-SEED\n===========\n\n.. image:: https://github.com/seed-platform/py-seed/actions/workflows/ci.yml/badge.svg?branch=develop\n :target: https://github.com/seed-platform/py-seed/actions/workflows/ci.yml/badge.svg\n\n.. image:: https://badge.fury.io/py/py-seed.svg\n :target: https://pypi.python.org/pypi/py-seed/\n\npy-SEED serves as a Python client for the SEED Platform API. This library is purpose-built for Python applications, enabling interaction with the SEED Platform API to access property lists, create properties, establish connections, and retrieve data from ENERGY STAR(R) Portfolio Manager, BETTER, and other sources. The SEED Platform has a robust API, granting users access to every front-end feature seamlessly via the API. Currently, this library exposes the most commonly used SEED API endpoints and will undergo continuous updates tailored to the community's evolving needs. py-SEED offers two interaction levels: a high-level API providing familiar endpoints for easy connectivity to SEED's API, and a low-level API that allows read-write access to any SEED API, demanding a deeper understanding of the SEED API architecture\n\npy-SEED is compatible with the latest version of the SEED Platform (>2.17.4) and only support SEED API Version 3.\n\nMore information can be found here:\n\n* https://seed-platform.org\n* https://energy.gov/eere/buildings/standard-energy-efficiency-data-platform\n* https://github.com/SEED-platform\n* https://buildingdata.energy.gov/#/seed\n* https://github.com/SEED-platform/pyseed-examples\n\n\nCompatibility Matrix\n--------------------\n\n.. list-table::\n :widths: 50 50\n :header-rows: 1\n\n * - py-SEED Version\n - SEED Version\n * - 0.5.0\n - 3.1.0\n * - 0.4.3\n - 2.21.0 - 3.0.0\n\nStakeholders\n-------------\n\nThe following list of stakeholders should be considered when making changes to this module\n\n* 179D Tax Deduction Web Application\n* Earth Advantage Green Building Registry\n* User scripts for managing building data\n* ECAM\n\nDocumentation\n-------------\nThe SEED client is a read-write client. To install the client run:\n\n.. code-block:: bash\n\n pip install py-seed\n\nWithin Python you can use the client like this:\n\n.. code-block:: python\n\n from pathlib import Path\n from pyseed.seed_client import SeedClient\n\n # The seed-config.json file defines the hosting location and credentials for your SEED instance.\n # If running SEED locally for testing, then you can run the following from your SEED root directory:\n # ./manage.py create_test_user_json --username user@seed-platform.org --host http://localhost:8000 --file ./seed-config.json --pyseed\n\n config_file = Path('seed-config.json')\n organization_id = 1\n seed_client = SeedClient(organization_id, connection_config_filepath=config_file)\n\n # Get/create the new cycle and upload the data. Make sure to set the cycle ID so that the\n # data end up in the correct cycle\n cycle = seed_client.get_or_create_cycle(\n 'pyseed-api-test', date(2021, 6, 1), date(2022, 6, 1), set_cycle_id=True\n )\n\n seed_client.upload_and_match_datafile(\n 'pyseed-properties-test',\n 'tests/data/test-seed-data.xlsx',\n 'Single Step Column Mappings',\n 'tests/data/test-seed-data-mappings.csv'\n )\n\n # See the projects unit tests for more examples. https://github.com/SEED-platform/py-seed/blob/develop/tests/test_seed_client.py\n # Or look at the py-SEED examples repository: https://github.com/SEED-platform/pyseed-examples\n\nLow-Level Documentation\n-----------------------\nThis client has access to the lower level API client by accessing `seed_client_base.SEEDOAuthReadOnlyClient`, `seed_client_base.SEEDOAuthReadWriteClient`, `seed_client_base.SEEDReadOnlyClient`, and `seed_client_base.SEEDReadWriteClient`. This provides two user authentication based Python clients and two authentication methods, basic and `OAuth2 <https://github.com/GreenBuildingRegistry/jwt_oauth2>`_. More information on authentication can be seen in the following py-SEED classes:\n\n.. code-block:: bash\n\n SEEDOAuthReadOnlyClient\n SEEDOAuthReadWriteClient\n SEEDReadOnlyClient\n SEEDReadWriteClient\n\nNote the clients do not provide per api-call methods, but does provide the standard CRUD methods: get, list, put, post, patch, delete. The intended use of these clients is to be further subclassed or wrapped in functions to provide the desired functionality. The CRUD methods are provided via mixins so its possible to create a client for example without the ability to delete by subclassing SEEDUserAuthBaseClient, or SEEDOAuthBaseClient, and adding only the mixins that provided the Create, Read and Update capabilities. Basic usage for the provided low-level clients is as follows:\n\n\n.. code-block:: python\n\n from pyseed import SEEDReadWriteClient\n\n seed_client = SEEDReadWriteClient(\n your_org_id,\n username=your_username,\n password=your_password,\n base_url=url_of_your_seed_host,\n )\n\n # list all properties\n seed_client.list(endpoint='properties')\n\n # get a single property\n seed_client.get(property_pk, endpoint='properties')\n\nTesting\n-------\n\nTests can be run via the `pytest` command.\n\nYou will need to export environment variables for a test portfolio manager account to test integration. Environment variables should be named:\n\n.. code-block:: bash\n\n SEED_PM_UN\n SEED_PM_PW\n\n\nSEED Platform\n-------------\nSEED (Standard Energy Efficiency Data Platform\u2122) is an open source \"web-based application that helps organizations easily manage data on the energy performance of large groups of buildings\" funded by the United States Department of Energy.\n\n\nLicense\n-------\nFull details in LICENSE file.\n\n\nReleasing\n---------\n\nThis project is configured with GitHub Actions to automatically release to PyPi when a new tag is created. To release a new version:\n\n* Create a branch with the prepared release change log\n* Merge branch to develop\n* To release, from the command line run merge develop into main `git merge --ff-only origin main`. This will point the HEAD of main to latest develop. Then push the main branch to GitHub, which may require a developer with elevated privileges to push to main.\n* Back in GitHub create a new tag in GitHub against main and copy the change log notes into the tag description.\n* GitHub Actions will automatically prepare the release the new version to PyPi\n* Go to GitHub actions to approve the release\n\nThe GitHub Action required updates to the GitHub repo to only release on tags (https://github.com/SEED-platform/py-seed/settings/environments) after approval and on PyPi to add an authorized publisher (https://pypi.org/manage/project/py-SEED/settings/publishing/).\n",
"bugtrack_url": null,
"license": null,
"summary": "A Python API client for the SEED Platform",
"version": "0.5.1",
"project_urls": {
"Homepage": "https://github.com/SEED-platform/py-seed"
},
"split_keywords": [
"seed",
" api"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d512883e163021a56271154139086b965d52112706194050f3a993ece944e618",
"md5": "efba47ad397df052db8df72bdf634ede",
"sha256": "453124e597461932e09c4c32ba4fd46ff27302c112da00c58c5a95063e32e82f"
},
"downloads": -1,
"filename": "py_SEED-0.5.1-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "efba47ad397df052db8df72bdf634ede",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 44103,
"upload_time": "2024-10-15T15:11:00",
"upload_time_iso_8601": "2024-10-15T15:11:00.199284Z",
"url": "https://files.pythonhosted.org/packages/d5/12/883e163021a56271154139086b965d52112706194050f3a993ece944e618/py_SEED-0.5.1-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ec15e069c3fd3c38e3e7cbb8a56556866c09ad567b4f487be7f220ca8a5d53c8",
"md5": "4f7fb2c77a932d6066c668bb676b2fa9",
"sha256": "9d2cbf963406cbb780d24134a34f89307be5604cf06493f0b8a5a6c6bf62a6de"
},
"downloads": -1,
"filename": "py_seed-0.5.1.tar.gz",
"has_sig": false,
"md5_digest": "4f7fb2c77a932d6066c668bb676b2fa9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 39886,
"upload_time": "2024-10-15T15:11:01",
"upload_time_iso_8601": "2024-10-15T15:11:01.962893Z",
"url": "https://files.pythonhosted.org/packages/ec/15/e069c3fd3c38e3e7cbb8a56556866c09ad567b4f487be7f220ca8a5d53c8/py_seed-0.5.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-15 15:11:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "SEED-platform",
"github_project": "py-seed",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [],
"tox": true,
"lcname": "py-seed"
}
JSON
