An API utility wrapper for accessing the e-Manifest hazardous waste tracking system maintainedby the US Environmental Protection Agency
Project description
e-Manifest
emanifest is a client library for accessing the e-Manifest REST APIs of the US Environmental Protection Agency's RCRAInfo national electronic hazardous waste management system.
Note: The emanifest package was substantially refactored after version 2.0.7 and was released as a new major version at 3.0.0. Code relying on versions ≤3.0.0 should not upgrade to version 3.0.0 of this package without refactoring.
Contents
Requirements
- Python 3.7
Installation
emanifest can be installed directly from the Python package Index (PyPI) using pip:
$ pip install emanifest
Getting Started
Before using the emanifest package, ensure you have a RCRAInfo user account and the necessary permissions to generate an API ID and key.
All methods to access the e-Manifest APIs are implemented by the RcrainfoClient
class which needs your API ID and Key
to authenticate. A new instance of the class can be initiated like so:
from emanifest import RcrainfoClient
rcrainfo = RcrainfoClient('preprod', api_id='YOUR_API_ID', api_key='YOUR_API_KEY')
And that's it! You're ready to start using the RCRAInfo Restful web services.
The RcrainfoClient class requires one positional argument, a string, either 'preprod'
, or 'prod'
.
Authentication
Starting with version 3.0 and above of this package, the RcrainfoClient will automatically authenticate as needed once
API credentials have been provided, either during object initiation or by passing the API ID and key to
the authenticate
method.
If you'd like to disable this behaviour, you can set the RcrainfoClient auto_renew = False
, and call
the authenticate
method as necessary.
from emanifest import RcrainfoClient
rcrainfo = RcrainfoClient('preprod', auto_renew=False)
# or
rcrainfo.auto_renew = False
# Returns False if no token present, or has expired.
if not rcrainfo.is_authenticated:
rcrainfo.authenticate(api_id='my_api_id', api_key='my_api_key')
# If RcrainfoClient already has your API credentials, you don't need to them supply again.
rcrainfo.authenticate()
The RcrainfoClient stores the JSON web token and its expiration period (20 minutes). See
the RcrainfoClient
definition here for more details.
Methods
After providing your API credentials, you are ready to use the full functionality of the emanifest package. The
RcrainfoClient class exposes a method for each API endpoint following an <action>_<resource>
naming convention.
Examples:
RCRAInfo endpoints that require a URL parameter should be passed as a string to the RcrainfoClient method.
from emanifest import RcrainfoClient
rcrainfo = RcrainfoClient('preprod', api_id='YOUR_API_ID', api_key='YOUR_API_KEY')
# Any endpoint with URL parameters will take that parameter as a positional, string argument.
site_resp = rcrainfo.get_site('VATEST000001')
Many of the POST request use keyword arguments to compose the http request's body. for example...
from emanifest import RcrainfoClient
rcrainfo = RcrainfoClient('preprod', api_id='YOUR_API_ID', api_key='YOUR_API_KEY')
resp = rcrainfo.search_mtn(siteId='VATEST000001', status='InTransit')
would send a http requests with the following body to the manifest tracking number (mtn) search endpoint.
{
"siteId": "VATEST000001",
"status": "InTransit"
}
Note, the keyword arguments use the same naming convention seen in the RCRAInfo swagger pages and documentation.
multipart/mixed
payloads (
e.g., JSON of a manifest
and .zip file of attachments) can be uploaded to
RCRAInfo
by passing a JSON string and the bytes of the optional attachment like so:
from emanifest import RcrainfoClient
rcrainfo = RcrainfoClient('preprod', api_id='YOUR_API_ID', api_key='YOUR_API_KEY')
# The JSON and .zip file could come from a database, filesystem, an external service,
# or json.dumps({'manifestTrackingNumber': '0123456789ELC', ... })
with open('./attachments.zip', 'rb') as f:
attachment = f.read()
with open('./manifest.json', 'r') as f:
manifest_json = f.read()
resp = rcrainfo.update_manifest(manifest_json, attachment)
Responses are returned as a RcraResponse object, which wraps around
the requests library
Response object. Methods that download file attachments can be accessed via the
RcrainfoResponse.json()
method and RcrainfoResponse.zip
property when appropriate. The
entire request.Response
object is returned in RcrainfoResponse.response
.
from emanifest import RcrainfoClient
rcrainfo = RcrainfoClient('preprod', api_id='YOUR_API_ID', api_key='YOUR_API_KEY')
resp = rcrainfo.get_manifest_attachments('123456789ELC')
# RcraInfoResponse re-exports a couple attributes of the requests.Response object.
print(resp.ok)
# Or you can access the full Response like such...
print(resp.response.json())
# For endpoints that return multipart/mixed bodies, you can access JSON with the resp.json()
downloaded_json = resp.json()
# The .zip file can be accessed in the resp.zip property.
downloaded_attachment = resp.zip
Regulators
Starting with version 3.0 and above of this package, regulator can use the same methods as industry but with
the reg
keyword argument set to True
. For example:
from emanifest import RcrainfoClient
rcrainfo = RcrainfoClient('preprod', api_id='YOUR_API_ID', api_key='YOUR_API_KEY')
resp = rcrainfo.get_manifest('123456789ELC', reg=True)
The reg
keyword argument is set to False
by default.
The following methods have regulator options:
- get_manifest_attachments
- search_mtn
- get_correction
- get_correction_version
- get_site_mtn
- get_manifest
- get_sites
The following methods are for regulator users only:
- get_handler
- get_cme_lookups
- get_cme_indicators
- get_cme_types
API endpoints designed for use by other groups, such as regulators or industry users, will return 'Access Denied' errors if you are not authorized to access these resources in RCRAInfo.
Advanced Usage and Help
As of version 3.0, the RcrainfoClient is a subclass of the requests library Session Class. As such, you can take advantage of its functionality.
RcrainfoClient can be also customized by subclassing and overriding. For example,
from emanifest import RcrainfoClient
class MyClass(RcrainfoClient):
def retrieve_id(self, api_id=None) -> str:
# Custom behavior to retrieve your RCRAInfo API ID
my_api_id = 'api_id_from_someplace_secure'
return super().retrieve_id(my_api_id)
For RcrainfoClient method specific documentation, you can use the help()
function from the Python console to get a
description of
each method and its inputs.
>>> from emanifest import RcrainfoClient
>>> help(RcrainfoClient.get_bill)
For more information about the RCRAInfo services, see the documentation in the root directory of the e-Manifest GitHub repo, and the Swagger page of your selected environment (Preproduction, Production). Do not use the RCRAInfo Production environment for testing. To register for a testing account in preproduction, visit the preprod site.
Please note, the API of emanifest python package was substantially modified from version 2.0 to 3.0. We intend for the 3.0 package version to be much more stable than its predecessors. We will continue to adhere to semantic versioning, and will not break backwards compatibility within a major release.
Contact
Please direct questions to the EPA e-Manifest team at USEPA/e-manifest
Disclaimer
The United States Environmental Protection Agency (EPA) GitHub project code is provided on an "as is" basis and the user assumes responsibility for its use. EPA has relinquished control of the information and no longer has responsibility to protect the integrity, confidentiality, or availability of the information. Any reference to specific commercial products, processes, or services by service mark, trademark, manufacturer, or otherwise, does not constitute or imply their endorsement, recommendation or favoring by EPA. The EPA seal and logo shall not be used in any manner to imply endorsement of any commercial product or activity by EPA or the United States Government.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for emanifest-3.0.3-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | dc23290cd6bbb5575cf73565fba4e839dd025c6f3a144816143f62f2d46f3311 |
|
MD5 | ec3c0cb8d2ac181bf59373c987b9f084 |
|
BLAKE2b-256 | 7c88931a6579c091b09acce96552c768e6e460780648fdea520e6125fdde14b4 |