Contributing to PRAW¶
PRAW gladly welcomes new contributions. As with most larger projects, we have an established consistent way of doing things. A consistent style increases readability, decreases bug-potential and makes it faster to understand how everything works together.
PRAW follows PEP 8 and PEP 257. The
pre_push.py script can be used to
test for compliance with these PEPs in addition to providing a few other
checks. The following are PRAW-specific guidelines in addition to those PEP’s.
- Within a single file classes are sorted alphabetically where inheritance permits.
- Within a class, methods are sorted alphabetically within their respective
groups with the following as the grouping order:
- Static methods
- Class methods
- Instance Methods
- Use descriptive names for the catch-all keyword argument. E.g.,
Contributions to PRAW requires 100% test coverage as reported by Coveralls. If you know how to add a feature, but aren’t sure how to write the necessary tests, please open a PR anyway so we can work with you to write the necessary tests.
Running the Test Suite¶
Travis CI automatically runs all updates to known branches and pull requests. However, it’s useful to be able to run the tests locally. The simplest way is via:
python setup.py test
Without any configuration or modification, all the tests should pass.
Adding and Updating Integration Tests¶
PRAW’s integration tests utilize Betamax to record an interaction with Reddit. The recorded interaction is then replayed for subsequent test runs.
To safely record a cassette without leaking your account credentials, PRAW utilizes a number of environment variables which are replaced with placeholders in the cassettes. The environment variables are (listed in bash export format):
export prawtest_client_id=myclientid export prawtest_client_secret=myclientsecret export prawtest_password=mypassword export prawtest_test_subreddit=reddit_api_test export prawtest_username=myusername export prawtest_user_agent=praw_pytest
By setting these environment variables prior to running
test, when adding or updating cassettes, instances of
mypassword we be
replaced by the placeholder text
<PASSWORD> and similar for the other
When adding or updating a cassette, you will likely want to force requests to occur again rather than using an existing cassette. The simplest way to rebuild a cassette is to first delete it, and then rerun the test suite.
Please always verify that only the requests you expect to be made are contained within your cassette.
- All publicly available functions, classes and modules should have a docstring.
- Use correct terminology. A subreddit’s fullname is something like
t5_xyfc7. The correct term for a subreddit’s “name” like python is its display name.
Files to Update¶
For feature additions, bugfixes, or code removal please add an appropriate
CHANGES.rst. If the
Unreleased section does not exist at the
CHANGES.rst please add it. See commit
for an example.
Please also read through: https://github.com/praw-dev/praw/blob/master/.github/CONTRIBUTING.md