draw 0.3.4

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

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.

This project is in early stages, but is in active development. Check back soon for more info!

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.createInstance(
    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.createInstance(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.createInstance(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.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.createInstance(
    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.3.4

2. Install it

You can install packages from the command line:

with pub:


$ pub get

Alternatively, your editor might support pub 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.3.4 Jun 13, 2018 Go to the documentation of draw 0.3.4 Download draw 0.3.4 archive
0.3.3 Jun 8, 2018 Go to the documentation of draw 0.3.3 Download draw 0.3.3 archive
0.3.2 May 8, 2018 Go to the documentation of draw 0.3.2 Download draw 0.3.2 archive
0.3.1 May 7, 2018 Go to the documentation of draw 0.3.1 Download draw 0.3.1 archive
0.3.0 May 6, 2018 Go to the documentation of draw 0.3.0 Download draw 0.3.0 archive
0.2.1 Apr 23, 2018 Go to the documentation of draw 0.2.1 Download draw 0.2.1 archive
0.2.0 Apr 13, 2018 Go to the documentation of draw 0.2.0 Download draw 0.2.0 archive
0.1.6 Apr 8, 2018 Go to the documentation of draw 0.1.6 Download draw 0.1.6 archive
0.1.5 Apr 4, 2018 Go to the documentation of draw 0.1.5 Download draw 0.1.5 archive
0.1.4 Mar 31, 2018 Go to the documentation of draw 0.1.4 Download draw 0.1.4 archive

All 17 versions...

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

We analyzed this package on Aug 17, 2018, and provided a score, details, and suggestions below. Analysis was completed with status tool failures using:

  • Dart: 2.0.0
  • pana: 0.11.8

Platforms

Detected platforms: unsure

Error(s) prevent platform classification:

Fix dependencies in pubspec.yaml.

Issues and suggestions

Fix dependencies in pubspec.yaml.

Running pub upgrade failed with the following output:

ERR: The current Dart SDK version is 2.0.0.
 
 Because draw depends on color >=0.2.0 which requires SDK version <2.0.0, version solving failed.

Fix platform conflicts.

Error(s) prevent platform classification:

Fix dependencies in pubspec.yaml.

The description is too short.

Add more detail about the package, what it does and what is its target use case. Try to write at least 60 characters.

Package is pre-v1 release.

While there is nothing inherently wrong with versions of 0.*.*, it usually means that the author is still experimenting with the general direction of the API.

Format lib/src/listing/mixins/redditor.dart.

Run dartfmt to format lib/src/listing/mixins/redditor.dart.

Format lib/src/listing/mixins/rising.dart.

Run dartfmt to format lib/src/listing/mixins/rising.dart.

Format lib/src/models/subreddit.dart.

Run dartfmt to format lib/src/models/subreddit.dart.

Format lib/src/reddit.dart.

Run dartfmt to format lib/src/reddit.dart.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.0.0-dev <3.0.0