Heroku3.py
==========
.. image:: https://img.shields.io/pypi/v/heroku3.svg
:target: https://pypi.org/project/heroku3
.. image:: https://circleci.com/gh/martyzz1/heroku3.py.svg?style=svg
:target: https://circleci.com/gh/martyzz1/heroku3.py
.. image:: https://coveralls.io/repos/github/martyzz1/heroku3.py/badge.svg?branch=master
:target: https://coveralls.io/github/martyzz1/heroku3.py?branch=master
.. image:: https://img.shields.io/pypi/pyversions/setuptools.svg
This is the updated Python wrapper for the Heroku `API V3. <https://devcenter.heroku.com/articles/platform-api-reference>`_
The Heroku REST API allows Heroku users to manage their accounts, applications, addons, and
other aspects related to Heroku. It allows you to easily utilize the Heroku
platform from your applications.
Introduction
============
First instantiate a heroku_conn as above::
import heroku3
heroku_conn = heroku3.from_key('YOUR_API_KEY')
Interact with your applications::
>>> heroku_conn.apps()
[<app 'sharp-night-7758'>, <app 'empty-spring-4049'>, ...]
>>> app = heroku_conn.apps()['sharp-night-7758']
General notes on Debugging
--------------------------
Heroku provides some useful debugging information. This code exposes the following
Ratelimit Remaining
~~~~~~~~~~~~~~~~~~~
Get the current ratelimit remaining::
num = heroku_conn.ratelimit_remaining()
Last Request Id
~~~~~~~~~~~~~~~
Get the unique ID of the last request sent to heroku to give them for debugging::
id = heroku_conn.last_request_id
General notes about list Objects
--------------------------------
The new heroku3 API gives greater control over the interaction of the returned data. Primarily this
centres around calls to the api which result in list objects being returned.
e.g. multiple objects like apps, addons, releases etc.
Throughout the docs you'll see references to using limit & order_by. Wherever you see these, you *should* be able to use *limit*, *order_by*, *sort* and *valrange*.
You can control ordering, limits and pagination by supplying the following keywords::
order_by=<'id'|'version'>
limit=<num>
valrange=<string> - See api docs for this, This value is passed straight through to the API call *as is*.
sort=<'asc'|'desc'>
**You'll have to investigate the api for each object's *Accept-Ranges* header to work out which fields can be ordered by**
Examples
~~~~~~~~
List all apps in name order::
heroku_conn.apps(order_by='name')
List the last 10 releases::
app.releases(order_by='version', limit=10, sort='desc')
heroku_conn.apps()['empty-spring-4049'].releases(order_by='version', limit=10, sort='desc')
List objects can be referred to directly by *any* of their primary keys too::
app = heroku_conn.apps()['myapp']
dyno = heroku_conn.apps()['myapp_id'].dynos()['web.1']
proc = heroku_conn.apps()['my_app'].process_formation()['web']
**Be careful if you use *limit* in a list call *and* refer directly to an primary key**
E.g.Probably stupid...::
dyno = heroku_conn.apps()['myapp'].dynos(limit=1)['web.1']
General Notes on Objects
------------------------
To find out the Attributes available for a given object, look at the corresponding Documentation for that object.
e.g.
`Formation <https://devcenter.heroku.com/articles/platform-api-reference#formation>`_ Object::
>>>print(feature.command)
bundle exec rails server -p $PORT
>>>print(feature.created_at)
2012-01-01T12:00:00Z
>>>print(feature.id)
01234567-89ab-cdef-0123-456789abcdef
>>>print(feature.quantity)
1
>>>print(feature.size)
1
>>>print(feature.type)
web
>>>print(feature.updated_at)
2012-01-01T12:00:00Z
Switching Accounts Mid Flow
---------------------------
It is also possible to change the underlying heroku_connection at any point on any object or listobject by creating a new heroku_conn and calling change_connection::
heroku_conn1 = heroku3.from_key('YOUR_API_KEY')
heroku_conn2 = heroku3.from_key('ANOTHER_API_KEY')
app = heroku_conn1.apps()['MYAPP']
app.change_connection(heroku_conn2)
app.config() # this call will use heroku_conn2
## or on list objects
apps = heroku_conn1.apps()
apps.change_connection(heroku_conn2)
for app in apps:
config = app.config()
Legacy API Calls
================
The API has been built with an internal legacy=True ability, so any functionlity not implemented in the new API can be called via the previous `legacy API <https://legacy-api-docs.herokuapp.com/>`_. This is currently only used for *rollbacks*.
Object API
==========
Account
-------
Get account::
account = heroku_conn.account()
Change Password::
account.change_password("<current_password>", "<new_password>")
SSH Keys
~~~~~~~~
List all configured keys::
keylist = account.keys(order_by='id')
Add Key::
account.add_key(<public_key_string>)
Remove key::
account.remove_key(<public_key_string - or fingerprint>)
Account Features (Heroku Labs)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
List all configured account "features"::
featurelist = account.features()
Disable a feature::
feature = account.disable_feature(id_or_name)
feature.disable()
Enable a feature::
feature = account.enable_feature(id_or_name)
feature.enable()
Plans - or Addon Services
-------------------------
List all available Addon Services::
addonlist = heroku_conn.addon_services(order_by='id')
addonlist = heroku_conn.addon_services()
Get specific available Addon Service::
addonservice = heroku_conn.addon_services(<id_or_name>)
App
--------
The App Class is the starting point for most of the api functionlity.
List all apps::
applist = heroku_conn.apps(order_by='id')
applist = heroku_conn.apps()
Get specific app::
app = heroku_conn.app(<id_or_name>)
app = heroku_conn.apps()[id_or_name]
Create an app::
app = heroku_conn.create_app(name=None, stack_id_or_name='cedar', region_id_or_name=<region_id>)
Destroy an app (**Warning this is irreversible**)::
app.delete()
Addons
~~~~~~
List all Addons::
addonlist = app.addons(order_by='id')
addonlist = applist[<id_or_name>].addons(limit=10)
addonlist = heroku_conn.addons(<app_id_or_name>)
Install an Addon::
addon = app.install_addon(plan_id_or_name='<id>', config={})
addon = app.install_addon(plan_id_or_name='<name>', config={})
addon = app.install_addon(plan_id_or_name=addonservice.id, config={})
addon = app.install_addon(plan_id_or_name=addonservice.id, config={}, attachment_name='ADDON_ATTACHMENT_CUSTOM_NAME')
Remove an Addon::
addon = app.remove_addon(<id>)
addon = app.remove_addon(addonservice.id)
addon.delete()
Update/Upgrade an Addon::
addon = addon.upgrade(plan_id_or_name='<name>')
addon = addon.upgrade(plan_id_or_name='<id>')
Buildpacks
~~~~~~~~~~~~~
Update all buildpacks::
buildpack_urls = ['https://github.com/some/buildpack', 'https://github.com/another/buildpack']
app.update_buildpacks(buildpack_urls)
*N.B. buildpack_urls can also be empty. This clears all buildpacks.*
App Labs/Features
~~~~~~~~~~~~~~~~~
List all features::
appfeaturelist = app.features()
appfeaturelist = app.labs() #nicename for features()
appfeaturelist = app.features(order_by='id', limit=10)
Add a Feature::
appfeature = app.enable_feature(<feature_id_or_name>)
Remove a Feature::
appfeature = app.disable_feature(<feature_id_or_name>)
App Transfers
~~~~~~~~~~~~~
List all Transfers::
transferlist = app.transfers()
transferlist = app.transfers(order_by='id', limit=10)
Create a Transfer::
transfer = app.create_transfer(recipient_id_or_name=<user_id>)
transfer = app.create_transfer(recipient_id_or_name=<valid_email>)
Delete a Transfer::
deletedtransfer = app.delete_transfer(<transfer_id>)
deletedtransfer = transfer.delete()
Update a Transfer's state::
transfer.update(state)
transfer.update("Pending")
transfer.update("Declined")
transfer.update("Accepted")
Collaborators
~~~~~~~~~~~~~
List all Collaborators::
collaboratorlist = app.collaborators()
collaboratorlist = app.collaborators(order_by='id')
Add a Collaborator::
collaborator = app.add_collaborator(user_id_or_email=<valid_email>, silent=0)
collaborator = app.add_collaborator(user_id_or_email=user_id, silent=0)
collaborator = app.add_collaborator(user_id_or_email=user_id, silent=1) #don't send invitation email
Remove a Collaborator::
collaborator = app.remove_collaborator(userid_or_email)
ConfigVars
~~~~~~~~~~
Get an apps config::
config = app.config()
Add a config Variable::
config['New_var'] = 'new_val'
Update a config Variable::
config['Existing_var'] = 'new_val'
Remove a config Variable::
del config['Existing_var']
config['Existing_var'] = None
Update Multiple config Variables::
# newconfig will always be a new ConfigVars object representing all config values for an app
# i.e. there won't be partial configs
newconfig = config.update({u'TEST1': u'A1', u'TEST2': u'A2', u'TEST3': u'A3'})
newconfig = heroku_conn.update_appconfig(<app_id_or_name>, {u'TEST1': u'A1', u'TEST2': u'A2', u'TEST3': u'A3'})
newconfig = app.update_config({u'TEST1': u'A1', u'TEST2': u'A2', u'TEST3': u'A3'})
Check if a var exists::
if 'KEY' in config:
print("KEY = {0}".format(config[KEY]))
Get dict of config vars::
my_dict = config.to_dict()
Domains
~~~~~~~
Get a list of domains configured for this app::
domainlist = app.domains(order_by='id')
Add a domain to this app::
domain = app.add_domain('domain_hostname', 'sni_endpoint_id_or_name')
domain = app.add_domain('domain_hostname', None) # domain will not be associated with an SNI endpoint
Example of finding a matching SNI, given a domain::
domain = 'subdomain.domain.com'
sni_endpoint_id = None
for sni_endpoint in app.sni_endpoints():
for cert_domain in sni_endpoint.ssl_cert.cert_domains:
# check root or wildcard
if cert_domain in domain or cert_domain[1:] in domain:
sni_endpoint_id_or_name = sni_endpoint.id
domain = app.add_domain(domain, sni_endpoint_id)
Remove a domain from this app::
domain = app.remove_domain('domain_hostname')
SNI Endpoints
~~~~~~~~~~~~~
Get a list of SNI Endpoints for this app::
sni_endpoints = app.sni_endpoints()
Add an SNI endpoint to this app::
sni_endpoint = app.add_sni_endpoint(
'-----BEGIN CERTIFICATE----- ...',
'-----BEGIN RSA PRIVATE KEY----- ...'
)
Update an SNI endpoint for this app::
sni_endpoint = app.update_sni_endpoint(
'sni_endpoint_id_or_name',
'-----BEGIN CERTIFICATE----- ...',
'-----BEGIN RSA PRIVATE KEY----- ...'
)
Delete an SNI endpoint for this app::
app.remove_sni_endpoint('sni_endpoint_id_or_name')
Dynos & Process Formations
~~~~~~~~~~~~~~~~~~~~~~~~~~
Dynos
_____
Dynos represent all your running dyno processes. Use dynos to investigate whats running on your app.
Use Dynos to create one off processes/run commands.
**You don't "scale" dyno Processes. You "scale" Formation Processes. See Formations section Below**
Get a list of running dynos::
dynolist = app.dynos()
dynolist = app.dynos(order_by='id')
Kill a dyno::
app.kill_dyno(<dyno_id_or_name>)
app.dynos['run.1'].kill()
dyno.kill()
**Restarting your dynos is achieved by killing existing dynos, and allowing heroku to auto start them. A Handy wrapper for this proceses has been provided below.**
*N.B. This will only restart Formation processes, it will not kill off other processes.*
Restart a Dyno::
#a simple wrapper around dyno.kill() with run protection so won't kill any proc of type='run' e.g. 'run.1'
dyno.restart()
Restart all your app's Formation configured Dyno's::
app.restart()
Run a command without attaching to it. e.g. start a command and return the dyno object representing the command::
dyno = app.run_command_detached('fab -l', size=1, env={'key': 'val'})
dyno = heroku_conn.run_command_on_app(<appname>, <command>, size=1, attach=False, printout=True, env={'key': 'val'})
Run a command and attach to it, returning the commands output as a string::
#printout is used to control if the task should also print to STDOUT - useful for long running processes
#size = is the processes dyno size 1X(default), 2X, 3X etc...
#env = Envrionment variables for the dyno
output, dyno = heroku_conn.run_command_on_app(<appname>, <command>, size=1, attach=True, printout=True, env={'key': 'val'})
output = app.run_command('fab -l', size=1, printout=True, env={'key': 'val'})
print output
Formations
__________
Formations represent the dynos that you have configured in your Procfile - whether they are running or not.
Use Formations to scale dynos up and down
Get a list of your configured Processes::
proclist = app.process_formation()
proclist = app.process_formation(order_by='id')
proc = app.process_formation()['web']
proc = heroku_conn.apps()['myapp'].process_formation()['web']
Scale your Procfile processes::
app.process_formation()['web'].scale(2) # run 2 dynos
app.process_formation()['web'].scale(0) # don't run any dynos
proc = app.scale_formation_process(<formation_id_or_name>, <quantity>)
Resize your Procfile Processes::
app.process_formation()['web'].resize(2) # for 2X
app.process_formation()['web'].resize(1) # for 1X
proc = app.resize_formation_process(<formation_id_or_name>, <size>)
Log Drains
~~~~~~~~~~
List all active logdrains::
logdrainlist = app.logdrains()
logdrainlist = app.logdrains(order_by='id')
Create a logdrain::
loggdrain = app.create_logdrain(<url>)
Remove a logdrain::
delete_logdrain - app.remove_logdrain(<id_or_url>)
Log Sessions
~~~~~~~~~~~~
Access the logs::
log = heroku_conn.get_app_log(<app_id_or_name>, dyno='web.1', lines=2, source='app', timeout=False)
log = app.get_log()
log = app.get_log(lines=100)
print(app.get_log(dyno='web.1', lines=2, source='app'))
2011-12-21T22:53:47+00:00 heroku[web.1]: State changed from down to created
2011-12-21T22:53:47+00:00 heroku[web.1]: State changed from created to starting
You can even stream the tail::
#accepts the same params as above - lines|dyno|source|timeout (passed to requests)
log = heroku_conn.stream_app_log(<app_id_or_name>, lines=1, timeout=100)
#or
for line in app.stream_log(lines=1):
print(line)
2011-12-21T22:53:47+00:00 heroku[web.1]: State changed from down to created
2011-12-21T22:53:47+00:00 heroku[web.1]: State changed from created to starting
Maintenance Mode
~~~~~~~~~~~~~~~~
Enable Maintenance Mode::
app.enable_maintenance_mode()
Disable Maintenance Mode::
app.disable_maintenance_mode()
OAuth
~~~~~
OAuthAuthorizations
___________________
List all OAuthAuthorizations::
authorizations = heroku_conn.oauthauthorizations(order_by=id)
Get a specific OAuthAuthorization::
authorization = authorizations[<oauthauthorization_id>]
authorization = heroku_conn.oauthauthorization(oauthauthorization_id)
Create an OAuthAuthorization::
authorization = heroku_conn.oauthauthorization_create(scope, oauthclient_id=None, description=None)
Delete an OAuthAuthorization::
authorization.delete()
heroku_conn.oauthauthorization_delete(oauthauthorization_id)
OAuthClient
___________
List all OAuthClients::
clients = heroku_conn.oauthclients(order_by=id)
Get a specific OAuthClient::
client = clients[<oauthclient_id>]
client = heroku_conn.oauthclient(oauthclient_id)
Create an OAuthClient::
client = heroku_conn.oauthclient_create(name, redirect_uri)
Update an existing OAuthClient::
client = client.update(name=None, redirect_uri=None)
Delete an OAuthClient::
client.delete()
heroku_conn.oauthclient_delete(oauthclient_id)
OAuthToken
__________
Create an OAuthToken::
heroku_conn.oauthtoken_create(client_secret=None, grant_code=None, grant_type=None, refresh_token=None)
Release
~~~~~~~
List all releases::
releaselist = app.releases()
releaselist = app.releases(order_by='version')
Release information::
for release in app.releases():
print("{0}-{1} released by {2} on {3}".format(release.id, release.description, release.user.name, release.created_at))
Rollback to a release::
app.rollback(release.id)
app.rollback("489d7ce8-1cc3-4429-bb79-7907371d4c0e")
Rename App
~~~~~~~~~~
Rename App::
app.rename('Carrot-kettle-teapot-1898')
Customized Sessions
-------------------
Heroku.py is powered by `Requests <http://python-requests.org>`_ and supports all `customized sessions <http://www.python-requests.org/en/latest/user/advanced/#session-objects>`_:
Logging
-------
Note: logging is now achieved by the following method::
import httplib
httplib.HTTPConnection.debuglevel = 1
logging.basicConfig() # you need to initialize logging, otherwise you will not see anything from requests
logging.getLogger().setLevel(logging.INFO)
requests_log = logging.getLogger("requests.packages.urllib3")
requests_log.setLevel(logging.INFO)
requests_log.propagate = True
heroku_conn.ratelimit_remaining()
>>>INFO:requests.packages.urllib3.connectionpool:Starting new HTTPS connection (1): api.heroku.com
>>>send: 'GET /account/rate-limits HTTP/1.1\r\nHost: api.heroku.com\r\nAuthorization: Basic ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ=\r\nContent-Type: application/json\r\nAccept-Encoding: gzip, deflate, compress\r\nAccept: application/vnd.heroku+json; version=3\r\nUser-Agent: python-requests/1.2.3 CPython/2.7.2 Darwin/12.4.0\r\n\r\n'
>>>reply: 'HTTP/1.1 200 OK\r\n'
>>>header: Content-Encoding: gzip
>>>header: Content-Type: application/json;charset=utf-8
>>>header: Date: Thu, 05 Sep 2013 11:13:03 GMT
>>>header: Oauth-Scope: global
>>>header: Oauth-Scope-Accepted: global identity
>>>header: RateLimit-Remaining: 2400
>>>header: Request-Id: ZZZZZZ2a-b704-4bbc-bdf1-e4bc263586cb
>>>header: Server: nginx/1.2.8
>>>header: Status: 200 OK
>>>header: Strict-Transport-Security: max-age=31536000
>>>header: Vary: Accept-Encoding
>>>header: X-Content-Type-Options: nosniff
>>>header: X-Runtime: 0.032193391
>>>header: Content-Length: 44
>>>header: Connection: keep-alive
Installation
------------
To install ``heroku3.py``, simply::
$ pip install heroku3
Or, if you absolutely must::
$ easy_install heroku3
But, you `really shouldn't do that <http://www.pip-installer.org/en/latest/other-tools.html#pip-compared-to-easy-install>`_.
License
-------
Original Heroku License left intact, The code in this repository is mostly my own, but credit where credit is due and all that :)
Copyright (c) 2013 Heroku, Inc.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
History
=======
3.4.0
-----
* Support for python 2.6 dropped
* Add Tests
* Get project building on circleci/travis-ci & coveralls
* Adding Slug to Release Models
* bugfixes
3.2.0-2
-------
* Various fixes for python3
* Add newer features from Heroku API, support for Organisations
3.1.4
-----
* bugfixes
3.1.3 (2015-03-12)
------------------
* removed debug
3.1.0 (2014-11-24)
------------------
* Moved to Heroku3 for pypi release
* Updated heroku/data/cacert.pem
3.0.0 - 3.1.0
-------------
* Add support for all of heroku's api
* Various bugfixes and enhancements
* Add Documentation
* Add examples.py
* Used in production on https://www.migreat.com & https://www.migreat.co.uk since 2013-10-01
3.0.0 (2013-08-28)
------------------
* Rewrite to support V3 API
* Initial release.
Raw data
{
"_id": null,
"home_page": "https://github.com/martyzz1/heroku3.py",
"name": "heroku3",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Martin Moss",
"author_email": "martin_moss@btinternet.com",
"download_url": "https://files.pythonhosted.org/packages/cf/2d/023afcaba9e4dd7443d8ee9a9dd56158775b19174d3b4997c634ec1c5621/heroku3-5.2.1.tar.gz",
"platform": null,
"description": "Heroku3.py\n==========\n\n.. image:: https://img.shields.io/pypi/v/heroku3.svg\n :target: https://pypi.org/project/heroku3\n\n.. image:: https://circleci.com/gh/martyzz1/heroku3.py.svg?style=svg\n :target: https://circleci.com/gh/martyzz1/heroku3.py\n\n.. image:: https://coveralls.io/repos/github/martyzz1/heroku3.py/badge.svg?branch=master\n :target: https://coveralls.io/github/martyzz1/heroku3.py?branch=master\n\n.. image:: https://img.shields.io/pypi/pyversions/setuptools.svg\n\nThis is the updated Python wrapper for the Heroku `API V3. <https://devcenter.heroku.com/articles/platform-api-reference>`_\nThe Heroku REST API allows Heroku users to manage their accounts, applications, addons, and\nother aspects related to Heroku. It allows you to easily utilize the Heroku\nplatform from your applications.\n\nIntroduction\n============\n\nFirst instantiate a heroku_conn as above::\n\n import heroku3\n heroku_conn = heroku3.from_key('YOUR_API_KEY')\n\nInteract with your applications::\n\n >>> heroku_conn.apps()\n [<app 'sharp-night-7758'>, <app 'empty-spring-4049'>, ...]\n\n >>> app = heroku_conn.apps()['sharp-night-7758']\n\nGeneral notes on Debugging\n--------------------------\n\nHeroku provides some useful debugging information. This code exposes the following\n\nRatelimit Remaining\n~~~~~~~~~~~~~~~~~~~\n\nGet the current ratelimit remaining::\n\n num = heroku_conn.ratelimit_remaining()\n\nLast Request Id\n~~~~~~~~~~~~~~~\n\nGet the unique ID of the last request sent to heroku to give them for debugging::\n\n id = heroku_conn.last_request_id\n\nGeneral notes about list Objects\n--------------------------------\n\nThe new heroku3 API gives greater control over the interaction of the returned data. Primarily this\ncentres around calls to the api which result in list objects being returned.\ne.g. multiple objects like apps, addons, releases etc.\n\nThroughout the docs you'll see references to using limit & order_by. Wherever you see these, you *should* be able to use *limit*, *order_by*, *sort* and *valrange*.\n\nYou can control ordering, limits and pagination by supplying the following keywords::\n\n order_by=<'id'|'version'>\n limit=<num>\n valrange=<string> - See api docs for this, This value is passed straight through to the API call *as is*.\n sort=<'asc'|'desc'>\n\n**You'll have to investigate the api for each object's *Accept-Ranges* header to work out which fields can be ordered by**\n\nExamples\n~~~~~~~~\n\nList all apps in name order::\n\n heroku_conn.apps(order_by='name')\n\nList the last 10 releases::\n\n app.releases(order_by='version', limit=10, sort='desc')\n heroku_conn.apps()['empty-spring-4049'].releases(order_by='version', limit=10, sort='desc')\n\nList objects can be referred to directly by *any* of their primary keys too::\n\n app = heroku_conn.apps()['myapp']\n dyno = heroku_conn.apps()['myapp_id'].dynos()['web.1']\n proc = heroku_conn.apps()['my_app'].process_formation()['web']\n\n**Be careful if you use *limit* in a list call *and* refer directly to an primary key**\nE.g.Probably stupid...::\n\n dyno = heroku_conn.apps()['myapp'].dynos(limit=1)['web.1']\n\nGeneral Notes on Objects\n------------------------\n\nTo find out the Attributes available for a given object, look at the corresponding Documentation for that object.\ne.g.\n\n`Formation <https://devcenter.heroku.com/articles/platform-api-reference#formation>`_ Object::\n\n >>>print(feature.command)\n bundle exec rails server -p $PORT\n\n >>>print(feature.created_at)\n 2012-01-01T12:00:00Z\n\n >>>print(feature.id)\n 01234567-89ab-cdef-0123-456789abcdef\n\n >>>print(feature.quantity)\n 1\n >>>print(feature.size)\n 1\n >>>print(feature.type)\n web\n\n >>>print(feature.updated_at)\n 2012-01-01T12:00:00Z\n\nSwitching Accounts Mid Flow\n---------------------------\n\nIt is also possible to change the underlying heroku_connection at any point on any object or listobject by creating a new heroku_conn and calling change_connection::\n\n heroku_conn1 = heroku3.from_key('YOUR_API_KEY')\n heroku_conn2 = heroku3.from_key('ANOTHER_API_KEY')\n app = heroku_conn1.apps()['MYAPP']\n app.change_connection(heroku_conn2)\n app.config() # this call will use heroku_conn2\n ## or on list objects\n apps = heroku_conn1.apps()\n apps.change_connection(heroku_conn2)\n for app in apps:\n config = app.config()\n\nLegacy API Calls\n================\n\nThe API has been built with an internal legacy=True ability, so any functionlity not implemented in the new API can be called via the previous `legacy API <https://legacy-api-docs.herokuapp.com/>`_. This is currently only used for *rollbacks*.\n\nObject API\n==========\n\nAccount\n-------\n\nGet account::\n\n account = heroku_conn.account()\n\nChange Password::\n\n account.change_password(\"<current_password>\", \"<new_password>\")\n\nSSH Keys\n~~~~~~~~\n\nList all configured keys::\n\n keylist = account.keys(order_by='id')\n\nAdd Key::\n\n account.add_key(<public_key_string>)\n\nRemove key::\n\n account.remove_key(<public_key_string - or fingerprint>)\n\nAccount Features (Heroku Labs)\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nList all configured account \"features\"::\n\n featurelist = account.features()\n\nDisable a feature::\n\n feature = account.disable_feature(id_or_name)\n feature.disable()\n\nEnable a feature::\n\n feature = account.enable_feature(id_or_name)\n feature.enable()\n\nPlans - or Addon Services\n-------------------------\n\nList all available Addon Services::\n\n addonlist = heroku_conn.addon_services(order_by='id')\n addonlist = heroku_conn.addon_services()\n\nGet specific available Addon Service::\n\n addonservice = heroku_conn.addon_services(<id_or_name>)\n\nApp\n--------\n\nThe App Class is the starting point for most of the api functionlity.\n\nList all apps::\n\n applist = heroku_conn.apps(order_by='id')\n applist = heroku_conn.apps()\n\nGet specific app::\n\n app = heroku_conn.app(<id_or_name>)\n app = heroku_conn.apps()[id_or_name]\n\nCreate an app::\n\n app = heroku_conn.create_app(name=None, stack_id_or_name='cedar', region_id_or_name=<region_id>)\n\nDestroy an app (**Warning this is irreversible**)::\n\n app.delete()\n\nAddons\n~~~~~~\n\nList all Addons::\n\n addonlist = app.addons(order_by='id')\n addonlist = applist[<id_or_name>].addons(limit=10)\n addonlist = heroku_conn.addons(<app_id_or_name>)\n\nInstall an Addon::\n\n addon = app.install_addon(plan_id_or_name='<id>', config={})\n addon = app.install_addon(plan_id_or_name='<name>', config={})\n addon = app.install_addon(plan_id_or_name=addonservice.id, config={})\n addon = app.install_addon(plan_id_or_name=addonservice.id, config={}, attachment_name='ADDON_ATTACHMENT_CUSTOM_NAME')\n\nRemove an Addon::\n\n addon = app.remove_addon(<id>)\n addon = app.remove_addon(addonservice.id)\n addon.delete()\n\nUpdate/Upgrade an Addon::\n\n addon = addon.upgrade(plan_id_or_name='<name>')\n addon = addon.upgrade(plan_id_or_name='<id>')\n\nBuildpacks\n~~~~~~~~~~~~~\n\nUpdate all buildpacks::\n\n buildpack_urls = ['https://github.com/some/buildpack', 'https://github.com/another/buildpack']\n app.update_buildpacks(buildpack_urls)\n\n*N.B. buildpack_urls can also be empty. This clears all buildpacks.*\n\nApp Labs/Features\n~~~~~~~~~~~~~~~~~\n\nList all features::\n\n appfeaturelist = app.features()\n appfeaturelist = app.labs() #nicename for features()\n appfeaturelist = app.features(order_by='id', limit=10)\n\nAdd a Feature::\n\n appfeature = app.enable_feature(<feature_id_or_name>)\n\nRemove a Feature::\n\n appfeature = app.disable_feature(<feature_id_or_name>)\n\nApp Transfers\n~~~~~~~~~~~~~\n\nList all Transfers::\n\n transferlist = app.transfers()\n transferlist = app.transfers(order_by='id', limit=10)\n\nCreate a Transfer::\n\n transfer = app.create_transfer(recipient_id_or_name=<user_id>)\n transfer = app.create_transfer(recipient_id_or_name=<valid_email>)\n\nDelete a Transfer::\n\n deletedtransfer = app.delete_transfer(<transfer_id>)\n deletedtransfer = transfer.delete()\n\nUpdate a Transfer's state::\n\n transfer.update(state)\n transfer.update(\"Pending\")\n transfer.update(\"Declined\")\n transfer.update(\"Accepted\")\n\nCollaborators\n~~~~~~~~~~~~~\n\nList all Collaborators::\n\n collaboratorlist = app.collaborators()\n collaboratorlist = app.collaborators(order_by='id')\n\nAdd a Collaborator::\n\n collaborator = app.add_collaborator(user_id_or_email=<valid_email>, silent=0)\n collaborator = app.add_collaborator(user_id_or_email=user_id, silent=0)\n collaborator = app.add_collaborator(user_id_or_email=user_id, silent=1) #don't send invitation email\n\nRemove a Collaborator::\n\n collaborator = app.remove_collaborator(userid_or_email)\n\nConfigVars\n~~~~~~~~~~\n\nGet an apps config::\n\n config = app.config()\n\nAdd a config Variable::\n\n config['New_var'] = 'new_val'\n\nUpdate a config Variable::\n\n config['Existing_var'] = 'new_val'\n\nRemove a config Variable::\n\n del config['Existing_var']\n config['Existing_var'] = None\n\nUpdate Multiple config Variables::\n\n # newconfig will always be a new ConfigVars object representing all config values for an app\n # i.e. there won't be partial configs\n newconfig = config.update({u'TEST1': u'A1', u'TEST2': u'A2', u'TEST3': u'A3'})\n newconfig = heroku_conn.update_appconfig(<app_id_or_name>, {u'TEST1': u'A1', u'TEST2': u'A2', u'TEST3': u'A3'})\n newconfig = app.update_config({u'TEST1': u'A1', u'TEST2': u'A2', u'TEST3': u'A3'})\n\nCheck if a var exists::\n\n if 'KEY' in config:\n print(\"KEY = {0}\".format(config[KEY]))\n\nGet dict of config vars::\n\n my_dict = config.to_dict()\n\nDomains\n~~~~~~~\n\nGet a list of domains configured for this app::\n\n domainlist = app.domains(order_by='id')\n\nAdd a domain to this app::\n\n domain = app.add_domain('domain_hostname', 'sni_endpoint_id_or_name')\n domain = app.add_domain('domain_hostname', None) # domain will not be associated with an SNI endpoint\n\nExample of finding a matching SNI, given a domain::\n\n domain = 'subdomain.domain.com'\n sni_endpoint_id = None\n for sni_endpoint in app.sni_endpoints():\n for cert_domain in sni_endpoint.ssl_cert.cert_domains:\n # check root or wildcard\n if cert_domain in domain or cert_domain[1:] in domain:\n sni_endpoint_id_or_name = sni_endpoint.id\n domain = app.add_domain(domain, sni_endpoint_id)\n\nRemove a domain from this app::\n\n domain = app.remove_domain('domain_hostname')\n\nSNI Endpoints\n~~~~~~~~~~~~~\n\nGet a list of SNI Endpoints for this app::\n\n sni_endpoints = app.sni_endpoints()\n\nAdd an SNI endpoint to this app::\n\n sni_endpoint = app.add_sni_endpoint(\n '-----BEGIN CERTIFICATE----- ...',\n '-----BEGIN RSA PRIVATE KEY----- ...'\n )\n\nUpdate an SNI endpoint for this app::\n\n sni_endpoint = app.update_sni_endpoint(\n 'sni_endpoint_id_or_name',\n '-----BEGIN CERTIFICATE----- ...',\n '-----BEGIN RSA PRIVATE KEY----- ...'\n )\n\nDelete an SNI endpoint for this app::\n\n app.remove_sni_endpoint('sni_endpoint_id_or_name')\n\nDynos & Process Formations\n~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nDynos\n_____\n\nDynos represent all your running dyno processes. Use dynos to investigate whats running on your app.\nUse Dynos to create one off processes/run commands.\n\n**You don't \"scale\" dyno Processes. You \"scale\" Formation Processes. See Formations section Below**\n\nGet a list of running dynos::\n\n dynolist = app.dynos()\n dynolist = app.dynos(order_by='id')\n\nKill a dyno::\n\n app.kill_dyno(<dyno_id_or_name>)\n app.dynos['run.1'].kill()\n dyno.kill()\n\n**Restarting your dynos is achieved by killing existing dynos, and allowing heroku to auto start them. A Handy wrapper for this proceses has been provided below.**\n\n*N.B. This will only restart Formation processes, it will not kill off other processes.*\n\nRestart a Dyno::\n\n #a simple wrapper around dyno.kill() with run protection so won't kill any proc of type='run' e.g. 'run.1'\n dyno.restart()\n\nRestart all your app's Formation configured Dyno's::\n\n app.restart()\n\nRun a command without attaching to it. e.g. start a command and return the dyno object representing the command::\n\n dyno = app.run_command_detached('fab -l', size=1, env={'key': 'val'})\n dyno = heroku_conn.run_command_on_app(<appname>, <command>, size=1, attach=False, printout=True, env={'key': 'val'})\n\nRun a command and attach to it, returning the commands output as a string::\n\n #printout is used to control if the task should also print to STDOUT - useful for long running processes\n #size = is the processes dyno size 1X(default), 2X, 3X etc...\n #env = Envrionment variables for the dyno\n output, dyno = heroku_conn.run_command_on_app(<appname>, <command>, size=1, attach=True, printout=True, env={'key': 'val'})\n output = app.run_command('fab -l', size=1, printout=True, env={'key': 'val'})\n print output\n\nFormations\n__________\n\nFormations represent the dynos that you have configured in your Procfile - whether they are running or not.\nUse Formations to scale dynos up and down\n\nGet a list of your configured Processes::\n\n proclist = app.process_formation()\n proclist = app.process_formation(order_by='id')\n proc = app.process_formation()['web']\n proc = heroku_conn.apps()['myapp'].process_formation()['web']\n\nScale your Procfile processes::\n\n app.process_formation()['web'].scale(2) # run 2 dynos\n app.process_formation()['web'].scale(0) # don't run any dynos\n proc = app.scale_formation_process(<formation_id_or_name>, <quantity>)\n\nResize your Procfile Processes::\n\n app.process_formation()['web'].resize(2) # for 2X\n app.process_formation()['web'].resize(1) # for 1X\n proc = app.resize_formation_process(<formation_id_or_name>, <size>)\n\nLog Drains\n~~~~~~~~~~\n\nList all active logdrains::\n\n logdrainlist = app.logdrains()\n logdrainlist = app.logdrains(order_by='id')\n\nCreate a logdrain::\n\n loggdrain = app.create_logdrain(<url>)\n\nRemove a logdrain::\n\n delete_logdrain - app.remove_logdrain(<id_or_url>)\n\nLog Sessions\n~~~~~~~~~~~~\n\nAccess the logs::\n\n log = heroku_conn.get_app_log(<app_id_or_name>, dyno='web.1', lines=2, source='app', timeout=False)\n log = app.get_log()\n log = app.get_log(lines=100)\n print(app.get_log(dyno='web.1', lines=2, source='app'))\n 2011-12-21T22:53:47+00:00 heroku[web.1]: State changed from down to created\n 2011-12-21T22:53:47+00:00 heroku[web.1]: State changed from created to starting\n\nYou can even stream the tail::\n\n #accepts the same params as above - lines|dyno|source|timeout (passed to requests)\n log = heroku_conn.stream_app_log(<app_id_or_name>, lines=1, timeout=100)\n #or\n for line in app.stream_log(lines=1):\n print(line)\n\n 2011-12-21T22:53:47+00:00 heroku[web.1]: State changed from down to created\n 2011-12-21T22:53:47+00:00 heroku[web.1]: State changed from created to starting\n\nMaintenance Mode\n~~~~~~~~~~~~~~~~\n\nEnable Maintenance Mode::\n\n app.enable_maintenance_mode()\n\nDisable Maintenance Mode::\n\n app.disable_maintenance_mode()\n\nOAuth\n~~~~~\nOAuthAuthorizations\n___________________\n\nList all OAuthAuthorizations::\n\n authorizations = heroku_conn.oauthauthorizations(order_by=id)\n\nGet a specific OAuthAuthorization::\n\n authorization = authorizations[<oauthauthorization_id>]\n authorization = heroku_conn.oauthauthorization(oauthauthorization_id)\n\nCreate an OAuthAuthorization::\n\n authorization = heroku_conn.oauthauthorization_create(scope, oauthclient_id=None, description=None)\n\nDelete an OAuthAuthorization::\n\n authorization.delete()\n heroku_conn.oauthauthorization_delete(oauthauthorization_id)\n\nOAuthClient\n___________\n\nList all OAuthClients::\n\n clients = heroku_conn.oauthclients(order_by=id)\n\nGet a specific OAuthClient::\n\n client = clients[<oauthclient_id>]\n client = heroku_conn.oauthclient(oauthclient_id)\n\nCreate an OAuthClient::\n\n client = heroku_conn.oauthclient_create(name, redirect_uri)\n\nUpdate an existing OAuthClient::\n\n client = client.update(name=None, redirect_uri=None)\n\nDelete an OAuthClient::\n\n client.delete()\n heroku_conn.oauthclient_delete(oauthclient_id)\n\nOAuthToken\n__________\n\nCreate an OAuthToken::\n\n heroku_conn.oauthtoken_create(client_secret=None, grant_code=None, grant_type=None, refresh_token=None)\n\nRelease\n~~~~~~~\n\nList all releases::\n\n releaselist = app.releases()\n releaselist = app.releases(order_by='version')\n\nRelease information::\n\n for release in app.releases():\n print(\"{0}-{1} released by {2} on {3}\".format(release.id, release.description, release.user.name, release.created_at))\n\nRollback to a release::\n\n app.rollback(release.id)\n app.rollback(\"489d7ce8-1cc3-4429-bb79-7907371d4c0e\")\n\nRename App\n~~~~~~~~~~\n\nRename App::\n\n app.rename('Carrot-kettle-teapot-1898')\n\nCustomized Sessions\n-------------------\n\nHeroku.py is powered by `Requests <http://python-requests.org>`_ and supports all `customized sessions <http://www.python-requests.org/en/latest/user/advanced/#session-objects>`_:\n\nLogging\n-------\n\nNote: logging is now achieved by the following method::\n\n import httplib\n httplib.HTTPConnection.debuglevel = 1\n\n logging.basicConfig() # you need to initialize logging, otherwise you will not see anything from requests\n logging.getLogger().setLevel(logging.INFO)\n requests_log = logging.getLogger(\"requests.packages.urllib3\")\n requests_log.setLevel(logging.INFO)\n requests_log.propagate = True\n\n heroku_conn.ratelimit_remaining()\n\n >>>INFO:requests.packages.urllib3.connectionpool:Starting new HTTPS connection (1): api.heroku.com\n >>>send: 'GET /account/rate-limits HTTP/1.1\\r\\nHost: api.heroku.com\\r\\nAuthorization: Basic ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ=\\r\\nContent-Type: application/json\\r\\nAccept-Encoding: gzip, deflate, compress\\r\\nAccept: application/vnd.heroku+json; version=3\\r\\nUser-Agent: python-requests/1.2.3 CPython/2.7.2 Darwin/12.4.0\\r\\n\\r\\n'\n >>>reply: 'HTTP/1.1 200 OK\\r\\n'\n >>>header: Content-Encoding: gzip\n >>>header: Content-Type: application/json;charset=utf-8\n >>>header: Date: Thu, 05 Sep 2013 11:13:03 GMT\n >>>header: Oauth-Scope: global\n >>>header: Oauth-Scope-Accepted: global identity\n >>>header: RateLimit-Remaining: 2400\n >>>header: Request-Id: ZZZZZZ2a-b704-4bbc-bdf1-e4bc263586cb\n >>>header: Server: nginx/1.2.8\n >>>header: Status: 200 OK\n >>>header: Strict-Transport-Security: max-age=31536000\n >>>header: Vary: Accept-Encoding\n >>>header: X-Content-Type-Options: nosniff\n >>>header: X-Runtime: 0.032193391\n >>>header: Content-Length: 44\n >>>header: Connection: keep-alive\n\nInstallation\n------------\n\nTo install ``heroku3.py``, simply::\n\n $ pip install heroku3\n\nOr, if you absolutely must::\n\n $ easy_install heroku3\n\nBut, you `really shouldn't do that <http://www.pip-installer.org/en/latest/other-tools.html#pip-compared-to-easy-install>`_.\n\nLicense\n-------\n\nOriginal Heroku License left intact, The code in this repository is mostly my own, but credit where credit is due and all that :)\n\nCopyright (c) 2013 Heroku, Inc.\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n\n\nHistory\n=======\n\n3.4.0\n-----\n* Support for python 2.6 dropped\n* Add Tests\n* Get project building on circleci/travis-ci & coveralls\n* Adding Slug to Release Models\n* bugfixes\n\n3.2.0-2\n-------\n* Various fixes for python3\n* Add newer features from Heroku API, support for Organisations\n\n3.1.4\n-----\n* bugfixes\n\n3.1.3 (2015-03-12)\n------------------\n* removed debug\n\n3.1.0 (2014-11-24)\n------------------\n* Moved to Heroku3 for pypi release\n* Updated heroku/data/cacert.pem\n\n3.0.0 - 3.1.0\n-------------\n* Add support for all of heroku's api\n* Various bugfixes and enhancements\n* Add Documentation\n* Add examples.py\n* Used in production on https://www.migreat.com & https://www.migreat.co.uk since 2013-10-01\n\n3.0.0 (2013-08-28)\n------------------\n* Rewrite to support V3 API\n\n* Initial release.\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Heroku API Wrapper.",
"version": "5.2.1",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8e2447b4cbdcfa52cd184b670d37627ba312fc0fd6780ef9949946e6ae7d1145",
"md5": "8ea3b770da4be6e680639d47fa3fc329",
"sha256": "7a33728b5f63e44312fcd7b378ba7941299dbeb5f16413995bce97486ca65117"
},
"downloads": -1,
"filename": "heroku3-5.2.1-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "8ea3b770da4be6e680639d47fa3fc329",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 161993,
"upload_time": "2023-04-17T20:09:33",
"upload_time_iso_8601": "2023-04-17T20:09:33.210468Z",
"url": "https://files.pythonhosted.org/packages/8e/24/47b4cbdcfa52cd184b670d37627ba312fc0fd6780ef9949946e6ae7d1145/heroku3-5.2.1-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cf2d023afcaba9e4dd7443d8ee9a9dd56158775b19174d3b4997c634ec1c5621",
"md5": "786a6ceb4e468e6a82c626b9b0175a3f",
"sha256": "f3553a154e9f595734be5129edf5d91c70c4e0aa58237d1ec584c721fadd0bcf"
},
"downloads": -1,
"filename": "heroku3-5.2.1.tar.gz",
"has_sig": false,
"md5_digest": "786a6ceb4e468e6a82c626b9b0175a3f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 160231,
"upload_time": "2023-04-17T20:09:34",
"upload_time_iso_8601": "2023-04-17T20:09:34.784411Z",
"url": "https://files.pythonhosted.org/packages/cf/2d/023afcaba9e4dd7443d8ee9a9dd56158775b19174d3b4997c634ec1c5621/heroku3-5.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-04-17 20:09:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "martyzz1",
"github_project": "heroku3.py",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"circle": true,
"requirements": [],
"lcname": "heroku3"
}
JSON
