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.
Note
Python 3.6+ is needed to run the script.
Note
In order to install the dependencies needed to run the script, you can install the
[dev]
package of praw, like so:
pip install praw[dev]
Code¶
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
Properties
Instance Methods
Use descriptive names for the catch-all keyword argument. E.g.,
**other_options
rather than**kwargs
.
Testing¶
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¶
Github Actions 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:
pytest
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 python setup.py test
, when
adding or updating cassettes, instances of mypassword
will be replaced by the
placeholder text <PASSWORD>
and similar for the other environment variables.
To use tokens instead of username/password set prawtest_refresh_token
instead of
prawtest_password
and prawtest_username
.
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.
Documentation¶
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.
Static Checker¶
PRAW’s test suite comes with a checker tool that can warn you of using incorrect
documentation styles (using .. code-block::
instead of .. code::
, using /r/
instead of r/
, etc.).
- class tools.static_word_checks.StaticChecker(replace: bool)¶
Run simple checks on the entire document or specific lines.
- __init__(replace: bool)¶
Initializes the class.
- Parameters
replace – Whether or not to make replacements.
- check_for_double_syntax(filename: str, content: str) → bool¶
Checks a file for double-slash statements (
/r/
and/u/
).- Parameters
filename – The name of the file to check & replace.
content – The content of the file.
- Returns
A boolean with the status of the check.
- check_for_noreturn(filename: str, line_number: int, content: str) → bool¶
Checks a line for
NoReturn
statements.- Parameters
filename – The name of the file to check & replace.
line_number – The line number.
content – The content of the line.
- Returns
A boolean with the status of the check.
- run_checks() → bool¶
Scan a directory and run the checks.
The directory is assumed to be the praw directory located in the parent directory of the file, so if this file exists in
~/praw/tools/static_word_checks.py
, it will check~/praw/praw
.It runs the checks located in the
self.full_file_checks
andself.line_checks
lists, with full file checks being run first.Full-file checks are checks that can also fix the errors they find, while the line checks can just warn about found errors.
Full file checks:
Line checks
Files to Update¶
CHANGES.rst¶
For feature additions, bugfixes, or code removal please add an appropriate entry to
CHANGES.rst
. If the Unreleased
section does not exist at the top of
CHANGES.rst
please add it. See commit 280525c16ba28cdd69cdbb272a0e2764b1c7e6a0 for
an example.
See Also¶
Please also read through: https://github.com/praw-dev/praw/blob/master/.github/CONTRIBUTING.md