Requirements, Installing, and Compatibility

The only requirement, included in requirements.txt is for requests. If you are using pip, you can install giphypop:

$ pip install requests giphypop

Alternatively:

$ pip install requests
$ pip install -e git+https://github.com/shaunduncan/giphypop.git#egg=giphypop

Then you should be off and running. giphypop has been tested against python versions 2.6, 2.7, 3.2 and 3.3.

Getting Started

Using giphypop is straightforward and aims provide interaction with the api without any regard to large bits of JSON. To get started, you can test out various features using the include api key. You should be warned, however, that while Giphy has been so kind as have a public “testing” key, it may be turned off in the future. See the api docs for more information.

The entry point for interacting with Giphy api is the giphypop.Giphy class. This class optionally accepts two arguments: api_key and strict. The api_key agument, when not preset, will default to the public key (see above). The strict argument controls how you expect the api to react when no results are returned. If enabled, an exception is raised, otherwise, None is returned.

>>> import giphypop
>>> g = giphypop.Giphy()

Now you’re ready to get started. There are a few key methods of the giphypop.Giphy object that you’ll want to know about

>>> g = giphypop.Giphy()
>>> results = [x for x in g.search('foo')]

Handling Results

All results that represent a single image are wrapped in a giphypop.GiphyImage object. This object acts like a dictionary, but also exposes keys as attributes. Note, that these are not a direct mirror of api response objects; their goal is to be simpler. Structure follows this layout:

<Result Object>
    - id
    - type: image type (i.e. gif)
    - url: URL to giphy page
    - raw_data: copy of original data response from giphy (JSON)
    - fullscreen: bit.ly link to giphy fullscreen gif
    - tiled: bit.ly link to giphy tiled gif
    - bitly: bit.ly version of `url`
    - media_url: URL directly to image (original size)
    - frames: number of frames
    - height: image height (original image)
    - width: image width (original image)
    - size: filesize (in bytes, original image)
    - fixed_height: (variable width @ 200px height)
        - url: URL directly to image
        - width: image width
        - height: image height
        - downsampled:
            - url: URL directly to image
            - width: image width
            - height: image height
        - still: (a still image of gif)
            - url: URL directly to image
            - width: image width
            - height: image height
    - fixed_width: (variable height @ 200px width)
        - url: URL directly to image
        - width: image width
        - height: image height
        - downsampled:
            - url: URL directly to image
            - width: image width
            - height: image height
        - still: (a still image of gif)
            - url: URL directly to image
            - width: image width
            - height: image height

For example:

>>> from giphypop import translate
>>> img = translate('foo')
>>> img.url
'http://giphy.com/foo/bar/baz'
>>> img.width
200
>>> img.fixed_height.downsampled.url
'http://giphy.com/foo/bar/downsampled'

Uploading

The Giphy API will accept uploads of gifs or videos. You are able to upload using the public API key, but you won’t be able to assign them to your username or delete them. In order to upload to your account, set the username when you and the API key when you upload.

For example:

>>> from giphypop import upload
>>> gif = upload(["foo", "bar"], "mycat.gif")
>>> gif
GiphyImage<26BRvG76mOYcvRxss> at http://giphy.com/gifs/bar-foo-26BRvG76mOYcvRxss

Or using your own API key to upload to your own account:

>>> from giphypop import upload
>>> gif = upload(["foo", "bar"], "mycat.gif", username="gifsarefun", api_key="abcdef12345678")
>>> gif
GiphyImage<26BRvG76mOYcvRxss> at http://giphy.com/gifs/bar-foo-26BRvG76mOYcvRxss

Changelog

Contribution and License

Developed by Shaun Duncan and is licensed under the terms of a MIT license. Contributions are welcomed and appreciated!