Configuration¶

Configuring Environment
Configuring User Agent
Configuring Logging
Appendix

The following are the available configuration options for pyTD.

Environment

Configuration Directory:
	Location in which pyTD’s log, cached tokens (if using on-disk caching), and SSL certificate and key are stored
SSL Certificate and Key:
	If using local web server authentication (script applications), a self-signed SSL certificate and key are needed.

User Agent - api

Consumer Key & Callback URL:
	TD Ameritrade authorization credentials
Token Caching:	Storage of authentication tokens. Can be cached on-disk or in-memory.
Request Parameters:
	Specify how requests should be be made. These include `retry_count`, `pause`, and `session`.

Logging

Log Level:	Logging level of pyTD. The `logging` module handles pyTD’s logging.

Configuring Environment¶

Configuration Directory¶

By default, pyTD creates the directory .tdm in your home directory, which serves as the default location for on-disk token caching, pyTD’s log, and your SSL certificate and key.

To specify a custom configuration directory, store such directory’s absolute path in the environment variable TD_CONFIG_DIR:

$ export TD_CONFIG_DIR=</path/to/directory>

replacing the bracketed text with your absolute path.

SSL Certificate and Key¶

Automatic¶

To generate the self-signed SSL key and certificate needed for local web server authentication, use the top-level configure function:

from pyTD import configure

configure()

This function will prompt creation of a self-signed SSL key and certificate, which will both be placed in your Configuration Directory.

Manual¶

The SSL key and certificate can be created manually with the following OpenSSL command:

$ openssl req -newkey rsa:2048 -nodes -keyout key.pem -x509 -days 365 -out cert.pem

Place the generated key and certificate in the ssl sub-directory of your Configuration Directory.

Setting Environment Variables¶

MacOS/Linux¶

To set the environment variables for your Consumer Key and Callback URL, use the following command:

$ export TD_CONSUMER_KEY='<YOUR_CONSUMER_KEY>'
$ export TD_CALLBACK_URL='<YOUR_CALLBACK_URL>'

replacing the bracketed text with your information.

The All-in-One Solution: `pyTD.configure`¶

pyTD provides the top-level function pyTD.configure which handles all configuration necessary to make an authenticated query.

pyTD.configure(options=None, **kwargs)¶

Create new api given configuration options

Parameters:	options (dict, optional) – A pre-instantiated argument dictionary consumer_key (str, optional) – OAuth ID of application callback_url (str, optional) – Redirect URI of application cache (str, optional) – Token cache (use for testing)

Configuring User Agent¶

There are three ways to configure your user agent:

1. Let pyTD do it for you. So long as you have your Configuration Directory set up, simply run any pyTD function or method and pyTD will create an api object for you, defaulting to an on-disk token cache.

from pyTD.market import get_quotes

get_quotes("AAPL")

Create a non-global API object

Either pass the required parameters individually:

from pyTD.api import api
from pyTD.market import get_quotes

consumer_key = "TEST@AMER.OAUTHAP"
callback_url = "https://localhost:8080"

my_api = api(consumer_key=consumer_key, callback_url=callback_url)

get_quotes("AAPL", api=my_api)

Or pass a pre-instantiated dictonary:

from pyTD.api import api
from pyTD.market import get_quotes

params = {
    "consumer_key": "TEST@AMER.OAUTHAP",
    "callback_url": "https://localhost:8080"
}

my_api = api(params)

get_quotes("AAPL", api=my_api)

Use pyTD.configure:

from pyTD import configure
from pyTD.market import get_quotes

consumer_key = "TEST@AMER.OAUTHAP"
callback_url = "https://localhost:8080"

configure(consumer_key=consumer_key, callback_url=callback_url)

get_quotes("AAPL")

The `api` object¶

The api object serves as the user agent for all requests to the TD Ameritrade Developer API. The api object:

Manages configuration (directory, SSL, Consumer Key, Callback URL)
Connects to the token cache
Verifies, validates, and handles authentication and authorization.

class pyTD.api.api(options=None, **kwargs)¶

User agent for authenticated TD Ameritrade HTTP requests

options¶: dict, optional – Pre-instantiated dictionary of options

consumer_key¶: str – Your application’s OAuth ID

callback_url¶: str – Your application’s Redirect URI

store_tokens¶: bool, default True, optional – Enables on-disk token cache if selected, which is default behavior. Disabled when access_token or refresh_token is passed

cache¶: MemCache or DiskCache, optional – A pre-instantiated token cache

retry_count¶: int, default 3, optional – Desired number of retries if a request fails

pause¶: float, default 0.5, optional – Pause time between retry attempts

session¶: requests_cache.session, default None, optional – A cached requests-cache session

Examples

>>> import pyTD
>>> api = pyTD.api(consumer_key="TEST@AMER.OAUTHAP",
                   callback_url="https://localhost:8080")
>>> api.market.get_quote("AAPL")

Attributes:	`access_token` Router to access token of cache `access_valid` Validity of cache access token `auth_valid` Validity of refresh token and access token `refresh_token` Router to refresh token of cache `refresh_valid` Validity of cache refresh token

Methods

handle_response
refresh_auth
request

Configuring Logging¶

pyTD uses Python’s logging module to log its activity for both informational and debugging purposes.

By default, a log is kept in pyTD’s Configuration Directory and named pyTD.log.

Setting the logging level¶

The console logging level of pyTD can be set in one of three ways:

Using pyTD.log_level:

import pyTD

pyTD.log_level = "DEBUG"

Using logging.setLevel:

import logging

logging.getLogger("pyTD").setLevel(logging.DEBUG)

Using environment variables

The environment variable TD_LOG_LEVEL will override any log level settings for the console logger.

export TD_LOG_LEVEL='DEBUG'

Appendix¶

Environment Variables¶

For reference, the following environment variables may be set to configure pyTD:

TD_CONSUMER_KEY (required) - TD Ameritrade Developer application OAUTH ID
TD_CALLBACK_URL (required) - TD Ameritrade Developer application Callback URL
TD_CONFIG_DIR - for specifying a custom pyTD configuration directory (defaults to ~/.tdm)
TD_STORE_TOKENS - set to false to disable on-disk authentication token caching
TD_LOG_LEVEL - for specifying a console logging level for pyTD