###CONTENTS
- About
- Getting Started
2.1. Initializing VAPy - VAPy Methods
3.1. Voat Content Dictionaries
3.2. Dictionary Methods
3.3. Filter Methods
3.4. Post Methods
3.5. Edit Methods
3.6. Delete Methods
3.7. Subverse Information Methods - Tests
###ABOUT
VAPy is intended to provide a simple, highly explicit Python interface to the Voat API.
While Python wrappers for other APIs are typically centered around Submission and Comment classes, VAPy encourages a somewhat more functional approach and consists largely of simple functions and methods designed to make it easier for users to chain those functions together in meaningful ways.
VAPy provides a Profiles class, which can be run as a standalone application providing a simple user agent and API key management system. Profiles can be used with VAPy applications, providing secure local persistence and renewal for API tokens. This gives users a "setup and ignore" approach to OAuth2 authentication. Profiles encrypts the voat username, API key, and API token with the Voat password. The Voat password is not stored in the database. Profiles uses SQLite3 and simplecrypt.
VAPy includes Vapp, a Voat application framework designed to make it even easier to implement simple applications using VAPy.
###GETTING STARTED
To use VAPy you need a valid Voat.co login and api key.
It is recommended that you first create a profile by running Profiles as a standalone applicaiton:
$ python3 Profiles.py
Select "add" and provide a profile name, Voat login credentials, and API key when prompted. That's all there is to it.
After creating a profile, VAPy can handle OAuth2 authentication with the Voat API. Voat usernames and API keys and tokens are encrytped in a locally persistent database. As a Voat password is required for Voat API token generation, that same Voat password is used as the encryption passphrase to eliminate the need for two passwords per profile. Voat passwords are not stored within the local database.
#####Initializing VAPy
All VAPy methods are available to any instance of VAPy with a properly initialized self.headers attribute. This attribute must contain a current Voat API key and token or communication with the Voat API will not be possible.
vapy = VAPy.VAPy()
vapy.load_profile(<profile>, <pwd>)
load_profile() will retreive the profile named <profile> and create a working headers attribute.
VAPy can be used without the Profiles component by directly calling the set_headers() method:
vapy = Vapy.Vapy()
vapy.set_headers(<uname>, <pwd>, <key>, <token>)
After setting the headers attribute, VAPy functions will work regardless of the use of Profiles.
Where does Profiles store information on my computer?
| Operating System | Directory |
|---|---|
| Linux | ~/.vapy/ |
| Windows | ??? |
| OS X | ??? |
###VAPy METHODS
####Voat Content Dictionaries Most VAPy functions take a voat content dicitonary as an argument. This is the Python dict corresponding to the json data of the API response to a GET query for a submission or comment.
######Sample submission_dict
######Sample comment_dict
get_subverse(subverse)
Returns a dictionary of {submission_dict: [comment_dicts],...}
get_submission_by_id(submissionID)
Returns a submission dictionary.
get_submissions(subverse)
Returns a list of submission dictionaries.
get_content_submissions(subverse)
Returns a list of content submission dictionaries.
get_url_submissions(subverse)
Returns a list of url submission dictionaries.
get_comment_by_id(commentID)
Returns a submission dictionary.
get_comments_by_submission(submissionID)
Returns a list comments dictionaries.
####Dictionary Methods
Returns values from (or calculated from) Voat content dictionaries.
user_names = [vapy.get_author(d) for d in some_itr_of_voat_content_dicts]
Some keys are shared between submission and comment dicts while others are unique to only one. As a result, some VAPy dictionary methods will only return data when passed a specific content dictionary type. For example, get_submission_type() will never return a result when passed a comment dictionary just as get_parent_id() will never return a result when passed a submission dictionary.
get_content(voat_dict, ignore_links=False)
Returns content of submission or comment. If ignore_links == True and voat_dict is a link submission, returns None.
get_subverse(voat_dict)
Returns name of subverse submission or comment is posted to.
get_author(voat_dict)
Returns author or submission or comment.
get_score(voat_dict)
Returns integer value of current score for submission or comment.
get_scores(voat_dict)
Returns (int, int) tuple of upvotes/downvotes for submission or comment.
get_date(voat_dict)
Returns date and time submission or comment was posted.
get_id(voat_dict)
Returns integer value of submission or comment ID.
get_permalink(voat_dict)
Returns Voat.co url for submission or comment.
get_submission_type(submission_dict)
Returns submission type: "url" or "content".
get_submission_title(submission_dict)
Returns title of submission.
get_submission_rank(submission_dict)
Returns current rank of submission.
get_submission_comment_count(submission_dict)
Returns integer value of total number of comments under a submission.
get_comment_submission(comment_dict)
Returns the ID of the submission a comment is under.
get_comment_parent(comment_dict)
Returns the ID of the a comment's parent comment. Returns None if comment is for a top-level comment.
####Filter Methods
Intended to be used primarily with filter(), VAPy filter methods accept voat content dictionaries and return a boolean value.
main_comments = filter(vapy.is_top_level_comment, itr_of_dicts
links = [vapy.get_links(d) for d in filter(is_url_submission, itr_of_dicts)]
contains_regex(voat_dict, ignore_links=False)
True if regex in title or content or link of submission or content of comment, False if not. If ignore_links == True, link submissions always return False.
is_submission(voat_dict)
True if submission, False if comment.
is_comment(voat_dict)
True if comment, False if submission.
is_top_level_comment(voat_dict)
True if comment is directly under submission, False is comment is under another comment.
####Post Methods
post_text_submission(subverse, title, text)
Submit a new text submission.
post_link_submission(subverse, title, url)
Submit a new link submission.
post_reply_to_submission(submission_id, comment)
Submit a new top-level comment to a submission.
post_reply_to_comment(comment_id, comment)
Submit a new comment in response to another comment.
post_reply_to_pm(pm_id, comment)
Submit reply to a personal message.
####Edit Methods
edit_submission(submission_id, title, content)
Replaces submissions title and content.
edit_comment(comment_id, comment)
Replaces submissions title and content.
####Delete Methods
delete_submission(submission_id)
Replaces submissions title and content.
delete_comment(comment_id)
Replaces submissions title and content.
####Subverse Information Methods Accept a subverse name as a string and return the appropriate subverse information.
get_subverse_creation_date(subverse)
Returns string "YYY-MM-DDDOWHH:MM:SS:MSS"
get_subverse_subscriber_count(subverse)
Returns int value of number of subverse subscribers
get_subverse_rated_adult(subverse)
Returns boolean value of adult content (NSFW) flag
get_subverse_sidebar(subverse)
Returns raw (html) sidebar text
###Tests VAPy methods are covered by tests.py, which uses Profiles for OAuth2 management. To run tests.py it is necessary to create a valid profile with the profile name "test". Alternatively, the user can alter the load_profile() call of VAPyTests.setUp() to load any profile desired.
Tests run rather slow because of the overhead on decrypting OAuth2 credentials for each VAPy instance. The values could get loaded into a holder in the setUpClass() call, and then passed to the VAPy isntance with setHeader() rather than using load_profile(). This should greatly reduce testing time.
##Vapp - Voat Application Framework
The Vapp framework attempt to make it easy for people to make simple Voat applications.
####Vapp()
Base superclass of the Vapp framework. Initializes VAPy and loads Profile. Initializes the Records class which provides local data persistence for the applicaiton.
user defined config.json attributes:
- app_name is the name of the applicaiton
- subverses is a list of one or more subverses (strings) that the application will read and write content to and from.
predefined config.json attributes:
- nsfw is a boolean value, default False. If False, the application ignores all NSFW flagged content.
- adult_app is a boolean value, default False. If True, all posts by application are flagged NSFW.