Initial commit

Author: Steven Cummings

.gitignore

@@ -0,0 +1 @@
+*.pyc

README.md

@@ -0,0 +1,24 @@
+PythonKC Meetup.com API Client
+==============================
+
+A clean, minimal client to the Meetup.com API for retrieving Meetup events for
+the [PythonKC group](http://www.meetup.com/pythonkc/).
+
+Example Usage
+-------------
+
+    >>> from pythonkc_meetups import PythonKCMeetups
+    >>> meetups = PythonKCMeetups(api_key='<your API key here>')
+    >>> next_meetup = meetups.get_upcoming_events()[0]
+    >>> next_meetup.name
+    u'Hackathon!'
+    >>> next_meetup.time
+    datetime.datetime(2011, 8, 13, 10, 0, tzinfo=tzoffset(None, -18000))
+    >>> next_meetup.venue.name
+    u"Salva O'Renick"
+    >>> next_meetup.venue.lat, next_meetup.venue.lon
+    (39.091053, -94.576996)
+    >>> next_meetup.yes_rsvp_count
+    9
+    >>> next_meetup.event_url
+    u'http://www.meetup.com/pythonkc/events/25940081/'

pythonkc_meetups/__init__.py

@@ -0,0 +1,8 @@
+# -*- coding: utf-8 -*-
+"""
+Provides PythonKC Meetup.com events.
+
+"""
+
+
+from pythonkc_meetups.client import PythonKCMeetups

pythonkc_meetups/client.py

@@ -0,0 +1,143 @@
+# -*- coding: utf-8 -*-
+"""
+Provides the PythonKC Meetup.com API client implementation.
+
+"""
+
+
+from pythonkc_meetups.exceptions import PythonKCMeetupsBadJson
+from pythonkc_meetups.exceptions import PythonKCMeetupsBadResponse
+from pythonkc_meetups.exceptions import PythonKCMeetupsMeetupDown
+from pythonkc_meetups.exceptions import PythonKCMeetupsNotJson
+from pythonkc_meetups.exceptions import PythonKCMeetupsRateLimitExceeded
+from pythonkc_meetups.parsers import parse_event
+import httplib2
+import json
+import mimeparse
+import urllib
+
+
+EVENTS_URL = 'https://api.meetup.com/2/events.json'
+GROUP_URLNAME = 'pythonkc'
+
+
+class PythonKCMeetups(object):
+
+    """
+    Retrieves information about PythonKC meetups.
+
+    """
+
+    def __init__(self, api_key, http_timeout=1, http_retries=2):
+        """
+        Create a new instance.
+
+        Parameters
+        ----------
+        api_key
+            The Meetup.com API consumer key to make requests with.
+        http_timeout
+            Time, in seconds, to give HTTP requests to complete.
+        http_retries
+            The number of times to retry requests when it is appropriate to do
+            so.
+
+        """
+        self._api_key = api_key
+        self._http_timeout = http_timeout
+        self._http_retries = http_retries
+
+    def get_upcoming_events(self):
+        """
+        Get the upcoming PythonKC meetup events.
+
+        Returns
+        -------
+        List of ``pythonkc_meetups.types.MeetupEvent``, ordered by event time,
+        ascending.
+
+        """
+
+        query = urllib.urlencode({'key': self._api_key,
+                                  'group_urlname': GROUP_URLNAME})
+        url = '{0}?{1}'.format(EVENTS_URL, query)
+        data = self._http_get_json(url)
+        events = data['results']
+        return [parse_event(event) for event in events]
+
+    def _http_get_json(self, url):
+        """
+        Make an HTTP GET request to the specified URL, check that it returned a
+        JSON response, and returned the data parsed from that response.
+
+        Parameters
+        ----------
+        url
+            The URL to GET.
+
+        Returns
+        -------
+        Dictionary of data parsed from a JSON HTTP response.
+
+        Exceptions
+        ----------
+        * PythonKCMeetupsBadJson
+        * PythonKCMeetupsNotJson
+        * PythonKCMeetupsMeetupDown
+        * PythonKCMeetupsRateLimitExceeded
+        * PythonKCMeetupsBadResponse
+
+        """
+        response, content = self._http_get(url)
+
+        content_type = response['content-type']
+        parsed_mimetype = mimeparse.parse_mime_type(content_type)
+        if parsed_mimetype[1] not in ('json', 'javascript'):
+            raise PythonKCMeetupsNotJson(content_type)
+
+        try:
+            return json.loads(content)
+        except ValueError as e:
+            raise PythonKCMeetupsBadJson(e)
+
+    def _http_get(self, url):
+        """
+        Make an HTTP GET request to the specified URL and return the response.
+
+        Retries
+        -------
+        The constructor of this class takes an argument specifying the number
+        of times to retry a GET. The statuses which are retried on are: 408,
+        500, 502, 503, and 504.
+
+        Returns
+        -------
+        A tuple of response, content, where response is a dictionary of
+        response metadata (headers), and content is the entity body returned.
+
+        Exceptions
+        ----------
+        * PythonKCMeetupsMeetupDown
+        * PythonKCMeetupsRateLimitExceeded
+        * PythonKCMeetupsBadResponse
+
+        """
+        for try_number in range(self._http_retries + 1):
+            client = httplib2.Http(timeout=self._http_timeout)
+            response, content = client.request(url, 'GET')
+            if response.status == 200:
+                return response, content
+
+            if (try_number >= self._http_retries or
+                response.status not in (408, 500, 502, 503, 504)):
+
+                if response.status >= 500:
+                    raise PythonKCMeetupsMeetupDown(response, content)
+                if response.status == 400:
+                    try:
+                        data = json.loads(content)
+                        if data.get('code', None) == 'limit':
+                            raise PythonKCMeetupsRateLimitExceeded
+                    except:  # Don't lose original error when JSON is bad
+                        pass
+                raise PythonKCMeetupsBadResponse(response, content)

pythonkc_meetups/exceptions.py

@@ -0,0 +1,67 @@
+# -*- coding: utf-8 -*-
+"""
+Overview
+========
+Defines exceptions raised by meetupy.
+
+"""
+
+
+class PythonKCMeetupsException(Exception):
+    """
+    Indicates a general problem interacting with the Meetup.com API.
+
+    This is meant to be the base type for exceptions that meetupy raises and
+    shouldn't itself be raised.
+
+    """
+    pass
+
+
+class PythonKCMeetupsBadResponse(PythonKCMeetupsException):
+    """
+    Indicates that there was a problem with a response returned by the
+    Meetup.com API.
+
+    This may include client-error status codes (i.e., 4XX), but those are not
+    expected as this client was coded to the HTTP spec and Meetup.com's API.
+
+    """
+    pass
+
+
+class PythonKCMeetupsNotJson(PythonKCMeetupsBadResponse):
+    """
+    Indicates that a media type other than JSON was returned where JSON was
+    expected. Either ``application/json`` or ``text/javascript`` is expected in
+    the ``Content-Type`` header of API HTTP responses.
+
+    """
+    pass
+
+
+class PythonKCMeetupsBadJson(PythonKCMeetupsBadResponse):
+    """
+    Indicates that the data returned from the server could not be parsed as
+    JSON, despite the content type indicating a JSON response.
+
+    """
+    pass
+
+
+class PythonKCMeetupsMeetupDown(PythonKCMeetupsException):
+    """
+    Indicates that a server error status code (i.e, 5XX) was returned from the
+    Meetup.com API.
+
+    """
+    pass
+
+
+class PythonKCMeetupsRateLimitExceeded(PythonKCMeetupsException):
+    """
+    Indicates that the rate limit has been exceed for the current API key or
+    OAuth token.
+
+    """
+    pass

pythonkc_meetups/parsers.py

@@ -0,0 +1,92 @@
+# -*- coding: utf-8 -*-
+"""
+Provides functions for converting Meetup.com API response data into the types
+returned by the PythonKC meetup client.
+
+"""
+
+
+from dateutil.tz import tzoffset
+from dateutil.tz import tzutc
+from pythonkc_meetups.types import MeetupEvent
+from pythonkc_meetups.types import MeetupVenue
+import datetime
+
+
+def parse_event(data):
+    """
+    Parse a ``MeetupEvent`` from the given response data.
+
+    Returns
+    -------
+    A ``pythonkc_meetups.types.MeetupEvent``.
+
+    """
+    return MeetupEvent(
+        id=data.get('id', None),
+        name=data.get('name', None),
+        description=data.get('description', None),
+        time=parse_datetime(data.get('time', None),
+                            data.get('utc_offset', None)),
+        status=data.get('status', None),
+        yes_rsvp_count=data.get('yes_rsvp_count', None),
+        maybe_rsvp_count=data.get('maybe_rsvp_count', None),
+        event_url=data.get('event_url', None),
+        photo_url=data.get('photo_url', None),
+        venue=parse_venue(data.get('venue', None))
+    )
+
+
+def parse_venue(data):
+    """
+    Parse a ``MeetupVenue`` from the given response data.
+
+    Returns
+    -------
+    A `pythonkc_meetups.types.`MeetupVenue`` if non-empty data is given,
+    otherwise ``None``.
+
+    """
+    if data:
+        return MeetupVenue(
+            id=data.get('id', None),
+            name=data.get('name', None),
+            address_1=data.get('address_1', None),
+            address_2=data.get('address_2', None),
+            address_3=data.get('address_3', None),
+            city=data.get('city', None),
+            state=data.get('state', None),
+            zip=data.get('zip', None),
+            country=data.get('country', None),
+            lat=data.get('lat', None),
+            lon=data.get('lon', None)
+        )
+
+
+def parse_datetime(utc_timestamp_ms, utc_offset_ms):
+    """
+    Create a timezone-aware ``datetime.datetime`` from the given UTC timestamp
+    (in milliseconds), if provided. Also, the offset is applied, if given.
+
+    Parameters
+    ----------
+    utc_timestamp_ms
+        UTC timestamp in milliseconds.
+    utc_offset_ms
+        Offset from UTC, in milliseconds, to apply to the time.
+
+    Returns
+    -------
+    A ``datetime.datetime`` if a timestamp is given, otherwise ``None``.
+
+    """
+    if utc_timestamp_ms:
+        utc_timestamp_s = utc_timestamp_ms / 1000
+        dt = datetime.datetime.fromtimestamp(utc_timestamp_s, tzutc())
+
+        if utc_offset_ms:
+            utc_offset_s = utc_offset_ms / 1000
+            tz_offset = tzoffset(None, utc_offset_s)
+            dt = dt.astimezone(tz_offset)
+
+        return dt