# Class reference

## Essentials

Classes doing most of the work.

class pypump.PyPump(client, verifier_callback, store=None, callback='oob', verify_requests=True, retries=0, timeout=30)

  Main class to interface with PyPump.

  This class keeps everything together and is responsible for making requests to the server on it’s own behalf and on the behalf of the other clients as well as handling the OAuth requests.

  Parameters:

    - client – an instance of `Client`.

    - verifier_callback – If this is our first time registering the client, this function will be called with a single argument, the url one can post to for completing verification.

    - store – this is the `pypump.Store` instance to save any data persistantly.

    - callback – the URI that is used for redirecting a user after they authenticate this client… assuming this is happening over the web. If not, the callback is “oob”, or “out of band”.

    - verify_requests – If this is set to False PyPump won’t check SSL/TLS certificates.

    - retries – number of times to retry if a request fails.

    - timeout – how long to give on a timeout for an http request, in seconds.

class pypump.Client(webfinger, type, name=None, contacts=None, redirect=None, logo=None, key=None, secret=None, expirey=None)

  This represents a client/application which is using the Pump API.

  Parameters:

    - webfinger – webfinger id of this user, ie “mary@example.org” This is probably your username @ the domain of the pump instance you’re using.

    - type – whether this is a “web” or “native” client. Unless you’re using pypump as part of a web service, you should choose “native”.

    - name – The name of this client, ie your application’s name. For example, if you were using PyPump to write CoolCommunicator, you would put “CoolCommunicator” here.

    - contacts – Who wrote this application? List of email addresses of those who authored this client.

    - redirect – a list of URIs as callbacks for the authorization server

    - logo – URI of your application’s logo.

  Additionally, the following init args should only be supplied if you’ve already registered this client with the server. If not, these will be filled in during the self.register() step.

  Parameters:

    - key – If This is the token (the client_id) we got back that identifies our client, assuming we’ve already registered our client.

    - secret – This is your secret token that authorizes you to connect to the pump instance (the client_secret).

    - expirey – When our token expires (espires_at)

  Note that the above three are not the same as the oauth permissions verifying the user has access to post, this is related to permissions and identification of the client software to post. For the premission related to the access of the account, see PyPump.key and PyPump.secret.

## Pump objects

Classes representing pump.io objects:

  - `Note`

  - `Image`

  - `Audio`

  - `Video`

  - `Comment`

  - `Person`

  - `Inbox`

  - `Outbox`

  - `Lists`

class pypump.models.note.Note(content=None, display_name=None, **kwargs)

  This object represents a pump.io note, notes are used to post text (or html) messages to the pump.io network.

  Parameters:

    - content – (optional) Note content.

    - display_name – (optional) Note title.

  Usage:

      >>> mynote = pump.Note(content='<b>Hello</b> world!')
      >>> mynote.send()

  property cc

    List of secondary recipients. The object will show up in the recipients inbox when sent.

    Example:

          >>> mynote = pump.Note('hello world')
          >>> mynote.cc = pump.Public

  comment(comment)

    Add a `Comment` to the object.

    Parameters:

      comment – A `Comment` instance, text content is also accepted.

    Example:

          >>> anote.comment(pump.Comment('I agree!'))

  property comments

    A `Feed` of the comments for the object.

    Example:

          >>> for comment in mynote.comments:
          ...     print(comment)
          ...
          comment by pypumptest2@pumpyourself.com

  delete()

    Delete the object content on the server.

    Example:

          >>> mynote.deleted
          >>> mynote.delete()
          >>> mynote.deleted
          datetime.datetime(2014, 10, 19, 9, 26, 39, tzinfo=tzutc())

  favorite()

    Favorite the object.

  property favorites

    A `Feed` of the people who’ve liked the object.

    Example:

          >>> for person in mynote.likes:
          ...     print(person.webfinger)
          ...
          pypumptest1@pumpity.net
          pypumptest2@pumpyourself.com

  like()

    Like the object.

    Example:

          >>> anote.liked
          False
          >>> anote.like()
          >>> anote.liked
          True

  property likes

    A `Feed` of the people who’ve liked the object.

    Example:

          >>> for person in mynote.likes:
          ...     print(person.webfinger)
          ...
          pypumptest1@pumpity.net
          pypumptest2@pumpyourself.com

  send()

    Send the object to the server.

    Example:

          >>> mynote = pump.Note('Hello world!)
          >>> mynote.send()

  share()

    Share the object.

    Example:

          >>> anote.share()

  property shares

    A `Feed` of the people who’ve shared the object.

    Example:

          >>> for person in mynote.shares:
          ...     print(person.webfinger)
          ...
          pypumptest1@pumpity.net
          pypumptest2@pumpyourself.com

  property to

    List of primary recipients. If entry is a `Person` the object will show up in their direct inbox when sent.

    Example:

          >>> mynote = pump.Note('hello pypumptest1')
          >>> mynote.to = pump.Person('pypumptest1@pumpity.net')
          >>> mynote.to
          [<Person: pypumptest1@pumpity.net>]

  unfavorite()

    Unfavorite a previously favorited object.

  unlike()

    Unlike a previously liked object.

    Example:

          >>> anote.liked
          True
          >>> anote.unlike()
          >>> anote.liked
          False

  unshare()

    Unshare a previously shared object.

    Example:

          >>> anote.unshare()

class pypump.models.media.Image(display_name=None, content=None, license=None, **kwargs)

  This object represents a pump.io image, images are used to post image content with optional text (or html) messages to the pump.io network.

  Parameters:

    - content – (optional) Image text content.

    - display_name – (optional) Image title.

  Example:

        >>> myimage = pump.Image(display_name='Happy Caturday!')
        >>> myimage.from_file('/path/to/kitteh.png')

  thumbnail

    `ImageContainer` holding information about the thumbnail image.

  original

    `ImageContainer` holding information about the original image.

  property cc

    List of secondary recipients. The object will show up in the recipients inbox when sent.

    Example:

          >>> mynote = pump.Note('hello world')
          >>> mynote.cc = pump.Public

  comment(comment)

    Add a `Comment` to the object.

    Parameters:

      comment – A `Comment` instance, text content is also accepted.

    Example:

          >>> anote.comment(pump.Comment('I agree!'))

  property comments

    A `Feed` of the comments for the object.

    Example:

          >>> for comment in mynote.comments:
          ...     print(comment)
          ...
          comment by pypumptest2@pumpyourself.com

  delete()

    Delete the object content on the server.

    Example:

          >>> mynote.deleted
          >>> mynote.delete()
          >>> mynote.deleted
          datetime.datetime(2014, 10, 19, 9, 26, 39, tzinfo=tzutc())

  favorite()

    Favorite the object.

  property favorites

    A `Feed` of the people who’ve liked the object.

    Example:

          >>> for person in mynote.likes:
          ...     print(person.webfinger)
          ...
          pypumptest1@pumpity.net
          pypumptest2@pumpyourself.com

  from_file(filename)

    Uploads a file from a filename on your system.

    Parameters:

      filename – Path to file on your system.

    Example:

          >>> myimage.from_file('/path/to/dinner.png')

  like()

    Like the object.

    Example:

          >>> anote.liked
          False
          >>> anote.like()
          >>> anote.liked
          True

  property likes

    A `Feed` of the people who’ve liked the object.

    Example:

          >>> for person in mynote.likes:
          ...     print(person.webfinger)
          ...
          pypumptest1@pumpity.net
          pypumptest2@pumpyourself.com

  share()

    Share the object.

    Example:

          >>> anote.share()

  property shares

    A `Feed` of the people who’ve shared the object.

    Example:

          >>> for person in mynote.shares:
          ...     print(person.webfinger)
          ...
          pypumptest1@pumpity.net
          pypumptest2@pumpyourself.com

  property to

    List of primary recipients. If entry is a `Person` the object will show up in their direct inbox when sent.

    Example:

          >>> mynote = pump.Note('hello pypumptest1')
          >>> mynote.to = pump.Person('pypumptest1@pumpity.net')
          >>> mynote.to
          [<Person: pypumptest1@pumpity.net>]

  unfavorite()

    Unfavorite a previously favorited object.

  unlike()

    Unlike a previously liked object.

    Example:

          >>> anote.liked
          True
          >>> anote.unlike()
          >>> anote.liked
          False

  unshare()

    Unshare a previously shared object.

    Example:

          >>> anote.unshare()

class pypump.models.media.Audio(display_name=None, content=None, license=None, **kwargs)

  This object represents a pump.io audio object, audio objects are used to post audio content with optional text (or html) messages to the pump.io network.

  Parameters:

    - content – (optional) Audio text content.

    - display_name – (optional) Audio title.

  Example:

        >>> myogg = pump.Audio(display_name='Happy Caturday!')
        >>> myogg.from_file('/path/to/kitteh.ogg')

  stream

    `StreamContainer` holding information about the stream.

  property cc

    List of secondary recipients. The object will show up in the recipients inbox when sent.

    Example:

          >>> mynote = pump.Note('hello world')
          >>> mynote.cc = pump.Public

  comment(comment)

    Add a `Comment` to the object.

    Parameters:

      comment – A `Comment` instance, text content is also accepted.

    Example:

          >>> anote.comment(pump.Comment('I agree!'))

  property comments

    A `Feed` of the comments for the object.

    Example:

          >>> for comment in mynote.comments:
          ...     print(comment)
          ...
          comment by pypumptest2@pumpyourself.com

  delete()

    Delete the object content on the server.

    Example:

          >>> mynote.deleted
          >>> mynote.delete()
          >>> mynote.deleted
          datetime.datetime(2014, 10, 19, 9, 26, 39, tzinfo=tzutc())

  favorite()

    Favorite the object.

  property favorites

    A `Feed` of the people who’ve liked the object.

    Example:

          >>> for person in mynote.likes:
          ...     print(person.webfinger)
          ...
          pypumptest1@pumpity.net
          pypumptest2@pumpyourself.com

  from_file(filename)

    Uploads a file from a filename on your system.

    Parameters:

      filename – Path to file on your system.

    Example:

          >>> myimage.from_file('/path/to/dinner.png')

  like()

    Like the object.

    Example:

          >>> anote.liked
          False
          >>> anote.like()
          >>> anote.liked
          True

  property likes

    A `Feed` of the people who’ve liked the object.

    Example:

          >>> for person in mynote.likes:
          ...     print(person.webfinger)
          ...
          pypumptest1@pumpity.net
          pypumptest2@pumpyourself.com

  share()

    Share the object.

    Example:

          >>> anote.share()

  property shares

    A `Feed` of the people who’ve shared the object.

    Example:

          >>> for person in mynote.shares:
          ...     print(person.webfinger)
          ...
          pypumptest1@pumpity.net
          pypumptest2@pumpyourself.com

  property to

    List of primary recipients. If entry is a `Person` the object will show up in their direct inbox when sent.

    Example:

          >>> mynote = pump.Note('hello pypumptest1')
          >>> mynote.to = pump.Person('pypumptest1@pumpity.net')
          >>> mynote.to
          [<Person: pypumptest1@pumpity.net>]

  unfavorite()

    Unfavorite a previously favorited object.

  unlike()

    Unlike a previously liked object.

    Example:

          >>> anote.liked
          True
          >>> anote.unlike()
          >>> anote.liked
          False

  unshare()

    Unshare a previously shared object.

    Example:

          >>> anote.unshare()

class pypump.models.media.Video(display_name=None, content=None, license=None, **kwargs)

  This object represents a pump.io video object, video objects are used to post video content with optional text (or html) messages to the pump.io network.

  Parameters:

    - content – (optional) Video text content.

    - display_name – (optional) Video title.

  Example:

        >>> myogv = pump.Video(display_name='Happy Caturday!')
        >>> myogv.from_file('/path/to/kitteh.ogv')

  stream

    `StreamContainer` holding information about the stream.

  property cc

    List of secondary recipients. The object will show up in the recipients inbox when sent.

    Example:

          >>> mynote = pump.Note('hello world')
          >>> mynote.cc = pump.Public

  comment(comment)

    Add a `Comment` to the object.

    Parameters:

      comment – A `Comment` instance, text content is also accepted.

    Example:

          >>> anote.comment(pump.Comment('I agree!'))

  property comments

    A `Feed` of the comments for the object.

    Example:

          >>> for comment in mynote.comments:
          ...     print(comment)
          ...
          comment by pypumptest2@pumpyourself.com

  delete()

    Delete the object content on the server.

    Example:

          >>> mynote.deleted
          >>> mynote.delete()
          >>> mynote.deleted
          datetime.datetime(2014, 10, 19, 9, 26, 39, tzinfo=tzutc())

  favorite()

    Favorite the object.

  property favorites

    A `Feed` of the people who’ve liked the object.

    Example:

          >>> for person in mynote.likes:
          ...     print(person.webfinger)
          ...
          pypumptest1@pumpity.net
          pypumptest2@pumpyourself.com

  from_file(filename)

    Uploads a file from a filename on your system.

    Parameters:

      filename – Path to file on your system.

    Example:

          >>> myimage.from_file('/path/to/dinner.png')

  like()

    Like the object.

    Example:

          >>> anote.liked
          False
          >>> anote.like()
          >>> anote.liked
          True

  property likes

    A `Feed` of the people who’ve liked the object.

    Example:

          >>> for person in mynote.likes:
          ...     print(person.webfinger)
          ...
          pypumptest1@pumpity.net
          pypumptest2@pumpyourself.com

  share()

    Share the object.

    Example:

          >>> anote.share()

  property shares

    A `Feed` of the people who’ve shared the object.

    Example:

          >>> for person in mynote.shares:
          ...     print(person.webfinger)
          ...
          pypumptest1@pumpity.net
          pypumptest2@pumpyourself.com

  property to

    List of primary recipients. If entry is a `Person` the object will show up in their direct inbox when sent.

    Example:

          >>> mynote = pump.Note('hello pypumptest1')
          >>> mynote.to = pump.Person('pypumptest1@pumpity.net')
          >>> mynote.to
          [<Person: pypumptest1@pumpity.net>]

  unfavorite()

    Unfavorite a previously favorited object.

  unlike()

    Unlike a previously liked object.

    Example:

          >>> anote.liked
          True
          >>> anote.unlike()
          >>> anote.liked
          False

  unshare()

    Unshare a previously shared object.

    Example:

          >>> anote.unshare()

class pypump.models.comment.Comment(content=None, in_reply_to=None, **kwargs)

  This object represents a pump.io comment, comments are used to post text (or html) messages in reply to other objects on the pump.io network.

  Parameters:

    - content – (optional) Comment content.

    - in_reply_to – (optional) Object to reply to.

  Example:

        >>> catpic
        <Image by alice@example.org>
        >>> mycomment = pump.Comment(content='Best cat pic ever!', in_reply_to=catpic)
        >>> mycomment.send()

  property cc

    List of secondary recipients. The object will show up in the recipients inbox when sent.

    Example:

          >>> mynote = pump.Note('hello world')
          >>> mynote.cc = pump.Public

  comment(comment)

    Add a `Comment` to the object.

    Parameters:

      comment – A `Comment` instance, text content is also accepted.

    Example:

          >>> anote.comment(pump.Comment('I agree!'))

  property comments

    A `Feed` of the comments for the object.

    Example:

          >>> for comment in mynote.comments:
          ...     print(comment)
          ...
          comment by pypumptest2@pumpyourself.com

  delete()

    Delete the object content on the server.

    Example:

          >>> mynote.deleted
          >>> mynote.delete()
          >>> mynote.deleted
          datetime.datetime(2014, 10, 19, 9, 26, 39, tzinfo=tzutc())

  favorite()

    Favorite the object.

  property favorites

    A `Feed` of the people who’ve liked the object.

    Example:

          >>> for person in mynote.likes:
          ...     print(person.webfinger)
          ...
          pypumptest1@pumpity.net
          pypumptest2@pumpyourself.com

  like()

    Like the object.

    Example:

          >>> anote.liked
          False
          >>> anote.like()
          >>> anote.liked
          True

  property likes

    A `Feed` of the people who’ve liked the object.

    Example:

          >>> for person in mynote.likes:
          ...     print(person.webfinger)
          ...
          pypumptest1@pumpity.net
          pypumptest2@pumpyourself.com

  send()

    Send the object to the server.

    Example:

          >>> mynote = pump.Note('Hello world!)
          >>> mynote.send()

  share()

    Share the object.

    Example:

          >>> anote.share()

  property shares

    A `Feed` of the people who’ve shared the object.

    Example:

          >>> for person in mynote.shares:
          ...     print(person.webfinger)
          ...
          pypumptest1@pumpity.net
          pypumptest2@pumpyourself.com

  property to

    List of primary recipients. If entry is a `Person` the object will show up in their direct inbox when sent.

    Example:

          >>> mynote = pump.Note('hello pypumptest1')
          >>> mynote.to = pump.Person('pypumptest1@pumpity.net')
          >>> mynote.to
          [<Person: pypumptest1@pumpity.net>]

  unfavorite()

    Unfavorite a previously favorited object.

  unlike()

    Unlike a previously liked object.

    Example:

          >>> anote.liked
          True
          >>> anote.unlike()
          >>> anote.liked
          False

  unshare()

    Unshare a previously shared object.

    Example:

          >>> anote.unshare()

class pypump.models.person.Person(webfinger=None, **kwargs)

  This object represents a pump.io person, a person is a user on the pump.io network.

  Parameters:

    webfinger – User ID in `nickname@hostname` format.

  Example:

        >>> alice = pump.Person('alice@example.org')
        >>> print(alice.summary)
        Hi, I'm Alice
        >>> mynote = pump.Note('Hey Alice, it's Bob!')
        >>> mynote.to = alice
        >>> mynote.send()

  property cc

    List of secondary recipients. The object will show up in the recipients inbox when sent.

    Example:

          >>> mynote = pump.Note('hello world')
          >>> mynote.cc = pump.Public

  property favorites

    `Feed` with all objects liked/favorited by the person.

    Example:

          >>> for like in pump.me.favorites[:3]:
          ...     print(like)
          ...
          note by alice@example.org
          image by bob@example.org
          comment by evan@e14n.com

  follow()

    Follow person

  property followers

    `Feed` with all `Person` objects following the person.

    Example:

          >>> alice = pump.Person('alice@example.org')
          >>> for follower in alice.followers[:2]:
          ...     print(follower.id)
          ...
          acct:bob@example.org
          acct:carol@example.org

  property following

    `Feed` with all `Person` objects followed by the person.

    Example:

          >>> bob = pump.Person('bob@example.org')
          >>> for followee in bob.following[:3]:
          ...     print(followee.id)
          ...
          acct:alice@example.org
          acct:duncan@example.org

  property inbox

    `Inbox feed` with all `activities` received by the person, can only be read if logged in as the owner.

    Example:

          >>> for activity in pump.me.inbox[:2]:
          ...     print(activity.id)
          ...
          https://microca.st/api/activity/BvqXQOwXShSey1HxYuJQBQ
          https://pumpyourself.com/api/activity/iQGdnz5-T-auXnbUUdXh-A

  property lists

    `Lists feed` with all lists owned by the person.

    Example:

          >>> for list in pump.me.lists:
          ...     print(list)
          ...
          Acquaintances
          Family
          Coworkers
          Friends

  property outbox

    `Outbox feed` with all `activities` sent by the person.

    Example:

          >>> for activity in pump.me.outbox[:2]:
          ...     print(activity)
          ...
          pypumptest2 unliked a comment in reply to a note
          pypumptest2 deleted a note

  property to

    List of primary recipients. If entry is a `Person` the object will show up in their direct inbox when sent.

    Example:

          >>> mynote = pump.Note('hello pypumptest1')
          >>> mynote.to = pump.Person('pypumptest1@pumpity.net')
          >>> mynote.to
          [<Person: pypumptest1@pumpity.net>]

  unfollow()

    Unfollow person

  update()

    Updates person object

class pypump.models.feed.Inbox(*args, **kwargs)

  This object represents a pump.io inbox feed, it contains all activities posted to the owner of the inbox.

  Example:

        >>> for activity in pump.me.inbox.items(limit=3):
        ...     print(activity)
        Alice posted a note
        Bob posted a comment in reply to a note
        Alice liked a comment

  property direct

    Direct inbox feed, contains activities addressed directly to the owner of the inbox.

  items(offset=None, limit=20, since=None, before=None, *args, **kwargs)

    Get a feed’s items.

    Parameters:

      - offset – Amount of items to skip before returning data

      - since – Return items added after this id (ordered old -> new)

      - before – Return items added before this id (ordered new -> old)

      - limit – Amount of items to return

  property major

    Major inbox feed, contains major activities such as notes and images.

  property minor

    Minor inbox feed, contains minor activities such as likes, shares and follows.

class pypump.models.feed.Outbox(*args, **kwargs)

  This object represents a pump.io outbox feed, it contains all activities posted by the owner of the outbox.

  Example:

        >>> for activity in pump.me.outbox.items(limit=3):
        ...     print(activity)
        Bob posted a note
        Bob liked an image
        Bob followed Alice

  items(offset=None, limit=20, since=None, before=None, *args, **kwargs)

    Get a feed’s items.

    Parameters:

      - offset – Amount of items to skip before returning data

      - since – Return items added after this id (ordered old -> new)

      - before – Return items added before this id (ordered new -> old)

      - limit – Amount of items to return

  property major

    Major outbox feed, contains major activities such as notes and images.

  property minor

    Minor outbox feed, contains minor activities such as likes, shares and follows.

class pypump.models.feed.Lists(url=None, *args, **kwargs)

  This object represents a pump.io lists feed, it contains the `collections` (or lists) created by the owner.

  Example:

        >>> for i in pump.me.lists.items():
        ...     print(i)
        Coworkers
        Acquaintances
        Family
        Friends

  create(display_name, content=None)

    Create a new user list `collection`.

    Parameters:

      - display_name – List title.

      - content – (optional) List description.

    Example:

          >>> pump.me.lists.create(display_name='Friends', content='List of friends')
          >>> myfriends = pump.me.lists['Friends']
          >>> print(myfriends)
          Friends

  items(offset=None, limit=20, since=None, before=None, *args, **kwargs)

    Get a feed’s items.

    Parameters:

      - offset – Amount of items to skip before returning data

      - since – Return items added after this id (ordered old -> new)

      - before – Return items added before this id (ordered new -> old)

      - limit – Amount of items to return

## Low level objects

Classes you probably don’t need to know about.

class pypump.models.media.ImageContainer(url, width, height)

  Container that holds information about an image.

  Parameters:

    - url – URL to image file on the pump.io server.

    - width – Width of the image.

    - height – Height of the image.

class pypump.models.media.StreamContainer(url)

  Container that holds information about a stream.

  Parameters:

    url – URL to the file on the pump.io server.

class pypump.models.feed.Feed(url=None, *args, **kwargs)

  This object represents a basic pump.io feed, which is used for navigating a list of objects (inbox, followers, shares, likes and so on).

  items(offset=None, limit=20, since=None, before=None, *args, **kwargs)

    Get a feed’s items.

    Parameters:

      - offset – Amount of items to skip before returning data

      - since – Return items added after this id (ordered old -> new)

      - before – Return items added before this id (ordered new -> old)

      - limit – Amount of items to return

class pypump.models.collection.Collection(id=None, **kwargs)

  This object represents a pump.io collection, collections have a members `Feed` and methods for adding and removing objects to that feed.

  Parameters:

    id – (optional) Collection id.

  Example:

        >>> friendlist = pump.me.lists['Friends']
        >>> list(friendlist.members)
        [<Person: alice@example.org>]
        >>> friendlist.add(pump.Person('bob@example.org'))

  add(obj)

    Adds a member to the collection.

    Parameters:

      obj – Object to add.

    Example:

          >>> mycollection.add(pump.Person('bob@example.org'))

  delete()

    Delete the object content on the server.

    Example:

          >>> mynote.deleted
          >>> mynote.delete()
          >>> mynote.deleted
          datetime.datetime(2014, 10, 19, 9, 26, 39, tzinfo=tzutc())

  property members

    `Feed` of collection members.

  remove(obj)

    Removes a member from the collection.

    Parameters:

      obj – Object to remove.

    Example:

          >>> mycollection.remove(pump.Person('bob@example.org'))