Welcome to PyInstapaper’s documentation!

PyInstapaper

https://img.shields.io/pypi/v/pyinstapaper.svg https://img.shields.io/travis/mdorn/pyinstapaper.svg Documentation Status

Instapaper is a tool for saving web pages to read later, e.g. offline on a mobile device. PyInstapaper is a Python wrapper for the full Instapaper API.

To use it, in addition to your Instapaper account username and password, you’ll need to request API credentials from Instapaper.

Usage

from pyinstapaper.instapaper import Instapaper, Folder

INSTAPAPER_KEY = 'MY_INSTAPAPER_API_KEY'
INSTAPAPER_SECRET = 'MY_INSTAPAPER_API_SECRET'
INSTAPAPER_LOGIN = 'me@example.com'
INSTAPAPER_PASSWORD = 'p@ssw0rd'

instapaper = Instapaper(INSTAPAPER_KEY, INSTAPAPER_SECRET)
instapaper.login(INSTAPAPER_LOGIN, INSTAPAPER_PASSWORD)

# Get the 10 latest instapaper bookmarks for the given account and do
# something with the article text
bookmarks = instapaper.get_bookmarks('starred')
for bookmark in enumerate(bookmarks):
    do_something(bookmark.get_text())
    bookmark.archive()

# Create a new folder
folder = Folder(instapaper, title='cool stuff')
result = folder.add()

Installation

To install PyInstapaper, simply:

pip install pyinstapaper

Additional info

Installation

Stable release

To install PyInstapaper, run this command in your terminal:

$ pip install pyinstapaper

This is the preferred method to install PyInstapaper, as it will always install the most recent stable release.

If you don’t have pip installed, this Python installation guide can guide you through the process.

From sources

The sources for PyInstapaper can be downloaded from the Github repo.

You can either clone the public repository:

$ git clone git://github.com/mdorn/pyinstapaper

Or download the tarball:

$ curl  -OL https://github.com/mdorn/pyinstapaper/tarball/master

Once you have a copy of the source, you can install it with:

$ python setup.py install

Usage

To use PyInstapaper in a project:

import pyinstapaper

pyinstapaper

pyinstapaper package

Submodules

pyinstapaper.instapaper module

class pyinstapaper.instapaper.Bookmark(client, **data)[source]

Bases: pyinstapaper.instapaper.InstapaperObject

Object representing an Instapaper bookmark/article.

ATTRIBUTES = ['bookmark_id', 'title', 'description', 'hash', 'url', 'progress_timestamp', 'time', 'progress', 'starred', 'type', 'private_source']
RESOURCE = 'bookmarks'
RESOURCE_ID_ATTRIBUTE = 'bookmark_id'
SIMPLE_ACTIONS = ['delete', 'star', 'archive', 'unarchive', 'get_text']
TIMESTAMP_ATTRS = ['progress_timestamp', 'time']
get_highlights()[source]

Get highlights for Bookmark instance.

Returns:list of Highlight objects
Return type:list
class pyinstapaper.instapaper.Folder(client, **data)[source]

Bases: pyinstapaper.instapaper.InstapaperObject

Object representing an Instapaper folder.

ATTRIBUTES = ['folder_id', 'title', 'display_title', 'sync_to_mobile', 'folder_id', 'position', 'type', 'slug']
RESOURCE = 'folders'
RESOURCE_ID_ATTRIBUTE = 'folder_id'
SIMPLE_ACTIONS = ['delete']
set_order(folder_ids)[source]

Order the user’s folders

Parameters:folders (list) – List of folder IDs in the desired order.
Returns:List Folder objects in the new order.
Return type:list
class pyinstapaper.instapaper.Highlight(client, **data)[source]

Bases: pyinstapaper.instapaper.InstapaperObject

Object representing an Instapaper highlight.

ATTRIBUTES = ['highlight_id', 'text', 'note', 'time', 'position', 'bookmark_id', 'type', 'slug']
RESOURCE = 'highlights'
RESOURCE_ID_ATTRIBUTE = 'highlight_id'
SIMPLE_ACTIONS = ['delete']
TIMESTAMP_ATTRS = ['time']
create()[source]
class pyinstapaper.instapaper.Instapaper(oauth_key, oauth_secret)[source]

Bases: object

Instapaper client class.

Parameters:
  • str (oauth_secret) – Instapaper OAuth consumer key
  • str – Instapaper OAuth consumer secret
get_bookmarks(folder='unread', limit=25, have=None)[source]

Return list of user’s bookmarks.

Parameters:
  • folder (str) – Optional. Possible values are unread (default), starred, archive, or a folder_id value.
  • limit (int) – Optional. A number between 1 and 500, default 25.
  • have (list) – Optional. A list of IDs to exclude from results
Returns:

List of user’s bookmarks
Return type:

list
get_folders()[source]

Return list of user’s folders.

Return type:list
login(username, password)[source]

Authenticate using XAuth variant of OAuth.

Parameters:
  • username (str) – Username or email address for the relevant account
  • password (str) – Password for the account
request(path, params=None, returns_json=True, method='POST', api_version='1')[source]

Process a request using the OAuth client’s request method.

Parameters:
  • path (str) – Path fragment to the API endpoint, e.g. “resource/ID”
  • params (dict) – Parameters to pass to request
  • method (str) – Optional HTTP method, normally POST for Instapaper
  • api_version (str) – Optional alternative API version
Returns:

response headers and body
Retval:

dict
class pyinstapaper.instapaper.InstapaperObject(client, **data)[source]

Bases: object

Base class for Instapaper objects like Bookmark.

Parameters:
  • client (oauth2.Client) – instance of the OAuth client for making requests
  • data (dict) – key/value pairs of object attributes, e.g. title, etc.
add()[source]

Save an object to Instapaper after instantiating it.

Example:

folder = Folder(instapaper, title='stuff')
result = folder.add()

Module contents

Top-level package for PyInstapaper.

Contributing

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

You can contribute in many ways:

Types of Contributions

Report Bugs

Report bugs at https://github.com/mdorn/pyinstapaper/issues.

If you are reporting a bug, please include:

  • Your operating system name and version.
  • Any details about your local setup that might be helpful in troubleshooting.
  • Detailed steps to reproduce the bug.

Fix Bugs

Look through the GitHub issues for bugs. Anything tagged with “bug” and “help wanted” is open to whoever wants to implement it.

Implement Features

Look through the GitHub issues for features. Anything tagged with “enhancement” and “help wanted” is open to whoever wants to implement it.

Write Documentation

PyInstapaper could always use more documentation, whether as part of the official PyInstapaper docs, in docstrings, or even on the web in blog posts, articles, and such.

Submit Feedback

The best way to send feedback is to file an issue at https://github.com/mdorn/pyinstapaper/issues.

If you are proposing a feature:

  • Explain in detail how it would work.
  • Keep the scope as narrow as possible, to make it easier to implement.
  • Remember that this is a volunteer-driven project, and that contributions are welcome :)

Get Started!

Ready to contribute? Here’s how to set up pyinstapaper for local development.

  1. Fork the pyinstapaper repo on GitHub.

  2. Clone your fork locally:

    $ git clone git@github.com:your_name_here/pyinstapaper.git

  3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development:

    $ mkvirtualenv pyinstapaper
$ cd pyinstapaper/
$ python setup.py develop

  4. Create a branch for local development:

    $ git checkout -b name-of-your-bugfix-or-feature

    Now you can make your changes locally.

  5. When you’re done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox:

    $ flake8 pyinstapaper tests
$ python setup.py test or py.test
$ tox

    To get flake8 and tox, just pip install them into your virtualenv.

  6. Commit your changes and push your branch to GitHub:

    $ git add .
$ git commit -m "Your detailed description of your changes."
$ git push origin name-of-your-bugfix-or-feature

  7. Submit a pull request through the GitHub website.

Pull Request Guidelines

Before you submit a pull request, check that it meets these guidelines:

  1. The pull request should include tests.
  2. If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst.
  3. The pull request should work for Python 2.7, 3.4, 3.5 and 3.6, and for PyPy. Check https://travis-ci.org/mdorn/pyinstapaper/pull_requests and make sure that the tests pass for all supported Python versions.

Tips

To run a subset of tests:

$ py.test tests.test_pyinstapaper

Deploying

A reminder for the maintainers on how to deploy. Make sure all your changes are committed (including an entry in HISTORY.rst). Then run:

$ bumpversion patch # possible: major / minor / patch
$ git push
$ git push --tags

Travis will then deploy to PyPI if tests pass.

Credits

Development Lead

Contributors

None yet. Why not be the first?

History

0.1.0 (2015-09-26)

  • First release on PyPI.

0.2.0 (2018-05-02)

  • Python 3 compatibility
  • Added ‘have’ param to get_bookmarks

Indices and tables