draw 0.4.6+1

  • README.md
  • CHANGELOG.md
  • Example
  • Installing
  • Versions
  • 83

DRAW: The Dart Reddit API Wrapper

Build Status Pub Version Coverage Status Join Gitter Chat Channel -

DRAW, also known as the Dart Reddit API Wrapper, is a Dart package that provides simple access to the Reddit API. DRAW is inspired by PRAW, the Python Reddit API Wrapper, and aims to also maintain a similar interface.

Want to get involved? Check out how to contribute to get started!

Disclaimer: This is not an official Google product.

Installation

Installing DRAW is simple using Dart's package management system, pub. Instructions on how to import DRAW into your project can be found here. If you would prefer to live on the hemorrhaging-edge, methods to depend on a local copy of DRAW or on the Github repository can be found here.

Getting Started

Assuming you already have your Reddit OAuth credentials, getting started with DRAW is simple:

import 'dart:async';
import 'package:draw/draw.dart';

Future<void> main() async {
  // Create the `Reddit` instance and authenticated
  Reddit reddit = await Reddit.createScriptInstance(
    clientId: CLIENT_ID,
    clientSecret: SECRET,
    userAgent: AGENT_NAME,
    username: "DRAWApiOfficial",
    password: "hunter12", // Fake
  );

  // Retrieve information for the currently authenticated user
  Redditor currentUser = await reddit.user.me();
  // Outputs: My name is DRAWApiOfficial
  print("My name is ${currentUser.displayName}");
}

This simple example is a great way to confirm that DRAW is working and that your credentials have been configured correctly.

Web Authentication

To authenticate via the Reddit authentication page, the web authentication flow needs to be used. This requires that a web application is registered with a valid Reddit account, which provides a client-id and a client-secret. As part of this process, a redirect URL is associated with the registered web application. These three values are all that is needed to complete the web authentication flow.

Here is a simple example of how to use web authentication with DRAW:

import 'package:draw/draw.dart';

main() async {
  final userAgent = 'foobar';
  final configUri = Uri.parse('draw.ini');

  // Create a `Reddit` instance using a configuration file in the
  // current directory.
  final reddit = await Reddit.createWebFlowInstance(userAgent: userAgent,
                                                    configUri: configUri);

  // Build the URL used for authentication. See `WebAuthenticator`
  // documentation for parameters.
  final auth_url = reddit.auth.url(['*'], 'foobar'));
  
  // ...
  // Complete authentication at `auth_url` in the browser and retrieve
  // the `code` query parameter from the redirect URL.
  // ...

  // Assuming the `code` query parameter is stored in a variable
  // `auth_code`, we pass it to the `authorize` method in the
  // `WebAuthenticator`.
  await reddit.auth.authorize(auth_code);

  // If everything worked correctly, we should be able to retrieve
  // information about the authenticated account.
  print(await reddit.user.me());
}

It is also possible to restore cached credentials in order to avoid the need to complete the web authentication flow on each run:

import 'package:draw/draw.dart';

// Provides methods to load and save credentials.
import 'credential_loader.dart';

main() async {
  final userAgent = 'foobar';
  final configUri = Uri.parse('draw.ini');

  // Load cached credentials from disk, if available.
  final credentialsJson = await loadCredentials();

  var reddit;

  if (credentialsJson == null) {
    reddit =
        await Reddit.createWebFlowInstance(userAgent: userAgent,
                                           configUri: configUri);

    // Build the URL used for authentication. See `WebAuthenticator`
    // documentation for parameters.
    final auth_url = reddit.auth.url(['*'], 'foobar');

    // ...
    // Complete authentication at `auth_url` in the browser and retrieve
    // the `code` query parameter from the redirect URL.
    // ...

    // Assuming the `code` query parameter is stored in a variable
    // `auth_code`, we pass it to the `authorize` method in the
    // `WebAuthenticator`.
    await reddit.auth.authorize(auth_code);

    // Write credentials to disk.
    await writeCredentials(reddit.auth.credentials.toJson());
  } else {
    // Create a new Reddit instance using previously cached credentials.
    reddit = await Reddit.restoreAuthenticatedInstance(
        userAgent: userAgent,
        configUri: configUri,
        credentialsJson: credentialsJson);
  }

  // If everything worked correctly, we should be able to retrieve
  // information about the authenticated account.
  print(await reddit.user.me());
}

Here's an example draw.ini suitable for web based authentication:

default=default
reddit_url='https://www.reddit.com'
oauth_url=https://oauth.reddit.com
redirect_uri=https://www.google.com
client_id=YOUR_CLIENT_ID_HERE
client_secret=YOUR_SECRET_HERE
userAgent=draw_testing_agent

Here the redirect URI is set to https://www.google.com, but you'll need to replace that with whatever redirect you have registered.

The format of draw.ini configuration files is very similar to that of praw.ini files used by PRAW, although there may be some minor differences due to the .ini parser used by DRAW.

License

DRAW is provided under a BSD 3-clause license. Copyright (c), 2017, the DRAW Project Authors and Google LLC.

Change Log

Version 0.4.6 (2019/11/02)

  • Added support for handling wiki pages:
    • Added SubredditWiki, which provides a set of wiki related functions to SubredditRef and Subreddit.
    • Added WikiPageRef and WikiPage which represent and allow for modification of wiki pages.
    • Added WikiEdit, a class which represents edits made to a wiki page.
    • Added WikiPermissionLevel enum, which describes all valid permissions available to control editing and viewing of wiki pages.
    • Added WikiPageSettings, a representation of all settings for a wiki page.
    • Added WikiPageModeration, a helper class for updating settings for a wiki page.
  • Added support for new Reddit Silver, Gold, and Platinum.

Deprecation Notice (Removal in 0.5.0)

  • Marked gilded property of UserContentInitialized as deprecated.

Version 0.4.5 (2019/10/20)

  • Added ModeratorRelationship, a class that allows for management of moderators for a subreddit.
  • Added moderator parameter to Subreddit that returns an instance of ModeratorRelationship for the given subreddit.
  • Added sort parameter to Submission.refreshComments to allow for different comment sorting methods.

Version 0.4.4 (2019/10/06)

  • Added Modmail, ModmailConversation, ModmailMessage, ModmailAction and ModmailActionType, which can be used to perform mod-mail actions.
  • Added vote getter to Submission to be consistent with Comment.

Deprecation Notice (Removal in 0.5.0)

  • Marked likes getter in Submission as deprecated.

Version 0.4.3 (2019/09/23)

  • Added nsfw and spoiler parameters to Subreddit.submit (Thanks @LucasCLuk!)
  • Fixed issue where exceptions generated during client authentication could not be caught.

Version 0.4.2 (2018/09/10)

  • Added support for flair. See documentation for SubredditFlair and SubmissionFlair for details.
  • Updated dependency versions for Dart 2.0.

Bug fixes:

  • PreviewImage now automatically replaces $amp; with $ (Issue #104).
  • Cleaned up various analyzer failures.

Version 0.4.0 (2018/09/01)

Major breaking changes:

Reddit.createInstance has been removed. Please use one of the following static methods instead:

  • createReadOnlyInstance
  • createScriptInstance
  • createUntrustedReadOnlyInstance
  • createWebFlowInstance
  • restoreAuthenticatedInstance

Other changes:

  • Bumped SDK constraints to reflect official Dart 2.0 release.
  • Added SubmissionPreview and PreviewImage which represent preview images for a Submission.
  • Added preview to Submission, which returns a List<SubmissionPreview>.
  • Fixed various bugs discovered while improving code coverage.

Version 0.3.4 (2018/06/12)

Deprecation Notice:

Reddit.createInstance has been deprecated and will be removed in the 0.4.0 release. Please use one of the following static methods instead:

  • createReadOnlyInstance
  • createScriptInstance
  • createUntrustedReadOnlyInstance
  • createWebFlowInstance
  • restoreAuthenticatedInstance

Other changes:

  • Added the following static methods to Reddit:
    • createWebFlowInstance
  • Added live tests to exercise the web implicit grant flow authentication mode.

Version 0.3.3 (2018/06/08)

  • Added the following static methods to Reddit:

    • createReadOnlyInstance
    • createScriptInstance
    • createUntrustedReadOnlyInstance

    This should make creating Reddit instances simpler and easier to debug.

  • Added live tests to exercise the read-only and script authentication modes.

Version 0.3.2 (2018/05/07)

Bug fixes:

  • Fixed additional Dart 2 runtime type errors.

Version 0.3.1 (2018/05/06)

Bug fixes:

  • Fixed exception thrown from WebAuthenticator when running in Dart 2.

Version 0.3.0 (2018/05/05)

Major breaking changes:

Dropped support for Dart 1.x. Flutter has moved to enable Dart 2 by default which required some changes in DRAW that are not compatible with Dart 1.x. Some of these changes required some method signatures to be modified, but this shouldn't require any changes for users.

If running in a command-line script, that script must be run using a dev SDK while passing the --preview-dart-2 flag.

If used in a Flutter application, --preview-dart-2 is enabled by default as of the Flutter Beta 2 release.

Functionality:

  • Basic Multireddit functionality:
    • Added Multireddit.parse(reddit, data) constructor that will create an instance of a Multireddit, given the correct Map of data.
    • Added add(subreddit) method to add the corresponding subreddit to the instance of Multireddit. subreddit can be of type Subreddit or String.
    • Added delete() method to delete the multireddit.
    • Added copy() and copy(multiName), this will create a copy of the Multireddit for for the currently authenticated user and return an instance of the new Multireddit encapsulated as a Future. When multiName is provided it will set the display name of the new Multireddit to multiName.
    • Added getters for the following properties: keyColor, iconName, subreddits, author displayName, visibility, weightingScheme, canEdit, over18.
  • Comment and Submission moderation.
  • Miscellaneous bug fixes.

Version 0.2.1 (2018/04/17)

  • Added Reddit.comment, which allows for the creation of CommentRef objects from a comment ID or url.
  • Added CommentRef.populate and Comment.refresh.
  • Added likes getter to Submission.
  • Miscellaneous fixes for minor bugs related to CommentForest.

Version 0.2.0 (2018/04/13)

Breaking changes:

  • Subreddit.submissions has been removed as the Reddit API endpoint no longer exists. See this post for context.

Miscellaneous:

  • Added initial support for Fuchsia. draw.ini configurations are not yet supported on this platform.
  • Loosened some version restrictions for pub packages.

Version 0.1.6 (2018/04/08)

  • Added the property Reddit.front, which exposes methods to retrieve content from the Reddit front page.

Version 0.1.5 (2018/04/03)

  • Added Reddit.restoreAuthenticatedInstance, which can be used to create a Reddit instance from previously cached credentials.
  • Documentation improvements.
  • Various bug fixes.

Version 0.1.4 (2018/03/31)

  • Added SubredditModeration, a class which implements moderator functionality for Subreddits.
  • Fixed issue #46 which was causing WebAuthenticator.url to hit an assertion when compactLogin was set to true.

Version 0.1.3 (2018/03/22)

  • Added additional convenience accessors to various classes, including Comment, Redditor, Submission, and Subreddit.
  • Added classes SubredditFilters and SubredditQuarantine.

Version 0.1.2 (2018/03/04)

Breaking changes:

  • Removed property method. Properties of initialized objects that do not yet have convenience accessors can be accessed through the data property
  • Removed fullname, id, and data fields from lazily initialized objects
  • Removed refresh() from lazily initialized objects

Miscellaneous:

  • Improved documentation
  • Various internal refactoring

Version 0.1.1 (2018/03/03)

Minor bug fix:

  • Fixed issue where DRAWConfigContext would throw an exception on Android and iOS.

Version 0.1.0 (2018/03/03)

Breaking changes:

  • Created separate classes for lazily initialized and initialized instances
  • Deprecated the property method. Will be completely removed in the near future

Major changes and bug fixes:

  • Added Inbox and Message functionality
  • Added convenience accessors for common properties. Properties without an accessor can be accessed through the data map in each object
  • Additional fixes to DRAWConfigContext
  • Rolled package:quiver forward to version 0.28.0 to match that used by flutter_test

Version 0.0.3 (2018/01/22)

Minor changes and bug fixes:

  • Fixed bug that caused authentication to fail when using draw.ini with the ScriptAuthenticator
  • Refactored DRAWConfigContext

Version 0.0.2 (2017/12/15)

Minor updates:

  • Added CHANGELOG.md
  • Formatted sample code in README.md
  • Renamed .analysis_options to analysis_options.yaml
  • Documentation added for classes and methods that had none
  • Commented out currently unimplemented functionality to clean up generated documents

Version 0.0.1 (2017/12/08)

Initial release with basic functionality, including:

  • OAuth2 support for login
  • Comment, Redditor, and Subreddit interfaces

example/example.dart

// Copyright (c) 2018, the Dart Reddit API Wrapper project authors.
// Please see the AUTHORS file for details. All rights reserved.
// Use of this source code is governed by a BSD-style license that
// can be found in the LICENSE file.

import 'dart:async';
import 'package:draw/draw.dart';

String kClientId;
String kSecret;
String kAgentName;

Future<void> main() async {
  // Create the `Reddit` instance and authenticate
  final Reddit reddit = await Reddit.createScriptInstance(
    clientId: kClientId,
    clientSecret: kSecret,
    userAgent: kAgentName,
    username: "DRAWApiOfficial",
    password: "hunter12", // Fake
  );

  // Retrieve information for the currently authenticated user
  final Redditor currentUser = await reddit.user.me();
  // Outputs: My name is DRAWApiOfficial
  print("My name is ${currentUser.displayName}");
}

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  draw: ^0.4.6+1

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter packages get

Alternatively, your editor might support pub get or flutter packages get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:draw/draw.dart';
  
Version Uploaded Documentation Archive
0.4.6+1 Nov 6, 2018 Go to the documentation of draw 0.4.6+1 Download draw 0.4.6+1 archive
0.4.6 Nov 2, 2018 Go to the documentation of draw 0.4.6 Download draw 0.4.6 archive
0.4.5+1 Oct 21, 2018 Go to the documentation of draw 0.4.5+1 Download draw 0.4.5+1 archive
0.4.5 Oct 21, 2018 Go to the documentation of draw 0.4.5 Download draw 0.4.5 archive
0.4.4+1 Oct 9, 2018 Go to the documentation of draw 0.4.4+1 Download draw 0.4.4+1 archive
0.4.4 Oct 6, 2018 Go to the documentation of draw 0.4.4 Download draw 0.4.4 archive
0.4.3 Sep 24, 2018 Go to the documentation of draw 0.4.3 Download draw 0.4.3 archive
0.4.2 Sep 10, 2018 Go to the documentation of draw 0.4.2 Download draw 0.4.2 archive
0.4.1 Sep 3, 2018 Go to the documentation of draw 0.4.1 Download draw 0.4.1 archive
0.4.0 Sep 2, 2018 Go to the documentation of draw 0.4.0 Download draw 0.4.0 archive

All 27 versions...

Popularity:
Describes how popular the package is relative to other packages. [more]
66
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
100
Overall:
Weighted score of the above. [more]
83
Learn more about scoring.

We analyzed this package on Dec 5, 2018, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.1.0
  • pana: 0.12.7

Platforms

Detected platforms: Flutter, other

Primary library: package:draw/draw.dart with components: io.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.0.0 <3.0.0
collection ^1.14.3 1.14.11
color ^2.1.1 2.1.1
http ^0.11.3+14 0.11.3+17 0.12.0
ini ^2.0.0 2.0.1
logging ^0.11.3+1 0.11.3+2
oauth2 ^1.1.0 1.2.3
path ^1.4.2 1.6.2
quiver >=2.0.0 <3.0.0 2.0.1
Transitive dependencies
async 2.0.8
charcode 1.1.2
http_parser 3.1.3
matcher 0.12.4
meta 1.1.6
source_span 1.4.1
stack_trace 1.9.3
string_scanner 1.0.4
typed_data 1.1.6
Dev dependencies
mockito ^3.0.0
reply ^0.1.2-dev
test ^1.3.0