Configuration Options
*********************

PRAW’s configuration options are broken down into the following
categories:

* Basic Configuration Options

* OAuth Configuration Options

* Reddit Site Configuration Options

* Miscellaneous Configuration Options

* Custom Configuration Options

All of these options can be provided in any of the ways mentioned in
Configuring PRAW.


Basic Configuration Options
===========================

check_for_updates:
   When "true", check for new versions of PRAW. When a newer version
   of PRAW is available a message is reported via standard error
   (default: "true").

user_agent:
   (Required) A unique description of your application. The following
   format is recommended according to Reddit’s API Rules:
   "<platform>:<app ID>:<version string> (by u/<reddit username>)".


OAuth Configuration Options
===========================

client_id:
   (Required) The OAuth client id associated with your registered
   Reddit application. See Authenticating via OAuth for instructions
   on registering a Reddit application.

client_secret:
   The OAuth client secret associated with your registered Reddit
   application. This option is required for all application types,
   however, the value must be set to "None" for **installed**
   applications.

refresh_token:
   For either **web** applications, or **installed** applications
   using the code flow, you can directly provide a previously obtained
   refresh token. Using a **web** application in conjunction with this
   option is useful, for example, if you prefer to not have your
   username and password available to your program, as required for a
   **script** application. See: Obtaining a Refresh Token and Using a
   Saved Refresh Token

redirect_uri:
   The redirect URI associated with your registered Reddit
   application. This field is unused for **script** applications and
   is only needed for both **web** applications, and **installed**
   applications when the "url()" method is used.

password:
   The password of the Reddit account associated with your registered
   Reddit **script** application. This field is required for
   **script** applications, and PRAW assumes it is working with a
   **script** application by its presence.

username:
   The username of the Reddit account associated with your registered
   Reddit **script** application. This field is required for
   **script** applications, and PRAW assumes it is working with a
   **script** application by its presence.


Reddit Site Configuration Options
=================================

PRAW can be configured to work with instances of Reddit which are not
hosted at reddit.com. The following options may need to be updated in
order to successfully access a third-party Reddit site:

comment_kind:
   The type prefix for comments on the Reddit instance (default:
   "t1_").

message_kind:
   The type prefix for messages on the Reddit instance (default:
   "t4_").

oauth_url:
   The URL used to access the Reddit instance’s API (default:
   https://oauth.reddit.com).

reddit_url:
   The URL used to access the Reddit instance. PRAW assumes the
   endpoints for establishing OAuth authorization are accessible under
   this URL (default: https://www.reddit.com).

redditor_kind:
   The type prefix for redditors on the Reddit instance (default:
   "t2_").

short_url:
   The URL used to generate short links on the Reddit instance
   (default: https://redd.it).

submission_kind:
   The type prefix for submissions on the Reddit instance (default:
   "t3_").

subreddit_kind:
   The type prefix for subreddits on the Reddit instance (default:
   "t5_").


Miscellaneous Configuration Options
===================================

These are options that do not belong in another category, but still
play a part in PRAW.

check_for_async:
   When "true", check if PRAW is being ran in an asynchronous
   environment whenever a request is made. If so, a warning will be
   logged recommending the usage of Async PRAW. (default: "true")

ratelimit_seconds:
   Controls the maximum amount of seconds PRAW will capture ratelimits
   returned in JSON data. Because this can be as high as 10 minutes,
   only ratelimits of up to 5 seconds are captured and waited on by
   default. Should be a number representing the amount of seconds to
   sleep.

   Note:

     PRAW sleeps for the ratelimit plus either 1/10th of the ratelimit
     or 1 second, whichever is smallest.

timeout:
   Controls the amount of time PRAW will wait for a request from
   Reddit to complete before throwing an exception. By default, PRAW
   waits 16 seconds before throwing an exception.


Custom Configuration Options
============================

Your application can utilize PRAW’s configuration system in order to
provide its own custom settings.

For instance you might want to add an "app_debugging: true" option to
your application’s "praw.ini" file. To retrieve the value of this
custom option from an instance of "Reddit" you can execute:

   reddit.config.custom["app_debugging"]

Note:

  Custom PRAW configuration environment variables are not supported.
  You can directly access environment variables via "os.getenv".
