The Configuration Files¶
PRAW can be configured on the global, user, local and Reddit
instance
levels. This allows for easy custom configuration to fit your needs.
To build the configuration settings, first the global configuration file is
loaded. It contains the default settings for all PRAW applications and should
never be modified. Then PRAW opens the user level configuration file (if it
exists) and any settings here will take precedence over those in the global
configuration file. Then PRAW opens the local level configuration file (if it
exists) and any settings here will take precedence over those previously
defined. Finally you can set configuration settings by giving them as
additional arguments when instantiating the Reddit
object. Settings given
this way will take precedence over those previously defined.
import praw
user_agent = ("Configuration setting example by /u/_Daimon_. See "
"https://praw.readthedocs.io/en/latest/pages/configuration_files.html")
r = praw.Reddit(user_agent=user_agent, log_requests=1)
Config File Locations¶
The configuration on all levels is stored in a file called praw.ini
.
The global configuration file is located in the praw package location. This file provides the system wide default and should never be modified.
The user configuration file location depends on your operating system. Assuming typical operating system installations and the username foobar the path for specific operating systems should be:
- WINDOWS XP: C:\Documents and Settings\foobar\Application Data\praw.ini
- WINDOWS Vista/7: C:\Users\foobar\AppData\Roaming\praw.ini
- OS with XDG_CONFIG_HOME defined: $XDG_CONFIG_HOME/praw.ini
- OS X / Linux: /home/foobar/.config/praw.ini
The local configuration file is located in the current working directory. This location works best if you want script-specific configuration files.
Configuration Variables¶
The following variables are provided in the [DEFAULT] section of the global config file. Each site can overwrite any of these variables.
- api_request_delay: A float that defines the number of seconds required between calls to the same domain.
- api_domain: A string that defines the domain to use for all standard API requests.
- check_for_updates: A boolean to indicate whether or not to check for package updates.
- cache_timeout: An integer that defines the number of seconds to internally cache GET/POST requests based on URL.
- http_proxy: A string that declares a http proxy to be used. It follows
the requests proxy conventions, e.g.,
http_proxy: http://user:pass@addr:port
. If no proxy is specified, PRAW will pick up the environment variable for http_proxy, if it has been set. - https_proxy: A string that declares a https proxy to be used. It follows
the requests proxy conventions, e.g.,
https_proxy: http://user:pass@addr:port
. If no proxy is specified, PRAW will pick up the environment variable for https_proxy, if it has been set. - log_requests: An integer that determines the level of API call logging.
- 0: no logging
- 1: log only the request URIs
- 2: log the request URIs as well as any POST data
- oauth_domain: A string that defines the domain where OAuth authenticated requests are sent.
- oauth_https: A boolean that determines whether or not to use HTTPS for oauth connections. This should only be changed for development environments.
- output_chars_limit: An integer that defines the maximum length of
unicode representations of
Comment
,Message
andSubmission
objects. This is mainly used to fit them within a terminal window line. A negative value means no limit. - permalink_domain: A string that defines the domain that is used for
- the display permalink for Submissions and Comments.
- short_domain: A string that defines the domain that is used for
- short urls.
- store_json_result: A boolean to indicate if json_dict, which contains
the original API response, should be stored on every object in the json_dict
attribute. Default is
False
as memory usage will double if enabled. For lazy objects, json_dict will beNone
until the data has been fetched. - timeout: Maximum time, a float, in seconds, before a single HTTP request times out. urllib2.URLError is raised upon timeout.
- validate_certs: A boolean to indicate if SSL certificates should be
validated or not. If not specified, will default to
True
. This is mainly for testing local reddit installations with self-signed certificates. - xxx_kind: A string that maps the type returned by json results to a local object. xxx is one of: comment, message, more, redditor, submission, subreddit, userlist. This variable is needed as the object-to-kind mapping is created dynamically on site creation and thus isn’t consistent across sites.
The are additional variables that each site can define. These additional variables are:
- domain: (REQUIRED) A string that provides the domain name, and optionally port, used to connect to the desired reddit site. For reddit proper, this is: www.reddit.com. Note that if you are running a custom reddit install, this name needs to match the domain name listed in the reddit configuration ini.
- user: A string that defines the default username to use when login is called without a user parameter.
- pswd: A string that defines the password to use in conjunction with the provided user.
- ssl_domain: A string that defines the domain where encrypted requests are sent. This is used for logging in, both OAuth and user/password. When not provided, these requests are sent in plaintext (unencrypted).
- oauth_client_id: A string that, if given, defines the
client_id
a reddit object is initialized with. - oauth_client_secret: A string that, if given, defines the
client_secret
a reddit object is initialized with. - oauth_redirect_uri: A string that, if given, defines the
redirect_uri
a reddit object is initialized with. If oauth_client_id and oauth_client_secret is also given, thenget_authorize_url()
can be run without first setting the oauth settings with runningset_oauth_app_info()
. - oauth_refresh_token: A string that, if given, defines the
refresh_token
a reddit object is initialized with. If oauth_client_id, oauth_client_secret, and oauth_redirect_uri are also given, thenrefresh_access_information()
can be run with no arguments to acquire new access information without first runningget_authorize_url()
andget_access_information()
.
Note: The tracking for api_request_delay and cache_timeout is on a per-domain, not per-site, basis. Essentially, this means that the time since the last request is the time since the last request from any site to the domain in question. Thus, unexpected event timings may occur if these values differ between sites to the same domain.
The Sites¶
The default provided sites are:
- reddit: This site defines the settings for reddit proper. It is used by default if the site parameter is not defined when creating the Reddit object.
- local: This site defines settings for a locally running instance of reddit.
The xxx_kind mappings may differ so you may need to shadow (overwrite) the
‘local’ site in your user-level or local-level
praw.ini
file.
Additional sites can be added to represent other instances of reddit or simply
provide an additional set of credentials for easy access to that account. This
is done by adding [YOUR_SITE]
to the praw.ini
file and then calling it
in praw.Reddit
. For example, you could add the following to your
praw.ini
file:
[YOUR_SITE]
domain: www.myredditsite.com
ssl_domain: ssl.myredditsite.com
user: bboe
pswd: this_isn't_my_password
api_request_delay: 7.0
From there, to specify the reddit instance of “YOUR_SITE”, you would do something like this:
import praw
r = praw.Reddit(user_agent='Custom Site Example for PRAW',
site_name='YOUR_SITE')
Of course, you can use any of the above Configuration Variables as well.
Example praw.ini file¶
The following is an example praw.ini
file which has 4 sites defined: 2 for
a reddit proper accounts and 2 for local reddit testing.
[bboe]
domain: www.reddit.com
ssl_domain: ssl.reddit.com
user: bboe
pswd: this_isn't_my_password
[reddit_dev]
domain: www.reddit.com
ssl_domain: ssl.reddit.com
user: someuser
pswd: somepass
[local_dev1]
domain: reddit.local:8000
user: someuser
pswd: somepass
[local_wacky_dev]
domain: reddit.local:8000
user: someuser
pswd: somepass
api_request_delay: 5.0
default_content_limit: 2