praw.ini Files
**************

PRAW comes with a "praw.ini" file in the package directory, and looks
for user defined "praw.ini" files in a few other locations:

1. In the current working directory at the time "Reddit" is
   initialized.

2. In the launching user’s config directory. This directory, if
   available, is detected in order as one of the following:

   1. In the directory specified by the "XDG_CONFIG_HOME" environment
      variable on operating systems that define such an environment
      variable (some modern Linux distributions).

   2. In the directory specified by "$HOME/.config" if the "HOME"
      environment variable is defined (Linux and Mac OS systems).

   3. In the directory specified by the "APPDATA" environment variable
      (Windows).

   Note:

        To check the values of the environment variables, you can open
        up a terminal (Terminal/Terminal.app/Command
        Prompt/Powershell) and echo the variables (replacing
        <variable> with the name of the variable):

     **MacOS/Linux**:

        echo "$<variable>"

     **Windows Command Prompt**

        echo "%<variable>%"

     **Powershell**

        Write-Output "$env:<variable>"

     You can also view environment variables in Python:

        import os
        print(os.environ.get("<variable>", ""))


Format of praw.ini
==================

"praw.ini" uses the INI file format, which can contain multiple groups
of settings separated into sections. PRAW refers to each section as a
"site". The default site, "DEFAULT", is provided in the package’s
"praw.ini" file. This site defines the default settings for
interaction with Reddit. The contents of the package’s "praw.ini" file
are:

   [DEFAULT]
   # A boolean to indicate whether or not to check for package updates.
   check_for_updates=True

   # Object to kind mappings
   comment_kind=t1
   message_kind=t4
   redditor_kind=t2
   submission_kind=t3
   subreddit_kind=t5
   trophy_kind=t6

   # The URL prefix for OAuth-related requests.
   oauth_url=https://oauth.reddit.com

   # The amount of seconds of ratelimit to sleep for upon encountering a specific type of 429 error.
   ratelimit_seconds=5

   # The URL prefix for regular requests.
   reddit_url=https://www.reddit.com

   # The URL prefix for short URLs.
   short_url=https://redd.it

   # The timeout for requests to Reddit in number of seconds
   timeout=16

Warning:

  Avoid modifying the package’s "praw.ini" file. Prefer instead to
  override its values in your own "praw.ini" file. You can even
  override settings of the "DEFAULT" site in user defined "praw.ini"
  files.


Defining Additional Sites
=========================

In addition to the "DEFAULT" site, additional sites can be configured
in user defined "praw.ini" files. All sites inherit settings from the
"DEFAULT" site and can override whichever settings desired.

Defining additional sites is a convenient way to store OAuth
credentials for various accounts, or distinct OAuth applications. For
example if you have three separate bots, you might create a site for
each:

   [bot1]
   client_id=Y4PJOclpDQy3xZ
   client_secret=UkGLTe6oqsMk5nHCJTHLrwgvHpr
   password=pni9ubeht4wd50gk
   username=fakebot1

   [bot2]
   client_id=6abrJJdcIqbclb
   client_secret=Kcn6Bj8CClyu4FjVO77MYlTynfj
   password=mi1ky2qzpiq8s59j
   username=fakebot2

   [bot3]
   client_id=SI8pN3DSbt0zor
   client_secret=xaxkj7HNh8kwg8e5t4m6KvSrbTI
   password=1guiwevlfo00esyy
   username=fakebot3


Choosing a Site
===============

Site selection is done via the "site_name" parameter to "Reddit". For
example, to use the settings defined for "bot2" as shown above,
initialize "Reddit" like so:

   reddit = praw.Reddit("bot2", user_agent="bot2 user agent")

Note:

  In the above example you can obviate passing "user_agent" if you add
  the setting "user_agent=..." in the "[bot2]" site definition.

A site can also be selected via a "praw_site" environment variable.
This approach has precedence over the "site_name" parameter described
above.


Using Interpolation
===================

By default PRAW doesn’t apply any interpolation on the config file but
this can be changed with the "config_interpolation" parameter which
can be set to “basic” or “extended”.

This can be useful to separate the components of the "user_agent" into
individual variables, for example:

   [bot1]
   bot_name=MyBot
   bot_version=1.2.3
   bot_author=MyUser
   user_agent=script:%(bot_name)s:v%(bot_version)s (by u/%(bot_author)s)

This uses basic interpolation thus "Reddit" need to be initialized as
follows:

   reddit = praw.Reddit("bot1", config_interpolation="basic")

Then the value of "reddit.config.user_agent" will be
"script:MyBot:v1.2.3 (by u/MyUser)".

See Interpolation of values for details.

Warning:

  The ConfigParser instance is cached internally at the class level,
  it is shared across all instances of "Reddit" and once set it’s not
  overridden by future invocations.
